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

Các tác vụ tạo bằng Meshy API (Text to 3D, Image to 3D, Rigging, v.v.) chạy bất đồng bộ — bạn gửi tác vụ rồi cần biết khi nào tác vụ 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 tác vụ và hai cách được hỗ trợ để biết khi nào một tác vụ đã xong: polling và webhook — cùng với cách tránh sự cố phổ biến nhất là "lỗi khi lấy mô hình".

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

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

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

• SUCCEEDED — tác vụ đã hoàn thành thành công và progress là 100. Các URL kết quả (tệp mô hình, texture, ảnh xem trước) hiện đã có trong phản hồi.

• FAILED — tác vụ không thể hoàn thành. Credit cho các tác vụ bị lỗi được tự động hoàn lại.

• CANCELED — tác vụ đã 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ố lấy hoặc sử dụng URL kết quả cho đến khi status của tác vụ là SUCCEEDED. Đọc kết quả khi tác vụ vẫn còn PENDING hoặc IN_PROGRESS là nguyên nhân phổ biến nhất của các báo cáo "lỗi khi lấy mô hình".

Polling nghĩa là liên tục gọi endpoint "get task" cho task ID của bạn cho đến khi tác vụ đạ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 và lưu id của tác vụ được trả về.

• Gọi endpoint "retrieve task" tương ứng (ví dụ: endpoint lấy tác vụ theo id của Text to 3D hoặc Image to 3D) theo một khoảng thời gian — thường là vài giây.

• Kiểm tra trường status trong mỗi phản hồi. Tiếp tục polling 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 giới hạn timeout/số lần thử hợp lý trong client để một tác vụ bị kẹt không polling mãi mãi.

Polling đơn giản và phù hợp với script, tác vụ hàng loạt và các tích hợp có lưu lượng thấp. Với các tích hợp lưu lượng cao hoặc yêu cầu độ trễ thấp, 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 tác vụ hoàn tất. Để sử dụng webhook:

• Cấu hình URL webhook (callback) mà Meshy có thể truy cập — thông thường được đặt ở cấp tài khoản/cài đặt API hoặc được truyền dưới dạng tham số trong yêu cầu tạo, 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 (trả về trạng thái 2xx ngay lập tức, sau đó xử lý payload một cách bất đồng bộ).

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

• Khi nhận được, hãy tra cứu đầy đủ chi tiết tác vụ theo id 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à mới 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 những tác vụ mà việc gửi webhook có thể bị bỏ lỡ hoặc bị 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 lũy đẳng — an toàn khi chạy nhiều lần cho cùng một tác vụ mà không gây tác dụng phụ. Điều này quan trọng vì:

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

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

Để duy trì tính lũy đẳng, hãy dựa logic xử lý của bạn vào id của tác vụ — 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 là đã xử lý" thành một bước nguyên tử duy nhất trong cơ sở dữ liệu của bạn.

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

• Kiểm tra status === "SUCCEEDED" trước khi đọc bất kỳ thứ gì từ các trường result/URL mô hình.

• Đừ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 tác vụ được hoàn tất hoàn toàn.

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

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

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

• Tài nguyên đã hết hạn. Chờ quá lâu sau SUCCEEDED mới tải xuống — URL kết quả sẽ ngừng hoạt động sau khi khoảng thời gian lưu giữ cho loại tác vụ đó trôi qua.

• Dùng ID tác vụ cũ hoặc sai — ví dụ, dùng lại ID từ mộ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 tác vụ đã thất bại thay vì gửi lại.

• Sự cố mạng/timeout giữa máy chủ của bạn và Meshy bị hiểu nhầm thành lỗi tạo.

Nếu một lần tạo 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ểm sau:

• API Meshy hiện không hỗ trợ thử lại một tác vụ hiện có tại chỗ — để thử lại, hãy gửi một yêu cầu tạo mới, yêu cầu này sẽ tiêu tốn tín dụng 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 chờ một khoảng thời gian ngắn với exponential backoff trước khi gửi lại yêu cầu là hợp lý.

• Đối với 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 poll thất bại là thất bại của quá trình tạo — chỉ tin tưởng vào 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 các lần tạo, hãy liên hệ với nhóm bán hàng của Meshy để tìm hiểu về các tùy chọn gói doanh nghiệp.

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

Polling dễ thiết lập hơn và phù hợp cho các script có lưu lượng thấp hoặc chạy một lần. Webhook phù hợp hơn cho các tích hợp production với nhiều tác vụ 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 tác vụ hoàn thành.

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

Quay lại polling tác vụ theo id trực tiếp. Cũng 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, vì endpoint chậm hoặc không thể truy cập có thể gây ra vấn đề giao hàng.

Hiện tại không — bạn cần gửi một yêu cầu tạo mới, yêu cầu này tiêu tốn credits bình thường. Liên hệ bộ phận kinh doanh về các tùy chọn enterprise 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 giữ trên máy chủ của Meshy trong một thời gian giới hạn sau khi tác vụ hoàn thành, vì vậy hãy tải outputs về bộ nhớ của riêng bạn ngay khi tác vụ thành công thay vì đợi.