Image to 3D API

Image to 3D API là một tính năng cho phép bạn tích hợp khả năng Ả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 bạn cần để bắt đầu sử dụng API này.

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

Create an Image to 3D Task

endpoint này cho phép bạn tạo một tác vụ Ảnh sang 3D mới. Tham khảo The Image to 3D Task Object để xem các thuộc tính có trong đối tượng tác vụ Ả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 Processing Times.

Tham số

Chỉ một trong hai tham số input_task_id hoặc image_url 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ó sẽ được dùng làm ảnh đầ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 hoặc Ảnh sang ảnh. Ngoài ra, nó phải được chạy thông qua API, có trạng thái SUCCEEDED, và tạo ra chính xác một ảnh.

Name
image_url
Type
string
Bắt buộc
Description
Cung cấp một ảnh để Meshy sử dụng trong việc tạo mô hình. Chúng tôi hiện hỗ trợ các định dạng .jpg, .jpeg, .png, và .webp.
Kích thước tệp tối đa: 20 MB.
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 cộng.
- Data URI: Một data URI mã hóa 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>.

Name
model_type
Type
string
mặc định standard
Description
Chỉ định loại tạo lưới 3D.
Các giá trị khả dụng:
- standard: Tạo lưới 3D chi tiết cao thông thường.
- smart-topology: Chọn mô hình Smart Topology với ai_model (meshy-t2 hoặc meshy-t2.5).
- lowpoly (không dùng nữa, sẽ ngừng hỗ trợ vào 30 tháng 10, 2026): Tạo lưới low-poly được tối ưu hóa cho các đa giác gọn gàng hơn. Chúng tôi khuyến nghị sử dụng Meshy T2.5 thay thế: smart-topology với meshy-t2.5.
Khi chọn smart-topology, các tham số should_remesh, save_pre_remeshed_model, và decimation_mode sẽ bị bỏ qua, và chỉ chấp nhận topology: triangle.
lowpoly sẽ ngừng hỗ trợ vào 30 tháng 10, 2026. Sau ngày đó, các yêu cầu với model_type: "lowpoly" sẽ trả về lỗi. Chúng tôi khuyến nghị chuyển sang Meshy T2.5 (model_type: "smart-topology" với ai_model: "meshy-t2.5"). Khi chọn lowpoly, các tham số ai_model, topology, target_polycount, should_remesh, và save_pre_remeshed_model sẽ bị bỏ qua.
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 phụ thuộc vào model_type.
Tạo thông thường (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (không dùng nữa): hãy dùng meshy-7.1 thay thế.
Tạo Smart Topology (model_type: smart-topology):
- meshy-t2: mô hình Smart Topology — topology gọn gàng hơn, các bộ phận được tách tự nhiên, đầu ra dạng tam giác, và số lượng mặt có thể thiết lập bằng target_polycount.
- meshy-t2.5 (mặc định): Chi tiết sắc nét hơn cho các asset trò chơi. Đầu ra dạng tam giác, và số lượng mặt có thể thiết lập bằng target_polycount.
Name
geometry_resolution
Type
string
mặc định standard
Description
Lượt tạo hình học. 2k chạy lượt Ultra ở độ phân giải 2048³; 4k chạy ở độ phân giải 4096³ để có chi tiết bề mặt tinh xảo nhất.
Các giá trị khả dụng: standard, 2k, 4k
Yêu cầu meshy-7.1 hoặc latest.
Name
ultra_mode
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy 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 có tạo texture hay không. Đặt thành false sẽ bỏ qua giai đoạn texture, cho ra 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 nền. Một bản đồ phát xạ (emission map) cũng được tạo khi ai_model là meshy-6, ngoại trừ ở texture_resolution: 8k. meshy-6-lite, meshy-7.1, meshy-t2 và latest không tạo bản đồ phát xạ.
Name
texture_resolution
Type
string
mặc định 2k
Description
Độ phân giải texture màu nề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 được nhiều chi tiết bề mặt hơn.
4k và 8k không khả dụng với ai_model meshy-6-lite. Ở 8k, không có bản đồ phát xạ nào được tạo ra.
Name
hd_texture
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy dùng texture_resolution thay thế — tương đương với texture_resolution: "4k". Khi cả hai được thiết lập, texture_resolution sẽ được ưu tiên.
Name
texture_prompt
Type
string
Description
Cung cấp một prompt văn bản để định hướng 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 để định hướng quá trình tạo texture. Chúng tôi hiện hỗ trợ các định dạng .jpg, .jpeg, .png, và .webp.
Kích thước tệp tối đa: 20 MB.
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 cộng
- Data URI: Một data URI mã hóa 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 đáng kể về hình học giữa asset gốc và ảnh được tải lên. Chỉ một trong hai tham số texture_image_url hoặc texture_prompt có thể được dùng để định hướng quá trình tạo texture. Nếu cả hai tham số đều được cung cấp, thì texture_prompt sẽ được dùng để tạo texture cho mô hình theo mặc định. Tạo texture bằng văn bản hoặc hình ảnh sẽ tốn 10 tín dụng mỗi tác vụ.

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ó bậ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.
Các giá trị khả dụng:
- quad: Tạo lưới chủ yếu là tứ giác (quad-dominant).
- triangle: Tạo lưới tam giác đã được giảm số đa giác (decimated).
Đầu ra của Smart Topology chỉ có dạng tam giác. Yêu cầu quad cùng với ai_model meshy-t2 hoặc meshy-t2.5 sẽ trả về lỗi.
Name
decimation_mode
Type
integer
Description
Bật chế độ giảm số đa giác thích ứng bằng cách đặt một mức số đa giác. Khi được thiết lập, 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ữ thêm một tệp GLB trước khi giai đoạn remesh hoàn tất.

Name
target_polycount
Type
integer
Description
Số đa giác (mặt) mục tiêu trong đầu ra. Số lượng thực tế có thể lệch so với mục tiêu tùy thuộc vào hình học.
target_polycount có hiệu lực trong hai trường hợp độc lập:
- Remesh — với should_remesh: true trên một mô hình standard. Lưới sẽ được remesh (giảm số đa giác) đến xấp xỉ con số này. Phạm vi từ 100 đến 300.000, mặc định 30.000. Nếu decimation_mode được thiết lập, nó sẽ được ưu tiên và target_polycount sẽ bị bỏ qua.
- Smart Topology — với model_type: smart-topology và ai_model là meshy-t2 hoặc meshy-t2.5. Mô hình được tạo trực tiếp với số lượng mặt này; không có lượt remesh nào chạy và should_remesh không bắt buộc. Đối với meshy-t2: phạm vi từ 100 đến 15.000, mặc định 4.000. Đối với meshy-t2.5: phạm vi từ 100 đến 30.000, mặc định 15.000.

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: Vô hiệu hóa đố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ư thế cho mô hình được tạo.
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ể nào.
Name
is_a_t_pose
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy dùng pose_mode thay thế. Có tạo mô hình ở tư thế A/T hay không.
Name
surface_mode
Type
string
⚠ không dùng nữa
Description
Không còn ảnh hưởng đến đầu ra. Nó chọn một chế độ tạo mô hình đã bị ngừng sử dụng; hãy dùng ai_model thay thế.
Các giá trị được chấp nhận là organic và hard; bất kỳ giá trị nào khác sẽ trả về 400.
Name
image_enhancement
Type
boolean
mặc định true
Description
Tối ưu hóa ảnh đầu vào để có kết quả tốt hơn. Đặt thành false để giữ nguyên hình dạng chính xác của ả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. Thiết lập nó với meshy-6-lite hoặc với model_type: smart-topology sẽ trả về lỗi.
Name
remove_lighting
Type
boolean
mặc định true
Description
Loại bỏ các điểm sáng và bóng đổ khỏi texture màu nền, tạo ra kết quả gọn gàng hơn, hoạt động tốt hơn với các thiết lập ánh sáng tùy chỉnh.
Chỉ có hiệu lực khi ai_model là meshy-6. meshy-7.1 và latest chấp nhận tham số này nhưng sẽ bỏ qua nó. Thiết lập nó với meshy-6-lite hoặc với model_type: smart-topology sẽ trả về lỗi.
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 sàng lọc để tìm nội dung có khả năng gây hại. Nếu phát hiện nội dung gây hại, tác vụ sẽ không tiếp tục đến giai đoạn tạo.
Nội dung từ các đầu vào image_url, texture_image_url, và texture_prompt sẽ được sàng lọc.
Name
target_formats
Type
string[]
Description
Chỉ định các định dạng tệp 3D nào sẽ được đưa vào đầu ra. Chỉ các định dạng được yêu cầu mới được tạo và trả về, điều này có thể giảm thời gian hoàn thành tác vụ. Khi bỏ trống, tất cả các định dạng được hỗ trợ sẽ được đưa vào.
Các giá trị khả dụng: glb, obj, fbx, stl, usdz, 3mf
Khi bỏ trống, tất cả các định dạng ngoại trừ 3mf sẽ được tạo. 3mf chỉ được đưa vào 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 thị giác AI để tự động ước tính chiều cao thực tế của đối tượng và thay đổ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 thiết lập rõ ràng.
Name
alpha_thumbnail
Type
boolean
mặc định false
Description
Khi được đặt thành true, tác vụ sẽ render thêm một phiên bản nền trong suốt (RGBA) của ảnh 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ẽ render thêm bốn ảnh thu nhỏ theo bốn hướng chính (trước, phải, sau, trái) và trả về chúng dưới trường thumbnail_urls trong phản hồi GET. Trường thumbnail_url hiện có không thay đổi và vẫn trỏ đến góc nhìn phía trước, vì vậy các client hiện tại không bị ảnh hưở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 bậ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ụ Ảnh sang 3D vừa được tạo.

Các chế độ 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 tham số image_url 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 hoặc Ảnh sang ảnh có trạng thái SUCCEEDED và tạo ra chính xác một ảnh.
- Định dạng ảnh không hợp lệ: image_url được cung cấp không phải là định dạng được hỗ trợ (.jpg, .jpeg, .png, .webp).
- URL không thể truy cập: Không thể tải xuống image_url (404 hoặc timeout).
- Ảnh quá lớn: Ảnh image_url hoặc texture_image_url vượt quá 20 MB.
- Data URI không hợp lệ: Chuỗi base64 bị sai định dạng.
- Kết hợp tham số không hợp lệ: enable_pbr chỉ được hỗ trợ khi should_texture là true.
- Mô hình không được hỗ trợ cho low poly: ai_model: "meshy-6-lite" không hỗ trợ model_type: "lowpoly".
- Mô hình không được hỗ trợ cho Ultra: geometry_resolution yêu cầu meshy-7.1 hoặc latest.
- Mô hình không được hỗ trợ cho các tùy chọn ảnh: image_enhancement hoặc remove_lighting được thiết lập cùng với ai_model: "meshy-6-lite" hoặc model_type: "smart-topology".
Name
401 - Unauthorized
Description
Xác thực thất bại. 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 độ.

Request

POST

/openapi/v1/image-to-3d

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

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

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

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

Truy xuất một tác vụ Ảnh sang 3D

endpoint này cho phép bạn truy xuất một tác vụ Ảnh sang 3D với một id tác vụ hợp lệ. Tham khảo Đối tượng tác vụ Ảnh sang 3D để xem các thuộc tính nào được bao gồm trong đối tượng tác vụ Ảnh sang 3D.

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất cho tác vụ Ảnh sang 3D cần truy xuất.

Giá trị trả về

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

Request

GET

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

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "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/image-to-3d/:id

Xóa một tác vụ Ảnh sang 3D

Endpoint này xóa vĩnh viễn một tác vụ Ả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ụ Ả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ụ đã ở 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 nó đạt trạng thái SUCCEEDED, FAILED hoặc CANCELED, rồi mới xóa.

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

Giá trị 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/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/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/image-to-3d

Liệt kê các tác vụ Ảnh sang 3D

Endpoint này cho phép bạn truy xuất danh sách các tác vụ Ảnh sang 3D.

Tham số

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

Name
page_num
Type
integer
Description
Số trang dùng cho phân trang. Bắt đầu và mặc định là 1.
Name
page_size
Type
integer
Description
Giới hạn số lượng trên mỗi 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 dùng để sắp xếp. 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ề một danh sách có phân trang gồm Đối tượng Tác vụ Ảnh sang 3D.

Request

GET

/openapi/v1/image-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "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/image-to-3d/:id/stream

Stream một tác vụ Ảnh sang 3D

endpoint này stream các cập nhật theo thời gian thực cho một tác vụ Ả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ụ Ảnh sang 3D cần stream.

Giá trị trả về

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

Đối với các tác vụ 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/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/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": "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 Task Ảnh sang 3D

Đối tượng Task Ảnh sang 3D là một đơn vị công việc mà Meshy theo dõi để tạo mô hình 3D từ đầu vào là ảnh. Đố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 task. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp theo k (k-sortable UUID) làm chi tiết triển khai cho id của task, 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 task Ảnh sang 3D. Giá trị là image-to-3d.
Name
model_urls
Type
object
Description
URL có thể tải xuống của tệp mô hình 3D có texture được tạo bởi Meshy. 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 của tệp GLB.
- Name
  fbx
  Type
  string
  Description
  URL có thể tải xuống của tệp FBX.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống của tệp OBJ.
- Name
  usdz
  Type
  string
  Description
  URL có thể tải xuống của tệp USDZ.
- Name
  mtl
  Type
  string
  Description
  URL có thể tải xuống của tệp MTL, được trả về cùng với các tệp xuất OBJ khi có texture.
- Name
  stl
  Type
  string
  Description
  URL có thể tải xuống của tệp STL.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống của tệp 3MF. Chỉ xuất hiện khi 3mf được yêu cầu thông qua target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  URL có thể tải xuống của tệp GLB đầu ra ban đầu trước khi remesh.
  Chỉ khả dụng khi task đượ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 của ả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 của phiên bản nền trong suốt (RGBA) của thumbnail_url. Chỉ xuất hiện khi task đượ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, 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 hướng chính của mô hình 3D được tạo ra. Mỗi giá trị là một URL đã ký cho ảnh PNG 512×512 được render với cùng vật liệu và ánh sáng như thumbnail_url. Hữu ích để xem trước mô hình từ nhiều góc độ trong các pipeline hàng loạt mà không cần tải xuống tệp GLB.
Chỉ xuất hiện khi task được tạo với multi_view_thumbnails: true và đã đạt trạng thái SUCCEEDED. Các task cũ hơn và các task được tạo mà không bật tùy chọn này sẽ không bao gồm trường này.
- Name
  front
  Type
  string
  Description
  Góc nhìn phía trước, xoay 0° quanh trục dọc (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 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 để định hướng quá trình tạo texture.
Name
texture_image_url
Type
string
Description
URL có thể tải xuống của ảnh texture được sử dụng để định hướng quá trình tạo texture.
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
Hạng Ultra mà task đã chạy (2k hoặc 4k); bị bỏ qua đối với standard.
Name
progress
Type
integer
Description
Tiến trình của task. Nếu task chưa bắt đầu, thuộc tính này sẽ là 0. Khi task thành công, giá trị này sẽ trở thành 100.
Name
started_at
Type
timestamp
Description
Dấu thời gian cho biết thời điểm task bắt đầu, tính bằng mili giây. Nếu task chưa bắt đầu, thuộc tính này sẽ là 0.
Dấu thời gian biểu thị số mili giây đã 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 CH GMT được biểu thị 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 cho biết thời điểm task được tạo, tính bằng mili giây.
Name
expires_at
Type
timestamp
Description
Dấu thời gian cho biết thời điểm kết quả task hết hạn, tính bằng mili giây.
Name
finished_at
Type
timestamp
Description
Dấu thời gian cho biết thời điểm task hoàn thành, tính bằng mili giây. Nếu task 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 task. Các giá trị có thể là một trong các giá trị 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ừ task. 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 của ảnh bản đồ màu nền (base color).
- Name
  metallic
  Type
  string
  Description
  URL có thể tải xuống của ảnh bản đồ kim loại (metallic).
  Nếu task đượ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 của ảnh bản đồ normal.
  Nếu task đượ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 của ảnh bản đồ độ nhám (roughness).
  Nếu task đượ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 của ảnh bản đồ phát xạ (emission).
  Nếu task được tạo với enable_pbr: false, hoặc ai_model là meshy-6-lite, meshy-7.1, meshy-t2, hoặc latest, thuộc tính này sẽ bị bỏ qua.
Name
preceding_tasks
Type
integer
Description
Số lượng task đang xếp trước.
Giá trị của trường này chỉ có ý nghĩa khi trạng thái task là PENDING.
Name
task_error
Type
object
Description
Chi tiết lỗi cho các task thất bại. Xem Lỗi để biết đầy đủ tài liệu tham khảo về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng đã tiêu thụ bởi task này. Có mặt khi trạng thái task là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 đối với các task FAILED (tín dụng được hoàn lại khi thất bại).

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "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": "",
  "texture_image_url": "",
  "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
}