Nota do autor: quando você chama a API de geração de imagens, uma resposta sem imagem não significa que a requisição falhou, e muito menos que a cobrança não foi feita. Este artigo traz um método de 4 passos (olhar a resposta primeiro, depois decidir se vale tentar de novo) e um código em Python que você pode aplicar direto.
Quem trabalha com APIs de imagem provavelmente já passou por isso: a requisição saiu, a API respondeu, mas na resposta não tem imagem nenhuma. A primeira reação de muita gente é achar que foi uma oscilação de rede e chamar de novo na hora, ou até escrever um loop que dispara várias vezes seguidas. Este artigo mostra uma ordem de tratamento mais segura: olhar a resposta primeiro e só então decidir se vale tentar de novo. Assim você aprende a investigar corretamente quando a geração de imagens não devolve nada.
Este não é um guia genérico de retentativas. Nos modelos de geração de imagens cobrados por requisição, cada chamada pode gerar uma cobrança. Veja o gpt-image-2.6-all, que entrou no APIYI em 2026-11-12 e custa US$ 0,025 por requisição. Se a resposta vier vazia e você tentar de novo sem avaliar nada, vai pagar duas vezes.
Valor central: ao terminar a leitura, você vai saber quais pontos checar primeiro quando a geração de imagens não devolve imagem, em que situações dá para tentar de novo e em quais isso não pode acontecer de jeito nenhum. Vai saber também como colocar esse raciocínio no código para evitar que a mesma imagem seja cobrada duas vezes.
Pontos-chave quando a geração de imagens não retorna imagem
Vamos direto à conclusão: quando a geração de imagens não retorna imagem, você não deve classificar o problema como “falha de rede” sem pensar. O correto é inspecionar o conteúdo da resposta em uma ordem fixa. A tabela abaixo resume os 4 passos desse método de diagnóstico.
| Passo | O que verificar | O que fazer se o resultado for “não” | Valor |
|---|---|---|---|
| Passo 1 | A requisição HTTP foi bem-sucedida? | Tratar conforme o código de status, sem seguir para as próximas verificações | Separa falha na camada de requisição de problema na camada de conteúdo |
| Passo 2 | A resposta traz dados de imagem ou URL de imagem? | Ir para o passo 3 | Se tem imagem, acabou: evita retentativa por engano |
| Passo 3 | A resposta traz alguma mensagem de erro? | Se houver erro, tratar como erro | Evita pagar repetidamente por uma requisição que fatalmente vai falhar |
| Passo 4 | Confirmado: sem imagem e sem erro | Tentar de novo apenas uma vez | Mantém o custo extra dentro de um limite previsível |
Por que não dá para sair retentando quando a geração de imagens não retorna imagem
Uma requisição de geração de imagens é diferente de uma conversa de texto comum: cada chamada custa mais, e o resultado muitas vezes não é “tudo ou nada”. Pode ser que o servidor já tenha terminado de gerar a imagem e o seu código simplesmente não a tenha extraído do campo certo. Também pode ser que a requisição tenha sido recusada, com o motivo escrito na própria resposta. Se você retentar na hora, no primeiro caso paga duas vezes pela mesma imagem; no segundo, paga repetidamente por uma requisição condenada ao fracasso.
Tome como exemplo o preço por chamada do gpt-image-2.6-all, de US$ 0,025. Cada retentativa às cegas custa mais US$ 0,025. Se você tratar uma resposta vazia como “instabilidade de rede” e colocar tudo num loop, 3 retentativas geram US$ 0,075 a mais, e é possível que nenhum centavo disso renda uma imagem válida. Ou seja, olhar a resposta antes de tentar de novo é, no fundo, fazer uma checagem de custo praticamente zero antes de gastar dinheiro.
A lógica de verificar a resposta antes de retentar
O princípio por trás dessa ordem é ir “de fora para dentro”. O código de status HTTP é o sinal mais externo: diz se a requisição foi processada normalmente. Os dados da imagem são o que você realmente quer, então vêm logo em seguida. A mensagem de erro é o motivo da falha informado ativamente pelo servidor, e por isso tem prioridade sobre a retentativa. Só depois de passar pelas três camadas, confirmando que de fato não há imagem nem qualquer explicação de erro, a retentativa passa a fazer sentido.
Há um detalhe que costuma passar batido: o passo 2 pede para checar “dados de imagem ou URL de imagem”. Cada tipo de interface devolve a imagem num lugar diferente. Algumas colocam em b64_json ou url dentro do array data; outras escrevem o link da imagem no texto do content da mensagem de conversa. Se o seu código de parsing só reconhece um desses formatos, ele vai classificar como vazia uma resposta que na verdade tem imagem, e essa é uma das causas mais comuns de retentativas indevidas.
Entendendo os tipos de resposta quando a geração de imagens não retorna nenhuma imagem
Para analisar a resposta antes de tentar de novo, primeiro você precisa saber como ela pode se apresentar. A tabela abaixo lista os tipos mais comuns de resposta e o tratamento recomendado para cada um.
| Tipo de resposta | Características típicas | A imagem foi gerada? | Tratamento recomendado |
|---|---|---|---|
| Falha na camada da requisição | Código de status HTTP diferente de 2xx | Não | Trate conforme o código de status; se for autenticação ou parâmetros, corrija antes de reenviar |
| Imagem gerada normalmente (estruturada) | data contém b64_json ou url |
Sim | Pegue a imagem direto, sem tentar de novo |
| Imagem gerada normalmente (embutida no texto) | O content da mensagem contém um link de imagem |
Sim | Extraia o link com regex, sem tentar de novo |
| Resposta de sucesso com informação de erro | HTTP com sucesso, mas o corpo traz error ou uma explicação de recusa |
Não | Leia o motivo do erro e ajuste o comando ou os parâmetros |
| Resposta realmente vazia | HTTP com sucesso, sem imagem e sem erro | Não | Registre a resposta original e tente de novo uma única vez |
| Timeout da requisição | O cliente não recebeu resposta | Não dá para confirmar | Não reenvie automaticamente; confira primeiro os logs e a cobrança |
Por que, no caso de timeout, também é preciso olhar antes de tentar de novo
O timeout é a situação que mais facilmente é tratada como “uma oscilação de rede”, mas é justamente a que pede mais cautela. Quando o cliente estoura o tempo limite, isso só significa que você não esperou pela resposta, e não que o servidor deixou de concluir a geração. A geração de imagens demora bastante, e se o timeout configurado no cliente for curto demais, é bem possível que o servidor já tenha terminado de gerar a imagem e feito a cobrança, enquanto o seu programa desistiu de esperar antes disso.
Nesses casos, o mais sensato é primeiro aumentar um pouco o tempo limite. Depois, quando um timeout acontecer, registre o horário e os parâmetros da requisição e vá conferir no log de invocações do painel de controle qual foi o estado real dela. Só depois de confirmar que não houve nenhum registro de sucesso é que vale reenviar manualmente, o que é bem mais seguro do que deixar o programa disparar requisições em sequência.
Respostas com informação de erro devem ser tratadas como erro
Algumas respostas têm status HTTP de sucesso, mas trazem um objeto de erro no corpo, ou então o modelo explica no texto por que não conseguiu gerar a imagem, por exemplo porque o comando acionou a moderação de conteúdo. Essas respostas não têm imagem, mas o motivo já está bem claro, e reenviar a mesma requisição sem mudar nada quase certamente vai dar o mesmo resultado.
O correto é ler a mensagem de erro e identificar se o problema está nos parâmetros, no conteúdo ou se é uma falha temporária do servidor. Problemas de parâmetros e de conteúdo exigem que você modifique a requisição antes de enviar de novo; só quando a mensagem de erro apontar claramente para uma falha temporária é que vale considerar uma nova tentativa, depois de esperar um pouco.
Imagem não veio na resposta? Olhe a resposta antes de tentar de novo: guia rápido
Abaixo, mostro em Python como colocar essa lógica de decisão no código. O exemplo usa a interface compatível com OpenAI e o modelo gpt-image-2.6-all. O endpoint e o formato de retorno podem variar, então confira o que a documentação da APIYI diz sobre esse modelo.
Exemplo mínimo: ao receber a resposta, verifique primeiro se tem imagem
O jeito mais simples é checar o campo da imagem assim que a resposta chega. Se tem imagem, acabou. Só se não tiver é que você segue para a investigação:
from openai import OpenAI
client = OpenAI（
api_key="YOUR_API_KEY"，
base_url="https://api.apiyi.com/v1", # Interface compatível com OpenAI da APIYI
）
resp = client.images.generate（
model="gpt-image-2.6-all"，
prompt="一只坐在窗台上的橘猫，水彩风格"，
）
item = resp.data[0] if resp.data else None
if item and （item.b64_json or item.url）:
print（"已拿到图片，不要重试"）
else:
print（"响应里没有图片，先打印原始响应再决定"）
print（resp.model_dump（））
O código tem pouco mais de uma dúzia de linhas, mas já evita o erro mais comum: repetir a requisição sem olhar o conteúdo da resposta. Falhas na camada HTTP são levantadas como exceção pelo SDK. Você pode capturá-las com um try por fora e tratar de acordo com o código de status, em vez de cair direto num loop de retentativas.
Exemplo completo: 4 passos de verificação e no máximo uma nova tentativa
Em produção, recomendo usar a versão mais completa abaixo. Ela cobre a checagem do status HTTP, a leitura das duas posições possíveis em que a imagem pode vir na resposta, a identificação de mensagens de erro, a regra de não reenviar automaticamente em caso de timeout e o limite de “no máximo uma nova tentativa depois de confirmar que não veio imagem”:
import re
import requests
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apiyi.com/v1" # Endereço unificado da interface da APIYI
MODEL = "gpt-image-2.6-all"
IMG_URL_RE = re.compile（r"https？://\S+？\.（？:png|jpe？g|webp）"， re.I）
def find_images（body）:
"""Verifica ao mesmo tempo o campo estruturado data e os links de imagem no content da conversa"""
images = []
for item in body.get（"data"） or []:
if item.get（"url"）:
images.append（item["url"]）
elif item.get（"b64_json"）:
images.append（"base64-image"）
for choice in body.get（"choices"） or []:
content = （choice.get（"message"） or {}）.get（"content"） or ""
images += IMG_URL_RE.findall（content）
return images
def generate_with_check（prompt， max_retry=1）:
for attempt in range（max_retry + 1）:
try:
resp = requests.post（
f"{BASE_URL}/images/generations"，
headers={"Authorization": f"Bearer {API_KEY}"}，
json={"model": MODEL， "prompt": prompt}，
timeout=300，
）
except requests.Timeout:
# Com o timeout, não dá para saber se o servidor já gerou e cobrou a imagem, então não reenvia automaticamente
return {"status": "timeout"， "action": "check_logs_first"}
# Passo 1: o HTTP foi bem-sucedido?
if resp.status_code ！= 200:
return {"status": "http_error"， "code": resp.status_code，
"detail": resp.text[:500]}
try:
body = resp.json（）
except ValueError:
return {"status": "bad_json"， "detail": resp.text[:500]}
# Passo 2: a resposta tem dados de imagem ou URL de imagem?
images = find_images（body）
if images:
return {"status": "ok"， "images": images}
# Passo 3: se houver mensagem de erro, trata como erro e não tenta de novo
if body.get（"error"）:
return {"status": "api_error"， "error": body["error"]}
# Passo 4: só permite nova tentativa depois de confirmar que não há imagem nem erro e de registrar a resposta original
print（f"第 {attempt + 1} 次请求无图片，原始响应：{str（body）[:300]}"）
return {"status": "empty_after_retry"， "action": "stop_and_report"}
result = generate_with_check（"一只坐在窗台上的橘猫，水彩风格"）
print（result）
Vale prestar atenção em algumas decisões de design desse código. O max_retry vem como 1 por padrão, ou seja, cada imagem gera no máximo duas cobranças, e o teto de custo fica previsível. No caso de timeout, a função retorna na hora em vez de continuar o loop, porque não há como saber se a cobrança já foi feita. E toda vez que uma resposta é considerada vazia, a resposta original é impressa, o que ajuda você a descobrir depois se o problema foi de parsing ou se o servidor realmente não gerou a imagem.
🚀 Comece rápido: se você quer validar essa lógica de verificação primeiro em um ambiente de testes, pode conseguir créditos gratuitos de teste pela APIYI (apiyi.com). Com a mesma chave API, dá para invocar o gpt-image-2.6-all e outros modelos populares, e só depois de fechar o fluxo de verificação você integra ao seu negócio de verdade.
Comparação de custo: retentativa às cegas quando a geração de imagem não retorna imagem
Antes de escrever a lógica de decisão no código, muita gente não tem uma noção concreta do preço de “tentar de novo algumas vezes”. A tabela abaixo usa o preço do gpt-image-2.6-all, de $0,025 por requisição, para comparar o gasto extra por imagem entre duas estratégias: bombardear sem olhar e analisar a resposta antes de tentar de novo.
| Estratégia | Máx. de requisições por imagem | Gasto extra no pior caso | Risco |
|---|---|---|---|
| Sem checar, repete 1 vez se falhar | 2 | $0,025 | Pode cobrar de novo por uma requisição que já gerou a imagem |
| Sem checar, repete em loop até 3 vezes | 4 | $0,075 | Cobra repetidamente por requisições que vão falhar de qualquer jeito |
| Sem checar, repete em loop até sair uma imagem | Indefinido | Sem limite | Continua cobrando quando a recusa vem da moderação de conteúdo |
| Analisa a resposta e repete 1 vez só se confirmar que não há imagem | 2 | $0,025 | Só gera custo extra quando a resposta está realmente vazia |
À primeira vista, “analisar a resposta antes de repetir” e “repetir 1 vez se falhar” têm o mesmo gasto extra no pior caso, mas o que dispara cada uma é completamente diferente. A primeira só gasta esses $0,025 quando se confirma que não veio imagem nem mensagem de erro. A segunda gasta o mesmo valor mesmo quando a imagem foi gerada e só o parsing falhou, ou quando o conteúdo foi recusado, e nesses casos você paga e não leva nada.
Quando o volume cresce para geração de imagens em lote, essa diferença se multiplica. Os $0,025 a mais por imagem, vezes o número de requisições por dia, viram um gasto totalmente evitável.
Referência de interfaces e modelos quando a geração de imagens não retorna imagem
Dependendo do modelo e do formato da interface, a imagem pode vir em lugares diferentes, e isso influencia diretamente se o diagnóstico do passo 2 vai estar certo. A tabela abaixo reúne os formatos de retorno mais comuns e os pontos de atenção de cada um, para você conferir se o seu código de parsing não está deixando a imagem passar.
| Formato de retorno | Onde está a imagem | Pontos de atenção no parsing | Plataformas disponíveis |
|---|---|---|---|
| Interface de geração de imagens (URL) | data[].url |
O link pode ter prazo de validade, então baixe e salve a imagem assim que receber | APIYI apiyi.com, conforme a documentação do modelo |
| Interface de geração de imagens (Base64) | data[].b64_json |
Decodifique e grave em arquivo; não trate o valor como string vazia por engano | Mesma da linha anterior |
| Imagem embutida na interface de chat | choices[].message.content |
Use regex para extrair imagens ou links em Markdown | Mesma da linha anterior |
| Retorno em streaming | Conteúdo completo, depois de juntar os fragmentos | Espere o stream terminar e o conteúdo estar todo concatenado antes de decidir se há imagem | Mesma da linha anterior |
O retorno em streaming é outro ponto que costuma gerar diagnóstico errado. Se você procura a imagem já no primeiro fragmento recebido, é claro que não vai encontrar nada. Quando a geração de imagens não retornar imagem, confirme sempre que você está verificando a resposta completa, e não um estado intermediário.
Perguntas frequentes (FAQ)
P1: Se a geração de imagem não retornou nada, com certeza não houve cobrança?
Não necessariamente. A cobrança depende de o servidor ter processado a requisição, e não de o seu código ter conseguido pegar a imagem. Campo de parsing errado, resposta em streaming que não foi montada por completo e timeout antecipado no cliente podem causar o cenário “cobrou, mas você não recebeu a imagem”. Por isso, o certo é olhar a resposta antes de tentar de novo, em vez de assumir que não houve cobrança e disparar outra requisição.
P2: Qual é a diferença entre “olhar a resposta antes de tentar de novo” e o retry com backoff exponencial de sempre?
O backoff exponencial resolve a questão de “quando tentar de novo” e funciona bem para limitação de taxa e falhas temporárias do servidor. Já olhar a resposta antes resolve a questão de “se vale a pena tentar de novo”. Em requisições de geração de imagens cobradas por chamada, você deve primeiro usar os 4 passos de verificação para confirmar que o retry é mesmo necessário e só então combinar com a estratégia de backoff para definir o momento. Uma coisa vem depois da outra, e uma não substitui a outra.
P3: Quando o gpt-image-2.6-all foi lançado e quanto custa?
O gpt-image-2.6-all entrou no ar na APIYI em 12/11/2026, com cobrança por chamada de US$ 0,025. Cobrança por chamada significa que cada requisição é precificada de forma independente: se você repetir uma resposta vazia, paga de novo. Esse é o motivo direto de o artigo insistir em olhar a resposta antes de tentar outra vez.
P4: Em quais situações, quando a geração não retorna imagem, eu nunca devo tentar de novo?
Há três categorias principais:
– **A resposta traz uma mensagem de erro**: por exemplo, o comando acionou a moderação de conteúdo ou algum parâmetro é inválido. Repetir a requisição do mesmo jeito dá o mesmo resultado.
– **Timeout da requisição**: não dá para saber se o servidor já gerou a imagem e cobrou, então confira os logs primeiro.
– **Erros HTTP de autenticação ou de cota**: tentar de novo não muda nada. Primeiro corrija a chave ou resolva o problema de cota.
P5: Como validar rapidamente se minha lógica de decisão está correta?
Recomendo rodar o fluxo completo em um ambiente de testes:
1. Crie uma conta na APIYI (apiyi.com) para obter a chave API e a cota gratuita de teste
2. Defina o `BASE_URL` do exemplo completo deste artigo como `https://api.apiyi.com/v1` e chame o gpt-image-2.6-all
3. Teste com um comando normal e com outro que possa ser recusado, e observe o retorno de cada ramificação
Depois de confirmar que cada tipo de resposta cai no ramo certo, aí sim integre ao seu sistema de produção.
P6: Tentei de novo uma vez e ainda não veio imagem. O que eu faço?
Pare os retries automáticos e registre as respostas brutas das duas requisições, os parâmetros enviados e os horários. Primeiro verifique se o seu código de parsing não deixou passar o campo da imagem e, depois, confira no console o registro das duas chamadas. Se ficar claro que o servidor devolveu resultados vazios em sequência, entre em contato com o suporte técnico da APIYI (apiyi.com) levando o horário das requisições e as respostas brutas. Isso resolve mais do que continuar pagando por novas tentativas.
P7: Na geração de imagens em lote, como controlo o custo dos retries?
Defina um contador de retry independente para cada tarefa de geração e fixe o limite em 1 tentativa extra por tarefa. Também vale acompanhar a “taxa de respostas vazias” no nível das tarefas: se um lote tiver muito mais respostas vazias que o normal, investigue primeiro os comandos e a lógica de parsing, em vez de aumentar o número de retries de forma geral.
Quando a geração de imagens não retorna imagem: veja a resposta antes de tentar de novo — Pontos principais (Key Takeaways)
- Sem imagem não significa sem cobrança: em requisições de geração de imagens cobradas por chamada, se o servidor chegou a processar o pedido, a cobrança já pode ter sido feita.
- A ordem de verificação é fixa: status HTTP → dados da imagem ou URL → mensagem de erro → só então, com a ausência de imagem confirmada, tentar de novo.
- Apenas uma nova tentativa: depois de confirmar que não há imagem nem erro, tente novamente uma única vez, para que o teto de custo seja previsível.
- Timeout não é motivo para reenviar automaticamente: com o timeout, você não consegue saber se a imagem foi gerada. Confira os logs primeiro e só depois decida se vale reenviar.
- O parsing precisa cobrir vários lugares: verifique o campo
datae também ocontentda conversa, para não confundir uma resposta válida com uma resposta vazia. - Retry às cegas tem custo claro: no gpt-image-2.6-all, cada retry às cegas a mais custa US$ 0,025 extras.
- Valide primeiro com créditos de teste: no APIYI (apiyi.com), você pode usar os créditos de teste gratuitos para rodar todo o fluxo de verificação antes de colocar em produção.
Resumo
Quando a geração de imagens não devolve imagem, estes são os pontos principais de olhar a resposta antes de tentar de novo:
- Investigue antes de gastar: inspecionar a resposta custa praticamente nada, enquanto cada retry às cegas é cobrado.
- Siga a verificação em 4 passos: o HTTP deu certo? Veio imagem? Veio algum erro? Só depois de confirmar que não há imagem, tente de novo uma única vez.
- Coloque essas regras no código: limite o número de tentativas, não reenvie automaticamente em caso de timeout e registre a resposta bruta. Assim o custo fica sob controle e os problemas ficam fáceis de rastrear.
Para quem desenvolve com modelos de imagem cobrados por chamada, esse método não é complicado, mas evita na prática que a mesma imagem seja cobrada duas vezes. Minha sugestão é percorrer todos os ramos do fluxo em um ambiente de teste e, depois, transformar isso no wrapper padrão das suas chamadas de geração de imagens.
Uma boa forma de validar essa lógica rapidamente é usar o APIYI (apiyi.com). A plataforma oferece uma interface compatível com a OpenAI e créditos de teste gratuitos, e com uma única chave você acessa o gpt-image-2.6-all e vários outros modelos populares.
📚 Referências
- Central de documentação da APIYI: formas de invocação do modelo e descrição dos formatos de retorno
- Link:
docs.apiyi.com -
Descrição: consulte os endpoints de chamada e os campos de resposta específicos do gpt-image-2.6-all; a documentação é sempre a fonte de referência
-
Referência da OpenAI Images API: estrutura padrão de resposta da interface de geração de imagens
- Link:
platform.openai.com/docs/api-reference/images - Descrição: entenda o significado dos campos
urleb64_jsondentro do arraydata
Autor: Equipe técnica da APIYI
Troca de experiências técnicas: fale com a gente na página inicial do site da APIYI. Para mais materiais de integração, acesse a central de documentação em docs.apiyi.com
