Guia: gere e edite imagens

Crie imagens a partir de texto, edite fotos com imagens de referência e use as ferramentas de fundo, upscale e limpeza — com escolha de modelos e custos.

Imagens são o que há de mais rápido e barato para gerar, por isso são o melhor lugar para aprender a API. A maioria dos modelos de imagem termina em menos de um minuto, então você pode usar ?wait=60 e receber a imagem na mesma resposta.

Texto para imagem

curl -X POST "https://api.popnow.ai/api/v1/jobs/createTask?wait=60" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "black-forest-labs/flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "Product photo of a ceramic coffee mug on a linen tablecloth, soft window light, shallow depth of field",
      "aspect_ratio": "4:3"
    }
  }'

O resultado fica em data.output.assets[0].url. Se a resposta for um 202, o modelo precisou de mais de 60 segundos; leia a tarefa com recordInfo.

Qual modelo usar

Você quer	Experimente	Por quê
Rascunhos o mais rápidos e baratos possível	`alibaba/z-image-turbo/text-to-image`	Uns dez segundos e um ou dois créditos por imagem
Boa qualidade geral por pouco	`black-forest-labs/flux-2-klein-9b/text-to-image`	Rápido, nítido, segue bem o prompt
Texto legível, pôsteres, diagramas	`google/nano-banana-2.1/text-to-image`, `openai/gpt-image-2/text-to-image`	Fortes em letras e layout; até 4K
Várias opções numa chamada	Modelos com `num_outputs`	Uma tarefa, várias imagens

Os preços mudam por modelo e opção. Modelos mostra o preço inicial de cada um; a página de referência dele lista todas as faixas.

Edite com imagens de referência

Modelos de edição terminam em /edit e recebem as imagens de origem em image_urls, na ordem em que o seu prompt se refere a elas:

{
  "model": "google/nano-banana-2.1/edit",
  "input": {
    "prompt": "Turn the scene into a bright summer afternoon and keep the composition",
    "image_urls": ["https://media.popnow.ai/movie/lighthouse.webp"]
  }
}

Diga o que deve continuar igual, não só o que deve mudar; modelos de edição levam "mantenha o rosto e a pose" ao pé da letra.
Com várias referências, chame-as pela posição: "coloque a jaqueta da segunda imagem na pessoa da primeira".
Arquivos locais passam antes por um upload; arquivos reaproveitados ficam na sua biblioteca de assets.

Ferramentas de um passo

As ferramentas da própria PopNow recebem uma imagem só e não precisam de prompt:

ID do modelo	O que faz
`popnow/background-remover-v1/edit`	Recorta o tema sobre um fundo transparente
`popnow/image-upscaler-v1/upscale`	Amplia e deixa a imagem mais nítida
`popnow/object-eraser-v1/edit`	Apaga um objeto que você indicar
`popnow/image-expander-v1/edit`	Estende a imagem além das bordas

{ "model": "popnow/background-remover-v1/edit",
  "input": { "image_url": "https://media.popnow.ai/movie/lighthouse.webp" } }

Configurações que importam

aspect_ratio e resolution são as duas configurações que mais mudam o preço. Na dúvida, pergunte ao jobs/quote.
seed: se você não enviar, uma é sorteada e devolvida no input da tarefa. Envie esse número de volta para ter uma variação próxima de um resultado de que gostou; seed fixa deixa os testes comparáveis, mas não promete imagem idêntica.
output_format: png preserva transparência e detalhes; jpeg fica menor.
Configurações desconhecidas são rejeitadas, então confira o schema do modelo em vez de copiar configurações de outro.

Prompts que funcionam

Descreva a imagem como se estivesse passando um briefing para um fotógrafo ou ilustrador: tema, cenário, composição, luz, estilo. "Uma caneca de cerâmica, vista de cima, sobre uma toalha de linho, luz da janela pela manhã, cores suaves" é bem melhor que "uma foto bonita de caneca". Coloque o mais importante primeiro e evite listas longas de palavras de estilo que puxam para lados diferentes.

Erros que podem aparecer

content_rejected — o modelo recusou o prompt ou a referência. Reescreva ou tente outro modelo.
invalid_asset — uma referência não pôde ser lida. Confira se a URL devolve a própria imagem ou faça upload do arquivo.
unsupported_combination — este modelo não aceita essa combinação de configurações agora; mude a que aparece na mensagem.

Todos liberam a reserva, então uma imagem que falhou não custa nada.