Como a API PopNow funciona
O que a API consegue criar, as cinco ideias em que todas as páginas se apoiam e em que ordem ler.
A API PopNow deixa o seu próprio software usar os modelos de imagem, vídeo e áudio que você conhece do popnow.ai. Mesmos modelos, mesmos preços, mesmos créditos — só que chamados por código em vez de cliques no navegador.
O que dá para criar
| Resultado | Exemplos |
|---|---|
| Imagens | Texto para imagem, edição com uma ou mais referências, upscale, remoção de fundo, separação de camadas |
| Vídeo | Texto para vídeo, imagem para vídeo, vídeo com primeiro e último quadro, vídeo por referência, estender e editar clipes, sincronia labial, avatares falantes |
| Áudio | Música, efeitos sonoros, texto para fala, trilha para um vídeo existente, fala para texto |
A lista completa, com o ID e o preço de cada modelo, está em Modelos. A API cobre apenas geração de imagem, vídeo e áudio; modelos de chat e de texto não fazem parte dela.
Cinco ideias que aparecem em todo lugar
ID do modelo
Tudo o que você pode chamar tem um ID no formato <maker>/<model>/<task>, por exemplo alibaba/wan-3.0/image-to-video ou google/nano-banana-2.1/edit. Ele vai no campo model de toda requisição. Edição de imagem sempre termina em /edit. Ferramentas feitas pela própria PopNow, como a remoção de fundo, usam popnow como criador.
Tarefa
Gerar leva de alguns segundos a vários minutos, então cada requisição cria uma tarefa. Você recebe um taskId na hora e lê o resultado quando ficar pronto. A tarefa passa de queued para running e depois para um estado final: succeeded, failed ou expired. Detalhes: Tarefas.
Créditos
A API gasta os mesmos créditos do site. Um crédito vale US$ 0,01 na taxa base. Quando uma tarefa é aceita, o maior preço possível fica reservado; quando ela termina, você paga o valor real (nunca mais que a reserva) e o resto é liberado. Tarefa que falha não custa nada. Detalhes: Créditos e cobrança.
Chave de idempotência
Um timeout de rede não diz se o servidor recebeu sua requisição. Envie um cabeçalho Idempotency-Key em toda tarefa que criar, e uma nova tentativa com a mesma chave devolve a tarefa original em vez de criar — e cobrar — uma segunda. Detalhes: Idempotência.
Webhook
Em vez de perguntar por uma tarefa repetidas vezes, passe um callBackUrl. Quando a tarefa termina, a PopNow envia o resultado completo para essa URL, com assinatura para você conferir que veio da gente. Detalhes: Webhooks.
Como é uma requisição
POST https://api.popnow.ai/api/v1/jobs/createTask
Authorization: Bearer sk-popnow-...
Idempotency-Key: 7d0c9a52-...
{ "model": "alibaba/wan-3.0/image-to-video",
"input": { "image_url": "https://…/photo.jpg", "prompt": "The waves roll in slowly" },
"callBackUrl": "https://your-app.example.com/hooks/popnow" }Toda resposta usa o mesmo envelope, { "code", "msg", "data", "request_id" }, em que code: 200 significa sucesso.
Ordem de leitura
- Início rápido — seu primeiro resultado em cinco minutos.
- Autenticação — como proteger uma chave e limitar o que ela pode fazer.
- Modelos — escolha um modelo e leia os parâmetros.
- Tarefas e Webhooks — o ciclo de vida completo.
- Mídia — envie suas próprias imagens, vídeos e áudios.
- Erros e Limites de taxa — antes de ir para produção.
Quer testar um modelo antes de escrever código? Cada modelo tem um Playground na página de API dele no popnow.ai, que roda na sua conta sem precisar de chave.