Guia de Cancelamento de Tarefas do Seedance e Cobrança de Trabalhos em Fila no TokenLab

As tarefas de geração de vídeo são assíncronas. Quando você envia uma solicitação de geração de vídeo via POST /v1/videos/generations, o TokenLab retorna um identificador de tarefa e coloca o trabalho na fila. Se uma solicitação for enviada por engano, duplicada durante uma nova tentativa de rede ou abandonada por um usuário final, cancelar a tarefa enquanto ela permanece na fila evita cobranças desnecessárias de computação e geração.

Este guia explica como chamar o endpoint de cancelamento de tarefas, tratar códigos de resposta da API e gerenciar reservas de cobrança e transições de polling.

Como Funciona o Cancelamento de Tarefas

O cancelamento de tarefas tem como alvo trabalhos assíncronos que ainda estão na fila em um estado pending. Uma vez que um worker do modelo começa a gerar quadros (fazendo a transição da tarefa para processing) ou a tarefa atinge um estado terminal (completed ou failed), o cancelamento não pode mais ocorrer.

O TokenLab oferece suporte ao cancelamento em modelos de vídeo Seedance na fila, incluindo seedance-2.0, seedance-2.0-fast e seedance-2.5. Para integrações que utilizam o endpoint de compatibilidade da Volcengine, consulte a referência de Cancelamento de Tarefa Compatível com Volc.

Estados do Ciclo de Vida da Tarefa

• pending: A tarefa está na fila e aguardando um worker disponível. O cancelamento é suportado nesta janela.
• processing: A execução do modelo começou. As solicitações de cancelamento serão rejeitadas.
• completed: A geração do vídeo foi concluída com sucesso. O resultado está pronto.
• failed: A tarefa encontrou um erro ou foi cancelada antes da execução.

Semântica de Cobrança e Reserva

De acordo com o guia de Cobrança e Preços do TokenLab, a cobrança de trabalhos de mídia assíncronos segue um modelo de reserva e liquidação em duas fases:

1. Pré-autorização / Reserva: Quando uma tarefa assíncrona de vídeo é aceita, o TokenLab pode reter ou reservar um valor estimado com base no modelo e parâmetros selecionados.
2. Liquidação: A cobrança final é liquidada apenas quando a tarefa atinge completed. Tarefas concluídas anexam um billing_transaction_id que representa o registro final no livro-razão (ledger).
3. Cancelamento e Falha: Tarefas que terminam em um estado failed — incluindo aquelas canceladas enquanto estavam na fila — não são cobradas. Qualquer reserva não utilizada ou retenção temporária é liberada de volta para o saldo do seu workspace.

Como uma tarefa cancelada na fila nunca conclui a geração, ela não produz uma liquidação de cobrança concluída.

Cancelando uma Tarefa na Fila via API

Para cancelar uma tarefa, emita uma solicitação DELETE para /v1/tasks/{id} com o ID da tarefa retornado durante a criação. Para obter detalhes completos do esquema, consulte a referência da API Cancel Task.

Exemplo de Solicitação

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

Resposta de Sucesso (HTTP 200)

Quando uma tarefa é cancelada com sucesso antes do início da execução, a API responde com HTTP 200. O status da tarefa faz a transição direta para failed, marcada com 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"
}

Códigos de Erro e Tratamento de Rejeições

Não presuma que uma chamada DELETE sempre será bem-sucedida. Sua aplicação deve tratar status de erro HTTP específicos:

Status HTTP	Código de Erro	Significado	Ação Recomendada
400	unsupported_task_cancel	O modelo ou tipo de tarefa não suporta cancelamento.	Deixe a tarefa terminar normalmente ou revise o suporte do modelo.
403	task_not_owned	A chave de API não é proprietária da tarefa.	Verifique as credenciais do workspace e o escopo da chave de API.
404	async_task_not_found	O ID da tarefa não existe ou expirou.	Confirme o ID da tarefa armazenado em seu banco de dados de fila local.
409	task_not_cancellable	A tarefa já iniciou o estado processing ou está em um estado terminal (completed/failed).	Aceite que a geração já está em andamento; não tente repetir a chamada de exclusão em loop.

Polling de Tarefas Canceladas

Ao fazer polling de uma tarefa via GET /v1/tasks/{id} ou pela poll_url retornada (conforme documentado no guia de Trabalhos Assíncronos e Polling), tenha em mente os seguintes comportamentos:

1. HTTP 200 em Tarefas Terminais: A leitura do status de uma tarefa que falhou ou foi cancelada retorna HTTP 200. Inspecione os campos status e cancelled no corpo JSON em vez de confiar nos códigos de resposta HTTP.
2. Identificação de Status: Uma tarefa cancelada exibe "status": "failed", "cancelled": true e "cancellation_status": "cancelled".
3. Ausência de IDs de Liquidação: Tarefas canceladas não conterão um billing_transaction_id, uma vez que não houve liquidação de cobrança.

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

Checklist de Integração de Filas em Produção

Ao integrar fluxos de trabalho de vídeo Seedance em arquiteturas de workers, siga estas práticas recomendadas:

• Persista os IDs Imediatamente: Armazene tanto o id (ou task_id) quanto a poll_url da resposta de POST /v1/videos/generations antes de despachar o trabalho downstream.
• Desduplique no Envio: Evite a geração acidental de tarefas eliminando cliques duplos do lado do cliente e novas tentativas de rede upstream antes de criar tarefas.
• Trate 409 como Não Fatal: Se uma solicitação de cancelamento retornar 409 task_not_cancellable, trate isso como uma indicação de que o processamento já começou. Recorra a aguardar o resultado e descartar a saída caso ela não seja mais necessária.
• Analise o Marcador de Cancelamento: Em seu loop de polling, verifique tanto status == "failed" quanto cancelled is True para distinguir cancelamentos iniciados pelo usuário de erros de infraestrutura.
• Reconcilie a Cobrança Usando IDs de Transação: Armazene o billing_transaction_id apenas quando presente em trabalhos concluídos. Não espere IDs de transação em tarefas canceladas ou com falha.

Para padrões de integração adicionais, consulte o Guia de Geração de Vídeo e a Referência da API Get Video Status.