Công Việc Không Đồng Bộ & Kiểm Tra

Nhiều điểm cuối truyền thông là không đồng bộ. Một yêu cầu tạo bắt đầu công việc và trả về một danh tính công việc TokenLab công khai; ứng dụng của bạn sẽ kiểm tra cho đến khi công việc đó đạt trạng thái cuối cùng. Không xây dựng quy trình làm việc của khách hàng xung quanh các URL công việc upstream, ID định tuyến, hoặc hành vi callback của nhà cung cấp.

Hợp Đồng Công Việc Công Khai

Các phản hồi tạo có thể bao gồm:

Trường	Ý nghĩa	Hành động
`id`	ID công việc TokenLab công khai	Lưu trữ nó cùng với bản ghi công việc của bạn
`task_id`	Bí danh tương thích cho cùng một danh tính công việc công khai	Xem nó như tương đương với `id`
`status`	Trạng thái công việc công khai hiện tại	Bắt đầu kiểm tra khi nó không phải là trạng thái cuối cùng
`poll_url`	URL trạng thái ưu tiên	Sử dụng cái này trước khi có mặt
`model`	Mô hình được yêu cầu hoặc giải quyết bởi điểm cuối	Lưu trữ nó để hỗ trợ và đối chiếu thanh toán

/v1/tasks/{id} là điểm cuối trạng thái cố định chuẩn cho các công việc truyền thông không đồng bộ công khai. Các tuyến trạng thái cụ thể cho truyền thông có thể tồn tại để tương thích, nhưng các tích hợp mới nên ưu tiên poll_url hoặc /v1/tasks/{id}.

Quy Trình Được Khuyến Nghị

Xác thực yêu cầu của người dùng và gửi cuộc gọi tạo với một model rõ ràng.
Lưu trữ id / task_id, poll_url, điểm cuối, mô hình, ID người dùng, và ID công việc của bạn trước khi trả lại quyền kiểm soát cho UI.
Kiểm tra mỗi 5-10s cho các công việc truyền thông chạy lâu.
Dừng lại chỉ khi công việc đã hoàn thành hoặc thất bại.
Khi hoàn thành, đọc các trường kết quả cụ thể cho truyền thông và lưu trữ các URL hoặc siêu dữ liệu cuối cùng.
Khi thất bại, lưu trữ lỗi công khai và chỉ đề nghị thử lại như một công việc mới có thể nhìn thấy bởi người dùng.

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}

Ví Dụ Kiểm Tra

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

Các trạng thái công khai mong đợi là pending, processing, completed, và failed. Các công việc bị hủy được biểu thị là failed với cancelled: true và cancellation_status: "cancelled" để xử lý trạng thái cũ vẫn hoạt động.

Quy Tắc Thử Lại của Khách Hàng

Thời gian chờ mạng là nguồn gốc phổ biến nhất của các công việc trùng lặp. Sử dụng quy tắc này:

Nơi xảy ra thời gian chờ	Hành vi an toàn hơn
Trước khi máy chủ của bạn nhận được phản hồi tạo	Kiểm tra nhật ký máy chủ cho `request_id`; thử lại chỉ nếu không có công việc nào được tạo
Sau khi phản hồi tạo được lưu trữ	Tiếp tục kiểm tra `task_id` đã lưu
Trong quá trình kiểm tra	Thử lại yêu cầu trạng thái với thời gian chờ
Sau trạng thái cuối cùng	Không kiểm tra lại trừ khi người dùng làm mới bản ghi một cách rõ ràng

Không gửi yêu cầu tạo thứ hai chỉ vì trình duyệt đã làm mới hoặc một cuộc kiểm tra trạng thái thất bại.

Thanh Toán Và Giải Quyết

Các công việc không đồng bộ có thể giữ một số tiền ước tính khi yêu cầu tạo được chấp nhận. Giải quyết cuối cùng xảy ra sau trạng thái cuối cùng. Khi có sẵn, phản hồi trạng thái công việc có thể tiết lộ billing_transaction_id và tiêu đề X-Billing-Transaction-ID. Để đối chiếu, kết hợp các định danh này trong nhật ký của bạn:

request_id từ yêu cầu tạo.
task_id / id từ công việc.
billing_transaction_id khi có mặt.
ID người dùng, ID dự án, hoặc ID công việc của riêng bạn.

Hủy Bỏ

DELETE /v1/tasks/{id} được thiết kế một cách có chủ ý. Nó hiện hỗ trợ các công việc video Volcengine Seedance đang chờ như seedance-1.5-pro, seedance-2.0, và seedance-2.0-fast. Các công việc không được hỗ trợ trả về 400 unsupported_task_cancel. Các công việc đã chạy hoặc ở trạng thái cuối cùng trả về 409 task_not_cancellable. Xây dựng giao diện hủy bỏ như “yêu cầu hủy bỏ” thay vì một nút dừng đảm bảo.

Khắc Phục Sự Cố

Triệu Chứng	Nguyên Nhân Có Thể	Những gì cần kiểm tra
`async_task_not_found`	Công việc không rõ, đã hết hạn, không thể truy cập bằng khóa API này, hoặc không phải là công việc không đồng bộ công khai	Xác nhận quyền sở hữu khóa API và `task_id` công khai đã lưu
Công việc không bao giờ hoàn thành	Khách hàng tiếp tục kiểm tra URL sai hoặc dừng lại trước trạng thái cuối cùng	Sử dụng `poll_url` hoặc `/v1/tasks/{id}` và kiểm tra trạng thái mới nhất
URL truyền thông cuối cùng bị thiếu	Công việc chưa hoàn thành, hoặc công việc upstream đã hoàn thành mà không có đầu ra sử dụng được	Tiếp tục kiểm tra cho đến khi đạt trạng thái cuối cùng, sau đó xử lý đầu ra bị thiếu như thất bại
Người dùng thấy trùng lặp	Đường dẫn thử lại đã tạo một công việc mới sau thời gian chờ hoặc làm mới	Loại bỏ trùng lặp bằng ID công việc của bạn và `task_id` đã lưu
Sự không khớp trong thanh toán	Giải quyết là không đồng bộ hoặc khách hàng đang so sánh ID của nhà cung cấp	So sánh `request_id`, `task_id`, và `billing_transaction_id`

Gói Hỗ Trợ

Khi liên hệ với hỗ trợ, bao gồm request_id, task_id, billing_transaction_id khi có mặt, điểm cuối, mô hình, dấu thời gian, và hình dạng yêu cầu đã được làm sạch. Không bao gồm khóa API, truyền thông riêng tư, URL đã ký, hoặc toàn bộ yêu cầu trừ khi hỗ trợ yêu cầu một mẫu đã được chỉnh sửa.

Tài Liệu API

Chủ Đề	Tài Liệu
Lấy Trạng Thái Công Việc	Get Task Status
Hủy Công Việc	Cancel Task
Tạo Hình Ảnh	Image Generation
Tạo Video	Video Generation
Tạo Nhạc	Music Generation
Tạo 3D	3D Generation
Thanh Toán & Giá Cả	Billing & Pricing

​Hợp Đồng Công Việc Công Khai

​Quy Trình Được Khuyến Nghị

​Ví Dụ Kiểm Tra

​Quy Tắc Thử Lại của Khách Hàng

​Thanh Toán Và Giải Quyết

​Hủy Bỏ

​Khắc Phục Sự Cố

​Gói Hỗ Trợ

​Tài Liệu API