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:
| Campo | Significado | O que fazer |
|---|---|---|
id | ID da tarefa TokenLab | Armazene com seu próprio registro de trabalho |
task_id | Outro nome para o mesmo ID de tarefa | Trate como equivalente ao id |
status | Status atual da tarefa | Continue verificando até que termine ou falhe |
poll_url | URL de status da tarefa | Armazene; faça o polling de /v1/tasks/{id} com o ID da tarefa |
model | Modelo usado para a tarefa | Armazene 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 ocorre | Comportamento mais seguro |
|---|---|
| Antes de seu servidor receber uma resposta de criação | Envie 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 armazenada | Retome o polling do task_id armazenado |
| Durante o polling | Tente novamente a solicitação de status com backoff |
| Após o status terminal | Nã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_idda solicitação de criação.task_id/idda tarefa.billing_transaction_idquando 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
| Sintoma | Causa provável | O que verificar |
|---|---|---|
404 async_task_not_found | O ID da tarefa é desconhecido, pertence a outro workspace ou a tarefa finalizada passou de sua janela de status | Verifique o task_id salvo e o workspace da chave de API |
403 task_not_owned | A propriedade da tarefa não pode ser confirmada para o workspace atual | Confirme o workspace ou organização associada à chave de API |
503 async_task_owner_unavailable | A propriedade da tarefa não pôde ser verificada agora. retryable é true | Tente novamente a solicitação de status com backoff |
| A tarefa nunca parece terminar | O cliente continua fazendo polling da URL errada ou parou antes do status terminal | Faç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 ausente | A tarefa não foi concluída ou terminou sem um arquivo utilizável | Continue fazendo polling até terminar, então trate um resultado ausente como falha |
| Usuário vê duplicatas | O caminho de repetição criou uma nova tarefa após timeout ou atualização | Desduplique pelo seu próprio ID de trabalho e task_id armazenado |
| Incompatibilidade de faturamento | O faturamento final ainda não foi registrado ou IDs errados estão sendo comparados | Compare 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ópico | Referência |
|---|---|
| Obter status da tarefa | Obter status da tarefa |
| Cancelar tarefa | Cancelar tarefa |
| Geração de imagem | Geração de imagem |
| Geração de vídeo | Geração de vídeo |
| Geração de música | Geração de música |
| Geração 3D | Geração 3D |
| Faturamento e preços | Faturamento 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.