Guia de Seleção de API de Edição de Imagem por IA: Endpoints, Inputs e Unidades de Custo

A melhor API de edição de imagem com IA raramente é aquela com a melhor demonstração. É aquela cujo endpoint, formato de entrada e unidade de cobrança correspondem à edição que seu produto realmente realiza. Edições com máscara, image-to-image guiado por referência e operações de edição específicas de modelos não compartilham um contrato único. Lemos a documentação de edição e as páginas de modelos ativos da TokenLab em 03/10/2026, e tudo abaixo provém dessas páginas. Os endpoints de imagem não escolhem nenhum modelo padrão para você, portanto, sempre envie o model explicitamente.

Principais conclusões

• Edições baseadas em máscara vão para POST /v1/images/edits. Edições de referência do Nano Banana vão para POST /v1/images/generations com operation: "image-to-image".
• As unidades de cobrança diferem. gpt-image-2 e os modelos de imagem Gemini são precificados por token, enquanto flux-kontext-pro é precificado por requisição a US$ 0,04.
• As evidências não contêm benchmarks para qualidade de inpainting, renderização de texto, preservação de estilo ou fidelidade de fotos de produtos. Teste esses aspectos em suas próprias imagens.
• Edições longas ou com múltiplas imagens devem usar async: true onde o modelo suportar. Armazene o ID da tarefa e leia a cobrança final em Usage.
• Verifique o preço e a unidade de cada página de modelo antes de se comprometer, pois a API ativa muda.

Escolhas iniciais por caso de uso

Estas escolhas seguem o contrato documentado e o preço listado. Elas não são rankings de qualidade, pois as evidências não possuem um benchmark de qualidade de edição. Trate cada uma como o primeiro modelo a ser colocado em seu próprio conjunto de testes.

Você precisa de	Escolha inicial	Por que	Fonte
Inpainting baseado em máscara	gpt-image-2	É o único modelo cujo contrato de máscara está detalhado: PNG, mesmas dimensões, áreas transparentes são editadas.	Referência de Edit Image, 03/10/2026
Muitas imagens de origem em uma edição	gpt-image-2	Limite documentado de 16 imagens de origem. Modelos de edição Grok Imagine limitam a 3.	Referência de Edit Image, 03/10/2026
Edição de referência com preço fixo mais barata	grok-imagine-image	US$ 0,02 por requisição, o menor preço fixo em nossa tabela.	API do modelo ativo, 03/10/2026
Manter a forma do produto, mudar o cenário	nano-banana-pro	O exemplo de referência documentado faz exatamente isso, a US$ 0,067 por imagem.	Referência de Create Image, 03/10/2026
Texto dentro de imagens editadas	Nenhuma escolha	As evidências não possuem dados de renderização de texto para nenhum modelo de edição.	n/a

Melhores candidatos a API de edição de imagem com IA: modelos, unidades e preços

A tabela lista todos os modelos do nosso conjunto de evidências que são listados como capazes de editar ou que a documentação de edição nomeia como um modelo de edição. Todos os preços são preços públicos da TokenLab em USD. A precificação reportada pela API ativa foi atualizada em 02/10/2026T16:53:30.068Z, e observamos cada página em 03/10/2026.

ID do Modelo	Capacidades listadas na API ativa	Unidade de precificação	Preço TokenLab (USD)	Fonte	Observado
gpt-image-2	text-to-image (edição documentada em /v1/images/edits)	per_token	US$ 3,50/1M entrada de texto, US$ 5,60/1M entrada de imagem, US$ 21/1M saída de imagem; entrada de texto em cache US$ 0,875/1M	API do modelo ativo	03/10/2026
flux-kontext-pro	image-edit, image-to-image, text-to-image	per_request	US$ 0,04	API do modelo ativo	03/10/2026
flux-pro-1.0-fill	image-to-image	per_image	US$ 0,035	API do modelo ativo	03/10/2026
flux-2-pro	image-to-image, text-to-image	per_image	US$ 0,03	API do modelo ativo	03/10/2026
nano-banana-pro	image-edit, image-to-image, text-to-image	per_image	US$ 0,067 (resumo de faixa de preço até US$ 0,12)	API do modelo ativo	03/10/2026
gemini-3-pro-image	image-to-image, text-to-image, vision	per_token	US$ 1/1M entrada, US$ 6/1M saída de texto, US$ 60/1M saída de imagem	API do modelo ativo	03/10/2026
gemini-3.1-flash-image	image-to-image, text-to-image, vision	per_token	US$ 0,25/1M entrada, US$ 1,50/1M saída de texto, US$ 30/1M saída de imagem	API do modelo ativo	03/10/2026
grok-imagine-image	image-to-image, text-to-image	per_request	US$ 0,02	API do modelo ativo	03/10/2026

Ao alinhar as páginas, encontramos três incompatibilidades. A API ativa lista gpt-image-2 apenas como text-to-image, mas a Referência de Edit Image diz que ele é suportado em /v1/images/edits. As páginas ativas para flux-pro-1.0-fill e flux-2-pro listam image-to-image, enquanto nosso snapshot de catálogo rotula ambos como image-edit. E nano-banana-pro lista image-edit, mas sua documentação o direciona através de /v1/images/generations. Tratamos a documentação como autoridade para roteamento e a API ativa como autoridade para preço.

Para os modelos com preço fixo, uma estimativa aproximada é uma multiplicação simples. Estas são estimativas, não cotações, e pressupõem uma cobrança por requisição concluída:

• 100 edições no grok-imagine-image: 100 × US$ 0,02 = US$ 2,00.
• 100 edições no flux-2-pro: 100 × US$ 0,03 = US$ 3,00.
• 100 edições no flux-pro-1.0-fill: 100 × US$ 0,035 = US$ 3,50.
• 100 edições no flux-kontext-pro: 100 × US$ 0,04 = US$ 4,00.

As evidências não fornecem uma estimativa por edição para os modelos precificados por token. gpt-image-2 cobra entrada de texto, entrada de imagem, entrada em cache reportada e tokens de saída de imagem, portanto, não é um modelo de preço fixo por imagem. As evidências não incluem contagens de tokens para uma edição típica. Execute algumas edições reais e leia o custo em Usage, conforme descrito no Guia de faturamento. A faixa de preço do nano-banana-pro implica níveis de resolução, mas as evidências não mapeiam níveis para preços.

O que o endpoint de edição aceita e o que ele não documenta

A Referência de Edit Image (observada em 03/10/2026) suporta um fluxo multipart compatível com OpenAI e requisições JSON. Aqui está o que ela declara para gpt-image-2:

• Imagem de entrada. Envie multipart image, JSON image_url / image_urls, ou objetos oficiais images[]. Cada objeto images[] contém exatamente um entre image_url ou file_id. Crie valores de file_id através de /v1/files primeiro.
• Múltiplas referências. Até 16 imagens de origem, cada uma PNG, JPEG ou WebP, até 50 MiB. Repita o campo image em requisições multipart. Em JSON, forneça exatamente um entre image_url, image_urls ou images.
• Máscara. Um PNG abaixo de 50 MiB com as mesmas dimensões da imagem de origem. Áreas totalmente transparentes marcam onde a edição é aplicada. Em JSON, mask pode ser um objeto com exatamente um entre image_url ou file_id.
• Saída. size aceita auto ou WIDTHxHEIGHT. As dimensões devem ser múltiplos de 16, a borda mais longa no máximo 3840px, a proporção entre o lado longo e o curto no máximo 3:1, e o total de pixels entre 655.360 e 8.294.400. Não envie resolution. background aceita auto ou opaque, não transparent.
• Campo rejeitado. input_fidelity não é suportado para gpt-image-2, e enviá-lo retorna 400 unsupported_parameter.
• URLs remotas. Devem ser http/https públicas, sem credenciais ou fragmentos incorporados. Não devem resolver para localhost, faixas privadas ou reservadas. Os limites são 50 MiB por imagem, 200 MiB total por requisição (incluindo a máscara), um timeout de busca de 30s e até 3 redirecionamentos. O payload buscado deve ser um PNG, JPEG ou WebP real.

Os modelos de edição Grok Imagine (grok-imagine-image, grok-imagine-image-quality) usam os mesmos campos de entrada, mas limitam as imagens de origem a 3. Uma requisição com mais falha com 400 too_many_images.

Nano Banana é diferente. A documentação diz que nano-banana-2 e nano-banana-pro aceitam requisições de imagem de referência em /v1/images/generations com operation: "image-to-image" e image_urls. Eles não pertencem a /v1/images/edits. images[] e file_id de nível superior são formatos de fluxo de edição e são rejeitados no endpoint de gerações. Aqui está um exemplo documentado para nano-banana-pro, que aceita resolution:

{
  "model": "nano-banana-pro",
  "prompt": "Keep the product shape, change the background to a bright studio setup",
  "operation": "image-to-image",
  "image_urls": ["https://example.com/input/product.png"],
  "aspect_ratio": "1:1",
  "resolution": "2k"
}

Para famílias de imagem Google, a Referência de Create Image diz para preferir aspect_ratio e enviar resolution (1k, 2k, 4k) apenas onde o modelo suportar. Detalhes do modelo para nano-banana-2 estão linkados aqui, mas o conjunto de evidências não inclui seu preço.

Não documentado nas evidências:

• Se modelos além do gpt-image-2 aceitam mask em /v1/images/edits, incluindo flux-pro-1.0-fill e stability-inpaint.
• Como uma única máscara se aplica quando você envia várias imagens de origem.
• Limites de imagem de origem para os modelos FLUX e Nano Banana.
• Se a ordem das imagens em uma requisição de múltiplas imagens afeta o resultado.

Leia a página de detalhes do modelo antes de construir sobre qualquer um deles.

Uma requisição de edição completa

Esta requisição usa apenas campos documentados para gpt-image-2: uma imagem de origem, uma máscara, um prompt, size e async. Ela segue o exemplo multipart na Referência de Edit Image.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@source.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "async=true"

Com async=true, a resposta carrega status: "pending", task_id e poll_url, e data permanece vazio. Remova a linha async para uma chamada síncrona. Uma chamada síncrona retorna data[].url por padrão, ou data[].b64_json se você definir response_format. Consulte a tarefa assim:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

Detalhes do modelo para gpt-image-2 estão na página do modelo. Para uma chamada síncrona, defina o timeout do seu cliente HTTP para pelo menos 120s, pois requisições de alta resolução podem levar perto de um minuto ou mais.

Escolhendo a melhor API de edição de imagem com IA por tarefa

As evidências declaram roteamento, entradas e preços. Elas não contêm benchmark de qualidade de edição, portanto, cada pergunta de "qual é melhor" abaixo precisa do seu próprio conjunto de testes.

Inpainting. gpt-image-2 é o único modelo cujo contrato de máscara a documentação detalha. O catálogo também lista ferramentas dedicadas de região e estrutura: stability-inpaint, stability-control-structure e stability-control-sketch. Para edições de preenchimento e contextuais, existem flux-pro-1.0-fill a US$ 0,035 por imagem e flux-kontext-pro a US$ 0,04 por requisição. As evidências não dizem qual produz emendas mais limpas.

Edições de preservação de estilo. O exemplo de referência documentado mantém a forma de um produto e altera o entorno. Esse é o padrão nano-banana-pro em /v1/images/generations. flux-kontext-pro lista capacidade de image-edit. Nenhuma das afirmações é comparada aqui quanto à retenção de identidade ou estilo.

Texto em imagens. As evidências não contêm informações sobre renderização de texto para nenhum modelo de edição. ideogram-edit-v3 e ideogram-reframe-v3 existem no catálogo, mas não encontramos dados de qualidade de texto. Teste com sua própria cópia, fontes e idiomas.

Fotos de produtos. Imagine uma equipe de catálogo que troca fundos em milhares de fotos de produtos. As ferramentas utilitárias são a primeira opção natural: image-background-remover, image-upscaler e stability-upscale-fast. Suas regras de precificação e entrada não estão em nossas evidências, portanto, leia cada página de modelo. Para trocas de fundo generativas, a precificação fixa por requisição torna os custos em lote fáceis de prever. A precificação por token faz com que dependam do tamanho da imagem e da saída.

Os requisitos de entrada são por modelo, não por provedor. Alguns modelos levam uma imagem de origem mais um prompt, alguns levam uma máscara e alguns levam entradas estruturais. Verifique as operações suportadas e os campos de requisição de cada modelo em sua página de detalhes. Você pode navegar pelas opções atuais no diretório de modelos.

Tratamento de async e confirmação de custo para edições

O Guia de geração de imagem e o Guia de jobs assíncronos (ambos observados em 03/10/2026) descrevem o fluxo. async: true é documentado para gpt-image-2 e modelos de edição oficiais FLUX/BFL. A resposta de criação retorna status: "pending", task_id e poll_url. Consulte poll_url quando presente, ou GET /v1/tasks/{id} para uma URL fixa. Os status são pending, processing, completed e failed. A documentação sugere verificar a cada 5–10 segundos para jobs de mídia longos e parar em um status terminal.

Quatro detalhes causam a maioria dos bugs:

• Uma leitura de status retorna HTTP 200 mesmo quando a tarefa falhou. Ramifique no status, e em error_details.code e type para falhas.
• Edições assíncronas concluídas retornam URLs independentemente de response_format. Use uma requisição síncrona quando precisar de b64_json.
• Após um timeout do cliente, verifique se uma tarefa existe antes de tentar novamente a chamada de criação. Tentar novamente uma geração falha cria uma nova tarefa e pode criar uma nova cobrança.
• URLs de resultado podem ser mantidas como cópias de mídia por 30 dias. Verifique media_retention.items para o status de cada item e expires_at.

Para custo, o Guia de faturamento diz que o Console mostra a estimativa máxima antes de você confirmar uma geração paga, e Usage mostra a cobrança final. Uma tarefa assíncrona pode reservar seu custo estimado quando aceita. Uma tarefa concluída é cobrada uma vez, e uma tarefa falha ou com timeout libera ou reembolsa o valor pendente. Opções de entrega também importam. TokenLab Verified usa preços públicos da TokenLab, Official usa a camada de preço oficial, e Auto tenta Verified primeiro, depois Official. Um traço na coluna de preço da página de Modelos significa que nenhuma oferta Verified está disponível, não que o modelo é gratuito. Um limite de gastos em uma chave de API retorna 402 Payment Required uma vez atingido.

Armazene request_id, task_id, poll_url, billing_transaction_id (quando presente), o modelo, o endpoint e seu próprio ID de job juntos. Na prática, esse registro resolve a maioria das questões de incompatibilidade de faturamento. As evidências documentam o cancelamento de tarefas apenas para tarefas de vídeo Seedance na fila. O cancelamento para edições de imagem não é documentado, portanto, projete seu fluxo sem ele.

FAQ

Posso enviar uma máscara para todo modelo de edição de imagem?

As evidências documentam máscaras apenas para gpt-image-2 em /v1/images/edits. A máscara deve ser um PNG abaixo de 50 MiB com as mesmas dimensões da origem, e áreas transparentes são editadas. Para outros modelos, incluindo flux-pro-1.0-fill, verifique a página de detalhes do modelo antes de assumir suporte a máscara.

Qual endpoint as edições Nano Banana usam?

Use POST /v1/images/generations com operation: "image-to-image" e image_urls. Enviar requisições de referência Nano Banana para /v1/images/edits não é suportado. Não envie images[] ou file_id de nível superior para o endpoint de gerações também.

Por que minha edição gpt-image-2 retorna 400 unsupported_parameter?

A causa mais documentada é input_fidelity, que não é um campo suportado para gpt-image-2. Também remova resolution e qualquer valor background: "transparent". A tabela de erros comuns aconselha remover qualquer campo que o modelo não documente.

Sou cobrado quando uma tarefa de edição assíncrona falha?

O guia de faturamento diz que uma tarefa falha não é cobrada, e seu valor reservado é liberado ou reembolsado. Uma tarefa concluída é cobrada uma vez, e o valor final aparece em Usage com um billing_transaction_id. Se Usage ainda não mostrar nada após a tarefa terminar, entre em contato com support@tokenlab.sh com o ID da requisição e o ID da tarefa.

Para executar as requisições acima, crie uma chave de API em Console → API Keys (limites de chave são explicados no Guia de faturamento), exporte-a como TOKENLAB_API_KEY e compare suas edições de amostra com o custo final em Usage.