Tarefas assíncronas

Esta página explica as tarefas assíncronas de geração de mídia. O saldo é reservado na criação, liquidado pelo uso real no sucesso e totalmente liberado em failed ou expired. Registros canceled históricos recebem o mesmo tratamento, mas uma nova tarefa aceita não pode ser cancelada.

API

GET /api/v1/models?includeSchema=1&includeExamples=1
# choose an item where enabled && available

curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: render-001" \
  -d '{
    "model": "MODEL_ID_FROM_CATALOG",
    "input": { "prompt": "a folded paper lantern, hard side light" }
  }'

Histórico da chave atual

GET /api/v1/jobs consulta apenas as tarefas da chave de API usada para autenticar a requisição. Não é possível selecionar outra chave, mesmo da mesma conta. A resposta traz somente metadados, sem input nem output. Para obter o resultado do taskId escolhido, use GET /api/v1/jobs/recordInfo.

from e to são datas UTC que delimitam o intervalo [from, to). O padrão é 7 dias, com máximo de 92. Os filtros são state e uma referência model exata; limit é 20 por padrão e pode chegar a 100. Se hasMore for true, envie nextCursor como o próximo cursor, mantendo from, to e os demais filtros. A ordenação é por createdAt decrescente e, em caso de empate, por id decrescente, para distinguir tarefas criadas no mesmo instante. Cada página lê os estados atuais; os estados e os resultados dos filtros não são um retrato congelado.

Quatro prazos diferentes

deadlineAt é o prazo real da tarefa informado pelo servidor. timeoutMs no SDK limita apenas a espera do cliente e não cancela uma tarefa já aceita. expiresAt indica a validade da URL do resultado, normalmente de 20 minutos; as mídias geradas ficam armazenadas por 14 dias. Uma URL vencida não significa que a tarefa falhou ou que o arquivo foi apagado.

Crie uma tarefa

Envie model, input e, opcionalmente, callBackUrl para POST /api/v1/jobs/createTask. Emita um Idempotency-Key por solicitação lógica e reutilize-o em tentativas de rede.

Interprete o estado

Em tarefas novas, queued e running não são terminais; succeeded, failed e expired são. O estado canceled histórico permanece apenas para leitura e compatibilidade; ele não representa uma ação disponível. Um HTTP bem-sucedido ou code: 200 só indica que a consulta funcionou. O resultado está em data.state.

Se output.assets[].pending for true, aguarde e consulte de novo. unavailable exige nova geração.

Webhooks e polling

Em produção, o webhook é o canal principal. O polling com backoff exponencial e jitter serve de recuperação. recordInfo e webhook compartilham o envelope {code,msg,data,request_id}, portanto podem usar o mesmo parser.

Consulte o contrato OpenAPI 3.1 para ver a definição completa dos campos.