Parâmetros da API do GPT Image 2: tamanho, resolução, proporção e qualidade
Os parâmetros da API do GPT Image 2 que definem a imagem: nome do modelo, tamanho, resolução, proporções, limites de 4K, qualidade, formatos e erros retornados.
Ler em MarkdownA API do GPT Image 2 recebe o nome do modelo em model, as dimensões de saída em size no formato WIDTHxHEIGHT em pixels e a qualidade em quality (low, medium, high ou auto). Não existe campo resolution nem aspect_ratio. Para obter uma imagem 16:9 em 4K, você envia "size": "3840x2160". Os tamanhos precisam usar múltiplos de 16, manter os dois lados em até 3840 pixels, ficar entre 1:3 e 3:1 e somar entre 655.360 e 8.294.400 pixels.
Este guia cobre cada parâmetro que muda a imagem, com o valor exato a enviar e o erro que um valor errado retorna. Todos os erros abaixo foram conferidos na API em produção.
Qual é o nome do modelo GPT Image 2 na API?
Use gpt-image-2 ou gpt-image-2-official. Os dois são o mesmo modelo com os mesmos campos; gpt-image-2 cobra um preço fixo por imagem entregue, e gpt-image-2-official cobra os tokens que cada renderização informa.
Nomes tirados de títulos não funcionam como IDs de modelo. gpt-image-2.0, GPT Image 2 ou chatgpt-images-2 retornam HTTP 400 com o código de erro 20002.
Como definir a resolução e a proporção?
Com size, em pixels. Escolha a proporção e a quantidade de pixels que você quer e envie a largura e a altura resultantes:
| Proporção | Cerca de 1K | Cerca de 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 3:2 | 1248x832 | 2496x1664 | 3504x2336 |
| 2:3 | 832x1248 | 1664x2496 | 2336x3504 |
| 4:3 | 1152x864 | 2304x1728 | 3264x2448 |
| 3:4 | 864x1152 | 1728x2304 | 2448x3264 |
| 16:9 | 1280x720 | 2560x1440 | 3840x2160 |
| 9:16 | 720x1280 | 1440x2560 | 2160x3840 |
| 21:9 | 1456x624 | 3024x1296 | 3808x1632 |
| 3:1 | 1728x576 | 3504x1168 | 3840x1280 |
São as mesmas conversões que o Playground usa quando você escolhe uma proporção e um preset de 1K, 2K ou 4K. O 4K quadrado para em 2880x2880 porque um quadrado de 3840 pixels passaria do limite total de pixels.
size: "auto" deixa as dimensões a cargo do modelo. É o padrão, e é prático, mas defina um tamanho explícito quando as saídas precisarem se encaixar em um layout ou combinar entre si.
A OpenAI descreve saídas acima de 2560×1440 como experimentais. Elas são aceitas dentro dos limites daqui, mas uma tela maior não garante mais detalhe.
Quais valores de tamanho são rejeitados?
| Valor enviado | Por que falha | Resposta |
|---|---|---|
"size": "16:9" | Proporção não é tamanho | 400 20001, a mensagem cita size |
"size": "4096x2304" | Lado acima de 3840 | 400 20001, a mensagem cita size |
"size": "1000x1000" | Não é múltiplo de 16 | 400 20001, a mensagem cita size |
"size": "3840x1024" | Mais largo que 3:1 | 400 20001, a mensagem cita size |
"resolution": "4k" | Campo desconhecido | 400 20001, nenhum campo citado |
"aspect_ratio": "16:9" | Campo desconhecido | 400 20001, nenhum campo citado |
Repare nas duas últimas linhas. Um campo desconhecido é rejeitado, mas o erro não diz qual é. Se você receber 20001 com a mensagem genérica “Check the parameters against the API documentation”, procure um campo que a API não aceita, como resolution, aspect_ratio ou response_format.
Qual qualidade escolher?
quality aceita low, medium, high e auto. Os níveis mais altos demoram mais e preservam detalhes mais finos. xhigh e max são exclusivos do GPT Image 2.5; enviá-los ao GPT Image 2 retorna 20001 com uma mensagem que cita quality.
Uma rotina prática: faça rascunhos em low enquanto a composição ainda muda, confira textura e texto pequeno em medium e produza as versões finais em high. No gpt-image-2, o preço é o mesmo em todos os níveis. No gpt-image-2-official, os níveis mais altos informam mais tokens de saída e, por isso, custam mais. O guia de preços mostra os números.
auto deixa o modelo escolher o nível. Defina um valor explícito quando comparar execuções, senão duas requisições "idênticas" podem renderizar em níveis diferentes.
O que controla formato e fundo?
output_format:png(padrão) oujpeg. Saída em WebP não é oferecida;webpretorna20001com uma mensagem que citaoutput_format.output_compression: de 0 a 100, só comjpeg.background:auto,opaqueoutransparent. Transparência exigepng;transparentcomjpegretorna20001com uma mensagem que citabackground.n: de 1 a 10 imagens por requisição. Você paga pelas imagens entregues.moderation:autooulow.
Como passar imagens de referência e máscaras?
Como URLs, nunca como arquivos ou base64. images recebe de 1 a 16 objetos no formato {"image_url": "https://..."}, e enviá-lo transforma a requisição em edição. mask recebe um objeto no mesmo formato: um PNG do tamanho da primeira imagem de referência, em que a área transparente marca o que mudar. A referência lista os limites de arquivo.
Perguntas frequentes
O GPT Image 2 suporta 4K?
Sim, dentro dos limites acima. 3840x2160 para 16:9 e 2160x3840 para 9:16 são os maiores quadros, e 2880x2880 é o maior quadrado.
Posso enviar uma proporção em vez de pixels?
Não para a API. Converta a proporção em um tamanho WIDTHxHEIGHT antes, usando a tabela acima ou o Playground, que mostra o tamanho exato antes de enviar.
Qual é o tamanho e a qualidade padrão?
Os dois têm auto como padrão, o que deixa a escolha para o modelo. Envie valores explícitos quando precisar de uma saída previsível.
Envie pixels, defina a qualidade e leia a mensagem de erro
Quase todo problema de parâmetro é uma de três coisas: uma proporção enviada como tamanho, um campo que a API não aceita ou um valor fora dos limites. No primeiro e no terceiro casos, a mensagem de erro cita o campo; uma mensagem genérica que não cita campo nenhum aponta para o segundo. Deixe esta página ao lado da referência da API do GPT Image 2 enquanto você integra.
