Trabalhos Assíncronos & Polling

Muitos endpoints de mídia são assíncronos. Um pedido de criação inicia o trabalho e retorna uma identidade de tarefa pública do TokenLab; sua aplicação consulta até que essa tarefa atinja um status terminal. Não construa fluxos de trabalho do cliente em torno de URLs de tarefas upstream, IDs de roteamento ou comportamento de callback do provedor.

Contrato de Tarefa Pública

As respostas de criação podem incluir:

Campo	Significado	O que fazer
`id`	ID da tarefa pública do TokenLab	Armazene-o com seu próprio registro de trabalho
`task_id`	Alias de compatibilidade para a mesma identidade de tarefa pública	Trate-o como equivalente a `id`
`status`	Status atual da tarefa pública	Comece a consultar quando não for terminal
`poll_url`	URL de status preferencial	Use esta primeiro quando presente
`model`	Modelo solicitado ou resolvido pelo endpoint	Armazene para suporte e reconciliação de cobrança

/v1/tasks/{id} é o endpoint de status fixo canônico para trabalhos de mídia assíncronos públicos. Rotas de status específicas de mídia podem existir para compatibilidade, mas novas integrações devem preferir poll_url ou /v1/tasks/{id}.

Fluxo Recomendado

Valide o pedido do usuário e envie a chamada de criação com um model explícito.
Persista id / task_id, poll_url, endpoint, modelo, ID do usuário e seu próprio ID de trabalho antes de retornar o controle para a UI.
Consulte a cada 5-10s para tarefas de mídia de longa duração.
Pare somente quando a tarefa estiver completed ou failed.
Ao completed, leia os campos de resultado específicos de mídia e armazene URLs ou metadados finais.
Ao failed, armazene o erro público e ofereça a tentativa novamente apenas como um novo trabalho visível ao usuário.

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

Exemplo de Polling

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

Os status públicos esperados são pending, processing, completed e failed. Tarefas canceladas são representadas como failed com cancelled: true e cancellation_status: "cancelled" para que o manuseio de status mais antigos continue funcionando.

Regras de Tentativa do Cliente

Os timeouts de rede são a fonte mais comum de trabalhos duplicados. Use esta regra:

Onde o timeout acontece	Comportamento mais seguro
Antes que seu servidor receba uma resposta de criação	Verifique os logs do servidor para `request_id`; tente novamente apenas se nenhuma tarefa foi criada
Depois que uma resposta de criação foi armazenada	Retome a consulta do `task_id` armazenado
Durante a consulta	Tente novamente a solicitação de status com backoff
Após status terminal	Não consulte novamente a menos que o usuário atualize explicitamente o registro

Não envie um segundo pedido de criação apenas porque o navegador foi atualizado ou uma consulta de status falhou.

Cobrança e Liquidação

Trabalhos assíncronos podem reservar um valor estimado quando o pedido de criação é aceito. A liquidação final acontece após o status terminal. Quando disponível, as respostas de status da tarefa podem expor billing_transaction_id e o cabeçalho X-Billing-Transaction-ID. Para reconciliação, junte esses identificadores em seus logs:

request_id do pedido de criação.
task_id / id da tarefa.
billing_transaction_id quando presente.
Seu próprio ID de usuário, ID de projeto ou ID de trabalho.

Cancelamento

DELETE /v1/tasks/{id} é intencionalmente restrito. Atualmente, suporta tarefas de vídeo em fila do Volcengine Seedance, como seedance-1.5-pro, seedance-2.0 e seedance-2.0-fast. Tarefas não suportadas retornam 400 unsupported_task_cancel. Tarefas que já estão em execução ou em status terminal retornam 409 task_not_cancellable. Construa a UI de cancelamento como “solicitar cancelamento” em vez de um botão de parada garantido.

Solução de Problemas

Sintoma	Causa provável	O que verificar
`async_task_not_found`	Tarefa é desconhecida, expirou, inacessível a esta chave de API, ou não é uma tarefa assíncrona pública	Confirme a propriedade da chave de API e o `task_id` público armazenado
A tarefa nunca parece terminar	O cliente continua consultando a URL errada ou parou antes do status terminal	Use `poll_url` ou `/v1/tasks/{id}` e inspecione o status mais recente
URL final de mídia ausente	A tarefa não está completa, ou o trabalho upstream foi concluído sem saída utilizável	Continue consultando até o terminal, depois trate a saída ausente como falha
O usuário vê duplicatas	O caminho de tentativa criou uma nova tarefa após timeout ou atualização	Deduplica pelo seu próprio ID de trabalho e `task_id` armazenado
Desvio de cobrança	A liquidação é assíncrona ou o cliente está comparando IDs de provedor	Compare `request_id`, `task_id` e `billing_transaction_id`

Pacote de Suporte

Ao entrar em contato com o suporte, inclua request_id, task_id, billing_transaction_id quando presente, endpoint, modelo, timestamp e uma forma de pedido sanitizada. Não inclua chaves de API, mídia privada, URLs assinadas ou prompts completos, a menos que o suporte peça um exemplo redigido.

Referência da API

Tópico	Referência
Obter Status da Tarefa	Get Task Status
Cancelar Tarefa	Cancel Task
Geração de Imagem	Image Generation
Geração de Vídeo	Video Generation
Geração de Música	Music Generation
Geração 3D	3D Generation
Cobrança & Preços	Billing & Pricing

​Contrato de Tarefa Pública

​Fluxo Recomendado

​Exemplo de Polling

​Regras de Tentativa do Cliente

​Cobrança e Liquidação

​Cancelamento

​Solução de Problemas

​Pacote de Suporte

​Referência da API