Tarefas

Toda geração é uma tarefa. Você a cria com uma chamada, ela roda sozinha e você pega o resultado quando estiver pronto — perguntando por ele, esperando na primeira chamada ou recebendo um webhook.

Crie uma tarefa

curl -X POST "https://api.popnow.ai/api/v1/jobs/createTask" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "alibaba/wan-3.0/image-to-video",
    "input": {
      "image_url": "https://media.popnow.ai/movie/lighthouse.webp",
      "prompt": "Waves roll in slowly, the camera drifts toward the lighthouse",
      "resolution": "480p",
      "duration_seconds": 5
    },
    "callBackUrl": "https://your-app.example.com/hooks/popnow"
  }'

Corpo

Cabeçalhos

Resposta

Uma tarefa nova volta como HTTP 202:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01JH8Z4Q5W2N7R3K9M6P1C0VXD",
    "state": "queued",
    "estimatedCredits": 34,
    "estimatedCost": "0.34",
    "deadlineAt": "2026-10-16T09:40:00Z"
  },
  "request_id": "req_…"
}

202 significa aceita, não concluída. estimatedCredits é o valor reservado do seu saldo — o máximo que esta tarefa pode custar (estimatedCost é o mesmo valor em dólares). Se a criação falhar, nada é criado nem reservado; o code diz o motivo (Erros).

Estados

Trate qualquer estado que você não reconheça como "ainda não terminou" e continue consultando.

Pule o polling com wait

Acrescente ?wait=<segundos> (até 60) ao createTask e a conexão fica aberta até a tarefa terminar ou o tempo acabar:

• Terminou a tempo → HTTP 200 com o registro completo da tarefa, no mesmo formato do recordInfo. Confira data.state: final nem sempre quer dizer sucesso.
• Não terminou → o 202 de sempre, e você continua consultando ou espera o webhook.

Use para imagens e áudios curtos; vídeo quase sempre passa de 60 segundos. Desconectar antes não para nem cancela a tarefa.

Leia uma tarefa

curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=job_01JH8Z4Q5W2N7R3K9M6P1C0VXD" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

Três prazos diferentes

• deadlineAt — quanto tempo a tarefa pode rodar. Passou disso, ela vira expired e a reserva é liberada.
• output.assets[].expiresAt — quanto tempo aquele link assinado funciona, uns 20 minutos. Leia a tarefa de novo para ter um link novo; o arquivo continua lá.
• retention.outputsExpireAt — quando o arquivo guardado é removido. Baixe antes o que quiser manter ou salve na sua biblioteca de assets.

O que vem em output

A maioria das tarefas devolve um arquivo. Algumas devolvem mais: várias imagens quando o modelo gera variações, o clipe unido e depois o trecho novo na extensão de vídeo (role: "video" e depois role: "segment"), ou uma imagem base mais camadas transparentes na separação de camadas (cada uma com um objeto layer). A transcrição de fala vem em output.text.

Os links dos arquivos são links ao portador: quem tiver a URL consegue baixar o arquivo até ela expirar. Não envie sua chave de API ao baixá-los.

Webhooks primeiro, polling como reserva

Polling funciona, mas o webhook sai mais barato para os dois lados: você fica sabendo do resultado assim que ele existe e não gasta requisições no meio do caminho. Uma integração robusta usa os dois — webhooks no fluxo normal e, de vez em quando, uma varredura com recordInfo nas tarefas cujo webhook não chegou.

Se for consultar, vá com calma: a cada 2–3 segundos para imagens, a cada 10–15 segundos para vídeo, e pare em deadlineAt.

A lista de tarefas

GET /api/v1/jobs devolve as tarefas criadas por esta chave, das mais recentes para as mais antigas, sem entradas nem resultados:

curl "https://api.popnow.ai/api/v1/jobs?state=failed&from=2026-10-01&limit=50" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

Filtros: from e to (datas UTC, no máximo 92 dias de diferença; o padrão são os últimos sete dias), state, model, limit (até 100). Quando hasMore for true, devolva nextCursor como cursor com os mesmos filtros.

Repita uma tarefa que falhou

POST /api/v1/jobs/retry com { "taskId": "…" } cria uma tarefa nova a partir de uma failed ou expired, com a entrada original e o preço de hoje. A tarefa original nunca muda. A resposta é 409 enquanto a tarefa de origem não estiver final, e uma tarefa que deu certo não pode ser repetida — crie uma nova.

Apague o conteúdo de uma tarefa

POST /api/v1/jobs/purge com { "taskId": "…" } apaga os arquivos, o resultado e o prompt guardado da tarefa. O registro de cobrança fica: o valor, o modelo, o estado e os horários continuam, e a resposta confirma isso com billingRetained: true. Só tarefas finalizadas podem ser apagadas, e repetir a chamada é seguro.

Próximos passos

• Webhooks — receba resultados em vez de consultar.
• Mídia — envie seus próprios arquivos de referência.
• Erros — cada código e se vale tentar de novo.