Text to 3D API

Text to 3D API 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 bạn. Trong phần này, bạn sẽ tìm thấy tất cả thông tin bạn cần để bắt đầu với API này.

Văn bản sang 3D sử dụng quy trình hai bước. Đầu tiên, tạo một tác vụ xem trước (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 đó, chuyển ID tác vụ xem trước đã hoàn thành sang một tác vụ cải tiến (mode: "refine") để áp dụng texture vào lưới. Cả hai bước đều sử dụng cùng một endpoint.

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

Tạo tác vụ xem trước Text to 3D

endpoint này tạo ra một tác vụ xem trước Text to 3D, tạo ra một lưới 3D không có texture (chỉ hình học) từ một prompt văn bản. Đây là bước đầu tiên của quy trình hai bước. Khi xem trước thành công, sử dụng ID tác vụ trả về để tạo tác vụ cải tiến cho việc áp dụng texture. Tham khảo Đối tượng tác vụ Text to 3D để có định dạng trả về đầy đủ.

Tham số

Name
mode
Type
string
Bắt buộc
Description
Trường này nên được thiết lập thành "preview" khi tạo một tác vụ xem trước.
Name
prompt
Type
string
Bắt buộc
Description
Mô tả loại đối tượng mà mô hình 3D là gì. Tối đa 600 ký tự.
Name
model_type
Type
string
mặc định standard
Description
Chỉ định loại tạo lưới 3D.
Giá trị có sẵn:
- 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 tối ưu cho đa giác sạch hơn. Chúng tôi khuyến khích sử dụng smart-topology thay thế.
Khi smart-topology được chọn, should_remesh và decimation_mode sẽ bị bỏ qua, và chỉ chấp nhận topology: triangle.
Khi lowpoly được chọn, 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 để sử dụng. Giá trị có sẵn phụ thuộc vào model_type.
Tạo thông thường (model_type: standard):
- meshy-5, meshy-6, meshy-7, latest (Meshy 7)
Tạo Smart Topology (model_type: smart-topology):
- meshy-t2 (mặc định): mô hình Smart Topology — topology sạch hơn, các phần tự nhiên tách biệt, đầu ra là tam giác, và số lượng mặt có thể đặt bằng target_polycount.
Name
ultra_mode
Type
boolean
mặc định false
Description
Kích hoạt tạo Ultra cho hình học chất lượng cao hơn với chi tiết bề mặt mịn hơn. Tạo ra sẽ mất nhiều thời gian hơn và thêm 5 tín dụng.
Chỉ hỗ trợ khi ai_model là meshy-7 (hoặc latest), và chỉ trên chế độ preview.
Name
should_remesh
Type
boolean
mặc định false (meshy-6, meshy-7), true (others)
Description
Kiểm soát xem liệu có kích hoạt pha remesh. Đối với mô hình chất lượng cao nhất, chúng tôi khuyến khích đặ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 ra.
Giá trị có sẵn:
- quad: Tạo một lưới chiếm ưu thế là tứ giác.
- triangle: Tạo một lưới tam giác thô.
Đầu ra Smart Topology chỉ có 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
Kích hoạt giảm đa giác thích ứng bằng cách đặt mức số đa giác. Khi được đặt, target_polycount sẽ bị bỏ qua.
Giá trị có sẵn:
- 1: Thích ứng — số đa giác cực kỳ cao.
- 2: Thích ứng — số đa giác cao.
- 3: Thích ứng — số đa giác trung bình.
- 4: Thích ứng — số đa giác thấp.

Name
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 riêng biệt:
- Remesh — với should_remesh: true trên mô hình standard. Lưới được remeshed (giảm bớt) đến xấp xỉ con số này. Phạm vi từ 100 đến 300,000, mặc định 30,000. Nếu decimation_mode được thiết lập, 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 ở số lượng mặt này; không remesh được thực hiện 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 điều chỉnh hành vi đối xứng trong quá trình tạo mô hình.
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 áp dụng đối xứng trong quá trình tạo.
Name
pose_mode
Type
string
mặc định ""
Description
Chỉ định chế độ tư thế cho mô hình được tạo ra.
Giá trị có sẵn:
- a-pose: Tạo mô hình ở tư thế A.
- t-pose: Tạo mô hình ở tư thế T.
- "" (chuỗi rỗng): Không áp dụng tư thế cụ thể nào.
Name
is_a_t_pose
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Sử dụng pose_mode thay thế. Dùng để chỉ định liệu có tạo mô hình ở tư thế A/T.
Name
art_style
Type
string
⚠ không dùng nữa
mặc định realistic
Description
Không 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ố tổ hợp có thể gây lỗi. Giá trị có sẵn: realistic, sculpture.
enable_pbr nên được thiết lập thành false khi sử dụng phong cách Sculpture, vì phong cách Sculpture có các 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 tra xem có nội dung có thể gây hại không. Nếu phát hiện nội dung có hại, tác vụ sẽ không tiến hành tạo.
Văn bản từ prompt sẽ được kiểm tra.
Name
target_formats
Type
string[]
Description
Chỉ định định dạng tệp 3D nào để bao gồm trong đầu ra. Chỉ những định dạng được yêu cầu sẽ được tạo ra 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.
Giá trị có sẵn: 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 ra. 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ẽ bổ sung thêm bản xem trước có nền trong suốt (RGBA) và trả về dưới dạng alpha_thumbnail_url trên phản hồi GET. Trường thumbnail_url hiện có không đổ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 để tự động ước tính chiều cao thực tế của đối tượng và thay đổi kích thước mô hình theo đó. origin sẽ mặc định là bottom ngoại 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 kích hoạt.
Giá trị có sẵn: bottom, center.

Trả về

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

Chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không thể chấp nhận được. Các nguyên nhân phổ biến:
- Tham số thiếu: Một tham số bắt buộc (ví dụ như prompt, mode) bị thiếu.
- Tham số không hợp lệ: art_style không phải là một trong những giá trị được phép.
- Prompt quá dài: prompt vượt quá giới hạn ký tự.
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
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.

Request

POST

/openapi/v2/text-to-3d

# Đơn giản xem trước với chỉ các tham số cần thiết
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"
}'

# Xem trước với remesh và 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ụ cải tiến Text to 3D

endpoint này tạo ra một tác vụ cải tiến Text to 3D, áp dụng texture vào lưới xem trước đã hoàn thành. Bạn phải cung cấp preview_task_id từ một tác vụ xem trước thành công. Đây là bước thứ hai của quy trình hai bước.

Tham số

Name
mode
Type
string
Bắt buộc
Description
Trường này nên được thiết lập thành "refine" khi tạo một tác vụ cải tiến.
Name
preview_task_id
Type
string
Bắt buộc
Description
ID tác vụ xem trước tương ứng.
Trạng thái của tác vụ xem trước đã cho phải là SUCCEEDED.
Name
enable_pbr
Type
boolean
mặc định false
Description
Tạo các bản đồ PBR (metallic, roughness, normal) ngoài màu cơ bản. Một bản đồ phát sáng cũng được bao gồm khi ai_model là meshy-6, ngoại trừ ở texture_resolution: 8k (không tạo ra bản đồ phát sáng). meshy-7 (và latest) không tạo ra bản đồ phát sáng.
Name
texture_resolution
Type
string
mặc định 2k
Description
Độ phân giải texture màu cơ bản. Một trong 2k (2048×2048), 4k (4096×4096), hoặc 8k (8192×8192). Độ phân giải cao hơn lưu nhiều chi tiết bề mặt hơn. Chỉ áp dụng cho chế độ refine.
4k và 8k yêu cầu ai_model meshy-6, meshy-7, hoặc latest. Ở 8k, không tạo ra bản đồ phát sáng.
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 thêm một prompt văn bản để hướng dẫn quá trình áp dụng texture. Tối đa 600 ký tự.
Name
texture_image_url
Type
string
Description
Cung cấp một hình ảnh 2d để hướng dẫn quá trình áp dụng texture. Hiện tại chúng tôi hỗ trợ định dạng .jpg, .jpeg, và .png.
Có hai cách để cung cấp hình ảnh:
- URL công khai: Một URL có thể truy cập từ mạng Internet công khai
- Data URI: Một URI dữ liệu được mã hóa base64 của hình ảnh. Ví dụ về một Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Áp dụng texture hình ảnh có thể không hoạt động tốt nếu có sự khác biệt hình học đáng kể giữa tài sản gốc và hình ảnh tải lên. Chỉ một trong texture_image_url hoặc texture_prompt có thể được sử dụng để hướng dẫn quá trình áp dụng texture. Nếu cả hai tham số được cung cấp, texture_prompt sẽ được sử dụng để áp dụng texture cho mô hình theo mặc định.
Name
ai_model
Type
string
mặc định latest
Description
ID của mô hình để sử dụng cho cải tiến. Giá trị có sẵn: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
latest sẽ xác định ở đây giống như nó xác định trên tác vụ xem trước (hiện tại là Meshy 7), do đó một tác vụ xem trước latest và cải tiến latest sẽ luôn tồn tại trên cùng một mô hình áp dụng 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 tra xem có nội dung có thể gây hại không. Nếu phát hiện nội dung có 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 sẽ được kiểm tra.
Name
remove_lighting
Type
boolean
mặc định true
Description
Loại bỏ các phản chiếu và bóng từ texture màu cơ bản, tạo ra kết quả sạch hơn phù hợp hơn với tùy chỉnh thiết lập ánh sáng.
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 định dạng tệp 3D nào để bao gồm trong đầu ra. Chỉ những định dạng được yêu cầu sẽ được tạo và trả về, điều này có thể giảm thời gian hoàn thành tác vụ. Khi không được chỉ định, tất cả định dạng được hỗ trợ sẽ được bao gồm.
Giá trị có sẵn: glb, obj, fbx, stl, usdz, 3mf
Khi không được chỉ định, tất cả các định dạng ngoại trừ 3mf sẽ được tạo ra. 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ẽ bổ sung thêm bản xem trước có nền trong suốt (RGBA) và trả về dưới dạng alpha_thumbnail_url trên phản hồi GET. Trường thumbnail_url hiện có không đổ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 để tự động ước tính chiều cao thực tế của đối tượng và thay đổi kích thước mô hình theo đó. origin sẽ mặc định là bottom ngoại 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 kích hoạt.
Giá trị có sẵn: bottom, center.

Trả về

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

Chế độ lỗi

Name
400 - Bad Request
Description
Yêu cầu không thể chấp nhận được. 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ụ xem trước chưa hoàn thành.
- Không khớp mô hình: Mô hình AI của tác vụ xem trước không tương thích với mô hình cải tiến đượ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
Tác vụ xem trước được chỉ định bởi preview_task_id không được tìm thấ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

# Tác vụ cải tiến cơ bản
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
}'

# Cải tiến với kích thước tự động và định dạng GLB
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

Lấy tác vụ Text to 3D

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

endpoint này hoạt động cho cả tác vụ xem trước và cải tiến.

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất cho tác vụ Text to 3D để lấy.

Trả về

Phản hồi chứa đối tượng tác vụ Text to 3D. Kiểm tra phần Đối tượng tác vụ Text to 3D để biết chi tiết.

Ví dụ

Chế độ	Mẫu Mô Hình
Xem trước
Cải tiến

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 tác vụ Text to 3D

endpoint này xóa vĩnh viễn một tác vụ Text to 3D, bao gồm tất cả các mô hình và dữ liệu liên quan. Hành động này là không thể đảo ngược.

Tham số Đường dẫn

Name
id
Type
path
Description
ID của tác vụ Text to 3D để xóa.

Trả về

Trả về 200 OK nếu 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

Liệt kê các tác vụ Text to 3D

endpoint này cho phép bạn lấy danh sách các tác vụ Text to 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 kích thước một trang. Tối đa cho phép là 50 mục.
Name
sort_by
Type
string
Description
Trường để sắp xếp.
Giá trị có sẵn:
- +created_at: Sắp xếp theo thời gian tạo theo thứ tự tăng dần.
- -created_at: Sắp xếp theo thời gian tạo theo thứ tự giảm dần.

Trả về

Trả về danh sách phân trang của Các Đối tượng tác vụ Text to 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

Truyền tải tác vụ Text to 3D

endpoint này truyền tải cập nhật theo thời gian thực cho một tác vụ Text to 3D sử dụng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất cho tác vụ Text to 3D để truyền tải.

Trả về

Trả về một dòng của Các Đối tượng tác vụ Text to 3D dưới dạng Server-Sent Events.

Với các tác vụ PENDING hoặc IN_PROGRESS, dòng phản hồi 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

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

// Ví dụ sự kiện tin nhắn minh họa tiến trình tác vụ.
// Đối với các tác vụ PENDING hoặc IN_PROGRESS, dòng phản hồi sẽ không bao gồm tất cả các trường.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

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

Đối tượng tác vụ Text to 3D

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

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

Thuộc tính

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