Hướng dẫn hủy tác vụ Seedance và tính phí tác vụ trong hàng đợi trên TokenLab

Các tác vụ tạo video diễn ra không đồng bộ. Khi bạn gửi một yêu cầu tạo video qua POST /v1/videos/generations, TokenLab sẽ trả về một mã định danh tác vụ và đưa tác vụ vào hàng đợi. Nếu yêu cầu bị gửi nhầm, bị trùng lặp do thử lại mạng, hoặc bị người dùng cuối hủy bỏ, việc hủy tác vụ trong khi tác vụ vẫn còn trong hàng đợi sẽ giúp tránh tiêu tốn tài nguyên tính toán và chi phí tạo không cần thiết.

Hướng dẫn này giải thích cách gọi endpoint hủy tác vụ, xử lý mã phản hồi API, cũng như quản lý việc tạm giữ thanh toán và các bước chuyển trạng thái khi thăm dò (polling).

Cách thức hoạt động của tính năng hủy tác vụ

Việc hủy tác vụ nhắm vào các tác vụ không đồng bộ vẫn đang nằm trong hàng đợi ở trạng thái pending. Một khi worker của mô hình bắt đầu tạo khung hình (chuyển tác vụ sang processing) hoặc tác vụ đạt đến trạng thái kết thúc (completed hoặc failed), việc hủy bỏ sẽ không thể thực hiện được nữa.

TokenLab hỗ trợ hủy đối với các mô hình video Seedance đang trong hàng đợi bao gồm seedance-2.0, seedance-2.0-fast, và seedance-2.5. Đối với các tích hợp sử dụng endpoint tương thích với Volcengine, hãy xem tài liệu tham khảo Hủy tác vụ tương thích Volc.

Các trạng thái trong vòng đời tác vụ

• pending: Tác vụ đã vào hàng đợi và đang chờ worker khả dụng. Việc hủy được hỗ trợ trong khoảng thời gian này.
• processing: Quá trình thực thi mô hình đã bắt đầu. Các yêu cầu hủy sẽ bị từ chối.
• completed: Quá trình tạo video đã hoàn tất thành công. Kết quả đã sẵn sàng.
• failed: Tác vụ gặp lỗi hoặc đã bị hủy trước khi thực thi.

Cơ chế tính phí và tạm giữ

Theo hướng dẫn Thanh toán và Định giá của TokenLab, việc thanh toán cho các tác vụ media không đồng bộ tuân theo mô hình hai giai đoạn gồm tạm giữ (reservation) và quyết toán (settlement):

1. Ủy quyền trước / Tạm giữ: Khi một tác vụ video không đồng bộ được tiếp nhận, TokenLab có thể tạm giữ hoặc bảo lưu một khoản ước tính dựa trên mô hình và các tham số đã chọn.
2. Quyết toán: Khoản phí cuối cùng chỉ được quyết toán khi tác vụ đạt trạng thái completed. Các tác vụ đã hoàn thành sẽ đính kèm một billing_transaction_id đại diện cho mục ghi sổ cái cuối cùng.
3. Hủy và Thất bại: Các tác vụ kết thúc ở trạng thái failed—bao gồm cả các tác vụ bị hủy khi còn trong hàng đợi—sẽ không bị tính phí. Bất kỳ khoản tạm giữ chưa sử dụng nào sẽ được giải phóng hoàn trả về số dư workspace của bạn.

Vì một tác vụ bị hủy trong hàng đợi không bao giờ hoàn tất quá trình tạo, tác vụ đó sẽ không tạo ra một khoản quyết toán thanh toán hoàn tất.

Hủy tác vụ trong hàng đợi qua API

Để hủy một tác vụ, hãy gửi yêu cầu DELETE tới /v1/tasks/{id} kèm theo ID tác vụ được trả về trong quá trình tạo. Để biết chi tiết đầy đủ về schema, vui lòng tham khảo Tài liệu tham khảo API Hủy tác vụ.

Ví dụ yêu cầu

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

Phản hồi thành công (HTTP 200)

Khi một tác vụ được hủy thành công trước khi bắt đầu thực thi, API sẽ phản hồi bằng HTTP 200. Trạng thái tác vụ chuyển trực tiếp sang failed, được đánh dấu bằng cancelled: true:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "failed",
  "cancelled": true,
  "cancellation_status": "cancelled",
  "error": "Task cancelled before execution"
}

Mã lỗi và xử lý trường hợp bị từ chối

Đừng mặc định rằng lệnh gọi DELETE luôn thành công. Ứng dụng của bạn phải xử lý các trạng thái lỗi HTTP cụ thể:

Mã HTTP	Mã lỗi	Ý nghĩa	Hành động khuyến nghị
400	unsupported_task_cancel	Mô hình hoặc loại tác vụ không hỗ trợ việc hủy.	Để tác vụ hoàn thành bình thường hoặc kiểm tra lại hỗ trợ của mô hình.
403	task_not_owned	API key không sở hữu tác vụ này.	Xác minh thông tin xác thực workspace và phạm vi của API key.
404	async_task_not_found	ID tác vụ không tồn tại hoặc đã hết hạn.	Xác nhận lại ID tác vụ được lưu trữ trong cơ sở dữ liệu hàng đợi cục bộ của bạn.
409	task_not_cancellable	Tác vụ đã bắt đầu processing hoặc đang ở trạng thái kết thúc (completed/failed).	Chấp nhận rằng quá trình tạo đã diễn ra; không thử lại lệnh gọi xóa trong một vòng lặp.

Thăm dò (Polling) các tác vụ đã hủy

Khi thăm dò trạng thái tác vụ qua GET /v1/tasks/{id} hoặc poll_url được trả về (như được ghi lại trong hướng dẫn Tác vụ không đồng bộ và Thăm dò), hãy ghi nhớ các hành vi sau:

1. HTTP 200 trên các tác vụ đã kết thúc: Việc đọc trạng thái của một tác vụ thất bại hoặc đã bị hủy sẽ trả về HTTP 200. Hãy kiểm tra các trường status và cancelled trong thân JSON thay vì chỉ dựa vào mã phản hồi HTTP.
2. Nhận diện trạng thái: Một tác vụ đã hủy sẽ hiển thị "status": "failed", "cancelled": true, và "cancellation_status": "cancelled".
3. Không có ID quyết toán: Các tác vụ đã hủy sẽ không chứa billing_transaction_id do không có quyết toán tính phí nào diễn ra.

import time
import requests

def cancel_and_verify(task_id: str, api_key: str):
    url = f"https://api.tokenlab.sh/v1/tasks/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    # Attempt cancellation
    cancel_res = requests.delete(url, headers=headers)
    if cancel_res.status_code == 200:
        data = cancel_res.json()
        if data.get("cancelled"):
            print(f"Task {task_id} successfully cancelled.")
            return True
    elif cancel_res.status_code == 409:
        print(f"Task {task_id} already in progress or terminal; cannot cancel.")
    else:
        print(f"Cancellation rejected with HTTP {cancel_res.status_code}: {cancel_res.text}")

    # Poll task to determine terminal state
    poll_res = requests.get(url, headers=headers)
    if poll_res.ok:
        status_data = poll_res.json()
        print(f"Current status: {status_data.get('status')}, cancelled: {status_data.get('cancelled', False)}")
    return False

Danh sách kiểm tra tích hợp hàng đợi trong môi trường Production

Khi tích hợp các luồng công việc video Seedance vào kiến trúc worker, hãy tuân theo các phương pháp hay nhất sau:

• Lưu trữ ID ngay lập tức: Lưu trữ cả id (hoặc task_id) và poll_url từ phản hồi của POST /v1/videos/generations trước khi điều phối công việc ở hạ nguồn.
• Loại bỏ trùng lặp khi gửi: Ngăn chặn việc tạo tác vụ ngoài ý muốn bằng cách khử trùng lặp các cú nhấp đúp phía client và các lần thử lại mạng ở thượng nguồn trước khi tạo tác vụ.
• Xử lý 409 như một lỗi không nghiêm trọng: Nếu một yêu cầu hủy trả về 409 task_not_cancellable, hãy coi đó là dấu hiệu cho thấy quá trình xử lý đã bắt đầu. Chuyển sang phương án dự phòng là chờ kết quả và loại bỏ dữ liệu đầu ra nếu không còn cần thiết.
• Phân tích cờ đánh dấu hủy: Trong vòng lặp thăm dò của bạn, hãy kiểm tra cả status == "failed" và cancelled is True để phân biệt các trường hợp hủy do người dùng khởi tạo với các lỗi cơ sở hạ tầng.
• Đối soát thanh toán bằng mã giao dịch: Chỉ lưu trữ billing_transaction_id khi nó xuất hiện trên các tác vụ đã hoàn thành. Đừng mong đợi mã giao dịch xuất hiện trên các tác vụ đã hủy hoặc thất bại.

Để biết thêm các mẫu tích hợp khác, hãy xem Hướng dẫn tạo video và Tài liệu tham khảo API Lấy trạng thái video.