Compromisso da tarefa e novas tentativas

Depois que createTask é aceito, a tarefa de geração está comprometida e não pode ser cancelada. Essa regra vale tanto em queued quanto em running: não é possível interromper a geração de forma confiável depois que ela começa. Por isso, a SpicyAPI nunca oferece uma ação local que possa indicar um cancelamento enquanto o trabalho — e seu custo — continua.

Repetir uma tarefa em estado final

Uma nova tentativa executa novamente uma tarefa encerrada sem sucesso: ela cria outra tarefa com o mesmo modelo, input e URL de callback, sem exigir que você reenvie o corpo original da solicitação. A nova tarefa é faturada como qualquer outra: o valor estimado é reservado quando ela é aceita, e a cobrança ocorre somente se ela for concluída com sucesso.

POST /api/v1/jobs/retry

curl -X POST https://api.spicyapi.ai/api/v1/jobs/retry \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: retry-order-8814-1" \
  -d '{"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3"}'

Substitua o taskId do exemplo pelo ID da sua tarefa com falha. Sempre envie um Idempotency-Key com retry, como retry-<sourceTaskId>-1: sem ele, um clique duplo ou uma repetição causada pela rede cria duas tarefas cobradas.

Somente tarefas failed e expired devem ser repetidas. Registros históricos canceled continuam disponíveis para leitura e também podem ser repetidos por compatibilidade, mas novas tarefas não podem entrar nesse estado por uma ação do usuário. Quando aceita, a nova tentativa cria uma nova tarefa na fila e retorna HTTP 200, em vez do 202 de createTask, com code: 200:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01k3mnewtask",
    "sourceTaskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued",
    "estimatedCost": "0.08",
    "deadlineAt": "2026-08-28T10:12:04Z"
  },
  "request_id": "req_01k3mretry"
}

Consulte ou aguarde o novo taskId, não o original; veja Tarefas assíncronas.

• A tarefa original permanece no estado final, sem alterações.
• O sourceTaskId da nova tarefa aponta para a original, preservando o histórico das tentativas.
• As verificações do schema, do preço, das permissões e do saldo atuais são executadas novamente. Uma nova tentativa é uma nova tarefa: ela volta à fila e é processada de forma independente da original.
• A nova tarefa envia o callback para o mesmo callBackUrl da tarefa original e mantém seu prazo de retenção; um cabeçalho X-Spicy-Retention em retry é ignorado.
• A nova tentativa reutiliza exatamente o input da tarefa original. Arquivos de referência enviados à SpicyAPI — incluindo pequenas imagens em Base64, armazenadas como uploads — duram um dia. Depois desse prazo, uma nova tentativa retorna 400: envie o arquivo novamente e crie uma nova tarefa com createTask.
• O escopo de Idempotency-Key abrange a tarefa original e a ação de nova tentativa. Repetir a mesma chave para a mesma tarefa original retorna a mesma nova tarefa, em vez de criar outra.

Quando uma nova tentativa é recusada

Nenhum valor é reservado ou cobrado quando retry retorna um erro.

Matriz de estados e novas tentativas

Antes de tentar novamente, confira errorCode. Vale repetir em casos de rate_limited, upstream_unavailable e upstream_failed; timeout e generation_failed podem voltar a falhar da mesma maneira. Em invalid_request, unsupported_combination e content_rejected, a mesma entrada voltará a falhar; em invalid_asset, o arquivo de referência precisa ser enviado novamente. Altere a entrada e use createTask nesses casos. Veja Códigos de falha das tarefas.