API Văn bản sang 3D

API Văn bản sang 3D là một tính năng cho phép bạn tích hợp khả năng Văn bản sang 3D của Meshy vào ứng dụng của riêng mình. Trong phần này, bạn sẽ tìm thấy tất cả thông tin cần thiết để bắt đầu sử dụng API này.

Văn bản sang 3D sử dụng quy trình làm việc hai bước. Đầu tiên, tạo một task preview (mode: "preview") để tạo ra một lưới 3D không có texture, để bạn có thể đánh giá hình dạng. Sau đó, truyền task ID của preview đã hoàn thành vào một task refine (mode: "refine") để áp dụng texture cho lưới. Cả hai bước đều dùng chung một endpoint.

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

Create a Text to 3D Preview Task

Endpoint này tạo một tác vụ Text to 3D preview, 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 làm việc hai bước. Sau khi preview thành công, hãy dùng ID tác vụ được trả về để tạo một refine task để tạo texture. Tham khảo The Text to 3D Task Object để biết đầy đủ schema phản hồi.

Tham số

Name
mode
Type
string
Bắt buộc
Description
Trường này nên được đặt thành "preview" khi tạo một tác vụ preview.
Name
prompt
Type
string
Bắt buộc
Description
Mô tả loại đối tượng mà mô hình 3D thể hiện. Tối đa 800 ký tự.
Name
model_type
Type
string
mặc định standard
Description
Chỉ định loại tạo lưới 3D.
Các giá trị khả dụng:
- standard: Tạo lưới 3D chi tiết cao thông thường.
- smart-topology: Chọn mô hình Smart Topology với ai_model (meshy-t2).
- lowpoly (không dùng nữa): Tạo lưới low-poly được tối ưu cho các đa giác gọn hơn. Chúng tôi khuyến nghị dùng smart-topology thay thế.
Khi chọn smart-topology, should_remesh và decimation_mode sẽ bị bỏ qua, và chỉ chấp nhận topology: triangle.
Khi chọn lowpoly, ai_model, topology, target_polycount, và should_remesh sẽ bị bỏ qua.
Name
ai_model
Type
string
mặc định latest
Description
ID của mô hình được sử dụng. Các giá trị khả dụng phụ thuộc vào model_type.
Tạo standard (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): mô hình Smart Topology — topology sạch hơn, các phần được tách riêng tự nhiên, đầu ra dạng tam giác, và số lượng mặt bạn có thể đặt bằng target_polycount.
Name
ultra_mode
Type
boolean
mặc định false
Description
Bật chế độ tạo Ultra để có hình học độ trung thực cao hơn với chi tiết bề mặt tinh xảo hơn. Quá trình tạo mất nhiều thời gian hơn và tốn thêm 5 tín dụng.
Chỉ được hỗ trợ khi ai_model là meshy-7 (hoặc latest), và chỉ ở mode preview.
Name
should_remesh
Type
boolean
mặc định false (meshy-6, meshy-7), true (others)
Description
Kiểm soát việc có bật giai đoạn remesh hay không. Đối với mô hình chất lượng cao nhất, chúng tôi khuyến nghị đặt should_remesh thành false.

Chỉ áp dụng khi should_remesh = true

Name
topology
Type
string
mặc định triangle
Description
Chỉ định topology của mô hình được tạo.
Các giá trị khả dụng:
- quad: Tạo lưới chủ yếu là tứ giác (quad-dominant).
- triangle: Tạo lưới tam giác đã được decimate.
Đầu ra Smart Topology chỉ ở dạng tam giác. Yêu cầu quad cùng với ai_model: meshy-t2 sẽ trả về lỗi.
Name
decimation_mode
Type
integer
Description
Bật chế độ decimation thích ứng bằng cách đặt một mức số đa giác. Khi được đặt, target_polycount sẽ bị bỏ qua.
Các giá trị khả dụng:
- 1: Thích ứng — số đa giác cực cao (ultra).
- 2: Thích ứng — số đa giác cao.
- 3: Thích ứng — số đa giác trung bình.
- 4: Thích ứng — số đa giác thấp.

Name
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ể lệch so với mục tiêu tùy thuộc vào hình học.
target_polycount có hiệu lực trong hai trường hợp độc lập:
- Remesh — với should_remesh: true trên mô hình standard. Lưới sẽ được remesh (decimate) đến xấp xỉ 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 sẽ bị bỏ qua.
- Smart Topology — với model_type: smart-topology và ai_model: meshy-t2. Mô hình được tạo trực tiếp với số lượng mặt này; không chạy remesh và không cần should_remesh. 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 kiểm soát hành vi đối xứng trong quá trình tạo mô hình.
Các giá trị hợp lệ là:
- off: Tắt đối xứng.
- auto: Tự động xác định và áp dụng đối xứng dựa trên hình học đầu vào.
- on: Bắt buộc đối xứng trong quá trình tạo.
Name
pose_mode
Type
string
mặc định ""
Description
Chỉ định pose mode cho mô hình được tạo.
Các giá trị khả dụng:
- a-pose: Tạo mô hình ở tư thế chữ A.
- t-pose: Tạo mô hình ở tư thế chữ T.
- "" (chuỗi rỗng): Không áp dụng tư thế cụ thể nào.
Name
is_a_t_pose
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Hãy dùng pose_mode thay thế. Có tạo mô hình ở tư thế A/T hay không.
Name
art_style
Type
string
⚠ không dùng nữa
mặc định realistic
Description
Không được hỗ trợ bởi Meshy-6. Các yêu cầu sử dụng Meshy-6 sẽ bỏ qua art_style, và một số kết hợp có thể gây ra lỗi. Các giá trị khả dụng: realistic, sculpture.
enable_pbr nên được đặt thành false khi sử dụng phong cách Sculpture, vì phong cách Sculpture tạo ra bộ bản đồ PBR riêng của nó.
Name
moderation
Type
boolean
mặc định false
Description
Khi được đặt thành true, nội dung đầu vào sẽ tự động được kiểm duyệt để phát hiện nội dung có khả năng gây hại. Nếu phát hiện nội dung gây hại, tác vụ sẽ không tiếp tục tạo.
Văn bản từ prompt sẽ được kiểm duyệt.
Name
target_formats
Type
string[]
Description
Chỉ định những định dạng tệp 3D nào sẽ được đưa vào đầu ra. Chỉ những định dạng được yêu cầu mới được tạo và trả về, điều này có thể giảm thời gian hoàn thành tác vụ. Khi bị bỏ qua, tất cả các định dạng được hỗ trợ sẽ được đưa vào.
Các giá trị khả dụng: glb, obj, fbx, stl, usdz, 3mf
Khi bị bỏ qua, tất cả các định dạng ngoại trừ 3mf sẽ được tạo. 3mf chỉ được đưa vào khi được chỉ định rõ ràng.
Name
alpha_thumbnail
Type
boolean
mặc định false
Description
Khi được đặt thành true, tác vụ sẽ render thêm một phiên bản nền trong suốt (RGBA) của preview và trả về dưới dạng alpha_thumbnail_url trong phản hồi GET. Trường thumbnail_url hiện có không thay đổi.
Name
auto_size
Type
boolean
mặc định false
Description
Khi được đặt thành true, dịch vụ sẽ sử dụng AI vision để tự động ước lượng chiều cao thực tế của đối tượng và đổ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.

Chỉ áp dụng khi auto_size = true

Name
origin_at
Type
string
mặc định bottom
Description
Vị trí gốc tọa độ khi auto_size được bật.
Các giá trị khả dụng: bottom, center.

Kết quả trả về

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

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

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Các nguyên nhân phổ biến:
- Thiếu tham số: Một tham số bắt buộc (ví dụ: prompt, mode) bị thiếu.
- Tham số không hợp lệ: art_style không thuộc các giá trị được cho phép.
- Prompt quá dài: prompt vượt quá giới hạn ký tự.
Name
401 - Unauthorized
Description
Xác thực thất bại. Vui lòng kiểm tra khóa API của bạn.
Name
402 - Payment Required
Description
Không đủ tín dụng để thực hiện tác vụ này.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.

Request

POST

/openapi/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 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",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

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

Tạo tác vụ Refine cho Văn bản sang 3D

Endpoint này tạo một tác vụ refine cho Văn bản sang 3D, áp dụng texture cho một lưới preview đã hoàn thành. Bạn phải cung cấp preview_task_id từ một tác vụ preview thành công. Đây là bước thứ hai trong quy trình hai bước.

Tham số

Name
mode
Type
string
Bắt buộc
Description
Trường này nên được đặt thành "refine" khi tạo một tác vụ refine.
Name
preview_task_id
Type
string
Bắt buộc
Description
ID tác vụ preview tương ứng.
Trạng thái của tác vụ preview đã cho phải là SUCCEEDED.
Name
enable_pbr
Type
boolean
mặc định false
Description
Tạo bản đồ PBR (metallic, roughness, normal) bên cạnh màu cơ bản (base color). Bản đồ emission cũng được bao gồm khi ai_model là meshy-6, ngoại trừ ở texture_resolution: 8k (không tạo bản đồ emission). meshy-7 (và latest) không tạo bản đồ emission.
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 sẽ nắm bắt được nhiều chi tiết bề mặt hơn. Chỉ áp dụng cho mode refine.
4k và 8k yêu cầu ai_model là meshy-6, meshy-7, hoặc latest. Ở mức 8k, không tạo bản đồ emission.
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 đều đượ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 bổ sung để định hướng quá trình tạo texture. Tối đa 800 ký tự.
Name
texture_image_url
Type
string
Description
Cung cấp một hình ảnh 2D để định hướng quá trình tạo texture. Hiện tại chúng tôi hỗ trợ các định dạng .jpg, .jpeg, và .png.
Có hai cách để cung cấp hình ảnh:
- URL truy cập công khai: Một URL có thể truy cập được từ internet công cộng
- Data URI: Một data URI của hình ảnh được mã hóa base64. Ví dụ về data URI: data:image/jpeg;base64,<dữ liệu hình ảnh mã hóa base64 của bạn>
Việc tạo texture từ hình ảnh có thể không hoạt động tối ưu nếu có sự khác biệt đáng kể về hình học giữa asset gốc và hình ảnh đã tải lên. Chỉ một trong hai tham số texture_image_url hoặc texture_prompt có thể được sử dụng để định hướng quá trình tạo texture. Nếu cả hai tham số đều được cung cấp, thì texture_prompt sẽ được sử dụng theo mặc định để tạo texture cho mô hình.
Name
ai_model
Type
string
mặc định inherited from the preview task
Description
ID của mô hình được sử dụng để refine. Các giá trị khả dụng: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Bỏ qua tham số này để kế thừa mô hình được sử dụng bởi tác vụ preview, giúp giữ cho một preview và bản refine của nó sử dụng cùng một mô hình từ đầu đến cuối. Truyền một giá trị cụ thể để ghi đè việc kế thừa đó.
Một giá trị latest cụ thể sẽ được phân giải ở đây giống hệt như trên tác vụ preview (hiện tại là Meshy 7), vì vậy một preview latest và bản refine latest của nó luôn sử dụng cùng một mô hình texture.
Name
moderation
Type
boolean
mặc định false
Description
Khi được đặt thành true, nội dung đầu vào sẽ tự động được kiểm duyệt để phát hiện nội dung có khả năng gây hại. Nếu phát hiện nội dung gây hại, tác vụ sẽ không tiến hành tạo.
Cả văn bản từ texture_prompt và hình ảnh từ texture_image_url đều sẽ được kiểm duyệt.
Name
remove_lighting
Type
boolean
mặc định true
Description
Loại bỏ các điểm sáng và bóng đổ khỏi texture màu cơ bản, tạo ra kết quả sạch hơn, hoạt động tốt hơn dưới các thiết lập ánh sáng tùy chỉnh.
Chỉ có hiệu lực khi ai_model là meshy-6. Trên meshy-7 (và latest), tham số này được chấp nhận nhưng bị bỏ qua.
Name
target_formats
Type
string[]
Description
Chỉ định các định dạng file 3D nào sẽ được bao gồm trong đầu ra. Chỉ những định dạng được yêu cầu mới được tạo và trả về, điều này có thể giảm thời gian hoàn thành tác vụ. Khi bỏ qua, tất cả các định dạng được hỗ trợ sẽ được bao gồm.
Các giá trị khả dụng: glb, obj, fbx, stl, usdz, 3mf
Khi bỏ qua, tất cả các định dạng ngoại trừ 3mf sẽ được tạo. 3mf chỉ được bao gồm khi được chỉ định rõ ràng.
Name
alpha_thumbnail
Type
boolean
mặc định false
Description
Khi được đặt thành true, tác vụ sẽ đồng thời kết xuất một phiên bản nền trong suốt (RGBA) của preview và trả về nó dưới dạng alpha_thumbnail_url trong phản hồi GET. Trường thumbnail_url hiện có không thay đổi.
Name
auto_size
Type
boolean
mặc định false
Description
Khi được đặt thành true, dịch vụ sẽ sử dụng thị giác AI để tự động ước tính chiều cao thực tế của đối tượng và đổ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.

Chỉ áp dụng khi auto_size = true

Name
origin_at
Type
string
mặc định bottom
Description
Vị trí của gốc tọa độ khi auto_size được bật.
Các giá trị khả dụng: bottom, center.

Kết quả trả về

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

Các chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Các nguyên nhân phổ biến:
- ID tác vụ không hợp lệ: preview_task_id không hợp lệ hoặc không tồn tại.
- Tác vụ chưa sẵn sàng: Tác vụ preview chưa hoàn thành thành công.
- Không khớp mô hình: Mô hình AI của tác vụ preview không tương thích với mô hình refine được yêu cầu.
Name
401 - Unauthorized
Description
Xác thực không thành công. Vui lòng kiểm tra khóa API của bạn.
Name
402 - Payment Required
Description
Không đủ tín dụng để thực hiện tác vụ này.
Name
404 - Not Found
Description
Không tìm thấy tác vụ preview được chỉ định bởi preview_task_id.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.

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

Response

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

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

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

Endpoint này cho phép bạn truy xuất một tác vụ Văn bản sang 3D dựa trên id tác vụ hợp lệ. Tham khảo Đối tượng tác vụ Văn bản sang 3D để xem những thuộc tính nào được bao gồm trong đối tượng tác vụ Văn bản sang 3D.

Endpoint này hoạt động cho cả tác vụ preview và refine.

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ Văn bản sang 3D cần truy xuất.

Kết quả trả về

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

Ví dụ

Mode	Mô hình mẫu
Preview
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": {

    "message": ""

  },

  "consumed_credits": 20
}

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

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

Endpoint này xóa vĩnh viễn một tác vụ Văn bản sang 3D, bao gồm tất cả các mô hình và dữ liệu liên quan. Hành động này không thể hoàn tác.

Tham số đường dẫn

Name
id
Type
path
Description
ID của tác vụ Văn bản sang 3D cần xóa.

Kết quả trả về

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

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

// Returns 200 Ok on success.

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

List Text to 3D Tasks

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

Tham số

Name
page_num
Type
integer
mặc định 1
Description
Số trang cho phân trang.
Name
page_size
Type
integer
mặc định 10
Description
Giới hạn số lượng mỗi trang. Tối đa cho phép là 50 mục.
Name
sort_by
Type
string
Description
Trường để sắp xếp theo.
Các giá trị khả dụng:
- +created_at: Sắp xếp theo thời gian tạo theo thứ tự tăng dần.
- -created_at: Sắp xếp theo thời gian tạo theo thứ tự giảm dần.

Kết quả trả về

Trả về một danh sách phân trang các Đối tượng Tác vụ Văn bản sang 3D.

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": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

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

Stream a Text to 3D Task

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

Tham số

Name
id
Type
path
Description
Định danh duy nhất của tác vụ Văn bản sang 3D cần truyền (stream).

Giá trị trả về

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.

Đối với các tác vụ ở trạng thái PENDING hoặc IN_PROGRESS, luồng phản hồi sẽ chỉ bao gồm các trường progress và status cần thiết.

Request

GET

/openapi/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "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": {

  "message": ""

},

"consumed_credits": 20
}

The Text to 3D Task Object

Đối tượng Text to 3D Task là một đơn vị công việc mà Meshy theo dõi để tạo mô hình 3D từ đầu vào văn bản. Có hai giai đoạn trong Text to 3D API, preview và refine. Giai đoạn preview dùng để tạo mô hình 3D chỉ có lưới, và giai đoạn refine dùng để tạo mô hình 3D có texture dựa trên kết quả của giai đoạn preview.

Đối tượng này có các thuộc tính sau:

Properties

Name
id
Type
string
Description
Mã định danh duy nhất cho tác vụ. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp theo k (k-sortable UUID) làm chi tiết triển khai cho id tác vụ, bạn không nên đưa ra bất kỳ giả định nào về định dạng của id.
Name
type
Type
string
Description
Loại tác vụ Text to 3D. Các giá trị có thể là text-to-3d-preview cho tác vụ giai đoạn preview và text-to-3d-refine cho tác vụ giai đoạn refine.
Name
model_urls
Type
object
Description
URL có thể tải xuống tới tệp mô hình 3D có texture được tạo bởi Meshy. Thuộc tính cho một định dạng sẽ bị bỏ qua nếu định dạng đó không được tạo, thay vì trả về một chuỗi rỗng.
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống tới tệp GLB.
- Name
  fbx
  Type
  string
  Description
  URL có thể tải xuống tới tệp FBX.
- Name
  usdz
  Type
  string
  Description
  URL có thể tải xuống tới tệp USDZ.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống tới tệp OBJ.
- Name
  mtl
  Type
  string
  Description
  URL có thể tải xuống tới tệp MTL.
- Name
  stl
  Type
  string
  Description
  URL có thể tải xuống tới tệp STL.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống tới tệp 3MF. Chỉ xuất hiện khi 3mf được yêu cầu thông qua target_formats.
Name
prompt
Type
string
Description
Đây là prompt không bị chỉnh sửa được dùng để tạo tác vụ.
Name
negative_prompt
Type
string
⚠ không dùng nữa
Description
Được duy trì để đảm bảo khả năng tương thích ngược. Trường này không có tác động chức năng nào đến các mô hình được tạo ra.
Name
art_style
Type
string
⚠ không dùng nữa
Description
art_style không bị chỉnh sửa được dùng để tạo tác vụ preview. Không được hỗ trợ bởi Meshy-6.
Name
texture_richness
Type
string
⚠ không dùng nữa
Description
Được duy trì để đảm bảo khả năng tương thích ngược. Trường này không có tác động chức năng nào đến các mô hình được tạo ra.
Name
texture_prompt
Type
string
Description
Prompt văn bản bổ sung được cung cấp để định hướng quá trình tạo texture trong giai đoạn refine.
Name
ultra_mode
Type
boolean
Description
Phản ánh lại giá trị ultra_mode mà tác vụ preview đã được tạo với. Chỉ xuất hiện đối với các tác vụ preview meshy-7 (hoặc latest) có thiết lập rõ ràng ultra_mode; ngược lại sẽ bị bỏ qua.
Name
texture_image_url
Type
string
Description
URL có thể tải xuống tới hình ảnh texture đã được dùng để định hướng quá trình tạo texture.
Name
thumbnail_url
Type
string
Description
URL có thể tải xuống tới ảnh thu nhỏ của tệp mô hình.
Name
alpha_thumbnail_url
Type
string
Description
URL có thể tải xuống tới phiên bản nền trong suốt (RGBA) của thumbnail_url. Chỉ xuất hiện khi tác vụ được tạo với alpha_thumbnail: true và bản xem trước trong suốt được render thành công; nếu không, trường này sẽ bị bỏ qua.
Name
video_url
Type
string
⚠ không dùng nữa
Description
URL có thể tải xuống tới video xem trước. Sẽ bị loại bỏ trong bản phát hành tương lai.
Name
progress
Type
integer
Description
Progress của tác vụ. Nếu tác vụ chưa bắt đầu, thuộc tính này sẽ là 0. Khi tác vụ đã thành công, giá trị này sẽ trở thành 100.
Name
started_at
Type
timestamp
Description
Dấu thời gian khi tác vụ đượ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.
Một 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 UTC, theo tiêu chuẩn RFC 3339. Ví dụ, Thứ Sáu, ngày 1 tháng 9 năm 2023, 12:00:00 CH GMT được biểu diễn dưới dạng 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
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, mảng này chỉ chứa một đối tượng URL texture. Mỗi URL texture có các thuộc tính sau:
- Name
  base_color
  Type
  string
  Description
  URL có thể tải xuống tới hình ảnh bản đồ màu cơ bản.
- Name
  metallic
  Type
  string
  Description
  URL có thể tải xuống tới hình ả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 tới hình ả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 tới hình ảnh bản đồ độ nhám.
  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 tới hình ảnh bản đồ phát xạ.
  Nếu tác vụ được tạo với enable_pbr: false, hoặc ai_model là meshy-5, thuộc tính này sẽ bị bỏ qua.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước.
Giá trị của trường này chỉ có ý nghĩa 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 để biết tham chiếu đầy đủ về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số tín dụng đã tiêu thụ bởi tác vụ này. Có mặt 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 sẽ được hoàn lại khi thất bại).

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": {

    "message": ""

  },

  "consumed_credits": 20
}