Guias principais

Tarefas assíncronas e polling

Crie tarefas de mídia e aguarde o resultado final

Muitos endpoints de mídia retornam uma tarefa em vez de um arquivo finalizado. Salve o ID da tarefa retornado e faça o polling de GET /v1/tasks/{id} até que o status seja completed ou failed. Este único endpoint atende a tarefas de imagem, vídeo, música, 3D, Worlds e transcrição de áudio assíncrona.

Snapshots de tarefas terminais assíncronas possuem um ciclo de vida separado da janela de captura de solicitação/resposta de 30 dias. URLs de arquivos de imagem, vídeo, áudio, 3D e Worlds gerados são URLs de resultado de mídia da TokenLab que permanecem válidas por 30 dias. Leituras de status de tarefas finalizadas funcionam por cerca de 7 dias, portanto, salve o resultado assim que a tarefa for concluída. Os campos media_retention da resposta informam o status de salvamento de cada item e o expires_at; eles podem estar ausentes quando o status de salvamento não é conhecido a tempo, e a URL ainda funciona. Tarefas falhas e em progresso retornam campos de URL de mídia vazios. Veja Retenção de dados.

Campos para salvar

As respostas de criação podem incluir:

CampoSignificadoO que fazer
idID da tarefa TokenLabArmazene com seu próprio registro de trabalho
task_idOutro nome para o mesmo ID de tarefaTrate como equivalente ao id
statusStatus atual da tarefaContinue verificando até que termine ou falhe
poll_urlURL de status da tarefaArmazene; faça o polling de /v1/tasks/{id} com o ID da tarefa
modelModelo usado para a tarefaArmazene com o registro da tarefa

Um único endpoint de status

Faça o polling de GET /v1/tasks/{id} com o id ou task_id da resposta de criação. Funciona para todos os tipos de tarefa. Para a maioria das tarefas, poll_url é este mesmo caminho. Uma resposta de criação de Worlds retorna uma poll_url em /v1/worlds/generations/{id}; faça o polling de /v1/tasks/{id} com o id da tarefa para Worlds também.

Caminhos de status por modalidade, como /v1/videos/generations/{id}, permanecem suportados para integrações existentes. Novas integrações devem usar /v1/tasks/{id}.

Salve a tarefa e verifique seu status

Salve o id ou task_id assim que a solicitação de criação for bem-sucedida. Armazene a poll_url, o modelo, o endpoint e seu próprio ID de usuário ou de trabalho com ele. Para trabalhos de mídia longos, verificar a cada 5–10 segundos geralmente é suficiente.

Pare quando o status se tornar completed ou failed. Uma tarefa concluída contém o resultado da mídia; uma tarefa falha contém o erro que você pode exibir ou registrar. Tentar novamente uma geração falha cria uma nova tarefa e pode gerar uma nova cobrança.

{
  "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 são pending, processing, completed e failed. Uma tarefa cancelada usa failed junto com cancelled: true e cancellation_status: "cancelled".

Uma leitura de status bem-sucedida retorna HTTP 200 mesmo quando a tarefa falhou. Use o status da tarefa para decidir se a geração foi bem-sucedida. O campo error mantém sua forma de string ou objeto. Tarefas falhas também podem incluir error_details com status (o status de erro de negócio), type, code, message, param e retryable. Por exemplo, error_details.status: 400 com param: "size" significa que a solicitação precisa de correção; não significa que a solicitação de status em si falhou. param é omitido quando nenhum campo específico é conhecido. Quando error_details.projection_version é 2, message é o motivo final da falha, geralmente a explicação do próprio serviço upstream, como um limite de parâmetro ou uma decisão de política de conteúdo. Para uma tarefa executada em uma rota oficial, error_details.upstream também carrega o erro upstream conforme relatado: message, além de code, param e source (o nome do serviço upstream) quando conhecido. Continue ramificando em code e type; os valores de upstream.code são definidos pelo serviço upstream e podem mudar.

Erros que rejeitam a solicitação de criação antes que uma tarefa seja aceita usam o status de erro HTTP normal e o objeto error estruturado. Repetir a mesma solicitação de criação idempotente preserva essa rejeição. Uma leitura de status falha não altera o estado terminal da tarefa.

Evite tarefas duplicadas

A maioria das gerações duplicadas vem da tentativa de repetir uma solicitação de criação após um timeout.

Onde o timeout ocorreComportamento mais seguro
Antes de seu servidor receber uma resposta de criaçãoEnvie a mesma solicitação novamente com o mesmo Idempotency-Key para obter a tarefa original. Sem uma chave, verifique o request_id e tente novamente apenas se nenhuma tarefa foi criada
Após uma resposta de criação ter sido armazenadaRetome o polling do task_id armazenado
Durante o pollingTente novamente a solicitação de status com backoff
Após o status terminalNão faça polling novamente, a menos que o usuário atualize explicitamente o registro

Não envie uma segunda solicitação de criação apenas porque o navegador foi atualizado ou um polling de status falhou.

Registros de faturamento

Uma tarefa assíncrona pode reservar seu custo estimado quando é aceita. O valor final é registrado após a tarefa terminar ou falhar. As respostas de status podem incluir billing_transaction_id e o cabeçalho X-Billing-Transaction-ID.

Mantenha estes identificadores juntos:

  • request_id da solicitação 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} pode cancelar tarefas de vídeo Seedance suportadas enquanto ainda estão na fila, incluindo seedance-2.0 e seedance-2.0-fast.

Tarefas não suportadas retornam 400 unsupported_task_cancel. Uma tarefa que já está em execução ou finalizada retorna 409 task_not_cancellable. O cancelamento é uma solicitação, não uma garantia de que o trabalho já em andamento será interrompido. Um cancelamento bem-sucedido retorna 200 com status: "failed", cancelled: true e cancellation_status: "cancelled". Uma tarefa cancelada não é cobrada.

Solução de problemas

SintomaCausa provávelO que verificar
404 async_task_not_foundO ID da tarefa é desconhecido, pertence a outro workspace ou a tarefa finalizada passou de sua janela de statusVerifique o task_id salvo e o workspace da chave de API
403 task_not_ownedA propriedade da tarefa não pode ser confirmada para o workspace atualConfirme o workspace ou organização associada à chave de API
503 async_task_owner_unavailableA propriedade da tarefa não pôde ser verificada agora. retryable é trueTente novamente a solicitação de status com backoff
A tarefa nunca parece terminarO cliente continua fazendo polling da URL errada ou parou antes do status terminalFaça o polling de GET /v1/tasks/{id} com o ID da tarefa salvo e inspecione o status mais recente
URL de mídia final ausenteA tarefa não foi concluída ou terminou sem um arquivo utilizávelContinue fazendo polling até terminar, então trate um resultado ausente como falha
Usuário vê duplicatasO caminho de repetição criou uma nova tarefa após timeout ou atualizaçãoDesduplique pelo seu próprio ID de trabalho e task_id armazenado
Incompatibilidade de faturamentoO faturamento final ainda não foi registrado ou IDs errados estão sendo comparadosCompare request_id, task_id e billing_transaction_id

O que enviar ao suporte

Inclua request_id, task_id, billing_transaction_id quando presente, endpoint, modelo, horário e os nomes dos campos que você enviou. Nunca envie chaves de API, mídia privada, URLs assinadas ou prompts completos, a menos que o suporte solicite especificamente um exemplo editado.

Referência da API

TópicoReferência
Obter status da tarefaObter status da tarefa
Cancelar tarefaCancelar tarefa
Geração de imagemGeração de imagem
Geração de vídeoGeração de vídeo
Geração de músicaGeração de música
Geração 3DGeração 3D
Faturamento e preçosFaturamento e preços

Pare de fazer polling de tarefas terminais e pare em 401, 403, 404 ou um erro não recuperável. Para receber resultados de tarefas sem polling, configure a API de gerenciamento de Webhooks com um Management Token mt-….

As respostas das tarefas também carregam os cabeçalhos X-Task-ID, X-Task-Type e X-Billing-Transaction-ID, que você pode registrar ao lado do ID da tarefa.

Nesta página