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ời gian 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ề ID tác vụ mà không chờ tác vụ chạy xong. Sau đó tác vụ chạy ở nền, và bạn theo dõi nó bằng một trong ba cách: thăm dò (poll) endpoint GET của nó, mở endpoint stream của nó, hoặc nhận 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 xuống kết quả. 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 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 một trong số đó, 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ư thế này:
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 sản xuất vào tháng 9 năm 2026.
Thời gian tính từ lúc 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ì 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ể 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 tính bằng giây (s), và thời gian dài hơn 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 model đó.
Đây là 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 cao điểm, một số tác vụ mất nhiều thời gian hơn nhưng 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 những thời gian này làm timeout trong mã của bạn. Để biết 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 phút | 3 phút | 75 s | 60 s | |
| Lưới với texture 4K | 2.5 phút | 3.5 phút | Không hỗ trợ | 80 s | |
| Lưới với texture 8K | 3.5 phút | 4 phút | Không hỗ trợ | 2.5 phút | |
| Nhiều ảnh sang 3D | Chỉ lưới | 65 s | 2 phút | 30 s | Không hỗ trợ |
| Lưới với texture 2K | 2.5 phút | 3.5 phút | 85 s | Không hỗ trợ | |
| Lưới với texture 4K | 3 phút | 4 phút | Không hỗ trợ | Không hỗ trợ | |
| Lưới với texture 8K | 3.5 phút | 4.5 phút | 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) thêm 30 đến 60 giây. - Hình học siêu cao (
geometry_resolution: "2k"hoặc"4k") thêm tối đa 1 phút. - Với cùng cài đặt, ả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 phút | |
| Tạo lại texture | 2K | 55 s |
| 4K | 90 s | |
| 8K | 2.5 phút |
Tạo ảnh
| API | nano-banana | nano-banana-2 | nano-banana-pro | Các model 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 |
| Văn bản sang chuyển động | mode prime | 15 s |
mode swift | 10 s |
Hậu xử lý
| API | Thời gian điển hình |
|---|---|
| Remesh | 2 phút |
| 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 | Mỗi yêu cầu | 70 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 cao điểm. - Giữ lại ID tác vụ. Bạn có thể lấy lại tác vụ bất kỳ lúc nào. Nếu sau 60 phút nó vẫn chưa ở trạng thái cuối cùng, hãy kiểm tra lại sau. Nếu nó vẫn như vậy, hãy liên hệ bộ phận hỗ trợ.
- Chỉ
FAILEDnghĩ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.
Sử dụng các giá trị sau trong mã của bạn:
| Thiết lập | Giá trị đề xuất |
|---|---|
Timeout yêu cầu tạo (POST) | 60 giây |
Timeout 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 yêu cầu trạng thái (GET) | 30 giây |
| Khoảng thời gian thăm dò | Tiêu đề Retry-After, hoặc 5 giây nếu không có. Các lần thăm dò đượ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 thăm dò 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 tính từ created_at. Đừng đặt lại thời gian đế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 thăm dò. |
Đối với nhiều tác vụ cùng lúc, hãy dùng webhooks thay vì thăm dò từng tác vụ một. 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ó.