Vòng đời tác vụ
Tìm hiểu cách một tác vụ di chuyển từ yêu cầu đến kết quả, thường mất bao lâu, và mã của bạn nên chờ nó trong bao lâu.
Cách một tác vụ chạy
Một yêu cầu tạo trả về một ID tác vụ mà không chờ tác vụ chạy xong. Tác vụ sau đó chạy ngầm, và bạn theo dõi nó theo một trong ba cách: polling endpoint GET của nó, mở endpoint stream của nó, hoặc nhận một webhook.
PENDING. Một worker nhận lấy nó và nó chuyển sang IN_PROGRESS, nơi nó dành phần lớn thời gian. Nó kết thúc ở SUCCEEDED hoặc FAILED, và một trạng thái cuối cùng không bao giờ thay đổi.PENDINGIN_PROGRESSSUCCEEDEDFAILEDTác vụ ghi lại mỗi bước trong các trường created_at, started_at, và finished_at của nó.
Bảng sau đây cho thấy mã của bạn nên làm gì ở mỗi trạng thái.
| Trạng thái | Mã của bạn nên làm gì |
|---|---|
PENDING | Tiếp tục chờ. |
IN_PROGRESS | Theo dõi progress: phần trăm công việc đã hoàn thành, từ 0 đến 100. |
SUCCEEDED | Tải kết quả xuống. Meshy giữ các tệp trong một khoảng thời gian giới hạn. Xem Lưu giữ tài nguyên. |
FAILED | Đọc task_error, sau đó sửa đầu vào hoặc tạo một tác vụ mới. Xem Lỗi. |
CANCELED | Ngừng chờ. Tác vụ sẽ không tạo ra kết quả. Chỉ các tác vụ Creative Lab mới dùng trạng thái này. |
SUCCEEDED, FAILED, và CANCELED là các trạng thái cuối cùng. Sau khi một tác vụ đạt đến một trong các trạng thái này, trạng thái của nó sẽ không bao giờ thay đổi nữa.
Từ phía mã của bạn, nó trông như sau:
Yêu cầu: POST/image-to-3d
Phản hồi: 202{ "result": "<task_id>" }tác vụ đã được tạo
- Lặp lại mỗi vài giây
Yêu cầu: GET/image-to-3d/<task_id>
Phản hồi: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5
Yêu cầu: GET/image-to-3d/<task_id>
Phản hồi: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }
GET nó sau với cùng ID tác vụ.Thời gian xử lý
Các bảng sau đây cho thấy thời gian trung vị trên lưu lượng API thực tế vào tháng 9 năm 2026.
Một khoảng thời gian chạy từ khi tạo tác vụ đến trạng thái cuối cùng. Gần như toàn bộ thời gian đó là xử lý, vì một tác vụ thường chỉ ở trạng thái PENDING trong vài giây. Khi hàng đợi bận, các tác vụ có thể phải chờ lâu hơn trước khi bắt đầu, và các tác vụ trên các gói có độ ưu tiên cao hơn thường bắt đầu sớm hơn.
Thời gian dưới 2 phút được tính bằng giây (s), và thời gian dài hơn được tính bằng phút (min). Không hỗ trợ nghĩa là API không cung cấp tùy chọn đó với mô hình đó.
Đây là các thời gian điển hình, không phải thời gian hoàn thành được đảm bảo. Trong các giai đoạn bận rộn, một số tác vụ mất nhiều thời gian hơn và vẫn thành công. Để kiểm tra trạng thái của Meshy, xem trang trạng thái. Đừng dùng các thời gian này làm timeout trong mã của bạn. Để biết các giá trị timeout, xem Nên chờ bao lâu.
Tạo mô hình 3D
| API | Cấu hình | meshy-7.1 (latest) | meshy-6 | meshy-6-lite | meshy-t2 |
|---|---|---|---|---|---|
| Văn bản sang 3D (Preview) | Chỉ lưới | 75 s | 90 s | 45 s | 10 s |
| Ảnh sang 3D | Chỉ lưới | 75 s | 90 s | 40 s | 4 s |
| Lưới với texture 2K | 2 min | 3 min | 75 s | 60 s | |
| Lưới với texture 4K | 2.5 min | 3.5 min | Không hỗ trợ | 80 s | |
| Lưới với texture 8K | 3.5 min | 4 min | Không hỗ trợ | 2.5 min | |
| Nhiều ảnh sang 3D | Chỉ lưới | 65 s | 2 min | 30 s | Không hỗ trợ |
| Lưới với texture 2K | 2.5 min | 3.5 min | 85 s | Không hỗ trợ | |
| Lưới với texture 4K | 3 min | 4 min | Không hỗ trợ | Không hỗ trợ | |
| Lưới với texture 8K | 3.5 min | 4.5 min | Không hỗ trợ | Không hỗ trợ |
Đối với Ảnh sang 3D và Nhiều ảnh sang 3D, "Chỉ lưới" nghĩa là should_texture: false. Các tùy chọn và đầu vào sau đây làm thay đổi thời gian:
- Bản đồ PBR (
enable_pbr) cộng thêm 30 đến 60 giây. - Hình học siêu chi tiết (
geometry_resolution: "2k"hoặc"4k") cộng thêm tối đa 1 phút. - Với cùng thiết lập, ảnh đầu vào phức tạp hơn sẽ mất nhiều thời gian hơn.
Tạo texture
| API | Độ phân giải texture | Thời gian điển hình |
|---|---|---|
| Văn bản sang 3D (Refine) | 2K hoặc 4K | 80 s |
| 8K | 3.5 min | |
| Tạo lại texture | 2K | 55 s |
| 4K | 90 s | |
| 8K | 2.5 min |
Tạo ảnh
| API | nano-banana | nano-banana-2 | nano-banana-pro | Các mô hình GPT Image |
|---|---|---|---|---|
| Văn bản sang ảnh | 20 s | 15 s | 25 s | 20 đến 35 s |
| Ảnh sang ảnh | 40 s | 20 s | 30 s | 20 đến 40 s |
Rigging và Hoạt hình
| API | Cấu hình | Thời gian điển hình |
|---|---|---|
| Auto-Rigging | Rigging tự động | 40 s |
| Hoạt hình | Mỗi yêu cầu | 15 s |
| Text to Motion | mode prime | 15 s |
mode swift | 10 s |
Hậu xử lý
| API | Thời gian điển hình |
|---|---|
| Remesh | 2 min |
| Trải UV | 35 s |
| Chuyển đổi | 7 s |
| Đổi kích thước | 15 s |
In 3D
| API | Cấu hình | Thời gian điển hình |
|---|---|---|
| Phân tích khả năng in | Chỉ kiểm tra lưới | 1 s |
| Kiểm tra lưới và thành mỏng | 10 s | |
| Multi-Color | Mỗi yêu cầu | 30 s |
| Sửa khả năng in | Chỉ sửa lưới | 10 s |
| Kiểm tra thành mỏng, giữ nguyên thành | 20 s | |
| Kiểm tra thành mỏng, làm dày thành | 100 s | |
| Auto Split | Các bộ phận màu phẳng | 70 s |
Các bộ phận có texture (keep_texture: true) | 170 s |
Trên v2, Sửa khả năng in và Phân tích khả năng in luôn chạy kiểm tra thành mỏng. Trên v1, chúng chạy kiểm tra đó khi bạn gửi loại máy in hoặc kích thước in.
Nên chờ bao lâu
Tác vụ vẫn tiếp tục chạy ngay cả khi mã của bạn ngừng chờ. Nếu yêu cầu của bạn bị timeout, kết nối của bạn bị ngắt, hoặc stream của bạn đóng lại, tác vụ không bị lỗi và không bị hủy.
- Chờ ít nhất 60 phút, tính từ
created_atcủa tác vụ, trước khi bạn ngừng chờ. Nếu bạn dừng sớm hơn, bạn có thể bỏ lỡ một tác vụ thành công sau đó. Điều này xảy ra chủ yếu trong các giai đoạn bận rộn. - Giữ lại ID tác vụ. Bạn có thể lấy lại tác vụ bất cứ lúc nào. Nếu nó vẫn chưa ở trạng thái cuối cùng sau 60 phút, hãy kiểm tra lại sau. Nếu nó vẫn như vậy, hãy liên hệ hỗ trợ.
- Chỉ
FAILEDmới có nghĩa là tác vụ thất bại. Meshy tự động hoàn lại tín dụng cho các tác vụ thất bại.
Hãy dùng các giá trị này trong mã của bạn:
| Thiết lập | Giá trị khuyến nghị |
|---|---|
Timeout của yêu cầu tạo (POST) | 60 giây |
Timeout của yêu cầu tạo (POST) với tệp model_url trên 100 MB | 120 giây. Meshy tải tệp xuống trước khi phản hồi. |
Timeout của yêu cầu trạng thái (GET) | 30 giây |
| Khoảng thời gian poll | Header Retry-After, hoặc 5 giây nếu không có. Các lần poll được tính vào giới hạn tốc độ của bạn. |
Yêu cầu trạng thái thất bại (timeout, 429, hoặc 5xx) | Thử lại ở lần poll tiếp theo. Điều này không có nghĩa là tác vụ thất bại. |
| Tổng thời gian chờ cho mỗi tác vụ | Ít nhất 60 phút kể từ created_at. Đừng đặt lại bộ đếm này khi bạn kết nối lại một stream. |
| Stream | Một stream có thể đóng lại trước khi tác vụ hoàn tất. Nếu nó đóng lại mà không có trạng thái cuối cùng, hãy kết nối lại hoặc chuyển sang polling. |
Đối với nhiều tác vụ cùng lúc, hãy dùng webhooks thay vì poll từng cái. Nếu sự kiện cuối cùng của một tác vụ chưa đến sau khoảng gấp đôi thời gian điển hình của nó, hãy lấy tác vụ từ endpoint GET của nó.