> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

1. Valide o pedido do usuário e envie a chamada de criação com um `model` explícito.
2. 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.
3. Consulte a cada `5-10s` para tarefas de mídia de longa duração.
4. Pare somente quando a tarefa estiver `completed` ou `failed`.
5. Ao `completed`, leia os campos de resultado específicos de mídia e armazene URLs ou metadados finais.
6. Ao `failed`, armazene o erro público e ofereça a tentativa novamente apenas como um novo trabalho visível ao usuário.

```json theme={null}
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}
```

## Exemplo de Polling

```bash theme={null}
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](/pt/api-reference/tasks/get-task-status) |
| Cancelar Tarefa        | [Cancel Task](/pt/api-reference/tasks/cancel-task)         |
| Geração de Imagem      | [Image Generation](/pt/guides/image-generation)            |
| Geração de Vídeo       | [Video Generation](/pt/guides/video-generation)            |
| Geração de Música      | [Music Generation](/pt/guides/music-generation)            |
| Geração 3D             | [3D Generation](/pt/guides/3d-generation)                  |
| Cobrança & Preços      | [Billing & Pricing](/pt/guides/billing)                    |