lowpoly sẽ ngừng hoạt động vào 30 thg 10, 2026. meshy-7 với vai trò mô hình tạo 3D sẽ ngừng hoạt động vào 31 thg 12, 2026; với vai trò mô hình texture thì vẫn dùng được. Hãy chuyển sang mô hình khác trước các ngày này để tránh lỗi yêu cầu. Xem tất cả mục ngừng hỗ trợ

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.

Một yêu cầu tạo khởi động một tác vụ ở trạng thái 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.
Yêu cầu tạo
PENDING
Đang chờ trong hàng đợi
IN_PROGRESS
Đang tạo kết quả
SUCCEEDED
Tải kết quả xuống
FAILED
Tín dụng được hoàn lại

Tá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áiMã của bạn nên làm gì
PENDINGTiếp tục chờ.
IN_PROGRESSTheo dõi progress: phần trăm công việc đã hoàn thành, từ 0 đến 100.
SUCCEEDEDTả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.
CANCELEDNgừ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:

Tạo một tác vụ, sau đó poll nó cho đến khi hoàn tất.
  1. Yêu cầu: POST/image-to-3d

  2. Phản hồi: 202{ "result": "<task_id>" }tác vụ đã được tạo

  3. Lặp lại mỗi vài giây
    1. Yêu cầu: GET/image-to-3d/<task_id>

    2. Phản hồi: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5

  4. Yêu cầu: GET/image-to-3d/<task_id>

  5. Phản hồi: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }

Nếu ứng dụng của bạn ngừng chờ, tác vụ vẫn tiếp tục chạy. Hãy 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 đó.

Tạo mô hình 3D

APICấu hìnhmeshy-7.1 (latest)meshy-6meshy-6-litemeshy-t2
Văn bản sang 3D (Preview)Chỉ lưới75 s90 s45 s10 s
Ảnh sang 3DChỉ lưới75 s90 s40 s4 s
Lưới với texture 2K2 min3 min75 s60 s
Lưới với texture 4K2.5 min3.5 minKhông hỗ trợ80 s
Lưới với texture 8K3.5 min4 minKhông hỗ trợ2.5 min
Nhiều ảnh sang 3DChỉ lưới65 s2 min30 sKhông hỗ trợ
Lưới với texture 2K2.5 min3.5 min85 sKhông hỗ trợ
Lưới với texture 4K3 min4 minKhông hỗ trợKhông hỗ trợ
Lưới với texture 8K3.5 min4.5 minKhô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 textureThời gian điển hình
Văn bản sang 3D (Refine)2K hoặc 4K80 s
8K3.5 min
Tạo lại texture2K55 s
4K90 s
8K2.5 min

Tạo ảnh

APInano-banananano-banana-2nano-banana-proCác mô hình GPT Image
Văn bản sang ảnh20 s15 s25 s20 đến 35 s
Ảnh sang ảnh40 s20 s30 s20 đến 40 s

Rigging và Hoạt hình

APICấu hìnhThời gian điển hình
Auto-RiggingRigging tự động40 s
Hoạt hìnhMỗi yêu cầu15 s
Text to Motionmode prime15 s
mode swift10 s

Hậu xử lý

APIThời gian điển hình
Remesh2 min
Trải UV35 s
Chuyển đổi7 s
Đổi kích thước15 s

In 3D

APICấu hìnhThời gian điển hình
Phân tích khả năng inChỉ kiểm tra lưới1 s
Kiểm tra lưới và thành mỏng10 s
Multi-ColorMỗi yêu cầu30 s
Sửa khả năng inChỉ sửa lưới10 s
Kiểm tra thành mỏng, giữ nguyên thành20 s
Kiểm tra thành mỏng, làm dày thành100 s
Auto SplitCác bộ phận màu phẳng70 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_at củ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ỉ FAILED mớ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ậpGiá 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 MB120 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 pollHeader 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.
StreamMộ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ó.