Guias principais
Trabalhos Assíncronos & Polling
Crie trabalhos de mídia assíncronos, consulte o status das tarefas públicas do TokenLab e reconcilie os resultados finais sem IDs específicos do provedor.
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
modelexplí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-10spara tarefas de mídia de longa duração. - Pare somente quando a tarefa estiver
completedoufailed. - 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_iddo pedido 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} é intencionalmente restrito. Quando a tarefa selecionada oferece cancelamento, ele se aplica a tarefas de vídeo Seedance em fila 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 |
|---|---|---|
404 async_task_not_found | A tarefa expirou ou não está mais disponível | Verifique os valores salvos de task_id e poll_url |
403 task_not_owned | Não é possível confirmar que a tarefa pertence ao espaço de trabalho atual | Verifique o espaço de trabalho ou a organização associados à chave API |
| 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 | 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 |
| Cobrança & Preços | Faturamento e Preços |