Muitos desenvolvedores que integram a interface de edição de imagens do gpt-image-2 acabam travando no mesmo problema: ao vasculhar a página de referência da API images/edit, encontram apenas a informação de que "os modelos GPT image suportam até 16 imagens", mas não conseguem localizar o limite de tamanho por arquivo. Será que não existe limite? Ou a documentação esqueceu de mencionar?
A resposta é: o limite existe e é bem claro — cada imagem deve ter menos de 50 MB, com suporte aos formatos PNG, WebP e JPG. O problema é que essa regra não está na tabela de parâmetros da página de referência, mas sim em um guia de uso separado para a geração de imagens. Essa fragmentação das informações acaba confundindo muita gente.
Neste artigo, vamos esclarecer de uma vez por todas as restrições de upload da API gpt-image-2: quantidade, tamanho, formato, regras de máscara, restrições de resolução e, o mais importante, uma questão prática que vai além do limite de 50 MB — por que não recomendamos que você envie arquivos tão pesados.
Limites de upload de imagem da API gpt-image-2: especificações oficiais completas
Vamos começar pelo que importa. O gpt-image-2 recebe imagens de entrada através do endpoint v1/images/edits. As restrições oficiais completas estão na tabela abaixo.
Tabela de consulta rápida de limites de upload do gpt-image-2
| Item de restrição | Especificação oficial | Fonte da documentação |
|---|---|---|
| Máximo de imagens por vez | 16 imagens (modelos GPT image) | Referência da API: images/edit |
| Tamanho por imagem | < 50 MB | Guia de uso de Geração de Imagens |
| Formatos suportados | PNG, WebP, JPG | Guia de uso de Geração de Imagens |
| Método de envio | image_url ou file_id (escolha um) |
Referência da API: images/edit |
| Máscara (mask) | Mesmo formato/tamanho da original, < 50 MB, deve conter canal alfa | Guia de uso de Geração de Imagens |
| Quantidade de geração (n) | 1-10 imagens | Referência da API: images/edit |
Ou seja, teoricamente, uma única requisição de edição pode conter até 16 imagens próximas de 50 MB. Mas "limite teórico" e "como usar na prática" são coisas diferentes, o que detalharemos a seguir.
Vale destacar um ponto onde muitos tropeçam: o parâmetro images da nova API recebe um array de objetos, onde cada objeto fornece image_url ou file_id. O file_id vem do pré-upload via Files API, ideal para bibliotecas de materiais reutilizáveis; o image_url suporta endereços públicos ou data URLs em base64, ideal para requisições únicas. O limite de 50 MB aplica-se a ambos os métodos.
🎯 Dica para validação rápida: Se você não tem certeza se suas imagens vão atingir o limite, a forma mais direta é enviar uma requisição real e verificar a mensagem de erro. Recomendamos realizar esses testes de limite através da interface compatível com OpenAI da APIYI (apiyi.com). O painel de logs da plataforma permite visualizar o tamanho do corpo da requisição e os detalhes do erro de forma muito mais intuitiva do que chamando a API oficial diretamente.
Por que o tamanho do upload do gpt-image-2 parece "invisível" na documentação?
Voltando à dúvida inicial: por que a página de Referência menciona apenas 16 imagens e não o tamanho do arquivo? Isso é, na verdade, uma escolha de design na estrutura da documentação da OpenAI. A página de Referência de images/edit é organizada por "Schema de parâmetros". O parâmetro images é, no nível do Schema, apenas um array de objetos; o limite de quantidade é uma restrição do array, por isso foi incluído. Já o tamanho e o formato do arquivo pertencem à "validação em tempo de execução", sendo classificados nos textos narrativos do guia de Geração de Imagens.
Existem outras regras "escondidas nos guias" que é melhor confirmar antes de implementar funcionalidades de edição de imagem:
- Três requisitos para a máscara (mask): Deve ter o mesmo formato e dimensões da imagem editada, o arquivo também deve ser menor que 50MB e deve conter um canal alfa — usar JPG como máscara é a causa mais comum de erro, pois o JPG não possui canal alfa.
- A resolução não é arbitrária: O parâmetro
sizedo gpt-image-2 suporta resoluções personalizadas, mas possui restrições rígidas: o lado mais longo não pode exceder 3840px, a largura e a altura devem ser múltiplos de 16px, a proporção (aspect ratio) não deve exceder 3:1 e o total de pixels deve estar entre 655.360 e 8.294.400. - Imagens de entrada são tarifadas: As imagens de referência em solicitações de edição são cobradas de acordo com os tokens de entrada de imagem; quando
input_fidelity: highé usado, o consumo de tokens de entrada aumenta significativamente.
Restrições de resolução e parâmetro size do gpt-image-2
| Dimensão da restrição | Regra | Exemplo |
|---|---|---|
| Lado mais longo | ≤ 3840px | 3840×2160 (4K horizontal) é permitido |
| Alinhamento de lados | Largura e altura múltiplos de 16px | 1024, 1536, 2048 são válidos |
| Proporção | ≤ 3:1 | 2048×1152 é válido, 3072×1024 é válido |
| Total de pixels | 655.360 – 8.294.400 | Abaixo de 768×854 será rejeitado |
| Predefinições comuns | 1024×1024 / 1536×1024 / 2048×2048 / 3840×2160 | O mesmo vale para o formato vertical |
Se o seu negócio exige alternar frequentemente entre diferentes resoluções, recomendo criar uma validação local baseada nesta tabela antes da solicitação, interceptando dimensões inválidas no cliente, o que economiza um "vai e vem" em comparação a esperar o erro 400 da API. No centro de documentação da APIYI (apiyi.com), também organizamos uma lista de verificação de parâmetros para o gpt-image-2, que você pode usar diretamente como referência.
Prática com gpt-image-2: 50MB é o limite, mas 1.5MB é o ponto ideal
Sabendo do limite rígido de 50MB, a pergunta mais importante é: qual o tamanho de imagem que devo enviar na engenharia real? Nossa recomendação é manter cada imagem em torno de 1.5MB, tentando não exceder 5MB. Isso não é um chute; existem três motivos por trás disso.
Primeiro, a expansão do base64. Se você usar o método data URL para incorporar imagens, a codificação base64 aumentará o tamanho em cerca de 33% — uma imagem original de 40MB chega a quase 53MB após a codificação, e com a estrutura JSON sobreposta, o corpo da solicitação pode exceder o limite diretamente. Ao incorporar 16 imagens via base64, esse problema é amplificado 16 vezes; portanto, para materiais de grande volume, use obrigatoriamente o canal de pré-upload file_id.
Segundo, o tempo de transmissão e decodificação. Acima de 5MB, o tempo de upload somado ao tempo de decodificação no servidor cresce de forma não linear, sendo fácil disparar tentativas de reenvio por timeout em caso de instabilidade na rede, o que acaba atrasando a velocidade geral de geração. Imagens em torno de 1.5MB levam de 1 a 2 segundos para serem carregadas em uma conexão doméstica comum, sendo o ponto de equilíbrio entre estabilidade e qualidade.
Terceiro, os retornos decrescentes de qualidade. O gpt-image-2 realiza um pré-processamento interno ao lidar com imagens de entrada. Quando a resolução de entrada é muito superior à de saída, os pixels excedentes são basicamente desperdiçados. Um JPG com lado longo de 3840px comprimido para menos de 2MB não apresenta diferença perceptível em relação a um PNG sem perdas de 40MB no resultado da edição, mas o custo e o tempo são ordens de grandeza diferentes.
Recomendações práticas de tamanho de imagem para gpt-image-2
| Situação da imagem original | Processamento sugerido | Efeito esperado |
|---|---|---|
| < 1.5MB | Envio direto | Melhor velocidade e estabilidade |
| 1.5MB – 5MB | Pode enviar diretamente, sugere-se converter para JPG/WebP | Velocidade aceitável |
| 5MB – 20MB | Comprimir para lado longo ≤ 3840px + qualidade 85 | Qualidade quase sem perdas, tempo reduzido |
| 20MB – 50MB | Deve comprimir, usar upload via file_id | Evita estouro por expansão base64 |
| > 50MB | Excede o limite rígido, deve comprimir | Caso contrário, erro imediato |
💡 Dica para cenários de lote: Em cenários de alta concorrência, como recorte de imagens para e-commerce ou estilização em lote, recomendamos usar o sharp ou Pillow para fazer uma pré-compressão unificada de "lado longo 3840px + qualidade JPG 85" antes do upload. Verificamos isso nos casos de clientes corporativos da APIYI (apiyi.com), e este passo reduz o tempo de ponta a ponta de uma única solicitação de edição em mais de 40%, com zero reclamações sobre qualidade de imagem.
Guia rápido da API gpt-image-2: exemplo de código para edição com múltiplas imagens
O gpt-image-2 segue o protocolo de interface padrão da OpenAI. Abaixo, apresento um exemplo simplificado de edição utilizando várias imagens de referência. Ao utilizar o serviço proxy de API da APIYI, basta substituir a base_url:
import base64
from openai import OpenAI
client = OpenAI(
api_key="sk-your-apiyi-key",
base_url="https://api.apiyi.com/v1" # Interface unificada APIYI
)
def to_data_url(path):
with open(path, "rb") as f:
b64 = base64.b64encode(f.read()).decode()
return f"data:image/jpeg;base64,{b64}"
result = client.images.edit(
model="gpt-image-2",
image=[to_data_url("product.jpg"), to_data_url("style-ref.jpg")],
prompt="Misture a imagem do produto com o estilo cyberpunk neon da imagem de referência, mantendo o objeto principal inalterado",
input_fidelity="high", # Alta fidelidade para preservar detalhes, consome mais tokens de entrada
size="2048x2048",
quality="high"
)
print(result.data[0].b64_json[:64]) # Retorna a imagem resultante codificada em base64
Alguns pontos importantes sobre os parâmetros: quando input_fidelity é definido como high, a preservação de detalhes como rostos e logotipos é significativamente aprimorada, ao custo de um maior consumo de tokens de entrada; quality e size são as duas principais alavancas que determinam o custo de saída; o parâmetro n permite gerar até 10 imagens por vez. Em termos de faturamento, o gpt-image-2 é cobrado por token: entrada de texto a US$ 5/M, entrada de imagem a US$ 8/M (cache hit a US$ 2/M) e saída de imagem a US$ 30/M. Convertendo para uma única imagem, o nível "low" de 1024×1024 custa cerca de US$ 0,006, o nível "medium" cerca de US$ 0,05 e o "high" cerca de US$ 0,21, sendo a saída sempre a maior parte do custo.
Além disso, observe que os limites de taxa oficiais variam de acordo com o nível da conta: o Tier 1 permite apenas 5 imagens/minuto, o Tier 4 permite 150 imagens/minuto e o Tier 5 permite 250 imagens/minuto. Contas novas possuem níveis baixos, o que faz com que tarefas em lote atinjam facilmente o limite de taxa. Ao utilizar plataformas de agregação como a APIYI (apiyi.com), é possível contornar as restrições de nível de conta individual, sendo ideal para ambientes de produção que exigem alta concorrência.
Diferenças nas restrições de upload entre o gpt-image-2 e modelos anteriores
Se o seu projeto está sendo migrado do gpt-image-1 ou DALL·E 2, você deve estar atento a algumas diferenças geracionais. A maior mudança ocorreu entre o DALL·E 2 e a série GPT image: a interface de edição do DALL·E 2 aceitava apenas uma imagem PNG quadrada com menos de 4MB; com a série GPT image, isso foi flexibilizado para 16 imagens, 50MB e três formatos. Muitas lógicas de pré-processamento de "PNG + compressão de 4MB" escritas em projetos antigos podem ser significativamente simplificadas após a migração.
A atualização do gpt-image-2 em relação ao gpt-image-1 reflete-se principalmente na resolução e no custo. O gpt-image-1 suportava apenas três resoluções fixas (1024×1024, 1536×1024, 1024×1536); o gpt-image-2 abriu a possibilidade de resoluções personalizadas, suportando até 4K com o lado mais longo em 3840px. Quanto ao preço, a entrada de imagem do gpt-image-2 caiu de US$ 10/M para US$ 8/M, a saída de imagem caiu de US$ 40/M para US$ 30/M, e foi adicionada uma camada de cache hit de US$ 2/M, reduzindo visivelmente os custos em cenários de uso repetido de imagens de referência.
Comparação das restrições de upload entre o gpt-image-2 e modelos anteriores
| Item de comparação | DALL·E 2 | gpt-image-1 | gpt-image-2 |
|---|---|---|---|
| Quantidade de imagens de entrada | 1 imagem | Até 16 imagens | Até 16 imagens |
| Limite de tamanho por imagem | < 4MB | < 50MB | < 50MB |
| Formato de entrada | Apenas PNG quadrado | PNG/WebP/JPG | PNG/WebP/JPG |
| Resolução de saída | Imagem quadrada fixa | 3 tamanhos fixos | Personalizado, lado longo 3840px |
| Preço de saída de imagem | Cobrado por imagem | US$ 40/M tokens | US$ 30/M tokens (entrada em cache US$ 2/M) |
| input_fidelity | Não suportado | Suportado | Suportado, alta fidelidade de detalhes |
Ao migrar o código, basta alterar o parâmetro model, mas recomendo atualizar simultaneamente a validação de resolução e a estratégia de compressão de acordo com a tabela de restrições deste artigo. Se quiser validar o efeito da migração antes de alterar o código de produção, você pode usar o mesmo conjunto de materiais na APIYI (apiyi.com) para chamar ambos os modelos e comparar visualmente a qualidade da edição e a diferença real de faturamento.
FAQ: Perguntas frequentes sobre o upload de imagens no gpt-image-2
Q1: Qual é o tamanho máximo de uma única imagem que posso enviar no gpt-image-2?
O limite rígido é de 50 MB, com suporte para PNG, WebP e JPG. Essa restrição está descrita no guia de uso de geração de imagens da OpenAI, e não na tabela de parâmetros de referência (Reference) do images/edit, por isso é comum não encontrá-la ao consultar apenas a página de referência. Na prática, recomendamos manter o arquivo entre 1,5 MB e 5 MB para uma melhor experiência.
Q2: Como funciona o limite de 16 imagens?
O parâmetro images aceita no máximo 16 objetos de imagem, onde cada objeto especifica uma imagem via image_url ou file_id. O modelo tratará várias imagens como uma referência combinada, o que é ideal para cenários de edição que envolvem "imagem do produto + imagem de estilo + referência de composição". Lembre-se de que 16 é o limite de entrada, enquanto a quantidade de saída é controlada pelo parâmetro n, com um limite de 10 imagens.
Q3: O que geralmente causa o erro "invalid mask" na máscara?
Em 90% dos casos, o problema está no canal alfa. A máscara deve ter o mesmo formato e as mesmas dimensões da imagem que está sendo editada e, obrigatoriamente, deve conter um canal alfa — como o JPG não suporta canal alfa, a máscara deve ser obrigatoriamente em PNG. As áreas transparentes indicam "permissão para redesenhar", enquanto as áreas opacas permanecem inalteradas.
Q4: Como escolher entre upload via base64 e upload via file_id?
Para imagens pequenas (< 5 MB) ou requisições únicas, o uso de data URL em base64 é o mais prático. Para imagens grandes ou materiais que precisam ser reutilizados várias vezes, utilize a API de Arquivos (Files API) para fazer o upload prévio e obter um file_id. Isso evita o aumento de 33% no tamanho causado pelo base64 e permite a reutilização entre requisições. Se estiver em dúvida, você pode testar ambas as formas no console da APIYI (apiyi.com) e comparar o tempo de resposta real antes de definir sua estratégia.
Resumo: Três números fundamentais sobre os limites de upload do gpt-image-2
Voltando à pergunta inicial, os limites de upload da API de edição de imagens gpt-image-2 podem ser resumidos em três números: 16 imagens (limite de entrada por requisição, conforme a referência), 50 MB (limite de tamanho por arquivo, conforme o guia de uso) e 1,5 MB (o tamanho ideal para práticas de engenharia). O fato de a documentação separar a quantidade e o tamanho em páginas diferentes é a raiz da confusão sobre o limite de 16 imagens.
As recomendações de implementação são simples: antes do upload, comprima as imagens para que o lado maior tenha no máximo 3840px e a qualidade do JPG fique em torno de 85; use sempre PNG com canal alfa para máscaras; e para materiais grandes, utilize o canal file_id. Ao transformar esses três passos em um pré-processamento padrão antes da requisição, você praticamente eliminará todos os erros relacionados a uploads.
Se você precisa de uma invocação estável do gpt-image-2 no Brasil ou deseja elevar os limites de taxa para um nível de produção, pode utilizar a interface unificada da APIYI (apiyi.com). Ela é compatível com a escrita nativa do SDK da OpenAI, bastando alterar apenas uma linha no base_url para realizar a migração.
Referências: OpenAI API Reference: developers.openai.com/api/reference/resources/images/methods/edit
Autor: Equipe APIYI
Focados em agregação de API de Modelos de Linguagem Grande e melhores práticas. Para mais avaliações de modelos e guias de integração, visite APIYI em apiyi.com.
