API Văn bản sang 3D

Tạo các mô hình 3D từ các gợi ý văn bản ngay trong ứng dụng của riêng bạn.

Văn bản sang 3D hoạt động theo hai bước. Đầu tiên, tạo một tác vụ preview (mode: "preview") để tạo một lưới 3D không có texture, nhờ đó bạn có thể kiểm tra hình dạng. Sau đó, gửi ID của tác vụ preview thành công đến một tác vụ refine (mode: "refine") để tạo texture cho lưới. Cả hai bước đều sử dụng cùng một endpoint.

POST/openapi/v2/text-to-3d

Create a Text to 3D preview task

Tạo một tác vụ xem trước Văn bản sang 3D, tạo ra một lưới 3D chưa có texture (chỉ có hình học) từ một prompt văn bản. Đây là bước đầu tiên trong quy trình hai bước. Sau khi bước xem trước thành công, hãy gửi ID tác vụ đó trong một tác vụ refine để thêm texture cho lưới. Xem Tạo một tác vụ refine Văn bản sang 3D. Để biết đầy đủ schema phản hồi, xem Đối tượng tác vụ Văn bản sang 3D.

Tác vụ chạy ở chế độ nền. Để biết thời gian một tác vụ thường mất bao lâu, xem Thời gian xử lý.

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

Tham số

Name
mode
Type
string
Bắt buộc
Description
Bước trong quy trình hai bước. Gửi preview để tạo một tác vụ xem trước.
Name
prompt
Type
string
Bắt buộc
Description
Văn bản mô tả đối tượng cần tạo, tối đa 800 ký tự. Văn bản dài hơn sẽ trả về 400.
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 3D chi tiết cao
- smart-topology: một lưới Smart Topology. Chọn mô hình bằng ai_model (meshy-t2 hoặc meshy-t2.5).
Với smart-topology, Meshy bỏ qua should_remesh 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 standard (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 gửi meshy-7.1 thay thế
Các mô hình Smart Topology (model_type: smart-topology):
- meshy-t2: topology sạch hơn, các bộ phận được tách riêng theo cách tự nhiên, đầu ra dạng tam giác, và số lượng mặt bạn đặt bằng target_polycount
- meshy-t2.5 (mặc định): chi tiết sắc nét hơn cho các asset game, đầu ra dạng tam giác, và số lượng mặt bạn đặt bằng target_polycount
Name
geometry_resolution
Type
string
mặc định standard
Description
Lượt tạo hình học. Chỉ áp dụng cho các tác vụ xem trước. Một tác vụ refine dùng tham số này sẽ trả về 400.
Các giá trị khả dụng:
- standard
- 2k: chạy lượt Ultra ở độ phân giải 2048³
- 4k: chạy lượt Ultra ở độ phân giải 4096³, cho chi tiết bề mặt tinh tế hơn
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. Các mô hình khác sẽ trả về 400.
Name
ultra_mode
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy gửi geometry_resolution thay thế. ultra_mode: true tương đương với geometry_resolution: "2k".
Name
should_remesh
Type
boolean
mặc định true (meshy-6-lite), false (other models)
Description
Có remesh mô hình sau khi tạo hay không. Để có mô hình 3D chất lượng cao nhất, hãy gửi 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 gồm mặt tứ giác
- triangle: một lưới tam giác đã được giảm mặt
Đầu ra của Smart Topology chỉ gồm tam giác. Gửi quad cùng với ai_model là meshy-t2 hoặc meshy-t2.5 sẽ trả về 400.
Name
decimation_mode
Type
integer
Description
Số lượng mặt thích ứng, theo cấp độ. Khi bạn đặt tham số này, Meshy sẽ bỏ qua target_polycount.
Các giá trị khả dụng:
- 1: ultra
- 2: high
- 3: medium
- 4: low

Name
target_polycount
Type
integer
Description
Số lượng mặt mục tiêu. Kết quả thực tế có thể khác với mục tiêu, tùy thuộc vào hình học. Tham số này áp dụng trong hai trường hợp riêng biệt:
- Remesh: với should_remesh: true trên một mô hình standard. Meshy remesh (giảm mặt) 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: với model_type: smart-topology và ai_model là meshy-t2 hoặc meshy-t2.5. Meshy tạo mô hình trực tiếp với số lượng mặt này. Không có bước remesh nào chạy, và bạn không cần should_remesh.
Bảng sau đây cho thấy phạm vi và giá trị mặc định cho 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ị nằm 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
Hãy bỏ qua tham số này. Tham số này không ảnh hưởng đến đầu ra.
Các giá trị khả dụng:
- off: tắt tính đối xứng
- auto: á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
Tư thế của mô hình được tạo ra.
Các giá trị khả dụng:
- a-pose: tư thế chữ A
- t-pose: tư thế chữ T
- "" (chuỗi rỗng): không có tư thế cụ thể
Name
is_a_t_pose
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy gửi pose_mode thay thế. Có tạo mô hình ở tư thế chữ A hay tư thế chữ T hay không.
Name
art_style
Type
string
⚠ không dùng nữa
mặc định realistic
Description
Hãy bỏ qua tham số này. Meshy sẽ bỏ qua nó.
Name
moderation
Type
boolean
mặc định false
Description
Có kiểm duyệt prompt để tìm nội dung có hại trước khi tạo hay không. Nếu Meshy phát hiện nội dung có hại, yêu cầu sẽ trả về 400 và Meshy sẽ không tạo tác vụ.
Name
target_formats
Type
string[]
Description
Các định dạng tệp cần tạo. Meshy chỉ tạo và trả về các định dạng này, đ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 ngoại trừ 3mf, định dạng mà nó chỉ tạo khi bạn yêu cầu.
Các giá trị khả dụng:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
mặc định false
Description
Có đồng thời render 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
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 AI thị giác và đổi kích thước mô hình cho phù hợp hay không. Meshy đặt gốc tọa độ ở dưới cùng trừ khi bạn đặt origin_at.

Chỉ áp dụng khi auto_size = true

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

Giá trị trả về

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

Các chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không thể chạy được. Thông báo lỗi cho biết vấn đề đã phát hiện. Ví dụ:
- Thiếu tham số: Thiếu một tham số bắt buộc, chẳng hạn như prompt hoặc mode.
- Prompt quá dài: prompt vượt quá giới hạn ký tự.
- Mô hình không hỗ trợ Ultra: geometry_resolution là 2k hoặc 4k, với một ai_model không thể chạy chế độ đó.
Hãy 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ệ. Hãy kiểm tra header Authorization.
Name
402 - Payment Required
Description
Ví dụ:
- Không đủ tín dụng: Tài khoản không có đủ tín dụng cho tác vụ này, hoặc tài khoản đã đạt đến giới hạn tín dụng. Hãy kiểm tra số dư tín dụng của bạn, sau đó thử lại.
- Gói miễn phí: Việc tạo một tác vụ yêu cầu gói trả phí. Hãy nâng cấp gói của bạn trong cài đặt đăng ký, sau đó thử lại.
Name
403 - Forbidden
Description
Kiểm duyệt nội dung đã chặn prompt hoặc một hình ảnh đầu vào. Hãy thay đổi đầu vào, sau đó thử lại.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ. Hãy đợi, sau đó thử lại. Xem Giới hạn tốc độ.

POST/openapi/v2/text-to-3d

Tạo một tác vụ refine Văn bản sang 3D

Tạo một tác vụ refine Văn bản sang 3D, tạo texture cho lưới của một tác vụ preview đã hoàn thành. Gửi ID của một tác vụ preview thành công dưới dạng preview_task_id. Xem Tạo một tác vụ preview Văn bản sang 3D. Đây là bước thứ hai trong quy trình hai bước.

Tác vụ chạy ở chế độ nền. Để biết thời gian thường mất cho một tác vụ, xem Thời gian xử lý.

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

# Refine with Meshy N1 from the preview's stored reference image
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "ai_model": "meshy-n1"
}'

Response

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

Tham số

Name
mode
Type
string
Bắt buộc
Description
Bước trong quy trình hai bước. Gửi refine để tạo một tác vụ refine.
Name
preview_task_id
Type
string
Bắt buộc
Description
ID của tác vụ preview cần tạo texture. Tác vụ preview phải có trạng thái SUCCEEDED.
Name
enable_pbr
Type
boolean
mặc định false
Description
Có tạo thêm bản đồ PBR (metallic, roughness và normal) cùng với màu nền hay không.
Với ai_model là meshy-6, Meshy cũng tạo bản đồ emission, ngoại trừ ở texture_resolution: 8k. meshy-6-lite, meshy-7, meshy-7.1 và latest không tạo bản đồ emission. Việc refine một preview meshy-t2 hoặc meshy-t2.5 không đặt ai_model cũng vậy. Với ai_model: meshy-n1, giá trị true trả về 400.
Name
texture_resolution
Type
string
mặc định 2k
Description
Độ phân giải của texture màu nền. Chỉ áp dụng cho các tác vụ refine. Một tác vụ preview có tham số này sẽ trả về 400.
Các giá trị khả dụng:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Độ phân giải cao hơn ghi lại nhiều chi tiết bề mặt hơn. 4k và 8k cần ai_model là meshy-6, meshy-7.1 hoặc latest. Với meshy-n1, chúng trả về 400. Ở 8k, Meshy không tạo bản đồ emission.
Name
hd_texture
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy gửi texture_resolution thay thế. hd_texture: true tương đương với texture_resolution: "4k". Nếu bạn gửi cả hai, Meshy sẽ dùng texture_resolution.
Name
texture_prompt
Type
string
Description
Văn bản hướng dẫn việc tạo texture, tối đa 800 ký tự. Văn bản dài hơn sẽ trả về 400. Gửi texture_prompt hoặc texture_image_url, không gửi cả hai. Nếu bạn gửi cả hai, Meshy sẽ dùng texture_prompt. Với ai_model: meshy-n1, việc gửi tham số này sẽ trả về 400.
Name
texture_image_url
Type
string
Description
Một hình ảnh 2D hướng dẫn việc tạo texture, dưới dạng URL công khai hoặc data URI mã hóa base64, chẳng hạn như data:image/jpeg;base64,<dữ liệu hình ảnh mã hóa base64 của bạn>.
Hình ảnh phải là tệp .jpg, .jpeg, .png hoặc .webp có dung lượng tối đa 20 MB, kích thước tối thiểu 32 pixel mỗi cạnh và tối đa 178.956.970 pixel (chiều rộng × chiều cao).
Với ai_model: meshy-n1, Meshy tạo texture từ hình ảnh này như góc nhìn chính diện.
Việc tạo texture từ hình ảnh có thể không hiệu quả khi hình dạng trong hình ảnh khác biệt nhiều so với mô hình.
Name
ai_model
Type
string
mặc định inherited from the preview task
Description
Mô hình AI tạo texture cho lưới.
Các giá trị khả dụng:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-n1: texture màu nền 2K chỉ từ một hình ảnh tham chiếu. Không có prompt văn bản, không có bản đồ PBR, không có 4K hay 8K.
- meshy-7 (không dùng nữa): hãy gửi meshy-7.1 thay thế
Bỏ trống để dùng mô hình của tác vụ preview, nhờ đó preview và refine của nó chạy trên cùng một mô hình từ đầu đến cuối. Gửi một giá trị để ghi đè lên nó. Một latest tường minh sẽ được phân giải theo cùng cách như trên tác vụ preview, do đó một preview latest và refine latest của nó luôn dùng cùng một mô hình texture.
Với meshy-n1, Meshy tạo texture từ texture_image_url. Nếu không có, Meshy dùng hình ảnh tham chiếu mà một preview meshy-7.1 hoặc latest lưu trữ. Bất kỳ preview nào khác sẽ trả về 400 trừ khi bạn gửi texture_image_url. Preview có thể có tối đa 7.999.999 tam giác. Một preview đã được remesh thành quad sẽ trả về 400.
Name
moderation
Type
boolean
mặc định false
Description
Có sàng lọc texture_prompt và texture_image_url để tìm nội dung có hại trước khi tạo hay không. Nếu Meshy phát hiện nội dung có hại, yêu cầu sẽ trả về 400 và Meshy sẽ không tạo tác vụ.
Name
remove_lighting
Type
boolean
mặc định true
Description
Có loại bỏ các vùng sáng và bóng đổ khỏi texture màu nền hay không. Kết quả sạch hơn sẽ phù hợp hơn khi sử dụng á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 nhưng bỏ qua tham số này, và việc refine một preview meshy-t2 hoặc meshy-t2.5 không đặt ai_model cũng vậy. Việc gửi tham số này với meshy-6-lite sẽ trả về 400. Với meshy-n1, giá trị true trả về 400.
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 này, điều này có thể rút ngắn thời gian của tác vụ. Nếu bạn bỏ trống tham số này, Meshy sẽ tạo mọi định dạng trừ 3mf, định dạng này chỉ được tạo khi bạn yêu cầu.
Các giá trị khả dụng:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
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
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 AI vision và đổi kích thước mô hình theo chiều cao đó hay không. Meshy đặt gốc tọa độ ở đáy trừ khi bạn thiết lập origin_at.

Chỉ áp dụng khi auto_size = true

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

Kết quả trả về

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

Các chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không thể chạy. Thông báo lỗi cho biết vấn đề mà nó phát hiện. Ví dụ:
- Invalid task ID: preview_task_id không hợp lệ, hoặc không khớp với bất kỳ tác vụ preview nào của bạn.
- Task not ready: Tác vụ preview chưa hoàn thành thành công.
- Model mismatch: Mô hình AI của tác vụ preview không hoạt động với mô hình refine được yêu cầu.
- Unsupported model for remove_lighting: remove_lighting đã được gửi kèm ai_model: "meshy-6-lite".
- No reference image for Meshy N1: ai_model: meshy-n1 đã được gửi mà không có texture_image_url, và preview không có hình ảnh tham chiếu nào mà Meshy N1 có thể sử dụng. Hãy gửi texture_image_url.
- Quad preview for Meshy N1: ai_model: meshy-n1 đã được gửi cho một preview đã remesh thành quad. Hãy refine nó với một ai_model khác.
- Too many triangles for Meshy N1: Với ai_model: meshy-n1, preview có nhiều hơn 7.999.999 tam giác. Hãy refine nó với một ai_model khác.
- Unsupported option for Meshy N1: ai_model: meshy-n1 đã được gửi kèm một trong các tùy chọn sau:
  - texture_prompt
  - enable_pbr: true
  - texture_resolution là 4k hoặc 8k
  - hd_texture: true mà không có texture_resolution
  - remove_lighting: true
Hãy sửa yêu cầu rồi gửi lại. Xem Lỗi.
Name
401 - Unauthorized
Description
Khóa API bị thiếu hoặc không hợp lệ. Hãy kiểm tra header Authorization.
Name
402 - Payment Required
Description
Ví dụ:
- Insufficient credits: Tài khoản không có đủ tín dụng cho tác vụ này, hoặc tài khoản đã đạt giới hạn tín dụng. Hãy kiểm tra số dư tín dụng của bạn, rồi thử lại.
- Free plan: Việc tạo tác vụ yêu cầu một gói trả phí. Hãy nâng cấp gói của bạn trong cài đặt đăng ký, rồi thử lại.
Name
403 - Forbidden
Description
Kiểm duyệt nội dung đã chặn prompt hoặc một hình ảnh đầu vào. Hãy thay đổi đầu vào, rồi thử lại.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ. Hãy đợi, rồi thử lại. Xem Giới hạn tốc độ.

GET/openapi/v2/text-to-3d/:id

Lấy một tác vụ Văn bản sang 3D

Trả về một tác vụ Văn bản sang 3D theo ID của nó. Hoạt động cho cả tác vụ preview và refine.

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 20
}

Tham số

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

Giá trị trả về

Đối tượng tác vụ Văn bản sang 3D.

Ví dụ

Bảng sau đây hiển thị một mô hình mẫu cho mỗi mode.

Mode	Mô hình mẫu
Preview
Refine

DELETE/openapi/v2/text-to-3d/:id

Xóa một tác vụ Văn bản sang 3D

Xóa vĩnh viễn một tác vụ Văn bản sang 3D, bao gồm 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/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Tham số đường dẫn

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

Trạng thái tác vụ

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

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

Giá trị trả về

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

GET/openapi/v2/text-to-3d

Liệt kê tác vụ Văn bản sang 3D

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

Request

GET

/openapi/v2/text-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 20
  }
]

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

Trả về

Một danh sách phân trang gồm các đối tượng tác vụ Văn bản sang 3D.

GET/openapi/v2/text-to-3d/:id/stream

Truyền trực tiếp (stream) tác vụ Văn bản sang 3D

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

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v2/text-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",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": 20
}

Tham số

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

Giá trị trả về

Một luồng đối tượng tác vụ Văn bản sang 3D dưới dạng Server-Sent Events.

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

Đối tượng tác vụ Văn bản sang 3D

Đối tượng tác vụ Văn bản sang 3D mô tả một tác vụ tạo mô hình 3D từ một prompt văn bản. Nó lưu trữ trạng thái, progress, và các tệp mô hình khi tác vụ thành công. Văn bản sang 3D có hai giai đoạn, preview và refine. Một tác vụ preview tạo ra một mô hình 3D chỉ có lưới, và một tác vụ refine tạo ra một mô hình 3D có texture từ kết quả của preview.

Thuộc tính

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": 20
}

Name
id
Type
string
Description
ID của tác vụ. Hãy coi nó như một chuỗi không minh bạch (opaque string), và đừng phụ thuộc vào định dạng của nó.
Name
type
Type
string
Description
Loại tác vụ, text-to-3d-preview cho tác vụ preview hoặc text-to-3d-refine cho tác vụ refine.
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à tác vụ không tạo ra sẽ không có khóa, thay vì có một chuỗi rỗng.
- Name
  glb
  Type
  string
  Description
  Tệp GLB.
- Name
  fbx
  Type
  string
  Description
  Tệp FBX.
- Name
  usdz
  Type
  string
  Description
  Tệp USDZ.
- Name
  obj
  Type
  string
  Description
  Tệp OBJ.
- Name
  mtl
  Type
  string
  Description
  Tệp MTL.
- 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
prompt
Type
string
Description
prompt bạn đã gửi để tạo tác vụ, không thay đổi.
Name
texture_prompt
Type
string
Description
Prompt văn bản bạn đã gửi để định hướng việc tạo texture ở giai đoạn refine.
Name
ultra_mode
Type
boolean
⚠ không dùng nữa
Description
Hãy dùng geometry_resolution thay thế.
Name
geometry_resolution
Type
string
Description
Cấp độ Ultra mà tác vụ preview đã chạy, 2k hoặc 4k. Trường này không xuất hiện đối với standard.
Name
texture_image_url
Type
string
Description
URL tải xuống cho hình ảnh bạn đã gửi để định hướng việc tạo texture.
Name
thumbnail_url
Type
string
Description
URL tải xuống cho ảnh thu nhỏ của mô hình 3D.
Name
alpha_thumbnail_url
Type
string
Description
URL tải xuống cho phiên bản thumbnail_url có nền trong suốt (RGBA). Chỉ xuất hiện khi bạn tạo tác vụ với alpha_thumbnail: true và Meshy đã render bản xem trước trong suốt.
Name
progress
Type
integer
Description
Tác vụ đã hoàn thành bao nhiêu, tính theo phần trăm. Giá trị là 0 cho đến khi tác vụ bắt đầu và 100 khi nó thành công.
Name
started_at
Type
timestamp
Description
Thời điểm tác vụ bắt đầu, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ bắt đầu.
Name
created_at
Type
timestamp
Description
Thời điểm tác vụ được tạo, tính bằng mili giây Unix.
Name
finished_at
Type
timestamp
Description
Thời điểm tác vụ kết thúc, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ kết thúc.
Name
status
Type
string
Description
Trạng thái của tác vụ, là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, hoặc CANCELED.
Name
texture_urls
Type
array
Description
URL tải xuống cho các bản đồ texture đã tạo, dưới dạng một mảng đối tượng. Thường chỉ có một đối tượng. Mỗi đối tượng có các trường sau:
- Name
  base_color
  Type
  string
  Description
  Bản đồ màu nền (base color).
- Name
  metallic
  Type
  string
  Description
  Bản đồ metallic. Không xuất hiện khi bạn tạo tác vụ với enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  Bản đồ normal. Không xuất hiện khi bạn tạo tác vụ với enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  Bản đồ roughness. Không xuất hiện khi bạn tạo tác vụ với enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  Bản đồ emission. Không xuất hiện trong bất kỳ trường hợp nào sau đây:
  
  Bạn tạo tác vụ với enable_pbr: false.
  
  ai_model là meshy-6-lite, meshy-7, meshy-7.1, hoặc latest.
  
  texture_resolution là 8k.
  
  Tác vụ refine một bản preview meshy-t2 hoặc meshy-t2.5 mà không đặt ai_model.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước tác vụ này trong hàng đợi. Giá trị này chỉ có ý nghĩa khi tác vụ đang ở trạng thái PENDING.
Name
task_error
Type
object
Description
Thông tin chi tiết về lỗi khi tác vụ thất bại. Giá trị là null trừ khi trạng thái là FAILED. Xem Lỗi.
Name
consumed_credits
Type
integer
Description
Số tín dụng mà tác vụ đã sử dụng. Xuất hiện khi trạng thái là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Giá trị là 0 đối với tác vụ FAILED, vì Meshy hoàn lại tín dụng khi một tác vụ thất bại.