Meshy API Webhooks so với Polling: Khi nào Kết quả Sẵn sàng

Các tác vụ tạo sinh của Meshy API (Text to 3D, Image to 3D, Rigging, v.v.) chạy không đồng bộ — bạn gửi một task và sau đó cần biết khi nào task hoàn tất trước khi lấy kết quả. Bài viết này giải thích vòng đời của task và hai cách được hỗ trợ để biết khi nào một task đã hoàn thành: polling và webhooks — cùng cách tránh vấn đề phổ biến nhất là "lỗi khi tải model".

Mỗi tác vụ tạo sinh đi qua một tập hợp trạng thái nhỏ, được trả về trong trường status của đối tượng task:

• PENDING — task đã được đưa vào hàng đợi nhưng chưa bắt đầu xử lý.

• IN_PROGRESS — task đang được xử lý. Trường progress (0-100) tăng dần khi công việc hoàn thành.

• SUCCEEDED — task hoàn thành thành công và progress là 100. Các URL kết quả (tệp model, texture, bản xem trước) giờ đã có sẵn trong phản hồi.

• FAILED — task không thể hoàn thành. Credits của các task thất bại sẽ được hoàn lại tự động.

• CANCELED — task đã bị hủy trước khi hoàn thành.

Quy tắc quan trọng nhất khi tích hợp với API: không bao giờ cố gắng tải hoặc sử dụng các URL kết quả cho đến khi status của task là SUCCEEDED. Việc đọc kết quả khi task vẫn đang ở trạng thái PENDING hoặc IN_PROGRESS là nguyên nhân phổ biến nhất dẫn đến các báo cáo "lỗi khi tải model".

Polling nghĩa là liên tục gọi endpoint "get task" cho ID task của bạn cho đến khi nó đạt trạng thái kết thúc (SUCCEEDED, FAILED hoặc CANCELED). Một vòng lặp polling đơn giản trông như sau:

• Gửi yêu cầu tạo sinh và lưu lại task id được trả về.

• Gọi endpoint "retrieve task" tương ứng (ví dụ: endpoint task-by-id của Text to 3D hoặc Image to 3D) theo chu kỳ — thường là vài giây một lần.

• Kiểm tra trường status trong mỗi phản hồi. Tiếp tục polling trong khi trạng thái là PENDING hoặc IN_PROGRESS.

• Dừng polling ngay khi status là SUCCEEDED (đọc các URL kết quả), FAILED hoặc CANCELED.

• Thêm cơ chế giới hạn thời gian chờ/số lần thử hợp lý trong client của bạn để một task bị kẹt không làm polling chạy mãi mãi.

Polling rất đơn giản và hoạt động tốt cho các script, công việc hàng loạt và tích hợp có khối lượng thấp. Đối với các tích hợp khối lượng cao hoặc nhạy cảm với độ trễ, webhook thường là lựa chọn phù hợp hơn.

Thay vì liên tục hỏi "xong chưa?", bạn có thể yêu cầu Meshy thông báo cho máy chủ của bạn ngay khi một task hoàn tất. Để sử dụng webhook:

• Cấu hình một URL webhook (callback) mà Meshy có thể truy cập — URL này thường được thiết lập ở cấp cài đặt tài khoản/API hoặc được truyền dưới dạng tham số trong yêu cầu tạo sinh, tùy thuộc vào endpoint.

• Đảm bảo endpoint của bạn có thể truy cập công khai qua HTTPS và phản hồi nhanh chóng (trả về trạng thái 2xx ngay lập tức, sau đó xử lý payload không đồng bộ).

• Khi task đạt trạng thái kết thúc, Meshy sẽ gửi một payload đến endpoint của bạn chứa task id và status cuối cùng của nó.

• Khi nhận được, hãy tra cứu chi tiết đầy đủ của task theo id thông qua API thay vì chỉ tin vào nội dung webhook, để đảm bảo bạn có kết quả chính xác và cập nhật nhất.

Webhook giúp giảm các lệnh gọi API không cần thiết và mang lại thông báo gần như tức thì, nhưng bạn vẫn nên duy trì cơ chế polling định kỳ dự phòng cho các task mà việc gửi webhook có thể bị bỏ lỡ hoặc trễ (ví dụ: do sự cố mạng tạm thời ở phía bạn).

Dù bạn dùng polling hay webhook, mã xử lý kết quả của bạn nên có tính idempotent — an toàn khi chạy nhiều lần cho cùng một task mà không gây ra tác dụng phụ. Điều này quan trọng vì:

• Một webhook có thể được gửi nhiều lần cho cùng một task (thử lại từ phía người gửi, trùng lặp mạng, v.v.).

• Vòng lặp polling và trình xử lý webhook có thể cùng cố gắng xử lý một task đã hoàn thành nếu cả hai đều đang chạy.

Để duy trì tính idempotent, hãy xây dựng logic xử lý của bạn dựa trên task id — ví dụ: kiểm tra xem bạn đã lưu/tải kết quả cho id đó chưa trước khi làm lại, và biến "đánh dấu đã xử lý" thành một bước nguyên tử (atomic) duy nhất trong cơ sở dữ liệu của bạn.

Một phản hồi với "status": "SUCCEEDED" và "progress": 100 là tín hiệu duy nhất đảm bảo payload kết quả (URL model, texture, hình thu nhỏ) đã hoàn chỉnh và an toàn để sử dụng. Cụ thể, trong mã của bạn:

• Xác minh status === "SUCCEEDED" trước khi đọc bất kỳ nội dung nào từ các trường result/URL model.

• Đừng chỉ dựa vào progress — luôn kiểm tra cả status, vì progress có thể tạm thời hiển thị giá trị cao trước khi task được hoàn tất hoàn toàn.

• Tải các tệp kết quả ngay sau khi SUCCEEDED — các tài sản được tạo ra chỉ được lưu giữ trên máy chủ của Meshy trong một khoảng thời gian hạn chế, sau đó các URL sẽ không còn hoạt động.

Hầu hết các báo cáo "tôi không thể tải model của mình" đều bắt nguồn từ một trong những nguyên nhân sau:

• Tải quá sớm. Gọi URL kết quả, hoặc đọc các trường model, trước khi status là SUCCEEDED. Đây là nguyên nhân phổ biến nhất.

• Tài sản đã hết hạn. Chờ quá lâu sau khi SUCCEEDED mới tải — các URL kết quả ngừng hoạt động sau khi thời gian lưu giữ cho loại task đó đã qua.

• Sử dụng task ID cũ hoặc sai — ví dụ: tái sử dụng một ID từ yêu cầu trước đó không liên quan.

• Coi FAILED là trạng thái tạm thời và tiếp tục polling một task đã thất bại thay vì gửi lại yêu cầu.

• Sự cố mạng/timeout giữa máy chủ của bạn và Meshy bị nhầm lẫn thành vấn đề khi tạo sinh.

Nếu một kết quả tạo sinh không đáp ứng kỳ vọng của bạn, hoặc một yêu cầu thất bại hoàn toàn, hãy lưu ý những điều sau:

• Meshy API hiện không hỗ trợ thử lại một task hiện có tại chỗ — để thử lại, hãy gửi một yêu cầu tạo sinh mới, yêu cầu này sẽ tiêu tốn credits như bình thường.

• Đối với các lỗi mạng tạm thời khi gọi API (timeout, phản hồi 5xx), việc sử dụng exponential backoff ngắn trước khi gửi lại yêu cầu là hợp lý.

• Đối với bản thân việc polling, hãy thử lại lệnh gọi "get task" khi gặp lỗi mạng tạm thời, nhưng đừng coi một lần polling thất bại là thất bại khi tạo sinh — chỉ tin tưởng trường status khi bạn nhận được phản hồi thành công.

• Nếu bạn cần chức năng thử lại tích hợp sẵn cho việc tạo sinh, hãy liên hệ với đội ngũ bán hàng của Meshy để tìm hiểu về các gói doanh nghiệp.

Điều này hầu như luôn xảy ra vì mã đang cố đọc kết quả trước khi task hoàn thành. Luôn xác nhận status là SUCCEEDED (và progress là 100) trước khi tải các URL model.

Polling đơn giản hơn để thiết lập và phù hợp với các script có khối lượng thấp hoặc dùng một lần. Webhook tốt hơn cho các tích hợp sản phẩm với nhiều task chạy đồng thời, vì chúng tránh được các yêu cầu lặp lại không cần thiết và thông báo cho bạn ngay khi task hoàn thành.

Xử lý theo cách idempotent — kiểm tra task id với những gì bạn đã xử lý, và bỏ qua việc xử lý lại nếu đã được xử lý rồi.

Hãy chuyển sang polling task trực tiếp theo id. Đồng thời xác nhận endpoint của bạn có thể truy cập công khai qua HTTPS và trả về phản hồi 2xx nhanh chóng, vì các endpoint chậm hoặc không thể truy cập có thể gây ra sự cố khi gửi.

Hiện chưa — bạn cần gửi một yêu cầu tạo sinh mới, yêu cầu này sẽ tiêu tốn credits như bình thường. Liên hệ với bộ phận bán hàng về các tùy chọn doanh nghiệp nếu bạn cần hỗ trợ thử lại tích hợp sẵn.

Các tệp kết quả chỉ được lưu giữ trên máy chủ của Meshy trong một khoảng thời gian hạn chế sau khi task hoàn thành, vì vậy hãy tải kết quả về bộ lưu trữ của bạn ngay khi task thành công thay vì chờ đợi.

• Tại sao tôi liên tục gặp lỗi khi tải Model từ kết quả tạo sinh bằng API?