Tutorial de integração da API GPT Image 2.6: seleção entre Flare e Sunburst, prática de saída GIF e SVG

Primeiro, três decisões: linha, modo e formato de saída

Antes de escrever a primeira linha de requisição, defina estas três coisas e você não precisará alterar o código repetidamente depois.

Primeiro, escolha a linha Flare ou Sunburst. Sem necessidade especial, use Flare por padrão: gera imagens mais rápido, ideal para iteração rápida e geração em lote. Só mude para Sunburst quando precisar fazer edições em múltiplas rodadas com qualidade média ou superior e se importar muito com a consistência de personagens/produtos/layout. Os parâmetros, uso e preço das duas linhas são completamente idênticos, então o custo de troca é apenas alterar um ID de modelo.

Segundo, escolha o modo texto-para-imagem ou imagem-para-imagem. Partir de um prompt é texto-para-imagem; ter de 1 a 16 imagens de origem e modificar a partir delas é imagem-para-imagem. Atenção: os formatos de saída disponíveis diferem — gif e svg só estão disponíveis em texto-para-imagem; imagem-para-imagem só pode gerar png, jpeg, webp.

Terceiro, escolha o formato de saída: estático, animado ou vetorial. Padrão é png; para fundo transparente use png ou webp; para animação use gif; para vetor escalável use svg.

Essas três decisões, no código, resumem-se aos valores dos campos ID do modelo e output_format. Defina-os como constantes desde o início; isso economiza muito mais tempo do que ajustar durante o desenvolvimento.

Os quatro IDs de modelo e o critério de seleção entre Flare e Sunburst

Os IDs de modelo são formados por duas partes: "linha + modo", totalizando quatro:

• gpt-image-2.6-flare/text-to-image

• gpt-image-2.6-flare/image-to-image

• gpt-image-2.6-sunburst/text-to-image

• gpt-image-2.6-sunburst/image-to-image

A lógica de nomenclatura é direta: a primeira parte é a linha, a segunda é o modo. Os nomes de parâmetros no corpo da requisição, as faixas de valores e os critérios de cobrança são completamente idênticos nas duas linhas, então você pode encapsular tudo em uma função e passar a linha como parâmetro.

Quando é obrigatório usar Sunburst

Sunburst é mais detalhado; ao fazer edições em múltiplas rodadas com qualidade média ou superior, os detalhes são mais consistentes. Cenários típicos são ajustes sucessivos com personagem fixo, aparência de produto fixa ou layout fixo. Se seu fluxo é "gerar primeiro, depois editar três vezes", o benefício do Sunburst aparecerá nas rodadas seguintes.

Quando permanecer no Flare

Geração de imagem única, produção em lote, verificação rápida do efeito do prompt — nesses cenários, o Flare é mais rápido e, portanto, a melhor escolha. Como os preços são completamente idênticos, escolher Flare não traz nenhuma desvantagem de custo.

Recomendação prática: durante o desenvolvimento, use Flare de forma unificada para validar parâmetros e formatos; em produção, mude de linha apenas para casos que exigem edições em múltiplas rodadas. Na página do modelo, consulte primeiro as descrições de campos de Flare texto-para-imagem e Sunburst texto-para-imagem.

Como preencher os parâmetros-chave de texto-para-imagem

Os parâmetros principais de texto-para-imagem são sete; veja a seguir os valores e restrições de cada um.

quality e resolution

quality aceita low / medium / high / xhigh / max, define o nível de detalhe e é também a única base de cobrança do GIF. resolution aceita 1K / 2K / 4K, padrão 1K. Esses dois parâmetros juntos determinam o preço por imagem e são os dois botões de controle de custo.

complexity

Aceita low / medium / high, padrão high, refere-se ao nível de planejamento. É independente de quality: um controla a profundidade do planejamento de composição, o outro controla o nível de detalhe da imagem. Não altere complexity só porque reduziu quality; os dois não são interligados.

aspect_ratio

Aceita auto ou uma das 15 proporções. Há uma regra fácil de errar: ao gerar GIF, não passe aspect_ratio ou passe auto, pois a proporção do GIF é determinada por frame_size; conflitar os dois não faz sentido.

output_format e output_compression

output_format aceita png (padrão) / jpeg / webp / gif / svg. output_compression aceita 0–100, só tem efeito em jpeg e webp; passar parâmetro de compressão para png não funcionará como esperado.

background

Aceita auto / opaque / transparent. transparent deve ser combinado com png ou webp; se quiser fundo transparente e escolher jpeg, será preciso mudar o formato.

Basta memorizar uma regra sobre essas restrições: o formato, por sua vez, limita os outros parâmetros — gif fixa a origem da proporção; jpeg/webp são os únicos que aceitam compressão; transparent só aceita png/webp.

Saída GIF: frame_size, número de quadros e limite de tamanho

GIF só pode ser gerado por texto-para-imagem; os parâmetros concentram-se nos quadros.

frame_size

Largura e altura em pixels de cada quadro, escrito no formato "largura x altura" como 512x512; ambos os lados devem ser múltiplos de 16, padrão 512x512. Isso também determina a proporção geral do GIF, então não passe aspect_ratio nesse caso. Observe que não aceita notação de proporção como 1:1; deve ser valor em pixels.

frame_count e frame_duration_ms

frame_count aceita 2–16, padrão 9. Há uma restrição relacionada ao tamanho: 768x768 aceita no máximo 12 quadros. frame_duration_ms não pode ser menor que 20, padrão 200, arredondado para múltiplos de 10ms.

Três limites rígidos

A montagem total do GIF também deve satisfazer: cada lado não pode exceder 3840, total de pixels não pode exceder 8.294.400, proporção não pode exceder 3:1. Exceder resulta em rejeição na fase de submissão, sem cobrança; portanto, esses erros não geram custo, mas desperdiçam seu tempo de depuração.

Um corpo de requisição GIF mínimo utilizável:

{
  "model": "gpt-image-2.6-flare/text-to-image",
  "prompt": "a bouncing paper plane on white",
  "output_format": "gif",
  "frame_size": "512x512",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "quality": "medium"
}

Para gerar de 13 a 16 quadros, use frame_size 512x512 ou menor; 768x768 aceita no máximo 12 quadros.

Como usar a saída SVG e como o preço é calculado

SVG também só está disponível em texto-para-imagem; imagem-para-imagem não aceita esse formato. No uso, basta definir output_format como svg e preencher os demais parâmetros conforme texto-para-imagem normal; se quiser background transparente, ainda é preciso observar as regras de combinação de formato.

Critério de cobrança

SVG é calculado como o preço do PNG do mesmo nível mais $ 0,030. Por exemplo, PNG low 1K custa $ 0,023; SVG no mesmo nível custa $ 0,053; PNG high 2K custa $ 0,090; SVG custa $ 0,120. Quanto mais alto o nível, mais caro o SVG, mas o acréscimo de $ 0,030 permanece o mesmo.

Recomendação de uso

SVG é adequado para logotipos, ícones, diagramas e outros alvos que exigem escala sem perdas. Se seu pipeline downstream ainda termina em bitmap, usar png diretamente é mais simples — o acréscimo pago pelo vetor não traz benefício.

Imagem-para-imagem: imagem de origem, máscara e imagem de anotação (escolha uma)

A entrada de imagem-para-imagem é de 1 a 16 imagens de origem, formatos limitados a jpeg / png / webp; a saída é apenas png / jpeg / webp.

mask_url e markup_url: apenas um dos dois

• mask_url: PNG RGBA com as mesmas dimensões da primeira imagem de origem, em que pixels transparentes indicam a área a ser modificada.

• markup_url: imagem de anotação PNG transparente, que circula no mapa a posição a ser alterada; a anotação em si não aparece no resultado gerado.

Os dois são mutuamente exclusivos; passar ambos resulta em rejeição. A lógica de escolha é simples: para que o sistema altere com precisão apenas um bloco de pixels, use máscara; para apenas indicar "mais ou menos este lugar" sem querer ficar limitado por bordas rígidas, use imagem de anotação.

Áreas fora da máscara também podem mudar

Ao usar mask_url, esteja preparado: áreas fora da máscara também podem sofrer alterações leves. Se seu negócio exige que áreas não selecionadas permaneçam inalteradas no nível de pixel, isso não pode ser garantido no caminho de imagem-para-imagem; deve ser tratado por conta própria na fase de composição.

Cobrança

Imagem-para-imagem segue a tabela de preços de texto-para-imagem, com acréscimo de $ 0,012 por imagem de referência. low 1K com 1 imagem custa $ 0,035; com 16 imagens custa $ 0,215. Envie apenas as imagens de referência realmente necessárias.

Exemplo de corpo de requisição:

{
  "model": "gpt-image-2.6-flare/image-to-image",
  "prompt": "change the background to warm sunset",
  "image_urls": ["https://your-cdn/source.png"],
  "mask_url": "https://your-cdn/mask.png",
  "output_format": "png"
}

Detalhes dos campos podem ser consultados na página Flare imagem-para-imagem.

Estimativa de custo: calcular o preço por imagem por nível de qualidade e tamanho

Memorize primeiro os três critérios de cobrança:

• Texto-para-imagem (png/jpeg/webp): o preço por imagem é determinado em conjunto por quality e resolution.

• SVG: preço do PNG do mesmo nível mais $ 0,030.

• GIF: cobrado apenas por quality, independente da resolução: low $ 0,070, medium $ 0,124, high $ 0,150, xhigh $ 0,266, max $ 0,598.

• Imagem-para-imagem: preço da mesma tabela, com acréscimo de $ 0,012 por imagem de referência.

Como estimar uma imagem

Quatro passos: determine o modo (texto-para-imagem ou imagem-para-imagem) → determine o formato (gif considera apenas qualidade; svg adiciona $ 0,030; os demais seguem qualidade × resolução) → consulte o preço unitário do nível correspondente → para imagem-para-imagem, adicione $ 0,012 × número de imagens de referência. Níveis comuns de texto-para-imagem: low 1K $ 0,023, medium 1K $ 0,041, high 1K $ 0,049, high 2K $ 0,090, high 4K $ 0,160.

Quando não há cobrança

Requisições rejeitadas na fase de submissão são totalmente devolvidas, sem desconto. Isso inclui parâmetros inválidos (por exemplo, background=transparent com jpeg, ou passar aspect_ratio para gif) e tamanho de GIF acima do limite. Isso significa que erros de validação de parâmetros não queimam dinheiro, mas atrasam a iteração; recomenda-se fazer uma rodada de validação no cliente primeiro.

Veja todos os 15 níveis na página de preços. Para comparar com o critério de cobrança da geração anterior, consulte GPT Image 2.5 Flare texto-para-imagem.

Resumindo em uma frase: padrão Flare + texto-para-imagem + png; quando houver edições em múltiplas rodadas, mude para Sunburst; quando precisar de animação ou vetor, altere output_format.