TokenLab

Hướng dẫn cốt lõi

Các tác vụ bất đồng bộ và polling

Tạo các tác vụ media và chờ kết quả hoàn thành

Nhiều endpoint media trả về một tác vụ thay vì tệp hoàn chỉnh. Hãy lưu ID tác vụ được trả về và thực hiện polling GET /v1/tasks/{id} cho đến khi trạng thái là completed (hoàn thành) hoặc failed (thất bại). Endpoint này phục vụ cho các tác vụ hình ảnh, video, âm nhạc, 3D, Worlds và chuyển đổi âm thanh sang văn bản bất đồng bộ.

Các bản ghi nhanh (snapshot) của tác vụ terminal bất đồng bộ có vòng đời tách biệt với cửa sổ lưu trữ request/response 30 ngày. Các URL tệp hình ảnh, video, âm thanh, 3D và Worlds được tạo là các URL kết quả media của TokenLab, có hiệu lực trong 30 ngày. Việc đọc trạng thái của các tác vụ đã hoàn thành chỉ hoạt động trong khoảng 7 ngày, vì vậy hãy lưu kết quả ngay khi tác vụ hoàn tất. Các trường media_retention trong phản hồi báo cáo trạng thái lưu trữ và expires_at của từng mục; các trường này có thể không xuất hiện khi trạng thái lưu trữ không được xác định kịp thời, nhưng URL vẫn hoạt động. Các tác vụ thất bại hoặc đang thực hiện sẽ trả về các trường URL media trống. Xem Lưu trữ dữ liệu.

Các trường cần lưu

Phản hồi tạo tác vụ có thể bao gồm:

TrườngÝ nghĩaViệc cần làm
idID tác vụ TokenLabLưu trữ cùng với bản ghi công việc của bạn
task_idMột tên gọi khác của cùng ID tác vụXử lý tương đương với id
statusTrạng thái tác vụ hiện tạiTiếp tục kiểm tra cho đến khi hoàn thành hoặc thất bại
poll_urlURL trạng thái của tác vụLưu trữ; thực hiện polling /v1/tasks/{id} với ID tác vụ
modelModel được sử dụng cho tác vụLưu trữ cùng với bản ghi tác vụ

Một endpoint trạng thái duy nhất

Thực hiện polling GET /v1/tasks/{id} với id hoặc task_id từ phản hồi tạo tác vụ. Nó hoạt động cho mọi loại tác vụ. Đối với hầu hết các tác vụ, poll_url chính là đường dẫn này. Phản hồi tạo Worlds trả về một poll_url dưới dạng /v1/worlds/generations/{id}; hãy thực hiện polling /v1/tasks/{id} với id của tác vụ cho cả Worlds.

Các đường dẫn trạng thái theo từng phương thức (modality), chẳng hạn như /v1/videos/generations/{id}, vẫn được hỗ trợ cho các tích hợp hiện có. Các tích hợp mới nên sử dụng /v1/tasks/{id}.

Lưu tác vụ và kiểm tra trạng thái

Lưu id hoặc task_id ngay khi request tạo tác vụ thành công. Lưu trữ poll_url, model, endpoint và ID người dùng hoặc ID công việc của riêng bạn cùng với nó. Đối với các tác vụ media dài, việc kiểm tra mỗi 5–10 giây thường là đủ.

Dừng lại khi trạng thái trở thành completed hoặc failed. Một tác vụ hoàn thành chứa kết quả media; một tác vụ thất bại chứa lỗi mà bạn có thể hiển thị hoặc ghi log. Việc thử lại một tác vụ tạo thất bại sẽ tạo ra một tác vụ mới và có thể phát sinh phí mới.

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

Ví dụ về Polling

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

Các trạng thái bao gồm pending, processing, completed và failed. Một tác vụ bị hủy sử dụng trạng thái failed cùng với cancelled: true và cancellation_status: "cancelled".

Việc đọc trạng thái thành công sẽ trả về HTTP 200 ngay cả khi tác vụ đã thất bại. Hãy sử dụng status của tác vụ để quyết định xem việc tạo có thành công hay không. Trường error giữ nguyên định dạng chuỗi hoặc đối tượng của nó. Các tác vụ thất bại cũng có thể bao gồm error_details với status (trạng thái lỗi nghiệp vụ), type, code, message, param và retryable. Ví dụ: error_details.status: 400 với param: "size" nghĩa là request cần được sửa đổi; điều này không có nghĩa là bản thân request trạng thái bị lỗi. param sẽ bị lược bỏ khi không xác định được trường cụ thể nào. Khi error_details.projection_version là 2, message là lý do cuối cùng dẫn đến thất bại, thường là giải thích từ dịch vụ thượng nguồn (upstream), chẳng hạn như giới hạn tham số hoặc quyết định về chính sách nội dung. Đối với tác vụ chạy trên route Official, error_details.upstream cũng mang lỗi từ thượng nguồn như đã báo cáo: message, cộng với code, param và source (tên dịch vụ thượng nguồn) khi được biết. Hãy tiếp tục phân nhánh dựa trên code và type; các giá trị upstream.code được định nghĩa bởi dịch vụ thượng nguồn và có thể thay đổi.

Các lỗi từ chối request tạo tác vụ trước khi tác vụ được chấp nhận sẽ sử dụng trạng thái lỗi HTTP thông thường và đối tượng error có cấu trúc. Việc lặp lại cùng một request tạo tác vụ idempotent sẽ bảo toàn sự từ chối đó. Việc đọc trạng thái thất bại không làm thay đổi trạng thái terminal của tác vụ.

Tránh các tác vụ trùng lặp

Hầu hết các tác vụ tạo trùng lặp đến từ việc thử lại request tạo tác vụ sau khi hết thời gian chờ (timeout).

Nơi xảy ra timeoutHành vi an toàn hơn
Trước khi server của bạn nhận được phản hồi tạo tác vụGửi lại cùng một request với cùng Idempotency-Key để nhận tác vụ gốc. Nếu không có key, hãy kiểm tra request_id và chỉ thử lại nếu chưa có tác vụ nào được tạo
Sau khi phản hồi tạo tác vụ đã được lưuTiếp tục polling task_id đã lưu
Trong khi pollingThử lại request trạng thái với cơ chế backoff
Sau trạng thái terminalKhông polling lại trừ khi người dùng chủ động làm mới bản ghi

Không gửi request tạo tác vụ thứ hai chỉ vì trình duyệt đã làm mới hoặc việc polling trạng thái thất bại.

Bản ghi thanh toán

Một tác vụ bất đồng bộ có thể đặt trước chi phí ước tính khi được chấp nhận. Số tiền cuối cùng được ghi lại sau khi tác vụ hoàn thành hoặc thất bại. Các phản hồi trạng thái có thể bao gồm billing_transaction_id và header X-Billing-Transaction-ID.

Hãy giữ các định danh này cùng nhau:

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

Hủy tác vụ

DELETE /v1/tasks/{id} có thể hủy các tác vụ video Seedance được hỗ trợ khi chúng vẫn đang trong hàng đợi, bao gồm seedance-2.0 và seedance-2.0-fast.

Các tác vụ không được hỗ trợ sẽ trả về 400 unsupported_task_cancel. Một tác vụ đang chạy hoặc đã hoàn thành sẽ trả về 409 task_not_cancellable. Hủy tác vụ là một yêu cầu, không đảm bảo rằng công việc đang thực hiện sẽ dừng lại ngay lập tức. Việc hủy thành công trả về 200 với status: "failed", cancelled: true và cancellation_status: "cancelled". Tác vụ bị hủy sẽ không bị tính phí.

Khắc phục sự cố

Triệu chứngNguyên nhân có thểViệc cần kiểm tra
404 async_task_not_foundID tác vụ không xác định, thuộc về workspace khác, hoặc tác vụ đã hoàn thành nằm ngoài cửa sổ trạng tháiKiểm tra task_id đã lưu và workspace của API key
403 task_not_ownedKhông thể xác nhận quyền sở hữu tác vụ cho workspace hiện tạiXác nhận workspace hoặc tổ chức liên kết với API key
503 async_task_owner_unavailableKhông thể kiểm tra quyền sở hữu tác vụ ngay lúc này. retryable là trueThử lại request trạng thái với cơ chế backoff
Tác vụ không bao giờ hoàn thànhClient liên tục polling sai URL hoặc dừng trước khi đạt trạng thái terminalPolling GET /v1/tasks/{id} với ID tác vụ đã lưu và kiểm tra trạng thái mới nhất
Thiếu URL media cuối cùngTác vụ chưa hoàn thành, hoặc đã hoàn thành mà không có tệp khả dụngTiếp tục polling cho đến khi hoàn tất, sau đó xử lý kết quả 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 tác vụ mới sau khi timeout hoặc làm mớiKhử trùng lặp bằng ID công việc của riêng bạn và task_id đã lưu
Sai lệch thanh toánThanh toán cuối cùng chưa được ghi lại, hoặc các ID sai đang được so sánhSo sánh request_id, task_id và billing_transaction_id

Những gì cần gửi cho bộ phận hỗ trợ

Bao gồm request_id, task_id, billing_transaction_id khi có, endpoint, model, thời gian và tên các trường bạn đã gửi. Không bao giờ gửi API key, media riêng tư, URL đã ký hoặc toàn bộ prompt trừ khi bộ phận hỗ trợ yêu cầu cụ thể một ví dụ đã được che thông tin nhạy cảm.

Tài liệu tham khảo API

Chủ đềTham khảo
Lấy trạng thái tác vụLấy trạng thái tác vụ
Hủy tác vụHủy tác vụ
Tạo hình ảnhTạo hình ảnh
Tạo videoTạo video
Tạo âm nhạcTạo âm nhạc
Tạo 3DTạo 3D
Thanh toán & Giá cảThanh toán & Giá cả

Dừng polling các tác vụ terminal, và dừng lại khi gặp 401, 403, 404 hoặc một lỗi không thể thử lại. Để nhận kết quả tác vụ mà không cần polling, hãy cấu hình API quản lý Webhook với một mt-… Management Token.

Các phản hồi tác vụ cũng mang các header X-Task-ID, X-Task-Type và X-Billing-Transaction-ID, bạn có thể ghi log các thông tin này bên cạnh ID tác vụ.

Trên trang này