> ## Documentation Index > Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt > Use this file to discover all available pages before exploring further. # Como usar 1K, 2K, 4K, Quality e Mask no GPT Image: guia de testes da BetterToken > Guia com testes reais de geração de imagens GPT, tamanhos entregues, qualidade, edição com máscara, roteamento, resultados observados e preços da BetterToken. export const GptImageComparison = ({kind, labels, caption, label}) => { const comparisonPanels = { crops: [["comparison-crop-1k.png", 480, 480], ["comparison-crop-2k.png", 480, 480], ["comparison-crop-4k.png", 480, 480]], mask: [["comparison-mask-original.png", 476, 476], ["comparison-mask-overlay.png", 476, 476], ["comparison-mask-result.png", 476, 476]], boundary: [["comparison-boundary-original.png", 576, 256], ["comparison-boundary-result.png", 576, 256]], circles: [["comparison-circles-original.png", 416, 416], ["comparison-circles-overlay.png", 416, 416], ["comparison-circles-result.png", 416, 416]] }; const panels = comparisonPanels[kind]; return
{labels.map((title, index) =>

{title}

)} {panels.map(([file, width, height], index) => {labels[index]} )}

{caption}

; }; Ao gerar imagens de produtos, materiais publicitários ou projetos com `gpt-image-2`, `gpt-image-2.5-flare` e `gpt-image-2.5-sunburst`, muitos desenvolvedores se deparam com algumas dúvidas: * **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?** Nas chamadas cotidianas à API, verificar apenas se o status HTTP é `200 OK` está longe de ser suficiente: estas três condições precisam ser atendidas ao mesmo tempo: **gerar a imagem, conseguir usá-la no layout previsto e ter custos transparentes e previsíveis**. Para ajudar os desenvolvedores a entender o comportamento real desses três modelos, a BetterToken implementou, na camada interna, **roteamento inteligente por capacidade, limpeza de parâmetros padrão, bloqueio prévio de parâmetros inválidos e cobrança transparente com base nos pixels efetivamente entregues**. Este guia se baseia nos dados de testes mais recentes e em uma captura de preços de 19 de outubro de 2026. Com imagens originais geradas e faturas reais, mostramos como fazer as chamadas, quais resultados você pode obter e quais limites objetivos os próprios modelos ainda têm. > **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? Na integração real, os diferentes nós de serviço por trás do mesmo nome de modelo costumam variar em capacidade e estabilidade: algumas rotas só oferecem geração básica em 1K, enquanto outras entregam imagens de alta resolução em `2048×2048` ou até `3840×2160`. O suporte aos valores de `quality`, à edição com imagem de referência e às máscaras `Mask` também varia entre os nós. Se a plataforma simplesmente encaminhar as solicitações às cegas pelo nome do modelo, os desenvolvedores frequentemente enfrentarão situações como “solicitei 4K, mas recebi uma imagem pequena em 1K”, “enviei uma Mask e a chamada falhou” ou “preciso ajustar os parâmetros várias vezes”. É por isso que precisamos de um padrão rigoroso de testes, que verifique separadamente a aceitação dos parâmetros pela API e o resultado realmente entregue. ## 2. Como testamos: o que conta como “compatível”? Para garantir conclusões objetivas e confiáveis, criamos **22 cenários de teste padrão** na regressão da versão estável (17 solicitações válidas entregaram 18 imagens; os 5 casos com parâmetros inválidos foram bloqueados como esperado e não geraram cobrança) e também geramos imagens de produtos e amostras de edição com Mask para cenários frequentes de comércio eletrônico. Nossos critérios de verificação são diretos: 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? Ao comparar os parâmetros solicitados, os pixels realmente entregues e a fatura final, encontramos alguns fatos importantes que os desenvolvedores costumam entender errado: | Cenário solicitado | Tamanho efetivamente entregue | Faixa de cobrança e preço em CNY | Resultado dos testes e significado prático | | :- | :- | :- | :- | | `gpt-image-2`, `2048x2048`, sem especificar `quality` | 2048×2048 | 2K, ¥0.11 | Nesta chamada, a imagem grande em 2K foi gerada com sucesso sem enviar `quality` (usou-se a qualidade padrão) | | `flare`, `2048x2048`, sem especificar `quality` | 2048×2048 | 2K, ¥0.15 | A entrega em 2048×2048 foi verificada nos testes | | `sunburst`, `2048x2048`, sem especificar `quality` | 2048×2048 | 2K, ¥0.15 | A entrega em 2048×2048 foi verificada nos testes | | `gpt-image-2`, `1024x1024` | **1024×936** | 1K, ¥0.035 | Uma imagem válida foi entregue, mas a altura ficou cerca de 8.6% menor; não atingiu o rigoroso padrão de tamanho desta rodada | | `flare` / `sunburst`, `1024x1024` | **ambos, 1254×1254** | **2K, ambos a ¥0.15** | **Solicitar 1K não garante cobrança em 1K**; as imagens quadradas entregues superaram o tamanho solicitado e foram classificadas como 2K | | `gpt-image-2`, `1536x1024` | 1536×1024 | 1K, ¥0.035 | Uma imagem horizontal com proporção comum também fica na faixa de cobrança 1K | | `gpt-image-2`, `3840x2160` | **3840×2159** | 4K, ¥0.13 | A altura difere por apenas 1 pixel (desvio \< 0.05%), atendendo ao critério de aceitação para 4K | | `gpt-image-2`, Mask válida + `2048x2048` + `high` | 2048×2048 | 2K, ¥0.11 | O fluxo de edição com Mask funcionou, mas o isolamento preciso da região precisa ser avaliado na imagem | Além disso, os testes mostraram o seguinte sobre compatibilidade de parâmetros e tratamento de erros: * **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 Diante das variações de tamanho e das diferenças entre os nós dos modelos subjacentes, a BetterToken cuida de quatro aspectos no gateway para que você não precise escrever código de adaptação para 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? A configuração de capacidades e a cobertura atual dos testes de `gpt-image-2`, `gpt-image-2.5-flare` e `gpt-image-2.5-sunburst` são as seguintes: | Dimensão de capacidade | `gpt-image-2` | `gpt-image-2.5-flare` | `gpt-image-2.5-sunburst` | | :- | :- | :- | :- | | **Solicitação de geração 1K** | Compatível (testado; o tamanho real pode divergir do alvo, por exemplo, 1024×936 ou 1254×1254) | Compatível (testado; nesta rodada retornou 1254×1254, maior, e cobrou como 2K) | Compatível (testado; nesta rodada retornou 1254×1254, maior, e cobrou como 2K) | | **Geração 2K (`2048x2048`)** | **Entrega testada nesta rodada** | **Entrega testada nesta rodada** | **Entrega testada nesta rodada** | | **Geração 4K (`3840x2160`)** | **Entrega horizontal testada nesta rodada** | Configuração de roteamento alinhada para oferecer suporte | Configuração de roteamento alinhada para oferecer suporte | | **Edição comum com imagem de referência (sem Mask)** | **Suporte testado nesta rodada** (omitir ou enviar uma Mask vazia aciona a edição comum) | Ainda não confirmado separadamente (suporte a Mask não comprova suporte à edição comum) | Ainda não confirmado separadamente (suporte a Mask não comprova suporte à edição comum) | | **Edição localizada com Mask** | **Entrega em 2K testada nesta rodada** | Configurado para suportar edição com Mask em 4K (outras faixas não confirmadas) | Configurado para suportar edição com Mask em 4K (outras faixas não confirmadas) | | **Parâmetro de qualidade (`quality`)** | Valores padrão/`auto`/`high` **todos verificados em testes** | Padrão/`auto` testados; roteamento de `high` alinhado na configuração | Padrão/`auto` testados; roteamento de `high` alinhado na configuração | *Observação: “Testado nesta rodada” significa que as regressões e a geração dos casos de hoje entregaram imagens e amostras de cobrança diretamente. “Configuração de roteamento alinhada para oferecer suporte” significa que a plataforma alinhou a configuração do canal para a capacidade correspondente, mas não repetiu hoje as chamadas para todas as combinações possíveis.* ## 6. Dois casos com imagens reais: como ficam os resultados? Para mostrar a qualidade de geração mais realista possível, usamos a estrutura **“sujeito explícito + textura do material + direção da luz + proporção da composição + elementos a excluir”** da [orientação oficial da OpenAI para prompts de imagem](https://developers.openai.com/api/docs/guides/image-prompting) e geramos os dois casos de comércio eletrônico a seguir pela API real da BetterToken (as saídas originais foram mantidas, sem retoque posterior). ### Caso A: fotografia de produto para comércio eletrônico, dimensões e detalhes em 1K / 2K / 4K **Descrição da cena (conceito original em chinês)**: > 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. **Prompt real enviado em inglês**: ```text theme={null} 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. ``` Usamos `gpt-image-2` (`quality="high"`, 1 imagem por geração), mantivemos o Prompt exatamente igual e solicitamos três faixas de tamanho diferentes apenas pelo parâmetro `size`, sem inserir “4K” no prompt para forçar o resultado: | Tamanho solicitado (`size`) | Tamanho efetivamente entregue | Faixa de cobrança / preço real | Duração da chamada | | :- | :- | :- | :- | | `1024x1024` | **1254×1254** | **2K / ¥0.11** | 34.35 segundos | | `2048x2048` | **2048×2048** | **2K / ¥0.11** | 31.97 segundos | | `3840x2160` | **3840×2161** | **4K / ¥0.13** | 24.36 segundos | **1. Imagem original entregue para a solicitação `1024x1024` (retorno real de 1254×1254):** Imagem de produto do GPT Image 2: solicitação de 1024×1024, entrega real de 1254×1254 **2. Imagem original entregue para a solicitação `2048x2048` (retorno real de 2048×2048):** Imagem de produto do GPT Image 2: solicitação e entrega real de 2048×2048 **3. Imagem horizontal original entregue para a solicitação `3840x2160` (retorno real de 3840×2161):** Imagem horizontal de produto do GPT Image 2: solicitação de 3840×2160, entrega real de 3840×2161 **4. Comparação de recortes em tamanho original das áreas correspondentes nas três imagens (texto da caneca e detalhes do material):** **Observações dos testes**: * **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 Usamos como imagem original a primeira imagem de produto do Caso A (`1254×1254`) e criamos uma máscara com canal Alpha e as mesmas dimensões [mask-mug.png](/images/gpt-image-guide/mask-mug.png): **somente o polígono do corpo da caneca ficou transparente (permitindo redesenho); a alça, a parede interna da borda e o fundo ficaram opacos (devem ser preservados); o texto da caneca ficou dentro da área transparente e o prompt pediu que ele fosse preservado**. Diagrama da área da Mask: preto indica a região transparente que pode ser alterada; branco, a região opaca que deve ser preservada *(Observação: a imagem acima é uma visualização em preto e branco; preto indica a região que pode ser modificada e branco, a região a preservar. O arquivo realmente enviado pela API foi `mask-mug.png`, com canal de transparência.)* **Descrição da cena (conceito original em chinês)**: > 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. **Prompt real de edição (modelo: `gpt-image-2`, `size="2048x2048"`, `quality="high"`)**: ```text theme={null} 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. ``` **Resultado real da edição entregue (2048×2048, duração 38.51 segundos, preço ¥0.11):** Resultado da edição com Mask no GPT Image 2: o corpo da caneca fica azul-escuro e a alça permanece vermelha, mas a parede interna da borda também muda de cor **Comparação detalhada do vazamento para a área protegida:** **Exemplo contrário: amostra de mudança de cor em “dois círculos” no teste de regressão (aceitar Mask ≠ isolamento preciso)** **Observações dos testes (limitações apresentadas com transparência)**: * **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? A BetterToken mantém preços transparentes. Abaixo está a captura dos preços públicos de **19 de outubro de 2026** (CNY se aplica a contas empresariais em renminbi; USD, a contas comuns em dólares; são preços independentes e não convertidos pela taxa de câmbio em tempo real): | Nome do modelo | Preço 1K / imagem | Preço 2K / imagem | Preço 4K / imagem | | :- | :- | :- | :- | | **`gpt-image-2`** (CNY / USD) | ¥0.035 / \$0.0062 | ¥0.11 / \$0.0194 | ¥0.13 / \$0.0229 | | **`gpt-image-2.5-flare`** (CNY / USD) | ¥0.035 / \$0.0062 | ¥0.15 / \$0.0265 | ¥0.18 / \$0.0318 | | **`gpt-image-2.5-sunburst`** (CNY / USD) | ¥0.035 / \$0.0062 | ¥0.15 / \$0.0265 | ¥0.18 / \$0.0318 | Com base nesses preços públicos, o custo de referência para 100 chamadas é o seguinte, supondo que as 100 imagens efetivamente entregues se enquadrem na faixa de cobrança correspondente (estimativa aritmética): | Nome do modelo | Custo de 100 imagens 1K | Custo de 100 imagens 2K | Custo de 100 imagens 4K | | :- | :- | :- | :- | | **`gpt-image-2`** (CNY / USD) | ¥3.50 / \$0.62 | ¥11.00 / \$1.94 | ¥13.00 / \$2.29 | | **`flare` ou `sunburst`** (CNY / USD) | ¥3.50 / \$0.62 | ¥15.00 / \$2.65 | ¥18.00 / \$3.18 | > 💡 **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”? Ao comparar os custos das APIs de imagem de diferentes plataformas, vale fazer estas três contas: 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 Salve sua BetterToken API Key na variável de ambiente `BETTERTOKEN_API_KEY` para copiar os comandos abaixo e começar a fazer chamadas. ### Exemplo 1: solicitação JSON para gerar uma imagem de produto em alta resolução (`POST /v1/images/generations`) O exemplo chama `gpt-image-2` para gerar uma imagem de produto em alta resolução de `2048x2048` (`model` pode ser substituído diretamente por `gpt-image-2.5-flare` ou `gpt-image-2.5-sunburst`): ```bash theme={null} 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`) Prepare a imagem original `product-1k-0.png` e a máscara transparente `mask-mug.png` do mesmo tamanho (se precisar apenas da edição comum com imagem de referência, basta excluir a linha `-F "mask=..."`): ```bash theme={null} 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) Além de `data[].b64_json`, o corpo da resposta BetterToken também contém o nó do campo estendido `bettertoken_image_billing`: ```json theme={null} { "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" } ] } } ``` Use o trecho de código Python a seguir para concluir, em uma etapa, a **decodificação da imagem, identificação do formato real, leitura das dimensões e conferência da cobrança**: ```python theme={null} 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']}") ``` *** **Referências**: * [Documentação oficial da OpenAI: guia para escrever prompts de imagem (Image Prompting Guide)](https://developers.openai.com/api/docs/guides/image-prompting) * [OpenAI Cookbook: exemplo de geração e edição de imagens com alta fidelidade de entrada](https://developers.openai.com/cookbook/examples/generate_images_with_high_input_fidelity) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.