TokenLab Seedance Task Cancellation and Queued Job Billing Guide

Video generation tasks are asynchronous. When you submit a video generation request via POST /v1/videos/generations, TokenLab returns a task identifier and enqueues the job. If a request is submitted by mistake, duplicated during a network retry, or abandoned by an end user, cancelling the task while it remains queued prevents unnecessary compute and generation charges.

This guide explains how to call the task cancellation endpoint, handle API response codes, and manage billing reservations and polling transitions.

How Task Cancellation Works

Task cancellation targets asynchronous jobs that are still queued in a pending state. Once a model worker begins generating frames (transitioning the task to processing) or the task reaches a terminal state (completed or failed), cancellation can no longer take place.

TokenLab supports cancellation on queued Seedance video models including seedance-2.0, seedance-2.0-fast, and seedance-2.5. For integrations using the Volcengine compatibility endpoint, see the Volc Compatible Task Cancellation reference.

Task Lifecycle States

• pending: The task is enqueued and waiting for an available worker. Cancellation is supported in this window.
• processing: Model execution has begun. Cancellation requests will be rejected.
• completed: Video generation finished successfully. The result is ready.
• failed: The task encountered an error or was cancelled before execution.

Charge and Reservation Semantics

According to TokenLab's Billing and Pricing guide, billing for asynchronous media jobs follows a two-phase reservation and settlement model:

1. Pre-authorization / Reservation: When an async video task is accepted, TokenLab may hold or reserve an estimated amount based on the selected model and parameters.
2. Settlement: The final charge is settled only when the task reaches completed. Completed tasks attach a billing_transaction_id representing the final ledger entry.
3. Cancellation and Failure: Tasks that finish in a failed state—including those cancelled while queued—are not charged. Any unused reservation or temporary hold is released back to your workspace balance.

Because a task cancelled in the queue never completes generation, it does not produce a completed billing settlement.

Cancelling a Queued Task via API

To cancel a task, issue a DELETE request to /v1/tasks/{id} with the task ID returned during creation. For complete schema details, consult the Cancel Task API reference.

Request Example

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

Success Response (HTTP 200)

When a task is successfully cancelled before execution starts, the API responds with HTTP 200. The task status transitions directly to failed, marked with 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"
}

Error Codes and Rejection Handling

Do not assume a DELETE call always succeeds. Your application must handle specific HTTP error statuses:

HTTP Status	Error Code	Meaning	Recommended Action
400	unsupported_task_cancel	The model or task type does not support cancellation.	Let the task finish normally or review model support.
403	task_not_owned	The API key does not own the task.	Verify workspace credentials and API key scope.
404	async_task_not_found	The task ID does not exist or has expired.	Confirm the task ID stored in your local queue database.
409	task_not_cancellable	The task has already started processing or is in a terminal state (completed/failed).	Accept that generation is already underway; do not retry the delete call in a loop.

Polling Cancelled Tasks

When polling a task via GET /v1/tasks/{id} or the returned poll_url (as documented in the Async Jobs and Polling guide), keep the following behaviors in mind:

1. HTTP 200 on Terminal Tasks: Reading the status of a failed or cancelled task returns HTTP 200. Inspect the JSON body's status and cancelled fields rather than relying on HTTP response codes.
2. Status Identification: A cancelled task displays "status": "failed", "cancelled": true, and "cancellation_status": "cancelled".
3. Absence of Settlement IDs: Cancelled tasks will not contain a billing_transaction_id since no charge settlement occurred.

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

Production Queue Integration Checklist

When integrating Seedance video workflows into worker architectures, follow these best practices:

• Persist IDs Immediately: Store both id (or task_id) and poll_url from the POST /v1/videos/generations response before dispatching downstream work.
• Deduplicate at Submit: Prevent accidental task generation by deduplicating client-side double clicks and upstream network retries before creating tasks.
• Handle 409 as Non-Fatal: If a cancellation request returns 409 task_not_cancellable, treat it as an indication that processing has started. Fall back to waiting for the result and discarding output if no longer required.
• Parse the Cancellation Marker: In your polling loop, check both status == "failed" and cancelled is True to distinguish user-initiated cancellations from infrastructure errors.
• Reconcile Billing Using Transaction IDs: Store billing_transaction_id only when present on completed jobs. Do not expect transaction IDs on cancelled or failed tasks.

For additional integration patterns, review the Video Generation Guide and Get Video Status API Reference.