gpt-image-2.6-all 的 2K/4K：não confie no size retornado na resposta

Nota do autor: nas faixas 2K/4K do gpt-image-2.6-all, o upscale (super-resolução) é aplicado depois da geração, então a resposta pode não devolver o size e os pixels reais às vezes saem diferentes do esperado. Este artigo explica o motivo e mostra como salvar a imagem, ler a largura e a altura reais e só então fazer a diagramação.

Muita gente conecta a interface de geração de imagens a pipelines de template de pôster, imagem principal de e-commerce ou capa de vídeo e acaba lendo direto o campo size da resposta para calcular o canvas e o layout. Nas faixas 2K/4K do gpt-image-2.6-all, essa abordagem é arriscada. Na descrição do modelo publicada em 2026-11-11, a APIYI (apiyi.com) deixa claro que 2K/4K são faixas de super-resolução: a resposta pode não devolver o size, e em alguns casos os pixels reais também diferem do esperado. O que vale é a largura e a altura reais do arquivo de imagem, e essa é a conclusão da própria documentação.

Esse problema afeta diretamente o resultado da diagramação. Uma imagem de 1365x2048 tratada como 9:16 e colocada num template vertical vai gerar espaços em branco ou esticamento, e o elemento principal ainda pode ser cortado.

Valor central: depois desta leitura, você vai entender por que não dá para confiar nos campos da resposta nas faixas 2K/4K e vai saber como salvar a imagem, ler os pixels reais e só então passar o resultado para a lógica de diagramação.

---

gpt-image-2.6-all 2K/4K: pontos principais sobre tamanho

A tabela abaixo reúne as informações da documentação relacionadas a tamanho. O código e a estratégia de diagramação que aparecem mais adiante se baseiam nelas.

Ponto	Explicação	Impacto na diagramação
2K/4K são faixas com super-resolução	O arquivo final passa por um processo de super-resolução, e os pixels são definidos nessa etapa	Não dá para calcular o tamanho final a partir dos parâmetros da requisição
O size pode não ser devolvido	Na resposta das faixas 2K/4K, talvez o campo size não venha	Se o código depender desse campo, vai ler um valor vazio ou dar erro
Desvios ocasionais de pixels	Em 9:16, às vezes sai 1365x2048; em 4K, às vezes sai 4096x2731	A proporção pode ficar diferente da que foi solicitada
quality=low tem diferenças	Na faixa 2K, a saída pode ser 2048x1153	Aparecem lados com número ímpar, o que faz alguns fluxos de codificação de vídeo darem erro
Vale a largura e a altura reais	A documentação diz claramente que o que vale é a largura e a altura reais do arquivo de imagem	Salvar a imagem e só então ler os pixels é a única fonte de dados confiável

Por que o campo size do gpt-image-2.6-all 2K/4K não é confiável

Uma boa forma de entender as faixas com super-resolução é pensar em dois passos: primeiro o modelo gera uma imagem base, depois ela é ampliada para 2K ou 4K. Os pixels do arquivo final são definidos na etapa de super-resolução, e o campo size da resposta nem sempre acompanha isso. A documentação descreve o comportamento das faixas 2K/4K como “pode não devolver o size”. Ou seja, com o mesmo código, às vezes você consegue ler esse campo e às vezes não.

O caso realmente chato é quando o campo existe, mas não bate com o arquivo. O código não dá erro, os números parecem normais, e o problema só aparece quando a diagramação já está pronta. Por isso, o mais seguro é não tratar o size como fonte do tamanho: no máximo, use-o para comparar nos logs. A largura e a altura usadas na diagramação devem sempre ser lidas do arquivo de imagem salvo.

gpt-image-2.6-all 2K/4K: desvios de pixels conhecidos

A documentação lista algumas situações pontuais de pixels. A tabela abaixo converte esses pixels em proporção de aspecto, para facilitar a avaliação do impacto na diagramação.

Cenário	Pixels reais que podem aparecer	Proporção convertida	Risco para a diagramação
Proporção 9:16	1365x2048	cerca de 0,667, próxima de 2:3	Num template 9:16, sobram margens laterais ou a imagem é cortada
Faixa 4K	4096x2731	cerca de 1,5, próxima de 3:2	O lado curto não bate com o esperado e um canvas fixo fica desalinhado
Faixa 2K + quality=low	2048x1153	cerca de 1,776, próxima de 16:9	A altura é ímpar, e fluxos de codificação que exigem lados pares falham

Esses exemplos mostram que o lado maior normalmente fica em 2048 ou 4096, enquanto o lado menor varia. No primeiro caso, o desvio de proporção é bem evidente: 9:16 é cerca de 0,5625, e 1365x2048 é cerca de 0,667. Se o código calcular o canvas com base no 9:16 solicitado, as margens ficam muito visíveis. No terceiro caso, a proporção quase não muda, mas 1153 é ímpar. Os formatos de pixel de vídeo mais comuns exigem largura e altura pares, então usar essa imagem como capa ou primeiro frame de um vídeo pode gerar erro na transcodificação.

Todos esses casos são “pontuais”: ao testar com algumas imagens, pode ser que tudo funcione bem, e o problema só aparece depois que o sistema vai ao ar. Por isso, a lógica de validação deve rodar após cada geração, e não apenas como amostragem na fase de testes.

---

Início rápido com gpt-image-2.6-all em 2K/4K: lendo os pixels reais

A ideia central cabe em uma frase: primeiro você pega o conteúdo binário da imagem e salva, depois usa uma biblioteca de imagens para ler a largura e a altura. O exemplo abaixo usa o SDK Python compatível com a OpenAI e o Pillow. Os parâmetros da requisição, como o nível 2K/4K e a proporção, devem seguir a documentação da APIYI, então no exemplo deixei só um placeholder.

Exemplo mínimo: comparando o size da resposta com os pixels reais

Este código gera uma imagem e imprime, lado a lado, o campo da resposta e os pixels reais, para você ver a diferença entre os dois.

import base64， io， requests
from openai import OpenAI
from PIL import Image

client = OpenAI（api_key="YOUR_API_KEY"， base_url="https://api.apiyi.com/v1"）

resp = client.images.generate（
    model="gpt-image-2.6-all"，
    prompt="一张竖版城市夜景海报"，
    # preencha os parâmetros de nível 2K/4K conforme a documentação da APIYI
）
item = resp.data[0]
raw = base64.b64decode（item.b64_json） if item.b64_json else requests.get（item.url， timeout=120）.content

img = Image.open（io.BytesIO（raw））
print（"真实像素："， img.size）                       # (largura, altura)
print（"响应 size:"， getattr（resp， "size"， None））   # pode ser None em 2K/4K

Usei getattr para ler o size porque ele não lança exceção quando o campo não existe. O código também funciona tanto com resposta em URL quanto em base64, e o restante da lógica depende só do conteúdo binário da imagem. Se, na documentação, o seu caso de uso passar por outro endpoint, basta trocar a etapa de “obter o conteúdo da imagem”. A parte que lê os pixels continua exatamente igual.

Implementação completa: validar após salvar e gerar parâmetros de layout

Em produção, o ideal é reunir tudo na mesma função: salvar o arquivo, ler a largura e a altura reais, comparar com os campos da resposta, checar desvio de proporção e lados com número ímpar, e só então calcular o redimensionamento com base no tamanho real.

import base64
import io
from pathlib import Path
from uuid import uuid4

import requests
from openai import OpenAI
from PIL import Image

client = OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://api.apiyi.com/v1",
）

# Os parâmetros de faixa 2K/4K, proporção etc. seguem a documentação da APIYI; aqui é apenas um placeholder
TIER_PARAMS = {}


def fetch_image_bytes（item） -> bytes:
    if getattr（item， "b64_json"， None）:
        return base64.b64decode（item.b64_json）
    return requests.get（item.url， timeout=120）.content


def parse_declared_size（resp）:
    size = getattr（resp， "size"， None）
    if not size or "x" not in str（size）.lower（）:
        return None
    w， h = str（size）.lower（）.split（"x"）
    return int（w）， int（h）


def generate_and_measure（prompt， expected_ratio=None， out_dir="outputs"）:
    resp = client.images.generate（
        model="gpt-image-2.6-all"，
        prompt=prompt，
        **TIER_PARAMS，
    ）
    raw = fetch_image_bytes（resp.data[0]）
    img = Image.open（io.BytesIO（raw））
    width， height = img.size  # Única fonte confiável para o tamanho

    Path（out_dir）.mkdir（exist_ok=True）
    ext = （img.format or "png"）.lower（）
    path = Path（out_dir） / f"{uuid4（）.hex[:8]}_{width}x{height}.{ext}"
    path.write_bytes（raw）

    declared = parse_declared_size（resp）
    report = {
        "path": str（path），
        "width": width，
        "height": height，
        "declared": declared，
        "declared_match": （declared == （width， height）） if declared else None，
        "odd_dimension": width % 2 == 1 or height % 2 == 1，
    }
    if expected_ratio:
        real_ratio = width / height
        report["ratio_drift"] = round（abs（real_ratio - expected_ratio） / expected_ratio， 4）
    return report


def fit_into_box（width， height， box_w， box_h， mode="contain"）:
    if mode == "contain":
        scale = min（box_w / width， box_h / height）
    else:
        scale = max（box_w / width， box_h / height）
    return round（width * scale）， round（height * scale）


if __name__ == "__main__":
    r = generate_and_measure（"竖版城市夜景海报"， expected_ratio=9 / 16）
    print（r）
    if r.get（"ratio_drift"， 0） > 0.01:
        print（"比例漂移超过 1%，建议改用 contain 或重新生成"）
    print（fit_into_box（r["width"]， r["height"]， 1080， 1920））

Essa implementação tem três decisões de design que valem uma explicação:

• O nome do arquivo carrega a largura e a altura reais: os serviços downstream não precisam decodificar a imagem de novo, porque o tamanho já está no nome.
• declared_match serve só para log: ele ajuda a medir com que frequência o campo vem ausente ou inconsistente, mas não entra no cálculo de layout.
• odd_dimension barra o problema cedo: uma imagem como 2048x1153 pode ter 1 pixel cortado ou preenchido antes de ir para a codificação de vídeo.

🚀 Dica para começar rápido: rode uma chave API na APIYI (apiyi.com) nas duas faixas, 2K e 4K, imprima o report acima e observe com que frequência aparecem campos ausentes e desvios de proporção. Só depois defina os limites de tolerância para produção. A plataforma usa uma interface compatível com a OpenAI, então basta ajustar o base_url no código de exemplo para ele funcionar.

---

Adaptação de layout para gpt-image-2.6-all em 2K/4K

Obter os pixels reais é só o primeiro passo. O próximo é fazer a lógica de layout rodar inteiramente com base nesses dados. Antes, vamos comparar as três fontes de informação de tamanho e definir qual delas serve para tomar decisões.

Fonte da informação	Confiabilidade	Comportamento em 2K/4K	Uso recomendado
Faixa e proporção escolhidas na requisição	Baixa	Após o upscaling, os pixels reais podem fugir do esperado	Expressa a expectativa e serve de referência para o desvio de proporção
Campo size na resposta	Baixa	Pode não vir na resposta, ou vir diferente do arquivo	Só para log e estatísticas
Largura e altura reais do arquivo de imagem	Alta	A documentação deixa claro que vale o que está no arquivo	Única base para layout, recorte e codificação

Lendo a largura e a altura reais do gpt-image-2.6-all em 2K/4K em cada etapa

A imagem pode ser gerada no back-end, exibida no front-end e, por fim, repassada para uma ferramenta de vídeo. Cada etapa tem uma forma própria de ler os pixels reais, então não é preciso ficar repassando a informação de tamanho de uma etapa para outra.

Etapa	Forma de leitura	Observações
Back-end em Python	Image.open(...).size do Pillow	Lê só o cabeçalho do arquivo para obter largura e altura, com custo muito baixo
Front-end no navegador	img.naturalWidth / img.naturalHeight	Leia depois do onload e não use o tamanho renderizado pelo CSS
Linha de comando ou transcodificação	ffprobe ou identify do ImageMagick	Aproveite para checar se as dimensões são pares antes de codificar
Armazenamento de objetos	Gravar largura e altura nos metadados ou no nome do arquivo no upload	Os serviços seguintes leem direto, sem precisar decodificar de novo

O front-end é a etapa em que mais se cai em armadilhas. Muitos componentes definem largura e altura fixas para a imagem, e aí o que você lê é o tamanho renderizado, não os pixels da imagem em si. Para saber se a imagem original está perto de 9:16, use naturalWidth e naturalHeight.

Estratégias para lidar com a deriva de proporção em 2K/4K no gpt-image-2.6-all

Não dá para eliminar totalmente a deriva de proporção. O que dá para fazer é decidir de antemão o que fazer quando ela aparecer. As três estratégias abaixo estão ordenadas do menor para o maior risco.

Estratégia	Como funciona	Cenários indicados	Custo
Ajuste com contain	Redimensiona mantendo a proporção real da imagem, encaixando-a por inteiro no canvas	Pôsteres e páginas de detalhe de produto, onde o assunto principal não pode ser cortado	Pode sobrar espaço em branco, exigindo cor de fundo ou uma imagem de fundo desfocada para preencher
Corte com cover	Amplia mantendo a proporção até preencher o canvas e corta o excedente	Capas e banners, onde as informações nas bordas não são importantes	Se o assunto estiver perto da borda, corre o risco de ser cortado
Nova tentativa por deriva	Gera de novo se a deriva de proporção passar de um limite	Templates com exigência rígida de proporção	Custo de uma chamada extra e mais tempo de espera

Para lados com número ímpar de pixels, o ideal é tratar tudo antes de entrar no fluxo de codificação: corte 1 pixel ou adicione uma borda de 1 pixel de cor sólida. Uma imagem de 2048x1153 cortada para 2048x1152 vira exatamente 16:9, e a diferença visual é praticamente imperceptível.

---

gpt-image-2.6-all 2K/4K: perguntas frequentes (FAQ)

Q1: O que são os modos 2K/4K do gpt-image-2.6-all?

De acordo com a descrição do modelo publicada pela APIYI em 2026-11-11, 2K/4K são modos de super-resolução: a imagem final passa por um processo de upscaling antes de ser devolvida. É por isso que o comportamento do tamanho é diferente dos modos comuns: a resposta pode não trazer o campo size de volta, e os pixels reais às vezes saem com pequenos desvios.

Q2: Nos modos 2K/4K, em qual eu devo confiar: o size da resposta ou o tamanho real do arquivo?

No arquivo. A documentação deixa claro que vale a largura e a altura reais da imagem. O size da resposta pode simplesmente não aparecer nos modos 2K/4K e, mesmo quando aparece, serve só para log. Não use esse valor para calcular canvas, áreas de recorte ou parâmetros de codificação.

Q3: Quais tamanhos fora do esperado já são conhecidos?

A documentação lista estes casos: na proporção 9:16, às vezes sai `1365×2048`; em 4K, às vezes sai `4096×2731`; e com quality=low no modo 2K, a saída pode ser `2048×1153`. Todos são casos ocasionais, então a validação deve rodar a cada geração, e não só como uma checagem por amostragem durante os testes.

Q4: Posso validar só algumas imagens na fase de testes e não validar mais depois de ir para produção?

Não é recomendado. Num teste com poucas amostras, é bem provável que o problema ocasional nunca apareça. Ler largura e altura custa muito pouco: o Pillow só precisa interpretar o cabeçalho do arquivo. Colocar a validação direto na função de geração dá bem menos trabalho do que investigar depois um layout desalinhado.

Q5: Como chamar o gpt-image-2.6-all pela API e verificar o tamanho rapidamente?

Siga estes passos:

1. Crie uma conta em apiyi.com (APIYI) e pegue sua chave API, além do crédito de teste para novos usuários
2. Defina o base_url do código de exemplo como `https://api.apiyi.com/v1` e preencha o parâmetro do modo conforme a documentação
3. Rode o código completo e confira no report os campos declared_match, ratio_drift e odd_dimension

Q6: Qual o impacto de uma altura ímpar no modo 2K?

Para exibir imagens estáticas, em geral nenhum. Mas se a imagem for usada como primeiro frame de vídeo, capa ou material para transcodificação, muitos fluxos de codificação exigem largura e altura pares. Ao se deparar com tamanhos como `2048×1153`, o recomendado é cortar ou completar 1 pixel antes de passar a imagem para o codificador.

Q7: Como é feita a cobrança do gpt-image-2.6-all?

A documentação indica cobrança por chamada, a US$ 0,025 por vez. Se você adotar a estratégia de “tentar de novo quando o desvio de proporção passar do limite”, precisa incluir o número de tentativas extras no custo. Dá para usar o crédito de teste na APIYI (apiyi.com) para medir a frequência dos desvios e só então decidir o quão rígido deve ser o limite.

---

gpt-image-2.6-all 2K/4K: pontos-chave (Key Takeaways)

• 2K/4K é uma faixa com super-resolução: o tamanho final em pixels é definido na etapa de super-resolução e não dá para calculá-lo a partir dos parâmetros da requisição.
• Não dependa do campo size: nas respostas 2K/4K, o size pode não ser devolvido; no máximo, use-o para comparar com os logs.
• Os desvios são esporádicos e difíceis de reproduzir: 1365x2048, 4096x2731 e 2048x1153 podem aparecer em produção.
• Primeiro salve, depois leia os pixels: use Pillow ou naturalWidth para ler a largura e a altura reais do arquivo e só então faça o layout.
• Trate lados ímpares com antecedência: antes de enviar para a codificação de vídeo, corte ou preencha 1 pixel.
• Use créditos de teste para definir limites: no APIYI (apiyi.com), rode um pequeno lote para medir a frequência da variação e só depois defina a estratégia de nova tentativa.

---

Resumo

Os pontos principais para lidar com os tamanhos 2K/4K do gpt-image-2.6-all:

1. Não confie no size da resposta: a faixa com super-resolução pode não devolver esse campo e, quando ele existe, pode não bater com o arquivo.
2. Considere sempre a largura e a altura reais da imagem: depois de salvar, leia os pixels. É o critério que a documentação define de forma explícita.
3. Faça um layout que tolere variações: use contain, cover ou uma estratégia de nova tentativa para lidar com desvios de proporção, e trate lados ímpares com antecedência.

Se você colocar a leitura dos pixels reais dentro da própria função de geração, evita desalinhamentos de layout na origem, e as etapas seguintes nem precisam se preocupar com a confiabilidade dos campos da resposta. Recomendamos usar o APIYI (apiyi.com) para rodar o fluxo de validação acima com uma única chave API e confirmar que as faixas 2K/4K se comportam de forma estável nos seus templates antes de ir para produção.

---

📚 Referências

1. Nota de lançamento do gpt-image-2.6-all na APIYI: faixas de super-resolução 2K/4K, eco do parâmetro size e pixels reais
2. Link: docs.apiyi.com/live/2026-11/gpt-image-2-6-all-launch

3. Descrição: traz a definição das faixas de super-resolução, os casos ocasionais de pixels diferentes do esperado, a orientação de sempre considerar a largura e a altura reais e o preço por chamada

4. Documentação oficial do Pillow: biblioteca Python para leitura de imagens

5. Link: pillow.readthedocs.io

6. Descrição: como usar Image.open e o atributo size, ideal para ler os pixels reais no backend

7. Documentação do MDN sobre HTMLImageElement: propriedades de imagem no navegador

8. Link: developer.mozilla.org/docs/Web/API/HTMLImageElement
9. Descrição: o que significam naturalWidth e naturalHeight, e como eles se diferenciam do tamanho renderizado

---

Autor: Equipe técnica da APIYI
Troca de ideias técnicas: fale com a gente pela página inicial do site da APIYI. Mais materiais estão disponíveis na central de documentação em docs.apiyi.com

Artigos relacionados

• Como escolher o canal GPT-Image: diferenças entre os 3 tipos de canais (conversão oficial e engenharia reversa oficial, -all e -vip), histórico de falhas e 5 estratégias de contingência: Comparar as diferenças entre os três canais GPT-Image (oficial, -all e -vip) quanto a cobrança, tamanho e edição localizada, revisar as falhas históricas de abril a outubro de 2026 e propor uma solução de contingência com "novas tentativas limitadas + disjuntor + canal de reserva".