Como usar 1K, 2K, 4K, Quality e Mask no GPT Image: guia de testes da BetterToken

• Por que os resultados variam entre chamadas com o mesmo modelo e os mesmos parâmetros?
• Por que, mesmo solicitando 4K ou um tamanho específico, recebo uma imagem reduzida para 1K?
• O retoque localizado com Mask ou quality=high realmente funciona? E qual é o critério de cobrança?

Observação: este guia se concentra em gpt-image-2, gpt-image-2.5-flare e gpt-image-2.5-sunburst. Os parâmetros e o sistema de cobrança da série Nano Banana são diferentes e serão detalhados em outro artigo para evitar confusão.

​

1. Por que os resultados podem variar com o mesmo modelo e os mesmos parâmetros?

​

2. Como testamos: o que conta como “compatível”?

1. Decodificar os pixels do arquivo original: não confiamos apenas no que a API declara. Decodificamos as dimensões de cada imagem entregue a partir do arquivo original e as comparamos com a faixa de cobrança informada na resposta e com o débito real na conta.
2. Determinar se o tamanho foi atingido: comparamos separadamente a largura e a altura solicitadas explicitamente. Se as dimensões reais forem maiores, consideramos aprovado; se qualquer lado ficar mais de 5% abaixo do tamanho-alvo, consideramos que não atingiu o padrão (observação: esse critério é usado para avaliar rigorosamente os resultados dos testes e não significa que a API descarte automaticamente imagens válidas abaixo do tamanho solicitado). Se o tamanho for omitido ou enviado como auto, não há uma tela fixa como objetivo.
3. Separar aceitação dos parâmetros de resultado real: o fato de a API não retornar erro significa apenas que “aceitou o parâmetro”. Para saber se a Mask realmente isola uma região ou se quality=high oferece um ganho visual, é necessário avaliar a imagem final.

​

3. Resultados dos testes: quais parâmetros são mais mal interpretados?

• Tolerância dos parâmetros padrão: a geração funciona normalmente quando quality e size são omitidos, enviados como null ou definidos explicitamente como "auto".
• Como solicitar 4K corretamente: “4K” é uma faixa de cobrança, não significa suporte a imagens quadradas 4096x4096. Para obter uma imagem horizontal de alta resolução em 4K, use o tamanho 3840x2160.
• Bloqueio de parâmetros inválidos sem cobrança: quando foram enviados 4096x4096, stream=true, quality="", size="" ou n=0, todas as solicitações de teste retornaram erro HTTP 400 e não houve cobrança.

​

4. O que a BetterToken oferece: você não precisa adaptar cada rota

1. Roteamento inteligente por capacidade: o sistema seleciona automaticamente um serviço disponível com as capacidades adequadas, considerando o modelo, o tamanho-alvo (como 2K/4K) e a presença de parâmetros de edição de imagem ou Mask.
2. API unificada e fallback de parâmetros: as APIs padrão POST /v1/images/generations (geração de imagem) e POST /v1/images/edits (edição com imagem de referência/Mask) processam automaticamente valores null, auto e parâmetros omitidos, além de bloquear entradas inválidas diretamente no gateway.
3. Retorno transparente das dimensões reais e dos detalhes de cobrança: junto com os dados da imagem, o campo bettertoken_image_billing no corpo da resposta informa diretamente a largura e a altura decodificadas reais (width/height), a faixa de cobrança (billing_resolution), a moeda e o valor liquidado (settled_amount).
4. Distinção clara entre dois conceitos essenciais:
   • Suporte ao parâmetro Mask ≠ garantia de retoque preciso em nível de pixel: a API permite enviar imagem de referência e Mask para edição, mas alguns resultados dos testes também alteraram áreas protegidas fora da máscara. Por exemplo, no teste geométrico com dois círculos, pedimos a mudança de cor do círculo esquerdo transparente e a proteção do círculo direito opaco; no resultado, os dois círculos mudaram de cor. Portanto, confirmamos o suporte ao envio do parâmetro Mask, mas não garantimos que o isolamento rigoroso de áreas em nível de pixel seja alcançado em todas as chamadas.
   • Suporte ao parâmetro quality ≠ promessa de um ganho fixo de qualidade: a API aceita parâmetros como "auto" ou "high" e os encaminha corretamente. Como a geração envolve aleatoriedade, não prometemos, com base em uma única amostra, que high proporcionará determinado percentual de melhoria na qualidade.

⚠️ Dois limites reais que você precisa conhecer antes da integração:

1. Roteamento por capacidade não significa fixar rigorosamente os pixels em toda chamada: devido às diferenças de saída dos serviços subjacentes, os pixels reais podem variar mesmo quando a solicitação é encaminhada ao nó correto (por exemplo, hoje houve solicitações 1024x1024 que retornaram 1024×936 e amostras de 3840x2160 que retornaram 3840×2161). Se a proporção da tela for crítica para o seu negócio, use a largura e a altura reais da resposta para recortar ou processar a imagem posteriormente.
2. Solicitar 1K não significa necessariamente pagar como 1K: o sistema classifica a imagem pela especificação válida efetivamente entregue. Hoje, dois modelos 2.5 (e alguns casos de gpt-image-2) retornaram 1254×1254 para solicitações 1024x1024; por isso, o sistema as classificou como faixa 2K e aplicou o preço correspondente.

​

5. Compatibilidade dos três modelos: qual devo chamar e quais valores enviar?

​

6. Dois casos com imagens reais: como ficam os resultados?

​

Caso A: fotografia de produto para comércio eletrônico, dimensões e detalhes em 1K / 2K / 4K

Gere uma foto realista de estúdio para comércio eletrônico: uma caneca de cerâmica vermelho-coral (com a alça voltada para a direita) sobre uma bancada de pedra cinza-clara, com um pano de linho bege dobrado à esquerda. A caneca traz o texto branco nítido “BETTER DAY”. Luz lateral suave vinda do alto à esquerda; preserve os reflexos sutis do esmalte cerâmico, as fibras do linho e as sombras naturais de contato. A caneca aparece inteira e centralizada; fundo neutro e simples, sem outros objetos, marca-d’água ou texto adicional.

Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads "BETTER DAY" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text.

• Imagens bem finalizadas: as três apresentam os reflexos do esmalte vermelho-coral, a alça à direita, a bancada de pedra cinza-clara, as fibras do linho bege e o texto branco “BETTER DAY” legível.
• Diferenças entre amostras independentes: cada geração é uma amostragem independente. Por isso, a proporção da caneca, a espessura das letras e a dobra do tecido variam naturalmente (por exemplo, na imagem horizontal 4K o texto foi disposto em duas linhas). Assim, os recortes mostram apenas os detalhes reais de cada imagem e não constituem um experimento óptico de nitidez com composições rigorosamente iguais.
• Limite de cobrança demonstrado diretamente: embora a primeira imagem tenha sido solicitada em 1024x1024, ela foi entregue como uma imagem quadrada de alta resolução em 1254×1254 e cobrada na faixa 2K (¥0.11), assim como a segunda imagem de 2048×2048.

​

Caso B: mudança localizada da cor do produto, efeito real e limite da Mask

Altere somente o corpo vermelho-coral da caneca dentro da área transparente da máscara para azul-marinho escuro. Preserve o material cerâmico, a iluminação e os reflexos. Mantenha inalterados o texto branco “BETTER DAY”, a alça vermelha, o pano de linho, a bancada, o fundo e a composição geral. Não adicione nem remova nenhum objeto.

Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask.

• A intenção principal de mudança de cor foi atendida: a parte externa do corpo da caneca ficou azul-marinho escuro e preservou o brilho da cerâmica; a alça vermelha fora da máscara, o pano de linho à esquerda e o fundo foram preservados, e o texto “BETTER DAY” dentro da máscara continuou legível.
• O limite rigoroso da Mask não foi aprovado (houve vazamento para fora): ao observar a borda e a parede interna da caneca, é possível notar que parte da área vermelho-coral originalmente protegida pela máscara opaca também foi alterada para azul-escuro. No teste geométrico mais extremo dos “dois círculos”, o círculo direito não mascarado também mudou de cor.
• Recomendação de uso: ao enviar imagem de referência e Mask, confira se ambas têm o mesmo tamanho de tela (a área a modificar deve ser transparente; a área a preservar deve ser opaca) e informe no Prompt tanto “o que mudar” quanto “o que preservar”. Para imagens comerciais industriais com logotipos de marca, textos pequenos em embalagens ou exigências rigorosas nas bordas, amplie a imagem após a geração e inspecione os limites da área protegida.

​

7. Preços e custo real de uso: quanto será cobrado?

💡 Ponto essencial para planejar o orçamento: calcule pelo “nível efetivamente entregue”, não pelos “parâmetros solicitados”. Como mostram os testes anteriores, hoje algumas solicitações 1024x1024 (1K) para flare, sunburst ou gpt-image-2 entregaram imagens 1254×1254. Nesse caso, o sistema classifica pelo resultado real como 2K (ou seja, cobra ¥0.15 ou ¥0.11, e não o preço de 1K de ¥0.035). Se todas as 100 solicitações 1024x1024 para flare retornassem 1254×1254, o custo dessas 100 imagens, pelos preços atuais, seria ¥15.00 (estimativa aritmética). Além disso, a classificação combina o tamanho-alvo com um limite razoável de variação (por exemplo, 3840×2159 normalmente é classificado como 4K, e 1536×1024 como 1K). Não recalcule a cobrança no seu sistema com uma regra simplista como “se o lado maior passar de 1024”; a liquidação é sempre determinada pelo campo bettertoken_image_billing no corpo da resposta.

​

Por que não basta olhar o “baixo preço por imagem”?

1. O preço só é comparável se a resposta real atingir o tamanho-alvo: uma chamada anunciada como “suporte a 4K com preço muito baixo”, mas que entrega apenas uma imagem reduzida em 1024, não pode ser usada em produção que exija imagens de alta resolução e não deve entrar na comparação como um preço válido de 4K.
2. Inclua no total os erros e o custo de novas gerações: os testes de parâmetros inválidos desta rodada não foram cobrados; quando uma imagem é entregue corretamente, mas não atende à necessidade, enviá-la novamente é uma nova solicitação e deve ser orçado separadamente. As 4 imagens dos casos de produto e Mask deste guia (3 geradas + 1 editada) foram entregues, cada uma, em uma única chamada. A amostra com Mask apresentou a alteração fora da área descrita acima. Os preços individuais foram ¥0.11, ¥0.11, ¥0.13 e ¥0.11, totalizando apenas ¥0.46 de custo real pelas 4 imagens; a fatura correspondeu exatamente aos débitos da conta. Se a instabilidade da rota ou a incompatibilidade de parâmetros exigir novas gerações, o custo total real para obter um material utilizável pode aumentar, mesmo quando o preço aparente por imagem é baixo.
3. Reduza o custo oculto de adaptação da equipe de desenvolvimento: ao padronizar os parâmetros, rotear por capacidade e retornar em tempo real os pixels e campos de cobrança reais, a BetterToken reduz o trabalho de adaptar serviços diferentes e organizar separadamente as informações de tamanho e preço.

​

8. Exemplos de chamadas prontos para copiar

​

Exemplo 1: solicitação JSON para gerar uma imagem de produto em alta resolução (POST /v1/images/generations)

curl https://bettertoken.ai/v1/images/generations -o response.json \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "gpt-image-2",
  "prompt": "Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads \"BETTER DAY\" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text.",
  "size": "2048x2048",
  "quality": "high",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}
JSON

• Observação sobre o tamanho: para uma imagem horizontal 4K, altere "size" para "3840x2160" (não use "4096x4096"). Os tamanhos válidos atuais precisam atender a estes critérios: largura e altura múltiplas de 16, maior lado de no máximo 3840, proporção entre lado maior e menor de no máximo 3:1 e total de pixels entre 655,360 e 8,294,400.
• Observação sobre a identificação do formato do arquivo: mesmo que a solicitação especifique "output_format": "png", alguns nós subjacentes ainda podem retornar conteúdo binário em JPEG. Ao salvar ou processar a imagem, recomendamos identificar o formato real pelo cabeçalho do arquivo (Magic Bytes), em vez de fixar a extensão.

​

Exemplo 2: edição localizada Multipart com imagem de referência e Mask (POST /v1/images/edits)

curl https://bettertoken.ai/v1/images/edits -o response.json \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@product-1k-0.png;type=image/png" \
  -F "mask=@mask-mug.png;type=image/png" \
  -F 'prompt=Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask.' \
  -F "size=2048x2048" \
  -F "quality=high" \
  -F "n=1" \
  -F "response_format=b64_json"

​

Exemplo 3: leitura dos pixels entregues e das informações de cobrança (estrutura da resposta e código de análise)

{
  "created": 1792398084,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "bettertoken_image_billing": {
    "currency": "CNY",
    "settled_amount": "0.11",
    "outputs": [
      {
        "index": 0,
        "width": 2048,
        "height": 2048,
        "billing_resolution": "2K",
        "currency": "CNY",
        "amount": "0.11"
      }
    ]
  }
}

import base64
import io
import json
from pathlib import Path
from PIL import Image  # 需要 Pillow

# 将 API 的 JSON 响应保存为 response.json 后执行。
resp_json = json.loads(Path("response.json").read_text())
if "error" in resp_json:
    raise RuntimeError(resp_json["error"])

billing = resp_json["bettertoken_image_billing"]
outputs = {item["index"]: item for item in billing["outputs"]}
for index, item in enumerate(resp_json["data"]):
    img_bytes = base64.b64decode(item["b64_json"], validate=True)
    with Image.open(io.BytesIO(img_bytes)) as image:
        image.load()
        width, height = image.size
        ext = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}.get(image.format)
        if ext is None:
            raise ValueError(f"未处理的图片格式：{image.format}")
    Path(f"output_{index}.{ext}").write_bytes(img_bytes)
    info = outputs[index]
    print(f"图片 {index}：原图 {width}×{height}；计费档位 {info['billing_resolution']}")
    print(f"单张费用：{info['amount']} {info['currency']}")
    if (width, height) != (info["width"], info["height"]):
        print("图片像素与响应尺寸不一致，请保留结果并联系支持。")
print(f"本次结算：{billing['settled_amount']} {billing['currency']}")

• Documentação oficial da OpenAI: guia para escrever prompts de imagem (Image Prompting Guide)
• OpenAI Cookbook: exemplo de geração e edição de imagens com alta fidelidade de entrada