API Nhiều ảnh sang 3D

Tạo mô hình 3D từ một đến bốn hình ảnh của cùng một đối tượng, được chụp từ các góc độ khác nhau.

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

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

Tạo một tác vụ Nhiều ảnh sang 3D. Tác vụ chạy ở chế độ nền. Để biết thời gian xử lý thường mất bao lâu, xem Thời gian xử lý. Để biết các trường của một tác vụ, xem Đối tượng tác vụ Nhiều ảnh sang 3D.

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"]
  }'

# Textured with Meshy N1 from the input images, the first as the front view
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 front view image url or base64-encoded data URI>",
      "<your back view image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "texture_model": "meshy-n1"
  }'

Response

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

Tham số

Name
input_task_id
Type
string
Bắt buộc
Description
Bắt buộc trừ khi bạn gửi image_urls. ID của một tác vụ Văn bản sang ảnh hoặc Ảnh sang ảnh, kể cả loại đa góc nhìn. Meshy dùng một đến bốn ảnh của tác vụ đó làm đầu vào. Tác vụ phải là tác vụ bạn tạo bằng API và có trạng thái SUCCEEDED.

Name
image_urls
Type
array
Bắt buộc
Description
Bắt buộc trừ khi bạn gửi input_task_id. Một đến bốn ảnh, mỗi ảnh ở dạng URL công khai hoặc data URI, chẳng hạn như data:image/jpeg;base64,<dữ liệu ảnh mã hóa base64 của bạn>. Nếu bạn gửi cả hai, Meshy sẽ dùng input_task_id.
Mỗi ảnh phải là tệp .jpg, .jpeg, .png, hoặc .webp tối đa 20 MB, mỗi cạnh ít nhất 32 pixel, và tối đa 178.956.970 pixel (chiều rộng × chiều cao). Gửi hơn bốn ảnh sẽ trả về 400.
Để có kết quả tốt nhất, các ảnh nên thể hiện cùng một đối tượng từ các góc khác nhau. Với meshy-7.1 hoặc latest, Meshy dùng ảnh đầu tiên làm góc nhìn trước mặt, còn thứ tự các ảnh khác không quan trọng.

Name
ai_model
Type
string
mặc định latest
Description
Mô hình AI tạo ra mô hình 3D.
Các giá trị khả dụng:
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7: không dùng nữa, hãy gửi meshy-7.1 thay thế
Name
geometry_resolution
Type
string
mặc định standard
Description
Mức độ chi tiết hình học cần tạo.
Các giá trị khả dụng:
- standard
- 2k: chạy bước Ultra ở 2048³. Cần meshy-7.1, latest, hoặc meshy-7 (đã không dùng nữa).
Name
ultra_mode
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy gửi 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
Có tạo texture hay không. true trả về mô hình có texture, còn false bỏ qua bước tạo texture và trả về lưới không có texture.

Chỉ áp dụng khi should_texture = true

Name
texture_model
Type
string
mặc định depends on ai_model
Description
Mô hình AI tạo texture cho mô hình 3D từ nhiều góc nhìn, trong cùng một tác vụ. Bỏ trống để dùng mô hình texture mặc định cho ai_model của bạn. Nó không làm thay đổi chi phí tín dụng.
Các giá trị khả dụng:
- meshy-7: Meshy 7, với bản đồ PBR và texture lên đến 8K
- meshy-n1: Meshy N1, một texture màu cơ bản 2K chỉ từ ảnh tham chiếu
Mọi ai_model đều chấp nhận cả hai. Một yêu cầu có texture với meshy-6 hoặc meshy-6-lite sẽ trả về 400, và một tùy chọn mà mô hình texture đã chọn không hỗ trợ cũng vậy. Với should_texture: false, Meshy bỏ qua texture_model, nhưng một giá trị không xác định vẫn trả về 400.
Với meshy-n1, Meshy tạo texture từ texture_image_urls hoặc texture_image_url, hoặc từ các ảnh đầu vào khi bạn không gửi cái nào. Ảnh đầu tiên là góc nhìn trước mặt. Một mô hình được tạo ra có hơn 7.999.999 tam giác sẽ khiến tác vụ thất bại, và Meshy sẽ hoàn lại tín dụng.
Xem Mô hình để biết mỗi mô hình texture làm gì và nên chọn mô hình nào.
Name
enable_pbr
Type
boolean
mặc định false
Description
Có tạo thêm bản đồ metallic, roughness, và normal, bên cạnh màu cơ bản hay không. Mô hình texture Meshy 6 cũng tạo bản đồ emission, trừ khi ở texture_resolution: 8k. Với texture_model: meshy-n1, true sẽ trả về 400.
Name
texture_resolution
Type
string
mặc định 2k
Description
Kích thước của texture màu cơ bản. Kích thước lớn hơn ghi lại nhiều chi tiết bề mặt hơn.
Các giá trị khả dụng:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k và 8k cần mô hình texture Meshy 7 hoặc Meshy 6, và trả về 400 với các mô hình khác. Ở 8k, Meshy không tạo bản đồ emission.
Name
hd_texture
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy gửi texture_resolution thay thế. hd_texture: true tương đương với texture_resolution: "4k". Nếu bạn gửi cả hai, Meshy sẽ dùng texture_resolution.
Name
texture_prompt
Type
string
Description
Văn bản định hướng texture, tối đa 800 ký tự. Văn bản dài hơn sẽ trả về 400. Với texture_model: meshy-n1, gửi trường này sẽ trả về 400.
Name
texture_image_url
Type
string
Description
Một ảnh 2D định hướng texture, ở dạng URL công khai hoặc data URI, chẳng hạn như data:image/jpeg;base64,<dữ liệu ảnh mã hóa base64 của bạn>. Ảnh phải là tệp .jpg, .jpeg, .png, hoặc .webp tối đa 20 MB, mỗi cạnh ít nhất 32 pixel, và tối đa 178.956.970 pixel (chiều rộng × chiều cao).
Nếu bạn gửi cả texture_image_url và texture_prompt, Meshy sẽ dùng texture_prompt. Với texture_model: meshy-n1, Meshy tạo texture từ ảnh này như góc nhìn trước mặt.
Texture có thể không ra đẹp khi hình dạng trong ảnh khác nhiều so với mô hình 3D.
Name
texture_image_urls
Type
string[]
Description
Một đến bốn ảnh của đối tượng từ các góc nhìn khác nhau để định hướng texture. Meshy dùng ảnh đầu tiên làm góc nhìn trước mặt. Thứ tự của các góc nhìn khác (trái, sau, phải) không quan trọng.
Mỗi ảnh tuân theo cùng quy tắc như texture_image_url. Đó là một URL công khai hoặc data URI, ở định dạng .jpg, .jpeg, .png, hoặc .webp, tối đa 20 MB, mỗi cạnh ít nhất 32 pixel, và tối đa 178.956.970 pixel (chiều rộng × chiều cao).
Những ảnh này chỉ định hướng texture và không phụ thuộc vào image_urls. Hai danh sách có thể chứa các ảnh khác nhau và số lượng ảnh khác nhau.
texture_image_urls cần mô hình texture Meshy 7 hoặc Meshy N1. Hãy gửi nó cùng với một trong các trường sau:
- ai_model là meshy-7.1, latest, hoặc meshy-7 (đã không dùng nữa)
- texture_model là meshy-7 hoặc meshy-n1
Bạn không thể gửi nó cùng với texture_image_url hoặc texture_prompt.

Name
should_remesh
Type
boolean
mặc định true (meshy-6-lite), false (other models)
Description
Có remesh mô hình sau khi tạo hay không. Để có mô hình 3D chất lượng cao nhất, hãy đặt thành false.

Chỉ áp dụng khi should_remesh = true

Name
topology
Type
string
mặc định triangle
Description
Loại mặt của mô hình đã remesh.
Các giá trị khả dụng:
- quad: một lưới chủ yếu là tứ giác
- triangle: một lưới tam giác đã giảm số lượng
Với texture_model: meshy-n1, quad sẽ trả về 400 khi mô hình được remesh, điều mà meshy-6-lite thực hiện theo mặc định.
Name
target_polycount
Type
integer
mặc định 30000
Description
Số lượng mặt mục tiêu, từ 100 đến 300000. Kết quả có thể khác với mục tiêu, tùy thuộc vào hình học của mô hình. Giá trị nằm ngoài phạm vi sẽ trả về 400.
Name
decimation_mode
Type
integer
Description
Số lượng mặt thích ứng, theo cấp độ. Khi bạn đặt trường này, Meshy bỏ qua target_polycount.
Các giá trị khả dụng:
- 1: ultra
- 2: high
- 3: medium
- 4: low
Name
save_pre_remeshed_model
Type
boolean
mặc định false
Description
Có lưu thêm tệp GLB từ trước khi remesh hay không, được trả về trong model_urls.pre_remeshed_glb.

Name
symmetry_mode
Type
string
⚠ không dùng nữa
mặc định auto
Description
Hãy bỏ trống. Nó không ảnh hưởng đến đầu ra.
Các giá trị khả dụng:
- off: không đối xứng
- auto: đối xứng dựa trên hình học đầu vào
- on: ép buộc đối xứng
Name
pose_mode
Type
string
mặc định ""
Description
Tư thế của mô hình được tạo ra.
Các giá trị khả dụng:
- a-pose: tư thế chữ A
- t-pose: tư thế chữ T
- "" (chuỗi rỗng): không có tư thế cụ thể
Name
is_a_t_pose
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy gửi pose_mode thay thế. Có tạo mô hình ở tư thế chữ A hay chữ T hay không.
Name
image_enhancement
Type
boolean
mặc định true
Description
Có tối ưu hóa ảnh đầu vào trước khi tạo hay không. false giữ nguyên hình dáng chính xác của ảnh đầu vào, không qua xử lý phong cách. Chỉ hỗ trợ với meshy-6, meshy-7.1, hoặc latest. Gửi trường này với meshy-6-lite sẽ trả về 400.
Name
remove_lighting
Type
boolean
mặc định true
Description
Có loại bỏ các điểm sáng và bóng đổ khỏi texture màu cơ bản hay không. Kết quả sạch hơn hoạt động tốt hơn dưới ánh sáng riêng của bạn. Chỉ mô hình texture Meshy 6 sử dụng trường này, và ở texture_resolution: 8k nó luôn loại bỏ ánh sáng. Với texture_model: meshy-n1, true sẽ trả về 400. Với ai_model: meshy-6-lite và mô hình texture mặc định của nó, gửi trường này sẽ trả về 400.
Name
moderation
Type
boolean
mặc định false
Description
Có sàng lọc đầu vào để tìm nội dung có hại hay không. Meshy sàng lọc từng ảnh đầu vào, texture_image_url hoặc từng ảnh trong texture_image_urls, và văn bản trong texture_prompt. Nếu Meshy phát hiện nội dung có hại, yêu cầu sẽ trả về 400 và Meshy sẽ không tạo tác vụ.
Name
target_formats
Type
string[]
Description
Các định dạng tệp 3D cần tạo. Meshy chỉ tạo và trả về các định dạng bạn liệt kê, điều này có thể rút ngắn thời gian tác vụ.
Các giá trị khả dụng:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Nếu bạn bỏ trống, Meshy sẽ tạo mọi định dạng trừ 3mf. Meshy chỉ tạo 3mf khi bạn liệt kê nó.
Name
auto_size
Type
boolean
mặc định false
Description
Có ước tính chiều cao thực tế của đối tượng bằng thị giác AI và thay đổi kích thước mô hình theo chiều cao đó hay không. Meshy đặt gốc tọa độ ở dưới cùng trừ khi bạn đặt origin_at.

Chỉ áp dụng khi auto_size = true

Name
origin_at
Type
string
mặc định bottom
Description
Vị trí đặt gốc tọa độ của mô hình, bottom hoặc center.

Name
alpha_thumbnail
Type
boolean
mặc định false
Description
Có kết xuất thêm bản xem trước với nền trong suốt (RGBA) hay không, được trả về trong alpha_thumbnail_url khi bạn lấy tác vụ. thumbnail_url không thay đổi.
Name
multi_view_thumbnails
Type
boolean
mặc định false
Description
Có kết xuất thêm các bản xem trước từ phía trước, phải, sau, và trái hay không, được trả về trong thumbnail_urls khi bạn lấy tác vụ. thumbnail_url không thay đổi và vẫn hiển thị góc nhìn trước mặt. Việc này thêm khoảng 5 giây vào tác vụ.

Kết quả trả về

Trường result của phản hồi chứa ID của tác vụ Nhiều ảnh sang 3D mới.

Các chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không thể chạy. Thông báo lỗi cho biết vấn đề nào đã được phát hiện. Ví dụ:
- Thiếu tham số: Không gửi image_urls lẫn input_task_id.
- Tác vụ đầu vào không hợp lệ: input_task_id không phải là một tác vụ Văn bản sang ảnh hoặc Ảnh sang ảnh có trạng thái SUCCEEDED, hoặc là loại đa góc nhìn.
- Số lượng ảnh không hợp lệ: image_urls hoặc texture_image_urls không chứa từ 1 đến 4 ảnh.
- Định dạng ảnh không hợp lệ: Một ảnh trong image_urls không ở định dạng được hỗ trợ.
- Đầu vào texture xung đột: texture_image_urls được gửi cùng với texture_image_url, với texture_prompt, hoặc với should_texture: false.
- Mô hình không được hỗ trợ cho texture đa góc nhìn: texture_image_urls được gửi cùng với ai_model là meshy-6 hoặc meshy-6-lite, trừ khi texture_model là meshy-7 hoặc meshy-n1.
- URL không thể truy cập: Meshy không thể tải xuống một ảnh trong image_urls hoặc texture_image_urls.
- Ảnh quá lớn: Một ảnh trong image_urls, texture_image_url, hoặc texture_image_urls vượt quá 20 MB.
- Kích thước ảnh không hợp lệ: Một ảnh trong image_urls, texture_image_url, hoặc texture_image_urls có cạnh ngắn hơn 32 pixel, hoặc hơn 178.956.970 pixel (chiều rộng × chiều cao).
- Độ phân giải không được hỗ trợ cho đầu vào nhiều ảnh: geometry_resolution là "4k", điều mà endpoint này không hỗ trợ. Hãy dùng 2k hoặc standard.
- Mô hình không được hỗ trợ cho tùy chọn ảnh: image_enhancement được gửi cùng với ai_model: "meshy-6-lite", hoặc remove_lighting được gửi cùng với ai_model: "meshy-6-lite" và mô hình texture mặc định của nó.
- Mô hình texture không hợp lệ: texture_model không phải là tên mô hình texture hợp lệ.
- Mô hình texture không khả dụng: Một yêu cầu có texture đã gửi texture_model là meshy-6 hoặc meshy-6-lite. Nhiều ảnh sang 3D chỉ chấp nhận các mô hình texture tạo texture từ nhiều góc nhìn. Hãy gửi meshy-7 hoặc meshy-n1, hoặc bỏ trống texture_model.
- Tùy chọn không được hỗ trợ cho mô hình texture: Yêu cầu đặt một tùy chọn cho mô hình texture mà mô hình đó không hỗ trợ, chẳng hạn như enable_pbr: true với meshy-n1 hoặc texture 4k với meshy-6-lite. Xem Mô hình.
Hãy sửa yêu cầu rồi gửi lại. Xem Lỗi.
Name
401 - Unauthorized
Description
Khóa API bị thiếu hoặc không hợp lệ. Hãy kiểm tra header Authorization.
Name
402 - Payment Required
Description
Ví dụ:
- Không đủ tín dụng: Tài khoản không có đủ tín dụng cho tác vụ này, hoặc tài khoản đã đạt đến giới hạn tín dụng. Hãy kiểm tra số dư tín dụng của bạn rồi thử lại.
- Gói miễn phí: Việc tạo tác vụ yêu cầu gói trả phí. Hãy nâng cấp gói của bạn trong cài đặt đăng ký rồi thử lại.
Name
403 - Forbidden
Description
Kiểm duyệt nội dung đã chặn prompt hoặc một ảnh đầu vào. Hãy thay đổi đầu vào rồi thử lại.
Name
404 - Not Found
Description
input_task_id không khớp với bất kỳ tác vụ nào của bạn. Hãy kiểm tra ID tác vụ rồi gửi lại yêu cầu.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ. Hãy chờ rồi thử lại. Xem Giới hạn tốc độ.

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

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

Trả về một tác vụ Nhiều ảnh sang 3D theo ID của nó.

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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Tham số

Name
id
Type
path
Description
ID tác vụ từ phản hồi tạo tác vụ.

Giá trị trả về

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

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

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

Xóa vĩnh viễn một tác vụ Nhiều ảnh sang 3D, bao gồm cả các mô hình và dữ liệu của nó. Bạn không thể hoàn tác việc xóa.

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 keeps 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."
}

Tham số đường dẫn

Name
id
Type
path
Description
ID của tác vụ cần xóa.

Trạng thái tác vụ

Việc xóa một tác vụ ở trạng thái PENDING sẽ hoàn lại số tín dụng đã sử dụng khi bạn tạo tác vụ đó.

Một tác vụ IN_PROGRESS không thể bị xóa. Yêu cầu sẽ trả về 409 Conflict, và tác vụ vẫn tiếp tục chạy. Meshy không hoàn lại tín dụng cho một tác vụ đã bắt đầu, vì vậy việc xóa nó sẽ khiến bạn mất cả tín dụng lẫn kết quả. Hãy đợi cho tác vụ đạt đến trạng thái SUCCEEDED, FAILED, hoặc CANCELED, sau đó mới xóa nó.

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

Kết quả trả về

200 OK khi tác vụ đã được xóa, hoặc 409 Conflict khi tác vụ đang ở trạng thái IN_PROGRESS.

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

List Multi-Image to 3D tasks

Trả về danh sách các tác vụ Nhiều ảnh sang 3D của bạn.

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"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 30
  }
]

Tham số

Name
page_num
Type
integer
mặc định 1
Description
Số trang cần trả về, tối đa 255. Giá trị lớn hơn sẽ trả về 400.
Name
page_size
Type
integer
mặc định 10
Description
Số lượng tác vụ trên mỗi trang, tối đa 100.
Name
sort_by
Type
string
Description
Thứ tự sắp xếp.
Các giá trị khả dụng:
- +created_at: cũ nhất trước
- -created_at: mới nhất trước

Giá trị trả về

Một danh sách phân trang các đối tượng tác vụ Nhiều ảnh sang 3D.

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

Stream một tác vụ Nhiều ảnh sang 3D

Stream các cập nhật của một tác vụ Nhiều ảnh sang 3D dưới dạng Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Tham số

Name
id
Type
path
Description
ID tác vụ từ phản hồi tạo tác vụ.

Giá trị trả về

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

Mỗi sự kiện chứa toàn bộ đối tượng tác vụ, theo cùng cấu trúc mà endpoint Get trả về. Trong khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường kết quả của nó chưa có giá trị.

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

Đối tượng tác vụ Nhiều ảnh sang 3D mô tả một lần tạo mô hình 3D từ một đến bốn ảnh của một đối tượng. Nó chứa trạng thái, progress, và các tệp mô hình khi tác vụ thành công.

Thuộc tính

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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Name
id
Type
string
Description
ID của tác vụ. Hãy coi đây là một chuỗi không minh bạch, và đừng dựa vào định dạng của nó.
Name
type
Type
string
Description
Loại tác vụ, luôn là multi-image-to-3d.
Name
model_urls
Type
object
Description
URL tải xuống cho mô hình 3D được tạo, mỗi URL ứng với một định dạng tệp. Một định dạng mà tác vụ không tạo ra sẽ không có khóa tương ứng, thay vì là một chuỗi rỗng.
- Name
  glb
  Type
  string
  Description
  Tệp GLB.
- Name
  fbx
  Type
  string
  Description
  Tệp FBX.
- Name
  obj
  Type
  string
  Description
  Tệp OBJ.
- Name
  usdz
  Type
  string
  Description
  Tệp USDZ.
- Name
  mtl
  Type
  string
  Description
  Tệp MTL, được trả về cùng tệp OBJ khi mô hình có texture.
- Name
  stl
  Type
  string
  Description
  Tệp STL.
- Name
  3mf
  Type
  string
  Description
  Tệp 3MF. Chỉ xuất hiện khi target_formats bao gồm 3mf.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Tệp GLB từ trước khi remesh. Chỉ xuất hiện khi bạn tạo tác vụ với cả should_remesh: true và save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL tải xuống cho ảnh xem trước của mô hình. Nó giống với thumbnail_urls.front khi trường đó có mặt.
Name
alpha_thumbnail_url
Type
string
Description
URL tải xuống cho một phiên bản của thumbnail_url với nền trong suốt (RGBA). Chỉ xuất hiện khi bạn tạo tác vụ với alpha_thumbnail: true và Meshy đã render bản xem trước trong suốt.
Name
thumbnail_urls
Type
object
Description
URL tải xuống cho các ảnh xem trước của mô hình 3D từ bốn phía. Mỗi URL là một URL đã ký trỏ tới ảnh PNG 512×512, được render với cùng vật liệu và ánh sáng như thumbnail_url. Bạn có thể dùng chúng để xem trước mô hình từ nhiều góc độ mà không cần tải xuống tệp GLB.
Chỉ xuất hiện khi bạn tạo tác vụ với multi_view_thumbnails: true và tác vụ đạt trạng thái SUCCEEDED. Một tác vụ được tạo mà không có multi_view_thumbnails: true sẽ không có trường này.
- Name
  front
  Type
  string
  Description
  Góc nhìn từ phía trước, ở 0° quanh trục dọc. Nó khớp với thumbnail_url.
- Name
  right
  Type
  string
  Description
  Góc nhìn bên phải, ở 90°.
- Name
  back
  Type
  string
  Description
  Góc nhìn phía sau, ở 180°.
- Name
  left
  Type
  string
  Description
  Góc nhìn bên trái, ở 270°.
Name
texture_prompt
Type
string
Description
Prompt văn bản dùng để định hướng texture.
Name
texture_image_urls
Type
string[]
Description
URL tải xuống cho các ảnh tham chiếu texture mà bạn đã dùng để tạo tác vụ, theo thứ tự bạn đã gửi chúng. Chỉ xuất hiện khi bạn tạo tác vụ với texture_image_urls.
Name
ultra_mode
Type
boolean
⚠ không dùng nữa
Description
Hãy đọc geometry_resolution thay thế.
Name
geometry_resolution
Type
string
Description
Bậc Ultra mà tác vụ đã chạy, là 2k. Một tác vụ standard sẽ không có trường này.
Name
progress
Type
integer
Description
Tác vụ đã hoàn thành bao nhiêu, tính theo phần trăm. Giá trị là 0 cho đến khi tác vụ bắt đầu và 100 khi nó thành công.
Name
started_at
Type
timestamp
Description
Thời điểm tác vụ bắt đầu, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ bắt đầu.
Name
created_at
Type
timestamp
Description
Thời điểm tác vụ được tạo, tính bằng mili giây Unix.
Name
expires_at
Type
timestamp
Description
Thời điểm kết quả của tác vụ hết hạn, tính bằng mili giây Unix.
Name
finished_at
Type
timestamp
Description
Thời điểm tác vụ hoàn tất, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ hoàn tất.
Name
status
Type
string
Description
Trạng thái tác vụ, là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, hoặc CANCELED.
Name
texture_urls
Type
array
Description
URL tải xuống cho các bản đồ texture mà tác vụ đã tạo, dưới dạng một mảng các đối tượng. Mảng này thường chứa một đối tượng. Mỗi đối tượng có các trường sau:
- Name
  base_color
  Type
  string
  Description
  Bản đồ màu nền (base color).
- Name
  metallic
  Type
  string
  Description
  Bản đồ metallic. Không được bao gồm khi bạn tạo tác vụ với enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  Bản đồ normal. Không được bao gồm khi bạn tạo tác vụ với enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  Bản đồ roughness. Không được bao gồm khi bạn tạo tác vụ với enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  Bản đồ emission. Chỉ được bao gồm khi bạn tạo tác vụ với tất cả các điều kiện sau:
  
  ai_model: meshy-6, với mô hình texture mặc định của nó
  
  enable_pbr: true
  
  texture_resolution là 2k hoặc 4k
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước tác vụ này trong hàng đợi. Giá trị này chỉ có ý nghĩa khi tác vụ đang ở trạng thái PENDING.
Name
task_error
Type
object
Description
Chi tiết lỗi khi tác vụ thất bại. Giá trị là null trừ khi trạng thái là FAILED. Xem Lỗi.
Name
consumed_credits
Type
integer
Description
Số tín dụng mà tác vụ đã sử dụng. Có mặt khi trạng thái là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Giá trị là 0 đối với tác vụ FAILED, vì Meshy hoàn lại tín dụng khi một tác vụ thất bại.