Créditos e cobrança

Como as chamadas da API gastam créditos, como funcionam a reserva e a cobrança final, cotação antes de rodar, saldo, uso e limites de gasto.

A API gasta os mesmos créditos do popnow.ai. Não existe plano separado para a API, nem assinatura, nem valor mínimo: compre um pacote de créditos quando precisar de mais, e os créditos grátis do cadastro também valem aqui.

1 crédito = US$ 0,01 na taxa base. Pacotes maiores vêm com créditos bônus, então cada crédito sai um pouco mais barato.
Os preços variam por modelo e opção — por imagem, por segundo de vídeo ou áudio, por requisição ou a cada 1.000 caracteres de voz. A página de cada modelo lista os valores.
As respostas trazem cada valor duas vezes: em créditos inteiros (credits, maxCredits, availableCredits …) e como string em dólares (cost, maxCharge, available …). Use os campos de créditos; as strings em dólares servem para a contabilidade.

Como uma tarefa é cobrada

hold

settlerelease

Os créditos são reservados na aceitação e resolvidos uma única vez: cobrados pelo uso real ou devolvidos por inteiro.

Reserva. Quando o createTask aceita uma tarefa, o maior preço que ela pode atingir é separado do seu saldo (estimatedCredits). Créditos reservados não podem ser gastos duas vezes, mas ainda não foram cobrados.
Cobrança ou liberação. Quando a tarefa termina:
- succeeded → você paga o que ela realmente usou, arredondado para cima em créditos inteiros e nunca mais que a reserva. O restante volta para o saldo.
- failed ou expired → a reserva inteira é liberada. Você não paga nada.

O registro da tarefa mostra em que pé ela está: enquanto settled for false, credits é a reserva; quando settled vira true, credits é a cobrança final.

Alguns poucos modelos cobram por uma requisição que o fabricante recusou por causa do conteúdo. Quando isso acontece, a página do modelo avisa; em todos os outros casos, falhar é de graça.

Situação	É cobrado?
`createTask` rejeitado (`400`, `402`, `403`, `429`, `50301` …)	Não — sem tarefa, sem reserva
Tarefa `succeeded`	Sim, o valor real, limitado à reserva
Tarefa `failed` ou `expired`	Não, exceto o caso de recusa por conteúdo acima
A conexão caiu depois do envio	Não dá para saber até conferir — reenvie com o mesmo `Idempotency-Key` para encontrar a tarefa
Consultar tarefas, modelos, saldo ou uso	Nunca

Pergunte o preço antes

POST /api/v1/jobs/quote recebe exatamente o corpo que você mandaria ao createTask e devolve o preço sem criar nada nem reservar créditos:

curl -X POST "https://api.popnow.ai/api/v1/jobs/quote" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "alibaba/wan-3.0/image-to-video", "input": {"image_url": "https://media.popnow.ai/movie/lighthouse.webp", "resolution": "720p", "duration_seconds": 5}}'

{
  "code": 200,
  "msg": "success",
  "data": {
    "quoteId": "q_…",
    "model": "alibaba/wan-3.0/image-to-video",
    "maxCredits": 68,
    "expectedCredits": 68,
    "estimatedCost": "0.68",
    "maxCharge": "0.68",
    "currency": "USD",
    "quantity": "5",
    "unit": "per_second",
    "expiresAt": "2026-10-16T09:25:00Z"
  },
  "request_id": "req_…"
}

maxCredits é o máximo que a requisição pode custar — o valor que será reservado. expectedCredits é o que ela costuma custar; os dois só diferem quando a cobrança final depende do resultado, como a duração real de um clipe.

Para garantir que o preço não mude entre mostrar ao usuário e rodar a tarefa, passe quoteId e expectedCredits (o maxCredits que você mostrou) ao createTask em até cinco minutos. Se algo mudou, o createTask responde 40901 e não reserva nada; cote de novo.

Saldo

curl "https://api.popnow.ai/api/v1/chat/credit" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

availableCredits é o que as tarefas novas podem usar, heldCredits é o que está separado para tarefas em andamento e totalCredits é a soma dos dois (available, held e total trazem os mesmos valores em dólares). O nome do caminho é histórico e não tem nada a ver com chat. Quando o saldo disponível não cobre a reserva de uma tarefa nova, o createTask retorna 40201.

Uso

GET /api/v1/usage?from=2026-10-01&to=2026-10-16 devolve, para a chave que faz a chamada, o número de tarefas, quantas deram certo e quantas falharam e quanto custaram em créditos — no total (totalCredits), por dia e por modelo. As datas são UTC, to é exclusivo e o intervalo é de no máximo 92 dias. Só entram cobranças fechadas, então o total de um dia ainda pode mudar enquanto tarefas atrasadas terminam. Este relatório tem limite de 30 requisições por minuto; para a conta inteira, use a página de uso do console da API.

Limites de gasto

Cada chave pode ter um limite diário, mensal e total, definido no console da API e mostrado em créditos. Uma requisição que estouraria um limite retorna 40202 e não reserva nada. Limites diários zeram às 00:00 UTC, os mensais no dia 1º às 00:00 UTC, e um limite total nunca zera. Sem configuração, as chaves não têm limites.

Comprar créditos e reembolsos

Créditos são comprados no site, não pela API. Pacotes e preços estão na página de preços; a política de reembolso explica o que pode ser reembolsado e quando.