API Ảnh sang 3D

API Ảnh sang 3D là một tính năng cho phép bạn tích hợp các 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 với API này.

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

Tạo tác vụ Ảnh sang 3D

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

Tham số

Chỉ một trong input_task_id hoặc image_url là bắt buộc. Nếu cung cấp cả hai, 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 tất 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 tác vụ sau: Văn bản sang ảnh hoặc Ảnh sang ảnh. Ngoài ra, tác vụ phải được chạy qua API, có trạng thái SUCCEEDED, và tạo ra đúng một ảnh.

Name
image_url
Type
string
Bắt buộc
Description
Cung cấp một ả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.
Có hai cách để cung cấp ảnh:
- URL có thể truy cập công khai: Một URL có thể truy cập từ internet công cộng.
- Data URI: Một Data URI của ảnh được mã hóa base64. Ví dụ về Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

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 thông thường với độ chi tiết cao.
- lowpoly: Tạo lưới low-poly được tối ưu hóa để có các đa giác sạch hơn.
Khi chọn lowpoly, ai_model, topology, target_polycount, should_remesh, save_pre_remeshed_model sẽ bị bỏ qua.
Name
ai_model
Type
string
mặc định latest
Description
ID của mô hình cần sử dụng. Các giá trị khả dụng: meshy-5, meshy-6, latest (Meshy 6).
Name
should_texture
Type
boolean
mặc định true
Description
Xác định liệu texture có được tạo hay không. Đặt 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) ngoài màu cơ bản. Một emission map cũng được bao gồm khi ai_model là meshy-6 hoặc latest.
Name
hd_texture
Type
boolean
mặc định false
Description
Tạo texture màu cơ bản ở độ phân giải 4K (4096×4096) để có độ chi tiết cao hơn.
Chỉ được hỗ trợ khi ai_model là meshy-6 hoặc latest. Bản đồ PBR luôn được tạo ở 2K.
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 600 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 có thể truy cập công khai: Một URL có thể truy cập từ internet công cộng
- Data URI: Một Data URI của ảnh được mã hóa base64. Ví dụ về Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Tạo texture bằng ảnh có thể không hoạt động tối ưu nếu có khác biệt đáng kể về hình học giữa asset gốc và ảnh đã tải lên. Chỉ một trong texture_image_url hoặc texture_prompt có thể được dùng để hướng dẫn quá trình tạo texture. Nếu cung cấp cả hai tham số, 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 ảnh sẽ tốn 10 tín dụng cho mỗi tác vụ.

Name
should_remesh
Type
boolean
mặc định false (meshy-6), true (others)
Description
Kiểm soát việc có bật giai đoạn Remesh hay không. Khi đặt thành false, API trả về lưới tam giác có độ chính xác cao nhất.

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 một lưới ưu tiên dạng quad.
- triangle: Tạo một lưới tam giác đã được giảm số lượng đ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. Số đa giác thực tế có thể lệch khỏi mục tiêu tùy theo độ 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
Bật giảm số lượng đ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 đặt thành true, Meshy cũng lưu trữ thêm một tệp GLB 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 (deprecated). 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 đố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: Buộc áp dụng đối xứng trong quá trình tạo.
Name
pose_mode
Type
string
mặc định ""
Description
Chỉ định pose mode 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ể.
Name
is_a_t_pose
Type
boolean
⚠ không dùng nữa
mặc định false
Description
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 ảnh đầu vào để có kết quả tốt hơn. Đặt thành false để giữ nguyên giao diện chính xác của ảnh đầu vào mà không xử lý phong cách nào.
Chỉ được hỗ trợ khi ai_model là meshy-6 hoặc latest.
Name
remove_lighting
Type
boolean
mặc định true
Description
Loại bỏ vùng sáng và bóng khỏi texture màu cơ bản, tạo ra kết quả sạch hơn và hoạt động tốt hơn trong các thiết lập ánh sáng tùy chỉnh.
Chỉ được hỗ trợ khi ai_model là meshy-6 hoặc latest.
Name
moderation
Type
boolean
mặc định false
Description
Khi đặt thành true, nội dung đầu vào sẽ tự động được sàng lọc để phát hiện 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 bước 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 cần bao gồm trong đầ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 tất tác vụ. Khi bỏ qua, tất cả các định dạng được hỗ trợ sẽ được bao gồm.
Các giá trị khả dụng: glb, obj, fbx, stl, usdz, 3mf
Khi bỏ qua, tất 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 đặt thành true, dịch vụ sử dụng thị giác AI để 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 độ (origin) 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 đặt thành true, tác vụ còn render thêm một phiên bản nền trong suốt (RGBA) của bản xem trước và trả về 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 đặt thành true, tác vụ còn render thêm bốn thumbnail theo các hướng chính (trước, phải, sau, trái) và trả về chúng trong thumbnail_urls ở phản hồi GET. Trường thumbnail_url hiện có không thay đổi và tiếp tục trỏ đến góc nhìn phía trước, vì vậy các client hiện có 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 bật.
Các giá trị khả dụng: bottom, center.

Trả về

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

Chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Nguyên nhân phổ biến:
- Thiếu tham số: Phải cung cấp 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 đúng 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).
- URL không truy cập được: Không thể tải xuống image_url (404 hoặc timeout).
- Data URI không hợp lệ: Chuỗi base64 bị sai định dạng.
- Tổ hợp tham số không hợp lệ: enable_pbr chỉ được hỗ trợ khi should_texture là true.
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 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>",
    "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 khi có id tác vụ hợp lệ. Tham khảo Đối tượng tác vụ Ảnh sang 3D để xem những 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 của tác vụ Ảnh sang 3D cần truy xuất.

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 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ả mô hình và dữ liệu liên quan. Hành động này không thể đảo ngượ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ả về

Trả về 200 OK khi thành công.

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

// Returns 200 Ok on success.

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 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à 50 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.

Trả về

Trả về danh sách được phân trang của Các đố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

Truyền phát tác vụ Ảnh sang 3D

endpoint này truyền phát 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
Mã định danh duy nhất của tác vụ Ảnh sang 3D cần truyền phát.

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 tác vụ Ảnh sang 3D

Đối tượng tác vụ Ả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 có các thuộc tính sau:

Thuộc tính

Name
id
Type
string
Description
Mã định danh duy nhất cho tác vụ. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp theo k cho id tác vụ như một 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 tác vụ Ảnh sang 3D. Giá trị là image-to-3d.
Name
model_urls
Type
object
Description
URL có thể tải xuống tới tệp mô hình 3D đã áp dụng texture được tạo bởi Meshy. Thuộc tính cho một định dạng sẽ bị lược bỏ nếu định dạng đó không được tạo, thay vì trả về một chuỗi rỗng.
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống tới tệp GLB.
- Name
  fbx
  Type
  string
  Description
  URL có thể tải xuống tới tệp FBX.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống tới tệp OBJ.
- Name
  usdz
  Type
  string
  Description
  URL có thể tải xuống tới tệp USDZ.
- Name
  mtl
  Type
  string
  Description
  URL có thể tải xuống tới 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 tới tệp STL.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống tới tệp 3MF. Chỉ có 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 tới đầu ra GLB gốc trước khi remesh.
  Chỉ khả dụng 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 tới ả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 tới phiên bản nền trong suốt (RGBA) của thumbnail_url. Chỉ có 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, trường này sẽ bị lược bỏ.
Name
thumbnail_urls
Type
object
Description
Các URL có thể tải xuống cho bốn ảnh thu nhỏ theo hướng nhìn chính của mô hình 3D được tạo. Mỗi giá trị là một URL đã ký tới 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 xử lý hàng loạt mà không cần tải xuống GLB.
Chỉ có khi tác vụ được tạo với multi_view_thumbnails: true và đã đạt SUCCEEDED. Các tác vụ cũ hơn và tác vụ được tạo mà không bật tùy chọn tham gia 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 dùng để hướng dẫn quá trình tạo texture.
Name
texture_image_url
Type
string
Description
URL có thể tải xuống tới hình ảnh texture đã được dùng để hướng dẫn quá trình tạo texture.
Name
progress
Type
integer
Description
Tiến độ của tác vụ. Nếu tác vụ chưa 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ụ bắt đầu, tính bằng mili giây. Nếu tác vụ 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, tuân theo tiêu chuẩn RFC 3339. Ví dụ, Thứ Sáu, ngày 1 tháng 9 năm 2023 12:00:00 PM GMT được biểu diễn là 1693569600000. Điều này áp dụng cho tất 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 mili giây.
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 mili giây.
Name
finished_at
Type
timestamp
Description
Dấu thời gian khi tác vụ hoàn tất, tính bằng mili giây. Nếu tác vụ chưa hoàn tất, 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 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 tới ảnh bản đồ màu cơ sở.
- Name
  metallic
  Type
  string
  Description
  URL có thể tải xuống tới ả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ị lược bỏ.
- Name
  normal
  Type
  string
  Description
  URL có thể tải xuống tới ả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ị lược bỏ.
- Name
  roughness
  Type
  string
  Description
  URL có thể tải xuống tới ảnh bản đồ roughness.
  Nếu tác vụ được tạo với enable_pbr: false, thuộc tính này sẽ bị lược bỏ.
- Name
  emission
  Type
  string
  Description
  URL có thể tải xuống tới ảnh bản đồ emission.
  Nếu tác vụ được tạo với enable_pbr: false, hoặc ai_model là meshy-5, thuộc tính này sẽ bị lược bỏ.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước.
Giá trị của trường này chỉ có ý nghĩa nếu 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 tham chiếu đầy đủ về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số tín dụng được tiêu thụ bởi tác vụ này. Có 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 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
}