API Ảnh sang 3D

API Ảnh sang 3D 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ả những thông tin bạn cần để bắt đầu với API này.

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

Tạo một 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 nào được bao gồm trong đối tượng tác vụ Ảnh sang 3D.

Tham số

Chỉ cần một trong hai yếu tố input_task_id hoặc image_url là bắt buộc. Nếu cả hai đượ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ụ sinh ảnh đã hoàn thành và dữ liệu đầu ra có thể sử 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, nó phải được chạy thông qua API, có trạng thái là SUCCEEDED và tạo ra chính xác một hình ảnh.

Name
image_url
Type
string
Bắt buộc
Description
Cung cấp một hình ảnh để Meshy sử dụng trong việc 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 hình ả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 mã hoá base64 của ảnh. Ví dụ về một 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ị sẵn có:
- 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-t1 hoặc meshy-t2).
- lowpoly (không dùng nữa): Tạo lưới low-poly tối ưu hoá cho đa giác sạch hơn. Chúng tôi khuyên dùng smart-topology thay thế.
Khi smart-topology được chọn, topology, should_remesh, và save_pre_remeshed_model sẽ bị bỏ qua.
Khi lowpoly được chọn, 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ử dụng. Các giá trị sẵn có phụ thuộc vào model_type.
Tạo thông thường (model_type: standard):
- meshy-5, meshy-6, meshy-7, latest (Meshy 7)
Tạo Smart Topology (model_type: smart-topology):
- meshy-t2 (mặc định, khuyên dùng): mô hình Smart Topology — topology sạch hơn, các phần được tách rời một cách tự nhiên, đầu ra tam giác, và số lượng mặt mà bạn có thể đặt với target_polycount.
- meshy-t1: mô hình low-poly cũ; không hỗ trợ việc đặt số lượng mặt với target_polycount.
Name
ultra_mode
Type
boolean
mặc định false
Description
Kích hoạt tạo Ultra để có hình học độ trung thực cao hơn với chi tiết bề mặt tinh tế hơn.
Chỉ hỗ trợ khi ai_model là meshy-7 (hoặc latest).
Name
should_texture
Type
boolean
mặc định true
Description
Xác định có nên tạo texture hay không. Đặt nó là false để bỏ qua pha texture, cung cấp một lưới mà 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 (kim loại, độ gồ ghề, bản đồ normal) ngoài màu cơ bản. Một bản đồ phát sáng cũng được bao gồm khi ai_model là meshy-6, ngoại trừ tại texture_resolution: 8k. meshy-7 và latest không tạo ra bản đồ phát sáng.
Name
texture_resolution
Type
string
mặc định 2k
Description
Độ phân giải texture màu cơ bản. Một trong các giá trị 2k (2048×2048), 4k (4096×4096), hoặc 8k (8192×8192). Độ phân giải cao hơn nắm bắt chi tiết bề mặt nhiều hơn.
4k và 8k không có sẵn với ai_model: meshy-5. Tại 8k, không có bản đồ phát sáng được tạo ra.
Name
hd_texture
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Sử dụng texture_resolution thay thế — tương đương với texture_resolution: "4k". Khi cả hai được đặt, texture_resolution sẽ được ưu tiên.
Name
texture_prompt
Type
string
Description
Cung cấp một prompt văn bản để hướng dẫn quá trình texturing. 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 texturing. Hiện tại, chúng tôi hỗ trợ định dạng .jpg, .jpeg và .png.
Có hai cách để cung cấp hình ả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 mã hoá base64 của ảnh. Ví dụ về một Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Texturing ảnh có thể không hoạt động hiệu quả nếu có sự khác biệt hình học lớn 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 sử dụng để hướng dẫn quá trình texturing. Nếu cả hai tham số được cung cấp, thì texture_prompt sẽ được sử dụng làm mặc định để texturing mô hình. Texturing thông qua văn bản hoặc hình ảnh sẽ tiêu tốn 10 tín dụng mỗi tác vụ.

Name
should_remesh
Type
boolean
mặc định false (meshy-6, meshy-7), true (others)
Description
Điều khiển việc kích hoạt pha remesh. Để có mô hình chất lượng cao nhất, chúng tôi khuyên đặt should_remesh là 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ị sẵn có:
- quad: Tạo một lưới ưu tiên quadrilateral.
- triangle: Tạo một lưới tam giác được giảm thiểu.
Name
decimation_mode
Type
integer
Description
Kích hoạt giảm thiểu thích ứng bằng cách đặt mức polycount. Khi được đặt, target_polycount sẽ bị bỏ qua.
Các giá trị sẵn có:
- 1: Thích ứng — polycount siêu cao.
- 2: Thích ứng — polycount cao.
- 3: Thích ứng — polycount trung bình.
- 4: Thích ứng — polycount thấp.
Name
save_pre_remeshed_model
Type
boolean
mặc định false
Description
Khi được đặt thành true, Meshy cũng lưu trữ một tệp GLB bổ sung trước khi pha remesh hoàn tất.

Name
target_polycount
Type
integer
Description
Số lượng đa giác (mặt) mục tiêu trong đầu ra. Số lượng thực tế có thể sai lệch so với mục tiêu tuỳ 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ô hình standard. Lưới sẽ được làm lại (giảm thiểu) để đạt gần số lượng này. Phạm vi từ 100 đến 300.000, mặc định 30.000. Nếu decimation_mode được đặt, nó sẽ được ưu tiên và target_polycount bị bỏ qua.
- Smart Topology — với model_type: smart-topology và ai_model: meshy-t2. Mô hình được tạo ra trực tiếp với số mặt này; không diễn ra remesh và should_remesh không bắt buộc. Phạm vi từ 100 đến 15.000, mặc định 4.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 điều khiển 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: Xác định và áp dụng đối xứng một cách tự động dựa trên hình học đầu vào.
- on: Áp đặt đối xứng trong quá trình tạo.
Name
pose_mode
Type
string
mặc định ""
Description
Chỉ định chế độ tạo dáng cho mô hình được tạo.
Các giá trị sẵn có:
- a-pose: Tạo mô hình trong tư thế A.
- t-pose: Tạo mô hình trong tư thế T.
- "" (chuỗi trố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
Sử dụng pose_mode thay. Có hay không tạo mô hình trong tư thế A/T.
Name
image_enhancement
Type
boolean
mặc định true
Description
Tối ưu hình ảnh đầu vào để có kết quả tốt hơn. Đặt thành false để giữ nguyên diện mạo bôglomerankió một cách chính xác, mà không qua bất kỳ xử lý phong cách nào.
Chỉ hỗ trợ khi ai_model là meshy-6, meshy-7, hoặc latest.
Name
remove_lighting
Type
boolean
mặc định true
Description
Loại bỏ ánh sáng và bóng từ texture màu cơ bản, tạo ra kết quả sạch hơn và hoạt động tốt hơn dưới điều kiện ánh sáng tuỳ chỉnh.
Chỉ hỗ trợ khi ai_model là meshy-6.
Name
moderation
Type
boolean
mặc định false
Description
Khi đặt thành true, nội dung đầu vào sẽ tự động được kiểm duyệt để phát hiện các 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ến hành đến quá trình tạo.
Nội dung từ các đầu vào image_url, texture_image_url, và texture_prompt sẽ được kiểm duyệt.
Name
target_formats
Type
string[]
Description
Xác định các định dạng tệp 3D nào sẽ được bao gồm trong đầu ra. Chỉ có các định dạng được yêu cầu sẽ được tạo và trả về, điều này có thể giảm thời gian hoàn thành tác vụ. Khi không có giá trị này, tất cả các định dạng được hỗ trợ sẽ được bao gồm.
Các giá trị sẵn có: glb, obj, fbx, stl, usdz, 3mf
Khi không có giá trị này, tất cả các định dạng 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 tầm nhìn 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 cho phù hợp. Gốc tọa độ sẽ mặc định là bottom trừ khi origin_at được đặt rõ ràng.
Name
alpha_thumbnail
Type
boolean
mặc định false
Description
Khi đặt thành true, tác vụ cũng tạo ra một phiên bản hình ảnh thu nhỏ (RGBA) có nền trong suốt và trả về nó dưới alpha_thumbnail_url trên phản hồi GET. Trường thumbnail_url hiện tại không bị thay đổi.
Name
multi_view_thumbnails
Type
boolean
mặc định false
Description
Khi đặt thành true, tác vụ thêm nữa tạo ra bốn hình ảnh thu nhỏ xem từ bốn góc (trước, phải, sau, trái) và trả về chúng dưới thumbnail_urls trên phản hồi GET. Trường thumbnail_url hiện có không bị thay đổi và tiếp tục chỉ vào hình ảnh phía trước, vì vậy khách hàng hiện hành không bị ảnh hưởng.
Thêm khoảng 3 giây vào độ trễ tác vụ.

Chỉ áp dụng khi auto_size = true

Name
origin_at
Type
string
mặc định bottom
Description
Vị trí gốc khi auto_size được bật.
Các giá trị sẵn có: bottom, center.

Kết quả

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

Các chế độ thất bại

Name
400 - Bad Request
Description
Yêu cầu không chấp nhận được. Các nguyên nhân thông thường:
- Thiếu tham số: Phải cung cấp hoặc 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 SUCCEEDED tạo ra đúng một hình ảnh.
- Định dạng ảnh không hợp lệ: image_url cung cấp không phải là định dạng được hỗ trợ (.jpg, .jpeg, .png).
- URL không thể truy cập: image_url không thể tải xuống (404 hoặc timeout).
- 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.
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
Tín dụng khô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

# Yêu cầu đơn giản với các tham số bắt buộc
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>"
  }'

# Với remesh, PBR, và tư thế A
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

Lấy một Tác vụ Ảnh sang 3D

Endpoint này cho phép bạn lấy 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
Định danh duy nhất cho tác vụ Ảnh sang 3D cần lấy.

Kết quả

Phản hồi chứa đối tượng tác vụ Ảnh sang 3D. Kiểm tra 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 toàn bộ 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.

Kết quả

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

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

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 lấy danh sách các tác vụ Ảnh sang 3D.

Tham số

Thuộc tính tuỳ chọn

Name
page_num
Type
integer
Description
Số trang cho phân trang. Bắt đầu từ 1 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. Các giá trị sẵn có:
- +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.

Kết quả

Trả về một danh sách có phân trang 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=***",
      "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
  }
]

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

Truyền một Tác vụ Ảnh sang 3D

Endpoint này truyền các cập nhật theo thời gian thực cho một tác vụ Ảnh sang 3D bằng cách sử dụng Server-Sent Events (SSE).

Tham số

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

Kết quả

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 cần thiết progress và status.

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

// Ví dụ về sự kiện lỗi
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Ví dụ về sự kiện thông báo minh họa tiến độ tác vụ.
// Đối với các tác vụ PENDING hoặc IN_PROGRESS, luồng phản hồi sẽ không bao gồm tất cả các trường.
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ột mô hình 3D từ đầu vào hình ảnh. Đối tượng có các thuộc tính sau:

Thuộc tính

Name
id
Type
string
Description
Định danh duy nhất cho tác vụ. Mặc dù chúng tôi sử dụng UUID k-sắp xếp cho các id tác vụ như là chi tiết triển khai, bạn không nên đưa ra bất kỳ giả định nào về định dạng của id.
Name
type
Type
string
Description
Loại của tác vụ Ảnh sang 3D. Giá trị là image-to-3d.
Name
model_urls
Type
object
Description
URL có thể tải xuống đến tệp mô hình 3D được tạo ra có texture 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 thay vì trả về chuỗi trống.
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống đến tệp GLB.
- Name
  fbx
  Type
  string
  Description
  URL có thể tải xuống đến tệp FBX.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống đến tệp OBJ.
- Name
  usdz
  Type
  string
  Description
  URL có thể tải xuống đến tệp USDZ.
- Name
  mtl
  Type
  string
  Description
  URL có thể tải xuống đến tệp MTL, được trả về cùng với xuất OBJ khi có texture.
- Name
  stl
  Type
  string
  Description
  URL có thể tải xuống đến tệp STL.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống đến tệp 3MF. Chỉ có khi 3mf được yêu cầu qua target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  URL có thể tải xuống đến đầu ra GLB gốc trước khi remesh.
  Chỉ có khi tác vụ được tạo với cả should_remesh: true và save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL có thể tải xuống đến ảnh thu nhỏ của tệp mô hình. Tương đương với thumbnail_urls.front khi có, giữ lại để tương thích ngược.
Name
alpha_thumbnail_url
Type
string
Description
URL có thể tải xuống đến phiên bản có 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à hình thu nhỏ trong suốt đã được tạo thành công; nếu không trường này sẽ bị bỏ qua.
Name
thumbnail_urls
Type
object
Description
URL có thể tải xuống cho bốn hình thu nhỏ xem từ bốn góc của mô hình 3D được tạo. Mỗi giá trị là một URL có chữ ký điểm đến một PNG 512×512 được render với cùng chất liệu và ánh sáng với thumbnail_url. Hữu ích cho việc xem trước mô hình từ nhiều góc trong các dây chuyền xử lý 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à các tác vụ được tạo mà không chọn tham gia sẽ không bao gồm trường này.
- Name
  front
  Type
  string
  Description
  View phía trước, xoay trục thẳng đứng 0° (khớp với thumbnail_url).
- Name
  right
  Type
  string
  Description
  View bên phải, xoay 90°.
- Name
  back
  Type
  string
  Description
  View phía sau, xoay 180°.
- Name
  left
  Type
  string
  Description
  View bên trái, xoay 270°.
Name
texture_prompt
Type
string
Description
Prompt văn bản được sử dụng để hướng dẫn quá trình texturing.
Name
texture_image_url
Type
string
Description
URL có thể tải xuống đến ảnh texture đã được sử dụng để hướng dẫn quá trình texturing.
Name
ultra_mode
Type
boolean
Description
Phản ánh giá trị ultra_mode mà tác vụ được tạo. Chỉ có mặt cho các tác vụ meshy-7 (hoặc latest) có đặt rõ ràng ultra_mode; nếu không, trường này sẽ bị bỏ qua.
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. Một khi tác vụ đã hoàn thành thành công, nó sẽ thành 100.
Name
started_at
Type
timestamp
Description
Dấu thời gian khi tác vụ được bắt đầu, tính bằng 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 đại diện cho số mili giây đã trôi qua kể từ ngày 1 tháng 1 năm 1970 theo giờ 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 giờ sáng GMT được biểu diễn là 1693569600000. Điều này áp dụng cho tất cả các dấu thời gian trong Meshy API.
Name
created_at
Type
timestamp
Description
Dấu thời gian khi tác vụ được tạo, tính bằng 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 thành, tính bằng mili giây. Nếu tác vụ chưa hoàn thành, thuộc tính này sẽ là 0.
Name
status
Type
string
Description
Trạng thái của tác vụ. Các giá trị có thể là một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Một mảng các đối tượng URL texture được tạo ra từ tác vụ. Thông thường nó chỉ chứa một đối tượng URL texture. Mỗi URL texture có các thuộc tính sau:
- Name
  base_color
  Type
  string
  Description
  URL có thể tải xuống đến ảnh bản đồ màu cơ bản.
- Name
  metallic
  Type
  string
  Description
  URL có thể tải xuống đến ảnh bản đồ kim loại.
  Nếu tác vụ được tạo với enable_pbr: false, thuộc tính này sẽ bị bỏ qua.
- Name
  normal
  Type
  string
  Description
  URL có thể tải xuống đến ảnh bản đồ normal.
  Nếu tác vụ được tạo với enable_pbr: false, thuộc tính này sẽ bị bỏ qua.
- Name
  roughness
  Type
  string
  Description
  URL có thể tải xuống đến ảnh bản đồ độ gồ ghề.
  Nếu tác vụ được tạo với enable_pbr: false, thuộc tính này sẽ bị bỏ qua.
- Name
  emission
  Type
  string
  Description
  URL có thể tải xuống đến ảnh bản đồ phát sáng.
  Nếu tác vụ được tạo với enable_pbr: false, hoặc ai_model là meshy-5, meshy-7, hoặc latest, thuộc tính này sẽ bị bỏ qua.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ phía trước.
Giá trị của trường này chỉ có ý nghĩa khi trạng thái tác vụ là PENDING.
Name
task_error
Type
object
Description
Chi tiết lỗi cho các tác vụ thất bại. Xem Lỗi để tham khảo đầy đủ về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng tiêu thụ bởi tác vụ này. Hiện diện khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các tác vụ FAILED (tín dụng được hoàn lại khi thất bại).

Example 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
}