API Ảnh sang 3D

Biến một hình ảnh thành mô hình 3D, có texture hoặc không có texture, theo định dạng bạn chọn. Gửi hình ảnh, hoặc sử dụng kết quả đầu ra của một tác vụ Văn bản sang ảnh hoặc Ảnh sang ảnh.

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

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

Tạo một tác vụ Ảnh sang 3D. Tác vụ chạy ngầm. Để biết thời gian thông thường của một tác vụ, xem Thời gian xử lý.

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

# Textured with Meshy N1 from the input image
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",
    "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_url. ID của một tác vụ Văn bản sang ảnh hoặc Ảnh sang ảnh mà bạn muốn dùng ảnh của nó làm đầu vào. Tác vụ đó phải do bạn tạo bằng 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
Bắt buộc trừ khi bạn gửi input_task_id. Ảnh để chuyển thành mô hình 3D, dưới dạng URL công khai hoặc data URI mã hóa base64, chẳng hạn 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.
Ảnh phải là tệp JPG, JPEG, PNG, hoặc WebP có dung lượng tối đa 20 MB, mỗi cạnh tối thiểu 32 pixel, và tối đa 178.956.970 pixel (chiều rộng × chiều cao).

Name
model_type
Type
string
mặc định standard
Description
Loại lưới 3D cần tạo.
Các giá trị khả dụng:
- standard: một lưới có độ chi tiết cao
- smart-topology: một lưới từ mô hình Smart Topology, bạn chọn bằng ai_model (meshy-t2 hoặc meshy-t2.5)
Với smart-topology, Meshy bỏ qua should_remesh, save_pre_remeshed_model, và decimation_mode, và chỉ chấp nhận topology: triangle.
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 phụ thuộc vào model_type.
Các mô hình tiêu chuẩn (model_type: standard):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (không dùng nữa): dùng meshy-7.1 thay thế
Các mô hình Smart Topology (model_type: smart-topology) tạo ra các tam giác, với số lượng mặt bạn có thể đặt bằng target_polycount:
- meshy-t2: topology sạch hơn và các phần tách rời tự nhiên
- meshy-t2.5 (mặc định): chi tiết sắc nét hơn cho các asset game
Name
geometry_resolution
Type
string
mặc định standard
Description
Giai đoạn tạo hình học.
Các giá trị khả dụng:
- standard
- 2k: chạy giai đoạn Ultra ở độ phân giải 2048³
- 4k: chạy giai đoạn Ultra ở độ phân giải 4096³, cho chi tiết bề mặt cao nhất
2k cần meshy-7.1, latest, hoặc meshy-7 đã không dùng nữa. 4k cần meshy-7.1 hoặc latest.
Name
ultra_mode
Type
boolean
⚠ không dùng nữa
mặc định false
Description
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
Có tạo texture hay không. true trả về mô hình có texture, và false bỏ qua việc tạo texture và trả về một 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, trong cùng một tác vụ. Bỏ qua tham số này để 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ừ các ảnh tham chiếu
- meshy-6-lite: Meshy 6 Lite, một texture 2K với chi phí thấp nhất
- meshy-6: Meshy 6, chỉ dùng làm mặc định cho ai_model: meshy-6
Mọi ai_model đều nhận meshy-7, meshy-n1, và meshy-6-lite. Một tùy chọn mà mô hình texture được chọn không hỗ trợ sẽ trả về 400. Với meshy-n1, một mô hình được tạo ra vượt quá 7.999.999 tam giác sẽ làm tác vụ thất bại, và Meshy hoàn lại tín dụng cho tác vụ đó. 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.
Xem Mô hình để biết mỗi mô hình texture làm gì và nên chọn cái nào.
Name
enable_pbr
Type
boolean
mặc định false
Description
Có tạo thêm bản đồ PBR (metallic, roughness, và normal) bên cạnh màu cơ bản hay không. true cần should_texture: true, và trả về 400 nếu should_texture: false. Với texture_model: meshy-n1, true trả về 400.
Mô hình texture Meshy 6 cũng tạo một bản đồ phát xạ (emission map), ngoại trừ ở texture_resolution: 8k.
Name
texture_resolution
Type
string
mặc định 2k
Description
Kích thước của texture màu cơ bản. Texture 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 đồ phát xạ.
Name
hd_texture
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Dùng 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 tham số này sẽ trả về 400.
Name
texture_image_url
Type
string
Description
Một ảnh định hướng texture, dưới dạng URL công khai hoặc data URI mã hóa base64, chẳng hạn 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 có dung lượng tối đa 20 MB, mỗi cạnh tối thiểu 32 pixel, và tối đa 178.956.970 pixel (chiều rộng × chiều cao).
Meshy chỉ dùng một trong hai tham số texture_prompt và texture_image_url để định hướng texture. Nếu bạn gửi cả hai, Meshy sẽ dùng texture_prompt. Để biết chi phí tín dụng khi tạo texture, xem Giá.
Với texture_model: meshy-n1, Meshy tạo texture từ ảnh này như góc nhìn phía trước, hoặc từ ảnh đầu vào nếu bạn bỏ qua tham số này.
Việc tạo texture từ một ảnh có thể không hoạt động tốt khi hình dạng của ảnh khác nhiều so với hình học của mô hình 3D.

Name
should_remesh
Type
boolean
mặc định true (meshy-6-lite), false (other models)
Description
Có chạy giai đoạn remesh hay không. Để có mô hình 3D chất lượng cao nhất, hãy đặt là 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 dạng tứ giác
- triangle: một lưới tam giác đã giảm mặt
Đầu ra của Smart Topology chỉ gồm tam giác, vì vậy quad với meshy-t2 hoặc meshy-t2.5 sẽ trả về 400. Với texture_model: meshy-n1, quad trả về 400 khi mô hình được remesh, điều mà meshy-6-lite thực hiện theo mặc định.
Name
decimation_mode
Type
integer
Description
Số lượng mặt thích ứng, theo cấp độ. Khi bạn đặt tham số 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 một tệp GLB của mô hình từ trước giai đoạn remesh hay không. Meshy trả về nó trong model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
Số lượng mặt mục tiêu cần đạt được. 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.
Tham số này áp dụng trong hai trường hợp riêng biệt:
- Remesh: Khi should_remesh là true trên một mô hình standard, Meshy giảm lưới xuống khoảng số lượng này. Nếu bạn đặt decimation_mode, Meshy sẽ dùng nó và bỏ qua target_polycount.
- Smart Topology: Khi model_type là smart-topology và ai_model là meshy-t2 hoặc meshy-t2.5, Meshy tạo mô hình với số lượng mặt này. Không có giai đoạn remesh nào chạy, và bạn không cần should_remesh.
Phạm vi và giá trị mặc định phụ thuộc vào từng trường hợp:
Trường hợp Phạm vi Mặc định
Remesh 100 đến 300000 30000
meshy-t2 100 đến 15000 4000
meshy-t2.5 100 đến 30000 15000
Một giá trị ngoài phạm vi sẽ trả về 400.

Trường hợp	Phạm vi	Mặc định
Remesh	`100` đến `300000`	`30000`
`meshy-t2`	`100` đến `15000`	`4000`
`meshy-t2.5`	`100` đến `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ không dùng nữa
mặc định auto
Description
Bỏ qua tham số này, vì nó không ảnh hưởng đến đầu ra. Các giá trị của nó từng kiểm soát tính đối xứng trong quá trình tạo:
- off: không có đối xứng
- auto: đối xứng được chọn từ 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ế cho mô hình được tạo.
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
Dùng pose_mode thay thế. Có tạo mô hình ở tư thế chữ A hoặc chữ T hay không.
Name
surface_mode
Type
string
⚠ không dùng nữa
Description
Dùng ai_model thay thế. Nó không ảnh hưởng đến đầu ra, vì phương pháp tạo mô hình mà nó chọn đã bị ngừng sử dụng.
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
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 nào.
Tham số này chỉ hoạt động với meshy-6, meshy-7.1, hoặc latest. Với meshy-6-lite hoặc model_type: smart-topology, nó 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ẽ sạch hơn và hoạt động tốt hơn dưới ánh sáng của riêng bạn.
Tham số này chỉ có hiệu lực với mô hình texture Meshy 6, và một mô hình texture không hỗ trợ nó sẽ trả về 400 cho giá trị true. Với model_type: smart-topology, hoặc với ai_model: meshy-6-lite và mô hình texture mặc định của nó, gửi tham số này sẽ trả về 400.
Name
moderation
Type
boolean
mặc định false
Description
Có kiểm duyệt nội dung có hại của các đầu vào này trước khi tạo hay không:
- image_url
- texture_image_url
- 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 không tạo tác vụ.
Name
target_formats
Type
string[]
Description
Các định dạng tệp 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ụ. Nếu bạn bỏ qua tham số này, Meshy sẽ tạo mọi định dạng trừ 3mf, mà bạn chỉ nhận được khi liệt kê nó.
Các giá trị khả dụng:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
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à đổi kích thước mô hình theo đó hay không. Meshy đặt gốc tọa độ ở phía dưới trừ khi bạn đặt origin_at.
Name
alpha_thumbnail
Type
boolean
mặc định false
Description
Có kết xuất thêm một 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 phía trước. Điều này thêm khoảng 5 giây vào tác vụ.

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.

Giá trị trả về

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

Các chế độ thất bạ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 cả image_url 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 và đã tạo ra đúng một ảnh.
- Định dạng ảnh không hợp lệ: Ảnh image_url không phải là tệp JPG, JPEG, PNG, hoặc WebP.
- URL không thể truy cập: Meshy không thể tải ảnh image_url, vì URL trả về 404 hoặc hết thời gian chờ.
- Ảnh quá lớn: Ảnh image_url hoặc texture_image_url vượt quá 20 MB.
- Kích thước ảnh không hợp lệ: Ảnh image_url hoặc texture_image_url có cạnh ngắn hơn 32 pixel, hoặc hơn 178.956.970 pixel (chiều rộng × chiều cao).
- 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 là true, và should_texture là false.
- Mô hình không được hỗ trợ cho Ultra: geometry_resolution là 2k hoặc 4k, với một ai_model không thể chạy chế độ đó.
- Mô hình không được hỗ trợ cho các tùy chọn ảnh: một trong các trường hợp sau:
  - image_enhancement được gửi cùng ai_model: "meshy-6-lite" hoặc model_type: "smart-topology".
  - remove_lighting được gửi cùng model_type: "smart-topology", hoặc cùng 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à một trong các giá trị khả dụng.
- Mô hình texture không khả dụng: texture_model là meshy-6 với một ai_model khác meshy-6. Hãy gửi meshy-7, meshy-n1, hoặc meshy-6-lite, hoặc bỏ qua tham số này.
- Tùy chọn không được hỗ trợ cho mô hình texture: Yêu cầu yêu cầu mô hình texture thực hiện một tùy chọn mà nó không hỗ trợ, chẳng hạn enable_pbr: true với meshy-n1 hoặc texture 4k với meshy-6-lite. Xem Mô hình.
Sửa yêu cầu, sau đó gửi lại. Xem Lỗi.
Name
401 - Unauthorized
Description
Khóa API bị thiếu hoặc không hợp lệ. Kiểm tra tiêu đề 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. Kiểm tra số dư tín dụng của bạn, sau đó thử lại.
- Gói miễn phí: Việc tạo tác vụ yêu cầu một gói trả phí. Nâng cấp gói của bạn trong cài đặt đăng ký, sau đó 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. Thay đổi đầu vào, sau đó 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. Kiểm tra ID tác vụ, sau đó 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ờ, sau đó thử lại. Xem Giới hạn tốc độ.

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

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

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

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": null,
  "consumed_credits": 30
}

Tham số

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

Giá trị trả về

Đối tượng tác vụ Ảnh sang 3D.

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

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

Xóa vĩnh viễn một tác vụ Ả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/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 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ụ

Xóa một tác vụ 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 đến khi tác vụ đạt trạng thái SUCCEEDED, FAILED, hoặc CANCELED, rồi mới xóa nó.

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.

Giá trị trả về

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

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

Danh sách tác vụ Ảnh sang 3D

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

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": 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ụ Ảnh sang 3D.

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

Truyền trực tiếp tác vụ Ảnh sang 3D

Truyền trực tiếp các cập nhật của tác vụ Ảnh sang 3D dưới dạng Server-Sent Events (SSE).

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.
// 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": "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": null,
  "consumed_credits": 30
}

Tham số

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

Giá trị trả về

Một luồng đối tượng tác vụ Ả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 đúng định dạng 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ị.

The Image to 3D task object

Một Image to 3D task object mô tả một lần tạo mô hình 3D từ ảnh. Nó lưu trạng thái, progress, và các tệp mô hình khi task thành công.

Thuộc tính

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": null,
  "consumed_credits": 30
}

Name
id
Type
string
Description
ID của task. Hãy coi nó như một chuỗi không minh bạch, và đừng phụ thuộc vào định dạng của nó.
Name
type
Type
string
Description
Loại task, luôn là image-to-3d.
Name
model_urls
Type
object
Description
URL tải xuống cho mô hình 3D đã tạo, mỗi URL ứng với một định dạng tệp. Một định dạng mà task 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 với 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 trước khi remesh. Chỉ xuất hiện khi bạn tạo task 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 3D. Khi thumbnail_urls xuất hiện, đây là cùng một ảnh với thumbnail_urls.front. Meshy giữ lại trường này để tương thích ngược.
Name
alpha_thumbnail_url
Type
string
Description
URL tải xuống cho một phiên bản của thumbnail_url có nền trong suốt (RGBA). Chỉ xuất hiện khi bạn tạo task với alpha_thumbnail: true và Meshy đã render ảnh 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 giá trị là một URL đã ký trỏ đến một ảnh PNG 512×512, được render với cùng vật liệu và ánh sáng như thumbnail_url. Dùng chúng để xem trước mô hình từ nhiều góc độ, ví dụ trong một pipeline xử lý hàng loạt, mà không cần tải GLB.
Chỉ xuất hiện khi bạn tạo task với multi_view_thumbnails: true và task đạt trạng thái SUCCEEDED. Các task được tạo không có multi_view_thumbnails: true sẽ không bao gồm trường này.
- Name
  front
  Type
  string
  Description
  Góc nhìn chính diện, ở 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
Đoạn prompt văn bản định hướng cho texture.
Name
texture_image_url
Type
string
Description
URL tải xuống cho ảnh định hướng cho texture.
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à task chạy, 2k hoặc 4k. Một task standard sẽ không bao gồm trường này.
Name
progress
Type
integer
Description
Phần task đã hoàn tất, tính theo phần trăm. Giá trị là 0 cho tới khi task bắt đầu và 100 khi task thành công.
Name
started_at
Type
timestamp
Description
Thời điểm task bắt đầu, tính bằng mili giây Unix. Giá trị là 0 cho tới khi task bắt đầu.
Name
created_at
Type
timestamp
Description
Thời điểm task đượ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 task hết hạn, tính bằng mili giây Unix.
Name
finished_at
Type
timestamp
Description
Thời điểm task kết thúc, tính bằng mili giây Unix. Giá trị là 0 cho tới khi task kết thúc.
Name
status
Type
string
Description
Trạng thái của task, là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, hoặc CANCELED.
Name
texture_urls
Type
array
Description
Các bản đồ texture mà task đã tạo, dưới dạng một mảng các object. Thường chứa một object, với các trường sau:
- Name
  base_color
  Type
  string
  Description
  URL tải xuống cho bản đồ màu nền (base color).
- Name
  metallic
  Type
  string
  Description
  URL tải xuống cho bản đồ metallic. Trường này không xuất hiện khi bạn tạo task với enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  URL tải xuống cho bản đồ normal. Trường này không xuất hiện khi bạn tạo task với enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  URL tải xuống cho bản đồ roughness. Trường này không xuất hiện khi bạn tạo task với enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  URL tải xuống cho bản đồ emission. Meshy chỉ bao gồm trường này khi bạn tạo task 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 task đứng trước task này trong hàng đợi. Giá trị này chỉ có ý nghĩa khi task đang ở trạng thái PENDING.
Name
task_error
Type
object
Description
Chi tiết lỗi khi task 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à task đã sử dụng. Xuất hiện khi trạng thái là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Giá trị là 0 đối với task FAILED, vì Meshy hoàn lại tín dụng khi task thất bại.