Melhor API de geração de imagens com IA em 2026: um framework de seleção

O preço anunciado por imagem é um filtro inicial ruim. Dois modelos com a mesma tarifa nominal podem se diferenciar quanto ao suporte a imagens de referência, edições com máscara, forma de seleção do tamanho de saída e se a cobrança é feita por requisição ou por token. Filtre os candidatos por capacidade primeiro e, depois, compare o custo por saída aceita em seus próprios prompts.

Este artigo é um framework de seleção para APIs de geração de imagens. Ele aborda geração de imagens, não de vídeo. Onde um pipeline precisa de ambos, a mesma mecânica assíncrona e de faturamento se aplica, mas vídeo está fora do escopo aqui.

Passo 1: Alinhe a operação suportada

A primeira rodada de eliminação é operacional. Um endpoint que gera apenas a partir de texto não consegue realizar uma edição com máscara, e um modelo construído para inpainting não é uma ferramenta geral para converter prompt em imagem.

Na TokenLab, geração e edição geralmente são endpoints diferentes:

O que você precisa	Endpoint	Observações
Text-to-image	POST /v1/images/generations	A requisição começa apenas a partir de um prompt
Image-to-image / geração orientada por referência	POST /v1/images/generations	Modelos que aceitam operation: "image-to-image" mais URLs de referência
Edição com máscara ou multipart	POST /v1/images/edits	Modelos que documentam um fluxo de edição
Variação de uma imagem existente	POST /v1/images/variations	Para integrações que já utilizam o formato de variações
Status da tarefa	GET /v1/tasks/{id}	Quando uma resposta de criação retorna task_id, status: "pending" ou poll_url

Consulte o guia de geração de imagens para a tabela de decisão e as referências Criar imagem e Editar imagem para os campos de requisição.

Uma regra de roteamento causa um número desproporcional de falhas: requisições com imagem de referência do Nano Banana (nano-banana-2, nano-banana-pro) vão para /v1/images/generations com operation: "image-to-image" e image_urls, e não para /v1/images/edits. Por outro lado, edições com o gpt-image-2 pertencem a /v1/images/edits, onde ele aceita uploads multipart de image, image_url / image_urls em JSON e referências em images[] com até 16 imagens de origem.

Agrupamentos úteis do catálogo atual da TokenLab:

• Tanto geram quanto editam: flux-2-klein-4b, flux-2-klein-9b, flux-2-pro, flux-2-flex, flux-2-max, flux-kontext-pro, flux-kontext-max, gemini-3-pro-image, gemini-3.1-flash-image, nano-banana-2, nano-banana-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst, grok-imagine-image, grok-imagine-image-quality, grok-imagine-image-2.0, qwen-image-2.0, qwen-image-2.0-pro, qwen-image-3.0, seedream-4.0, seedream-4.5, seedream-5.0, seedream-5.0-lite, seedream-5.0-pro, vidu-image-lite, vidu-image-pro.
• Apenas text-to-image: flux-1-dev, flux-pro-1.1, flux-pro-1.1-ultra, sd3.5-medium, sd3.5-large, sd3.5-large-turbo, sd3.5-flash, stable-image-core, stable-image-ultra, z-image, z-image-turbo, kling-image, kling-omni-image, hy-image-lite.
• Ferramentas especializadas de edição: stability-inpaint, stability-control-sketch, stability-control-structure, stability-style-guide, stability-upscale-fast, stability-upscale-conservative, image-upscaler, image-background-remover, flux-pro-1.0-fill, qwen-image-edit.

Verifique as operações por modelo em vez de por família. GET /v1/models?recommended_for=image retorna o conjunto recomendado atual, e a referência Obter um modelo mostra o campo supported_operations, que informa o que um ID específico aceita.

Passo 2: Verifique como o modelo aceita imagens de referência

O tratamento de imagens de referência é onde as integrações costumam falhar. Os nomes dos campos não são intercambiáveis:

• image_url — uma única imagem de referência.
• image_urls — uma ou mais referências em JSON.
• reference_image_urls — referências adicionais para modelos que separam entradas principais de referências.
• image — um upload de arquivo multipart, para imagens de origem privadas ou protegidas por cabeçalhos.
• images[] com image_url ou file_id — uma estrutura do fluxo de edição; não é aceita em /v1/images/generations.

Restrições importantes a considerar na arquitetura, de acordo com a referência da API:

• Referências remotas devem ser URLs públicas http/https, sem credenciais incorporadas ou fragmentos, e não devem resolver para faixas de IP locais (localhost), privadas ou reservadas. Cada redirecionamento é verificado novamente.
• Imagens buscadas via URL: 50 MiB por imagem, 200 MiB no total por requisição (incluindo a máscara), timeout de busca de 30s, até 3 redirecionamentos. O payload buscado deve ser um PNG, JPEG ou WebP real.
• Os limites de imagens de origem variam: o gpt-image-2 aceita até 16; o limite documentado de 3 imagens de entrada aplica-se especificamente a grok-imagine-image e grok-imagine-image-quality (que falham com 400 too_many_images acima de 3) e não está documentado para o grok-imagine-image-2.0.
• Uma mask deve ser um PNG menor que 50 MiB com as mesmas dimensões da imagem de origem.

Se as suas imagens de origem forem privadas, planeje o uso de upload multipart ou de uma referência a /v1/files em vez de passar uma URL assinada com expiração. Uma URL assinada que expira antes do início do processamento é uma entrada rejeitada, não uma falha de geração.

Passo 3: Compare os controles de saída, não apenas os nomes dos modelos

Dois modelos no mesmo nível podem expor controles de tamanho e qualidade completamente diferentes. Confirme o contrato do seletor antes de construir uma interface em torno dele.

Controle	O que verificar
size	Famílias no estilo OpenAI aceitam auto ou WIDTHxHEIGHT. Para o gpt-image-2, as dimensões devem ser múltiplos de 16, a borda mais longa no máximo 3840px, a proporção lado maior/menor no máximo 3:1 e o total de pixels entre 655,360 e 8,294,400
aspect_ratio	Famílias de imagem do Google e Grok Imagine usam 1:1, 16:9, 9:16, 3:2, 2:3 e valores semelhantes
resolution	gemini-3.1-flash-image, gemini-3-pro-image, nano-banana-2 e nano-banana-pro suportam 1k, 2k, 4k, enquanto nano-banana-2-lite suporta apenas 1k. Grok Imagine suporta 1k e 2k
quality	Modelos GPT Image usam auto, low, medium, high. Outros modelos podem usar valores diferentes
n	Número de imagens por requisição, dependente do modelo
response_format	url ou b64_json. Tarefas assíncronas retornam URLs independentemente do formato solicitado
background, output_format, output_compression	Documentados para gpt-image-2; transparent não é suportado
async	Suportado para gpt-image-2 e modelos de imagem oficiais do FLUX/BFL

Enviar um campo não documentado não é inofensivo. input_fidelity, por exemplo, não faz parte dos campos atualmente suportados para gpt-image-2 e retorna 400 unsupported_parameter. Campos não suportados em outros modelos falham de maneira semelhante. A lista completa de campos está na referência Criar imagem.

Passo 4: Identifique a unidade de cobrança antes de comparar qualquer coisa

As comparações de custo dão errado quando um modelo cobrado por token é comparado com um modelo cobrado por imagem como se fossem a mesma unidade.

• O gpt-image-2 é precificado por token. A TokenLab segue o detalhamento de uso do desenvolvedor para tokens de entrada de texto, entrada de imagem, entrada em cache reportada e saída de imagem; ele não é cobrado como um modelo fixo por imagem.
• A maioria dos outros modelos de imagem é precificada por requisição, por imagem ou por outra unidade exibida na página do modelo.

A consequência prática: para o gpt-image-2, o mesmo prompt nas mesmas configurações nominais pode ter custos diferentes dependendo da resolução, da qualidade e do próprio prompt, porque o volume de tokens de saída muda. Meça antes de se comprometer com uma regra de roteamento.

Consulte a unidade de cobrança e o preço atuais no momento da requisição em vez de fixar uma tabela no código:

• Faturamento e preços explica como funcionam as cobranças, estimativas e a reserva assíncrona.
• Obter um modelo retorna tokenlab.pricing e tokenlab.pricing_unit para um único modelo.
• Listar modelos retorna o catálogo com tokenlab.pricing, tokenlab.capabilities e tokenlab.deliveryAvailability.
• A página de Modelos mostra as mesmas informações para navegação.

Um traço na coluna de preços da TokenLab significa que nenhuma oferta TokenLab Verified está disponível no momento para esse modelo, e não que o modelo é gratuito. Modelos com fornecimento Official ainda podem ser acessados por meio da opção de entrega Official ou Auto.

Passo 5: Decida entre o fluxo síncrono ou baseado em tarefas

Requisições de imagens em alta resolução podem levar perto de um minuto ou mais. Configure o timeout do seu cliente HTTP para pelo menos 120s para chamadas síncronas ou use o fluxo de tarefas.

• Envie async: true com gpt-image-2 ou modelos de imagem oficiais do FLUX/BFL para obter um task_id e uma poll_url em vez de uma imagem finalizada.
• Não defina no código um modelo como sempre síncrono ou sempre assíncrono. Verifique a resposta de criação: se ela contiver status: "pending", task_id ou poll_url, siga a poll_url retornada.
• Os status são pending, processing, completed e failed. Uma leitura de status bem-sucedida retorna HTTP 200 mesmo quando a tarefa falhou; use o campo status, não o código HTTP.
• Os resultados assíncronos de imagem são retornados como URLs. Se você precisa de b64_json bruto, use uma requisição síncrona.
• Faça polling a cada poucos segundos e pare ao atingir um status terminal. As URLs HTTP(S) de resultado de imagens geradas podem ser retidas como cópias de mídia por 30 dias; verifique media_retention.items para o status de cada item e seu expires_at.

Os detalhes estão no guia de tarefas assíncronas e polling e na referência Obter status da imagem.

Tentativas de repetição (retries) representam um risco de cobrança, não apenas um risco de latência. Uma requisição de criação repetida após um timeout pode produzir uma segunda tarefa e uma segunda cobrança. Armazene request_id, task_id e qualquer billing_transaction_id, e verifique se uma tarefa foi criada antes de tentar novamente.

Passo 6: Avalie com seu próprio conjunto de prompts

Nenhum ranking de qualidade neutro em relação aos fornecedores foi incluído neste artigo, e nenhum deve ser considerado com base em material de marketing. Justifique a escolha com uma medição na sua própria carga de trabalho:

1. Monte um conjunto fixo de prompts que reflita a sua distribuição de produção — os temas, estilos e formatos de instrução que você realmente recebe. Prompts genéricos de demonstração não vão diferenciar os modelos para você.
2. Execute o mesmo conjunto em todos os modelos candidatos com as mesmas configurações e registre o tempo de geração por requisição, incluindo tentativas de repetição.
3. Avalie as saídas com um critério de pontuação fixo, seja automatizado ou por meio de um painel de revisão humana, em vez de avaliar amostras superficialmente a olho nu.
4. Calcule o custo por imagem aceita, não o custo por imagem gerada. Um modelo mais barato que precisa de duas tentativas por saída utilizável não é mais barato.
5. Se o seu produto for sensível à latência, registre percentis em vez de médias, pois a cauda da distribuição é o que os usuários percebem.
6. Execute a comparação novamente quando trocar de provedor ou de metas de resolução, pois tanto as unidades de precificação quanto o comportamento do modelo podem mudar.

O custo por imagem aceita é o único número que responde se um modelo mais caro compensa o seu valor para a sua carga de trabalho.

Requisição ilustrativa

A seguir, um exemplo ilustrativo do formato da chamada de geração, não um resultado medido. Ele usa um modelo que expõe aspect_ratio e resolution.

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k"
  }'

Se essa resposta retornar com status: "pending", faça polling na poll_url retornada em vez de tratar isso como uma falha.

O acesso aos modelos não é uniforme entre os formatos de API. A TokenLab aceita formatos de requisição Chat Completions, Responses, Anthropic Messages e Gemini, e um determinado modelo pode suportar apenas alguns deles. Verifique tokenlab.accepted_request_formats no modelo antes de reutilizar um cliente existente — consulte Formatos de API.

Limitações deste artigo

• Nenhum benchmark independente de qualidade, medição de latência ou métrica de throughput para qualquer modelo de imagem foi incluído aqui. O posicionamento de fornecedores sobre anatomia, renderização de texto ou fotorrealismo não é reproduzido como fato.
• Nenhum preço é citado. As unidades de precificação dos modelos de imagem diferem e mudam; consulte o valor atual na página de Modelos ou em GET /v1/models/{model}.
• A disponibilidade dos modelos varia de acordo com a opção de entrega e o workspace. tokenlab.deliveryAvailability descreve o suporte configurado; ele não garante a disponibilidade em tempo real, que é verificada no momento da execução da requisição.
• Restrições de região pública se aplicam.

Leituras relacionadas

• Guia de geração de imagens
• Criar imagem e Editar imagem
• Tarefas assíncronas e polling
• Faturamento e preços
• Listar modelos e Obter um modelo
• Formatos de API
• Lista atual de modelos e preços: Página de Modelos