Como usar a API GPT Image 2: guia de geração de imagem a partir de texto e de imagem

O que a API GPT Image 2 oferece aos desenvolvedores

A API GPT Image 2 oferece uma interface unificada e consistente para gerar imagens a partir de prompts. Em vez de montar vários fornecedores ou manter múltiplos SDKs, basta enviar uma única requisição HTTP ao HiAPI.ai e receber os dados da imagem. Isso importa quando você constrói recursos como geradores de materiais de marketing, ilustrações de onboarding de aplicativos ou ferramentas criativas voltadas ao usuário, porque latência, disponibilidade (uptime) e uma estrutura de requisição previsível são fundamentais.

Você usará dois modos de geração:

• Texto para imagem: você fornece um prompt e o tamanho desejado, e o modelo gera a imagem do zero.
• Imagem para imagem: você fornece um prompt além de uma ou mais imagens de referência, e o modelo gera a imagem guiado por essas referências.

Os dois modos compartilham a mesma autenticação e a mesma estrutura de resposta, então, uma vez que você tenha uma chamada funcionando, o segundo é apenas uma pequena alteração, e não uma integração nova. Este guia aborda, em ordem, como escolher entre as duas variantes, uma requisição curl mínima, o tratamento de imagens de referência, como solicitar saída em 4K, a portabilidade para Python e padrões de tratamento de erros que evitam falhas silenciosas em pipelines de imagens em produção.

Se você está construindo qualquer funcionalidade que precise de geração de imagens com um contrato de API estável, o restante deste artigo é o caminho mais curto do zero até uma requisição funcional.

Texto para imagem e imagem para imagem: escolha a variante

Antes de escrever código, determine qual variante seu produto realmente precisa. Essa escolha depende principalmente de quanto controle você quer sobre a saída e de quanto conteúdo espera que os usuários forneçam.

Quando usar texto para imagem

Texto para imagem é a opção padrão adequada quando:

• Os usuários descrevem em texto o que querem, sem material de origem.
• Você gera imagens de placeholder, imagens principais (key visuals) ou variações a partir de um modelo fixo de prompt.
• Você quer o corpo de requisição mais simples possível — um prompt e um tamanho — para manter o volume da requisição pequeno e a latência previsível.

Quando usar imagem para imagem

Imagem para imagem é a escolha correta quando a saída precisa se aproximar de algo que já existe:

• Reestilizar ou renderizar novamente fotos de produtos enviadas pelo usuário.
• Aplicar um tratamento visual consistente a um conjunto de materiais de referência.
• Guiar a composição, a paleta de cores ou o sujeito para que o resultado corresponda à marca ou ao cenário existente.

Regra prática

Se o prompt sozinho determina completamente a saída, use texto para imagem. Se parte da intenção está na imagem e não no texto — e descrevê-la com prompt seria prejudicial, verboso ou não confiável — use imagem para imagem e envie imagens de referência.

Um erro comum é usar imagem para imagem quando um prompt melhor resolveria o problema. Imagens de referência aumentam a sobrecarga de upload e também trazem mais chances de falha na validação da requisição. Comece com texto para imagem e só migre para a variante com referência quando você conseguir apontar um atributo visual específico que o prompt não captura.

Faça sua primeira requisição de texto para imagem com curl

Comece com curl. Ele elimina a variável do comportamento do SDK, então, quando algo falhar, você saberá que o problema está na autenticação ou na estrutura do corpo da requisição, e não na biblioteca cliente.

Primeiro, defina a chave de API como variável de ambiente, para que ela não entre no histórico do shell nem no controle de versão:

export HIAPI_API_KEY="your_api_key_here"

Depois, envie uma requisição mínima:

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024"
  }'

O que verificar na resposta:

1. Código de status HTTP. 200 significa que a requisição foi aceita e processada. Para qualquer outro código, leia o corpo da resposta de erro antes de alterar qualquer coisa.
2. Autenticação. 401 quase sempre indica chave ausente, mal formatada ou expirada — confirme que o cabeçalho Authorization está no formato Bearer seguido da chave.
3. Corpo da requisição. 400 normalmente aponta para um campo: nome de parâmetro errado, string de tamanho não aceita pelo modelo ou prompt que não passou na validação.
4. Carga da imagem. Dependendo do modo de resposta, você receberá uma URL para baixar ou dados de imagem em base64. Trate os dois casos, para que seu cliente não seja pego de surpresa depois.

Quando essa chamada funcionar, você terá validado três coisas ao mesmo tempo: a chave é válida, o caminho do endpoint está correto e a estrutura JSON é aceitável. Toda alteração posterior neste guia parte dessa linha de base comprovada.

Guiar a saída com imagens de referência

Uma requisição de imagem para imagem mantém o mesmo invólucro da requisição de texto para imagem e adiciona uma entrada de imagem de referência. O prompt continua carregando as instruções — as imagens de referência carregam o contexto visual.

A mudança no corpo da requisição é que agora você fornece dados de imagem além do prompt. Na prática, isso significa fornecer uma URL que o serviço possa buscar ou uma imagem codificada em base64 embutida, dependendo do formato que sua integração suporta. Lembre-se das seguintes regras:

• O prompt e a imagem de referência precisam ser coerentes. Se o prompt descreve um produto vermelho e a referência é azul, o modelo recebe sinais conflitantes. Escreva o prompt como uma instrução sobre a referência ("repinte esta cena em estilo aquarela"), e não como uma descrição que contradiz a referência.
• Envie apenas o necessário. Uma referência forte costuma ser melhor que várias referências fracas. Múltiplas referências aumentam o volume de upload e dificultam identificar qual delas guiou a saída.
• Atenção ao volume da requisição. Imagens em base64 incham significativamente o payload da requisição. Se você está enviando fotos grandes, este é o primeiro lugar a verificar quando a requisição ficar lenta ou for rejeitada.
• Valide antes de enviar. Verifique se a imagem está em um formato aceito e se decodifica sem erros. Strings base64 malformadas produzem falhas obscuras e demoradas de diagnosticar.

A estrutura de requisição utilizável é a seguinte:

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Restyle this scene as a soft watercolor painting, keep composition intact",
    "image": "https://example.com/reference.jpg",
    "size": "1024x1024"
  }'

Como o invólucro da requisição não muda, a chamada curl que você validou antes continua sendo a ferramenta de depuração: troque o corpo, mantenha os cabeçalhos e compare a resposta campo a campo.

Solicitar saída em 4K

A resolução de saída é especificada na requisição, e não presumida pelo modelo. Se você precisa de saída em alta resolução, especifique-a explicitamente com o parâmetro size — não conte com um valor padrão grande.

{
  "model": "gpt-image-2",
  "prompt": "A detailed isometric illustration of a city block, warm evening light",
  "size": "3840x2160"
}

Ao migrar para resolução mais alta, vale verificar alguns pontos:

• Strings de tamanho suportadas. Os valores de tamanho são validados conforme a faixa aceita pelo modelo. Tamanhos rejeitados retornam 400, em vez de degradar silenciosamente — então confirme a string exata de tamanho necessária, em vez de adivinhar um valor próximo e errado.
• Volume da resposta. Dados de imagem em 4K são muito maiores que resultados em 1K. Se a resposta carrega base64 ou uma URL que você baixa imediatamente, reserve orçamento de memória e timeout para isso.
• Latência. Geração em resolução mais alta demora mais. Defina timeouts de cliente generosos, em vez de deixar uma requisição lenta, porém bem-sucedida, estourar o tempo do seu lado.
• Modelo de custo. A cobrança depende do tamanho e da quantidade de saída solicitada, então escolha com consciência: gere na resolução que a funcionalidade realmente precisa e, se a interface não precisar da resolução total, reduza a escala no seu próprio pipeline. Consulte o painel de preços do site para os valores atuais.
• Cuidado ao ampliar. Se você precisa de uma saída maior que a do modelo, ampliar após a geração é uma etapa separada, com suas próprias compensações de qualidade. Decida conscientemente qual caminho seguir.

Antes de ligar o 4K à execução em lote, teste o 4K com um prompt comprovado, para que falhas relacionadas à resolução não se confundam com problemas de autenticação ou de corpo da requisição.

Portar a requisição para Python

Não reescreva a requisição do zero em Python. Porte o mesmo corpo de requisição que você já validou em curl e depois confirme o tratamento da resposta separadamente.

import os
import base64
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()

item = data["data"][0]
if item.get("b64_json"):
    image_bytes = base64.b64decode(item["b64_json"])
    with open("output.png", "wb") as f:
        f.write(image_bytes)
else:
    image_url = item["url"]
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)

Notas sobre a portabilidade:

• Mantenha a chave em variável de ambiente, exatamente como no curl. Nunca a coloque inline.
• Defina timeouts explícitos. Geração de imagens é mais lenta que uma chamada típica de API JSON; usar o timeout curto padrão é uma causa comum de falhas falsas.
• Trate os dois modos de resposta. Ramificar conforme b64_json versus url faz o código funcionar independentemente de como a resposta for configurada.
• Reutilize em uma função. Encapsule isso em um pequeno helper generate_image(prompt, size), de modo que texto para imagem e imagem para imagem só se diferenciem pelo campo opcional image no payload.

Como o dicionário payload é o mesmo objeto que você testou em curl, qualquer mudança de comportamento observada em Python quase certamente vem do lado do cliente — cabeçalhos, codificação ou timeout — o que reduz muito o escopo da depuração.

Tratar erros e validar respostas

A geração de imagens é, por natureza, uma chamada propensa a falhas: é mais lenta que a maioria dos endpoints de API, carrega payloads grandes e depende da disponibilidade do modelo. Trate-a como uma operação que falha ocasionalmente e precisa de nova tentativa, e não como uma operação única.

Lista de verificação da resposta

1. Verifique o status antes de analisar. Chame raise_for_status() ou verifique o código de status e leia o corpo da resposta de erro — ele normalmente indica o campo problemático.
2. Valide a estrutura. Antes de indexar, confirme que data existe e não está vazio. Não presuma que data[0] sempre existe.
3. Verifique os bytes da imagem. Após decodificar, confira se a saída não está vazia e começa com uma assinatura de imagem válida. Um arquivo de zero bytes é um tipo de falha silenciosa que só aparece muito depois.
4. Registre o ID da requisição. Mantenha o identificador de requisição da resposta nos logs, para que gerações com falha possam ser rastreadas sem precisar reproduzi-las.

Estratégia de novas tentativas

• Só repita falhas temporárias. Timeouts, conexões redefinidas e respostas 5xx valem nova tentativa. 401 ou 400 falharão sempre da mesma forma — corrija a requisição, em vez de repeti-la.
• Use backoff exponencial com jitter. Comece com um atraso curto e aumente gradualmente; o jitter evita que um grupo de workers repita em sincronia.
• Limite o número de tentativas. Normalmente duas ou três tentativas bastam. Daí em diante, exponha o erro ao usuário ou encaminhe a tarefa para uma rota de mensagens mortas.
• Torne idempotente. Como as novas tentativas podem gerar duplicatas, associe o resultado ao ID da tarefa original, para que uma nova tentativa nunca cobre duas vezes uma ação visível ao usuário.

Adapte para assíncrono

Geração em alta resolução demora, então, se sua arquitetura permitir, não mantenha a thread da requisição ocupada o tempo todo. Coloque a tarefa em uma fila, devolva o ID da tarefa ao chamador e deixe um worker executar a chamada com a estratégia de novas tentativas descrita acima. Assim sua camada web permanece responsiva e o trabalho lento e propenso a falhas fica onde repeti-lo é barato.

Conecte essas verificações desde a primeira chamada funcional, e não depois do primeiro incidente em produção — o custo de um pequeno helper de validação é muito menor que depurar um arquivo de imagem vazio três semanas depois. Com autenticação, estrutura do corpo de requisição, resolução e novas tentativas confirmadas, a API GPT Image 2 se torna um bloco de construção confiável, em vez de uma integração apenas para demonstração.