API Nhiều ảnh sang 3D

API Nhiều ảnh sang 3D là một tính năng cho phép bạn tích hợp khả năng Nhiều ảnh sang 3D của Meshy vào ứng dụng của riêng bạn. Trong phần này, bạn sẽ tìm thấy tất cả thông tin cần thiết để bắt đầu sử dụng API này.

POST/openapi/v1/multi-image-to-3d

Tạo một tác vụ Nhiều ảnh sang 3D

Endpoint này cho phép bạn tạo một tác vụ Nhiều ảnh sang 3D mới. Tham khảo The Multi-Image to 3D Task Object để xem các thuộc tính có trong đối tượng tác vụ Nhiều ảnh sang 3D.

Tham số

Chỉ một trong hai input_task_id hoặc image_urls là bắt buộc. Nếu cả hai đều được cung cấp, input_task_id sẽ được ưu tiên.

Name
input_task_id
Type
string
Bắt buộc
Description
ID của một tác vụ tạo ảnh đã hoàn thành mà đầu ra của nó (1-4 ảnh) sẽ được dùng làm đầu vào. Tác vụ này phải là một trong các loại sau: Văn bản sang ảnh, Ảnh sang ảnh, Văn bản sang ảnh Đa góc nhìn, hoặc Ảnh sang ảnh Đa góc nhìn. Ngoài ra, nó phải được chạy qua API và có trạng thái là SUCCEEDED.

Name
image_urls
Type
array
Bắt buộc
Description
Cung cấp từ 1 đến 4 ảnh để Meshy sử dụng trong quá trình tạo mô hình. Hiện tại chúng tôi hỗ trợ các định dạng .jpg, .jpeg, và .png. Tất cả các ảnh nên mô tả cùng một đối tượng từ các góc khác nhau để có kết quả tốt nhất.
Có hai cách để cung cấp mỗi ảnh:
- URL truy cập công khai: Một URL có thể truy cập được từ internet công khai.
- Data URI: Một data URI dạng base64 của ảnh. Ví dụ về data URI: data:image/jpeg;base64,<dữ liệu ảnh đã mã hóa base64 của bạn>.
Đối với meshy-7.1 (hoặc latest), ảnh đầu tiên được dùng làm góc nhìn chính (mặt trước). Thứ tự của các ảnh còn lại không quan trọng.

Name
ai_model
Type
string
mặc định latest
Description
ID của mô hình sẽ sử dụng.
Các giá trị khả dụng:
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (không dùng nữa): hãy sử dụng meshy-7.1 thay thế.
Name
geometry_resolution
Type
string
mặc định standard
Description
Giai đoạn tạo hình học. 2k chạy giai đoạn Ultra ở độ phân giải 2048³. Yêu cầu meshy-7.1 hoặc latest.
Các giá trị khả dụng: standard, 2k
Name
ultra_mode
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy sử dụng geometry_resolution thay thế. ultra_mode: true tương đương với geometry_resolution: "2k".
Name
should_texture
Type
boolean
mặc định true
Description
Xác định liệu texture có được tạo hay không. Đặt giá trị này thành false sẽ bỏ qua giai đoạn texture, cung cấp một lưới không có texture.

Chỉ áp dụng khi should_texture = true

Name
enable_pbr
Type
boolean
mặc định false
Description
Tạo bản đồ PBR (metallic, roughness, normal) bên cạnh màu sắc cơ bản. Một bản đồ emission cũng được bao gồm khi ai_model là meshy-6, ngoại trừ ở texture_resolution: 8k. meshy-6-lite, meshy-7.1 và latest không tạo ra bản đồ emission.
Name
texture_resolution
Type
string
mặc định 2k
Description
Độ phân giải texture màu sắc cơ bản. Một trong các giá trị 2k (2048×2048), 4k (4096×4096), hoặc 8k (8192×8192). Độ phân giải cao hơn sẽ nắm bắt chi tiết bề mặt tốt hơn.
4k và 8k yêu cầu ai_model là meshy-6, meshy-7.1 hoặc latest. Ở mức 8k, không có bản đồ emission nào được tạo ra.
Name
hd_texture
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy sử dụng texture_resolution thay thế — tương đương với texture_resolution: "4k". Khi cả hai được đặt, texture_resolution sẽ được ưu tiên.
Name
texture_prompt
Type
string
Description
Cung cấp một prompt văn bản để hướng dẫn quá trình tạo texture. Tối đa 800 ký tự.
Name
texture_image_url
Type
string
Description
Cung cấp một ảnh 2D để hướng dẫn quá trình tạo texture. Hiện tại chúng tôi hỗ trợ các định dạng .jpg, .jpeg, và .png.
Có hai cách để cung cấp ảnh:
- URL truy cập công khai: Một URL có thể truy cập được từ internet công khai
- Data URI: Một data URI dạng base64 của ảnh. Ví dụ về data URI: data:image/jpeg;base64,<dữ liệu ảnh đã mã hóa base64 của bạn>
Việc tạo texture từ ảnh có thể không hoạt động tối ưu nếu có sự khác biệt lớn về hình học giữa asset ban đầu và ảnh đã tải lên. Chỉ một trong hai texture_image_url hoặc texture_prompt có thể được sử dụng để hướng dẫn quá trình tạo texture. Nếu cả hai tham số đều được cung cấp, thì texture_prompt sẽ được sử dụng để tạo texture cho mô hình theo mặc định.
Name
texture_image_urls
Type
string[]
Description
Cung cấp từ 1 đến 4 ảnh cho thấy cùng một đối tượng từ các góc nhìn khác nhau để hướng dẫn tạo texture. Ảnh đầu tiên là góc nhìn chính (mặt trước); thứ tự của các góc nhìn còn lại (trái, sau, phải) không quan trọng.
Mỗi phần tử chấp nhận các định dạng giống như texture_image_url (một URL truy cập công khai hoặc data URI dạng base64, .jpg/.jpeg/.png).
Các ảnh này chỉ hướng dẫn cho texture, và độc lập với image_urls — hai danh sách này có thể chứa các ảnh khác nhau và số lượng ảnh khác nhau.
Yêu cầu ai_model là meshy-7.1 hoặc latest. Không thể kết hợp với texture_image_url hoặc texture_prompt.

Name
should_remesh
Type
boolean
mặc định false (Meshy 6 and Meshy 7 models), true (others)
Description
Kiểm soát việc có kích hoạt giai đoạn remesh hay không. Để có mô hình chất lượng cao nhất, chúng tôi khuyến nghị đặt should_remesh thành false.

Chỉ áp dụng khi should_remesh = true

Name
topology
Type
string
mặc định triangle
Description
Chỉ định topology của mô hình được tạo ra.
Các giá trị khả dụng:
- quad: Tạo một lưới chủ yếu là tứ giác.
- triangle: Tạo một lưới tam giác đã giảm số đa giác.
Name
target_polycount
Type
integer
mặc định 30,000
Description
Chỉ định số đa giác mục tiêu trong mô hình được tạo ra. Số đa giác thực tế có thể khác với mục tiêu tùy thuộc vào độ phức tạp của hình học.
Phạm vi giá trị hợp lệ thay đổi tùy theo cấp người dùng:
- 100 đến 300,000 (bao gồm cả hai đầu)
Name
decimation_mode
Type
integer
Description
Kích hoạt giảm số đa giác thích ứng bằng cách đặt một mức số đa giác. Khi được đặt, target_polycount sẽ bị bỏ qua.
Các giá trị khả dụng:
- 1: Thích ứng — số đa giác cực cao.
- 2: Thích ứng — số đa giác cao.
- 3: Thích ứng — số đa giác trung bình.
- 4: Thích ứng — số đa giác thấp.
Name
save_pre_remeshed_model
Type
boolean
mặc định false
Description
Khi được đặt thành true, Meshy cũng sẽ lưu trữ một tập tin GLB bổ sung trước khi giai đoạn remesh hoàn tất.

Name
symmetry_mode
Type
string
⚠ không dùng nữa
mặc định auto
Description
Không dùng nữa. Tham số này không còn ảnh hưởng đến đầu ra.
Trường symmetry_mode kiểm soát hành vi đối xứng trong quá trình tạo mô hình.
Các giá trị hợp lệ là:
- off: Tắt chế độ đối xứng.
- auto: Tự động xác định và áp dụng đối xứng dựa trên hình học đầu vào.
- on: Bắt buộc đối xứng trong quá trình tạo.
Name
pose_mode
Type
string
mặc định ""
Description
Chỉ định mode tạo dáng cho mô hình được tạo ra.
Các giá trị khả dụng:
- a-pose: Tạo mô hình ở tư thế A.
- t-pose: Tạo mô hình ở tư thế T.
- "" (chuỗi rỗng): Không áp dụng tư thế cụ thể.
Name
is_a_t_pose
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy sử dụng pose_mode thay thế. Liệu có tạo mô hình ở tư thế A/T hay không.
Name
image_enhancement
Type
boolean
mặc định true
Description
Tối ưu hóa các ảnh đầu vào để có kết quả tốt hơn. Đặt thành false để giữ nguyên vẻ ngoài chính xác của các ảnh đầu vào mà không qua bất kỳ xử lý phong cách nào.
Chỉ được hỗ trợ khi ai_model là meshy-6, meshy-7.1 hoặc latest.
Name
remove_lighting
Type
boolean
mặc định true
Description
Loại bỏ vùng sáng và bóng tối từ texture màu sắc cơ bản, tạo ra kết quả sạch hơn, hoạt động tốt hơn trong các thiết lập chiếu sáng tùy chỉnh.
Chỉ được hỗ trợ khi ai_model là meshy-6, meshy-7.1 hoặc latest.
Name
moderation
Type
boolean
mặc định false
Description
Khi được đặt thành true, nội dung đầu vào sẽ tự động được kiểm tra để phát hiện nội dung có thể gây hại. Nếu phát hiện nội dung có hại, tác vụ sẽ không tiếp tục sang giai đoạn tạo.
Mỗi ảnh từ image_urls và văn bản từ texture_prompt sẽ được kiểm tra.
Name
target_formats
Type
string[]
Description
Chỉ định các định dạng tập tin 3D nào sẽ được bao gồm trong đầu ra. Chỉ các định dạng được yêu cầu sẽ được tạo và trả về, điều này có thể giảm thời gian hoàn thành tác vụ.
Các giá trị khả dụng: glb, obj, fbx, stl, usdz, 3mf
Khi bị bỏ qua, tất cả các định dạng ngoại trừ 3mf sẽ được tạo. 3mf chỉ được bao gồm khi được chỉ định rõ ràng.
Name
auto_size
Type
boolean
mặc định false
Description
Khi được đặt thành true, dịch vụ sẽ sử dụng AI vision để tự động ước tính chiều cao thực tế của đối tượng và đổi kích thước mô hình tương ứng. Gốc tọa độ sẽ mặc định là bottom trừ khi origin_at được đặt rõ ràng.
Name
alpha_thumbnail
Type
boolean
mặc định false
Description
Khi được đặt thành true, tác vụ sẽ thêm việc kết xuất một phiên bản nền trong suốt (RGBA) của bản xem trước và trả về nó dưới dạng alpha_thumbnail_url trong phản hồi GET. Trường thumbnail_url hiện có không thay đổi.
Name
multi_view_thumbnails
Type
boolean
mặc định false
Description
Khi được đặt thành true, tác vụ sẽ thêm việc kết xuất bốn hình thu nhỏ theo các góc nhìn chính (trước, phải, sau, trái) và trả về chúng dưới thumbnail_urls trong phản hồi GET. Trường thumbnail_url hiện có không thay đổi và vẫn tiếp tục chỉ đến góc nhìn phía trước, vì vậy các client hiện tại sẽ không bị ảnh hưởng.
Tăng thêm khoảng 3 giây vào độ trễ của tác vụ.

Chỉ áp dụng khi auto_size = true

Name
origin_at
Type
string
mặc định bottom
Description
Vị trí của gốc tọa độ khi auto_size được kích hoạt. Các giá trị khả dụng: bottom, center.

Kết quả trả về

Thuộc tính result của phản hồi chứa id của tác vụ Nhiều ảnh sang 3D vừa được tạo.

Các trường hợp lỗi

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Các nguyên nhân phổ biến:
- Thiếu tham số: Phải cung cấp một trong hai image_urls hoặc input_task_id.
- Tác vụ đầu vào không hợp lệ: input_task_id phải tham chiếu đến một tác vụ Văn bản sang ảnh, Ảnh sang ảnh, hoặc biến thể đa góc nhìn có trạng thái SUCCEEDED.
- Số lượng ảnh không hợp lệ: image_urls phải chứa từ 1 đến 4 ảnh, và texture_image_urls từ 1 đến 4.
- Định dạng ảnh không hợp lệ: Một hoặc nhiều ảnh trong image_urls không phải là định dạng được hỗ trợ.
- Xung đột đầu vào texture: texture_image_urls không thể kết hợp với texture_image_url hoặc texture_prompt, và yêu cầu should_texture: true.
- Mô hình không được hỗ trợ cho texture đa góc nhìn: texture_image_urls yêu cầu ai_model là meshy-7.1 hoặc latest.
- URL không thể truy cập: Một hoặc nhiều phần tử trong image_urls hoặc texture_image_urls không thể tải xuống.
- Độ phân giải không được hỗ trợ cho đầu vào nhiều ảnh: geometry_resolution: "4k" không khả dụng trên endpoint này; hãy sử dụng 2k hoặc standard.
Name
401 - Unauthorized
Description
Xác thực không thành công. Vui lòng kiểm tra khóa API của bạn.
Name
402 - Payment Required
Description
Không đủ tín dụng để thực hiện tác vụ này.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ của mình.

Request

POST

/openapi/v1/multi-image-to-3d

# Simple request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ]
  }'

# With Ultra 2K geometry, PBR texturing and GLB format
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "geometry_resolution": "2k",
    "should_texture": true,
    "enable_pbr": true,
    "target_formats": ["glb"]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/multi-image-to-3d/:id

Truy xuất một tác vụ Nhiều ảnh sang 3D

Endpoint này cho phép bạn truy xuất một tác vụ Nhiều ảnh sang 3D dựa trên id tác vụ hợp lệ. Tham khảo Đối tượng tác vụ Nhiều ảnh sang 3D để xem các thuộc tính có trong đối tượng tác vụ Nhiều ảnh sang 3D.

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ Nhiều ảnh sang 3D cần truy xuất.

Giá trị trả về

Phản hồi chứa đối tượng tác vụ Nhiều ảnh sang 3D. Xem phần Đối tượng tác vụ Nhiều ảnh sang 3D để biết chi tiết.

Request

GET

/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 30
}

DELETE/openapi/v1/multi-image-to-3d/:id

Xóa tác vụ Nhiều ảnh sang 3D

Endpoint này xóa vĩnh viễn một tác vụ Nhiều ảnh sang 3D, bao gồm tất cả các mô hình và dữ liệu liên quan. Hành động này không thể hoàn tác.

Tham số đường dẫn

Name
id
Type
path
Description
ID của tác vụ Nhiều ảnh sang 3D cần xóa.

Trạng thái tác vụ

Một tác vụ vẫn đang ở trạng thái PENDING sẽ bị xóa và số tín dụng đã tiêu tốn tại thời điểm tạo sẽ được hoàn lại.

Một tác vụ đã đang ở trạng thái IN_PROGRESS thì không thể xóa: yêu cầu sẽ bị từ chối với mã 409 Conflict và tác vụ vẫn tiếp tục chạy. Tín dụng cho một tác vụ mà worker đã bắt đầu xử lý sẽ không được hoàn lại, vì vậy việc xóa nó giữa chừng sẽ khiến bạn mất cả tín dụng lẫn kết quả. Hãy đợi cho đến khi tác vụ đạt trạng thái SUCCEEDED, FAILED hoặc CANCELED, rồi mới xóa nó.

Một tác vụ ở trạng thái cuối (SUCCEEDED, FAILED hoặc CANCELED) sẽ bị xóa mà không được hoàn lại tín dụng.

Kết quả trả về

Trả về 200 OK khi thành công, hoặc 409 Conflict khi tác vụ đang ở trạng thái IN_PROGRESS.

Request

DELETE

/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/multi-image-to-3d

List Multi-Image to 3D Tasks

Endpoint này cho phép bạn lấy danh sách các tác vụ Nhiều ảnh sang 3D.

Tham số

Thuộc tính tùy chọn

Name
page_num
Type
integer
Description
Số trang cho phân trang. Bắt đầu và mặc định là 1.
Name
page_size
Type
integer
Description
Giới hạn kích thước trang. Mặc định là 10 mục. Tối đa cho phép là 100 mục.
Name
sort_by
Type
string
Description
Trường để sắp xếp theo. Các giá trị khả dụng:
- +created_at: Sắp xếp theo thời gian tạo theo thứ tự tăng dần.
- -created_at: Sắp xếp theo thời gian tạo theo thứ tự giảm dần.

Giá trị trả về

Trả về danh sách phân trang của Đối tượng Tác vụ Nhiều ảnh sang 3D.

Request

GET

/openapi/v1/multi-image-to-3d

curl https://api.meshy.ai/openapi/v1/multi-image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "multi-image-to-3d",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
        "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
        "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
        "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
        "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 30
  }
]

GET/openapi/v1/multi-image-to-3d/:id/stream

Stream a Multi-Image to 3D Task

Endpoint này truyền trực tiếp các cập nhật theo thời gian thực cho một tác vụ Nhiều ảnh sang 3D bằng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ Nhiều ảnh sang 3D cần truyền trực tiếp.

Kết quả trả về

Trả về một luồng Đối tượng tác vụ Nhiều ảnh sang 3D dưới dạng Server-Sent Events.

Đối với các tác vụ ở trạng thái PENDING hoặc IN_PROGRESS, luồng phản hồi sẽ chỉ bao gồm các trường progress và status cần thiết.

Request

GET

/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-image-to-3d",
  "model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
  "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
  "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
  "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
  "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
  "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
  "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
  "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 30
}

Đối tượng Tác vụ Nhiều ảnh sang 3D

Đối tượng Tác vụ Nhiều ảnh sang 3D là một đơn vị công việc mà Meshy theo dõi để tạo ra một mô hình 3D từ nhiều ảnh (từ 1 đến 4 ảnh). Các ảnh nên là của cùng một đối tượng, lý tưởng nhất là từ các góc nhìn hoặc góc độ khác nhau. Đối tượng này có các thuộc tính sau:

Thuộc tính

Name
id
Type
string
Description
Định danh duy nhất cho tác vụ. Trong khi chúng tôi sử dụng một UUID có thể k-sắp xếp cho id tác vụ như là chi tiết triển khai, bạn không nên đưa ra bất kỳ giả định nào về định dạng của id.
Name
type
Type
string
Description
Loại của tác vụ Nhiều ảnh sang 3D. Giá trị là multi-image-to-3d.
Name
model_urls
Type
object
Description
URL có thể tải xuống đến tệp mô hình 3D đã được phủ texture do Meshy tạo ra. Thuộc tính cho một định dạng sẽ bị bỏ qua nếu định dạng đó không được tạo ra, thay vì trả về một chuỗi rỗng.
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống đến tệp GLB.
- Name
  fbx
  Type
  string
  Description
  URL có thể tải xuống đến tệp FBX.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống đến tệp OBJ.
- Name
  usdz
  Type
  string
  Description
  URL có thể tải xuống đến tệp USDZ.
- Name
  mtl
  Type
  string
  Description
  URL có thể tải xuống đến tệp MTL, được trả về cùng với các bản xuất OBJ khi có texture.
- Name
  stl
  Type
  string
  Description
  URL có thể tải xuống đến tệp STL.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống đến tệp 3MF. Chỉ xuất hiện khi 3mf được yêu cầu qua target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  URL có thể tải xuống đến tệp GLB đầu ra ban đầu trước khi remesh.
  Chỉ có sẵn khi tác vụ được tạo với cả should_remesh: true và save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL có thể tải xuống đến ảnh thu nhỏ của tệp mô hình. Tương đương với thumbnail_urls.front khi có, được giữ lại để tương thích ngược.
Name
alpha_thumbnail_url
Type
string
Description
URL có thể tải xuống đến phiên bản nền trong suốt (RGBA) của thumbnail_url. Chỉ xuất hiện khi tác vụ được tạo với alpha_thumbnail: true và bản xem trước trong suốt được render thành công; nếu không thì trường này sẽ bị bỏ qua.
Name
thumbnail_urls
Type
object
Description
Các URL có thể tải xuống cho bốn ảnh thu nhỏ theo bốn góc nhìn chính của mô hình 3D được tạo ra. Mỗi giá trị là một URL đã ký đến một ảnh PNG 512×512 được render với cùng vật liệu và ánh sáng như thumbnail_url. Hữu ích cho việc xem trước mô hình từ nhiều góc trong các quy trình xử lý theo lô mà không cần tải xuống tệp GLB.
Chỉ xuất hiện khi tác vụ được tạo với multi_view_thumbnails: true và đã đạt trạng thái SUCCEEDED. Các tác vụ cũ hơn và các tác vụ được tạo mà không có tùy chọn đăng ký này sẽ không bao gồm trường này.
- Name
  front
  Type
  string
  Description
  Góc nhìn từ phía trước, xoay 0° quanh trục thẳng đứng (khớp với thumbnail_url).
- Name
  right
  Type
  string
  Description
  Góc nhìn bên phải, xoay 90°.
- Name
  back
  Type
  string
  Description
  Góc nhìn từ phía sau, xoay 180°.
- Name
  left
  Type
  string
  Description
  Góc nhìn bên trái, xoay 270°.
Name
texture_prompt
Type
string
Description
Prompt văn bản được sử dụng để hướng dẫn quá trình tạo texture.
Name
texture_image_urls
Type
string[]
Description
Các URL có thể tải xuống đến các ảnh tham chiếu texture đã được sử dụng để tạo tác vụ, theo thứ tự chúng được cung cấp. Chỉ xuất hiện khi tác vụ được tạo với texture_image_urls.
Name
ultra_mode
Type
boolean
⚠ không dùng nữa
Description
Không dùng nữa; hãy đọc geometry_resolution thay thế.
Name
geometry_resolution
Type
string
Description
Cấp độ Ultra mà tác vụ đã chạy (2k); bị bỏ qua đối với standard.
Name
progress
Type
integer
Description
Tiến độ của tác vụ. Nếu tác vụ chưa được bắt đầu, thuộc tính này sẽ là 0. Khi tác vụ đã thành công, giá trị này sẽ trở thành 100.
Name
started_at
Type
timestamp
Description
Dấu thời gian khi tác vụ được bắt đầu, tính bằng milliseconds. Nếu tác vụ chưa được bắt đầu, thuộc tính này sẽ là 0.
Một dấu thời gian đại diện cho số milliseconds đã trôi qua kể từ ngày 1 tháng 1 năm 1970 UTC, theo tiêu chuẩn RFC 3339. Ví dụ, thứ Sáu, ngày 1 tháng 9 năm 2023 12:00:00 chiều GMT được biểu diễn là 1693569600000. Điều này áp dụng cho tất cả các dấu thời gian trong Meshy API.
Name
created_at
Type
timestamp
Description
Dấu thời gian khi tác vụ được tạo, tính bằng milliseconds.
Name
expires_at
Type
timestamp
Description
Dấu thời gian khi kết quả tác vụ hết hạn, tính bằng milliseconds.
Name
finished_at
Type
timestamp
Description
Dấu thời gian khi tác vụ hoàn thành, tính bằng milliseconds. Nếu tác vụ chưa hoàn thành, thuộc tính này sẽ là 0.
Name
status
Type
string
Description
Trạng thái của tác vụ. Các giá trị có thể là một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Một mảng các đối tượng URL texture được tạo ra từ tác vụ. Thông thường mảng này chỉ chứa một đối tượng URL texture. Mỗi URL texture có các thuộc tính sau:
- Name
  base_color
  Type
  string
  Description
  URL có thể tải xuống đến ảnh bản đồ màu cơ bản.
- Name
  metallic
  Type
  string
  Description
  URL có thể tải xuống đến ảnh bản đồ metallic.
  Nếu tác vụ được tạo với enable_pbr: false, thuộc tính này sẽ bị bỏ qua.
- Name
  normal
  Type
  string
  Description
  URL có thể tải xuống đến ảnh bản đồ normal.
  Nếu tác vụ được tạo với enable_pbr: false, thuộc tính này sẽ bị bỏ qua.
- Name
  roughness
  Type
  string
  Description
  URL có thể tải xuống đến ảnh bản đồ độ nhám.
  Nếu tác vụ được tạo với enable_pbr: false, thuộc tính này sẽ bị bỏ qua.
- Name
  emission
  Type
  string
  Description
  URL có thể tải xuống đến ảnh bản đồ phát xạ.
  Nếu tác vụ được tạo với enable_pbr: false, hoặc ai_model là meshy-6-lite, thuộc tính này sẽ bị bỏ qua.
Name
preceding_tasks
Type
integer
Description
Số lượng các tác vụ đứng trước.
Giá trị của trường này chỉ có ý nghĩa khi trạng thái tác vụ là PENDING.
Name
task_error
Type
object
Description
Chi tiết lỗi cho các tác vụ thất bại. Xem Lỗi để biết tài liệu tham khảo đầy đủ về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng đã được tiêu thụ bởi tác vụ này. Xuất hiện khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các tác vụ FAILED (tín dụng được hoàn lại khi thất bại).

Example Multi-Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 30,
}