Ciclo de vida da task
Como uma task de geração evolui da criação (queued) até o estado terminal, e como acompanhá-la por polling.
Os endpoints de geração (POST /api/v1/generate/*) são assíncronos: a
criação devolve um taskId e o resultado fica pronto depois. Esta página
explica os status pelos quais a task passa.
Criação — 202 com status: "queued"
A resposta de criação (202 Accepted) sempre retorna status: "queued":
{
"success": true,
"data": { "taskId": "...", "status": "queued" }
}queued é apenas um rótulo do contrato público — significa "task aceita e
enfileirada". Ele não reaparece no polling.
Polling — GET /api/v1/tasks/:id
Ao consultar a task, ela assume os status internos:
pending → submitted → processing → completed | failed| Status | Significado | O que fazer |
|---|---|---|
pending | Aguardando início | Em andamento — continue o polling |
submitted | Enviada ao provider | Em andamento — continue o polling |
processing | Em processamento | Em andamento — continue o polling |
completed | Concluída com sucesso | Leia o resultUrl |
failed | Falhou | Leia o errorMessage |
Trate qualquer um de pending/submitted/processing como "em andamento".
Quando a task chega a completed, traz o resultUrl; quando chega a failed,
traz o errorMessage.
Consulte o detalhe em
GET /api/v1/tasks/:id.
Alternativa fortemente recomendada ao polling: webhook
Em vez de consultar repetidamente - o que é uma má prática, informe um callbackUrl
na criação para receber um POST assim que a task atingir estado terminal.
Ver Webhooks.