Como chamar gpt-image-2.5-sunburst/text-to-image pela API HiAPI: curl e Python

O que este endpoint de modelo oferece

gpt-image-2.5-sunburst/text-to-image é um modelo de geração de imagens exposto pela API unificada do HiAPI. Você o chama pelo ID do modelo, envia o prompt em um corpo de requisição no formato chat-completions igual ao dos modelos de texto e recebe os dados da imagem gerada na resposta.

O impacto prático é: se sua base de código já usa o HiAPI para texto, você não precisa de um segundo SDK, de um esquema de autenticação separado nem de aprender uma nova família de endpoints. A única coisa que muda é o ID do modelo.

Escolha este endpoint quando sua tarefa for geração de imagem a partir de prompt — criar uma nova imagem a partir de uma descrição textual, opcionalmente guiada por imagens de referência fornecidas na requisição. Se você precisa analisar ou descrever imagens existentes em vez de gerá-las, um modelo de chat com capacidade visual é mais adequado; deixe a geração de imagens neste endpoint e a compreensão de imagens em outro lugar.

É preciso estabelecer uma expectativa desde já: chamadas de imagem são mais lentas que completions de texto. Latências na casa de alguns segundos são normais, e o timeout do seu cliente deve ser ajustado a essa realidade, não herdado de uma configuração de texto puro.

Antes de enviar a primeira requisição

Três coisas precisam estar prontas.

Uma chave de API

Crie a chave na sua conta HiAPI e armazene-a como variável de ambiente, em vez de escrevê-la no código-fonte:

export HIAPI_API_KEY="your-key-here"

O ID exato do modelo

A string é gpt-image-2.5-sunburst/text-to-image. Trate-a como um identificador opaco — copie-a, não a redigite de memória. A barra faz parte do ID. Erros de digitação aqui são a causa mais comum de falha na primeira chamada e aparecem como erros do tipo modelo não encontrado, não como problemas de payload.

Um cliente capaz de fazer requisições HTTPS

Para a primeira validação, basta o curl, pré-instalado na maioria dos sistemas. Para o código da aplicação, Python com a biblioteca requests (ou qualquer cliente HTTP) é suficiente. Este endpoint não exige que o cliente use uma biblioteca especializada em imagens; você apenas envia JSON e lê JSON de volta.

Antes da primeira chamada puramente textual, você não precisa fazer upload prévio de imagens nem configurar armazenamento. Comece com a requisição mínima abaixo e adicione imagens de referência apenas depois que o ida-e-volta básico funcionar.

Uma requisição mínima funcional com curl

Esta é a chamada mínima correta:

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
      {
        "role": "user",
        "content": "A sunlit coastal cliff at golden hour, wide angle, high detail"
      }
    ]
  }'

Campo a campo:

• URL — o caminho padrão de chat-completions do HiAPI. Modelos de imagem usam a mesma rota dos modelos de texto.
• Authorization — token bearer com a chave de API. Se este cabeçalho estiver mal formatado, você receberá um 401 antes mesmo de chegar ao modelo.
• Content-Type — deve ser application/json.
• model — o ID exato do modelo da seção anterior.
• messages — o array padrão de objetos role/content. Seu prompt é o content da mensagem do usuário.

Em caso de sucesso, você recebe uma resposta JSON contendo os dados da imagem gerada e os metadados usuais de completion. Primeiro salve a resposta bruta em um arquivo e inspecione-a antes de conectar a lógica de parsing ao script:

curl -sS ... -o response.json

Assim que isso retornar uma imagem, suas credenciais e o formato do payload estarão corretos, e todos os problemas posteriores serão de lógica da aplicação, não de configuração.

Escrevendo a mesma requisição em Python

A convenção da requisição não muda — o que muda é a configuração do cliente, o timeout e a forma de tratar a resposta.

import os
import requests

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

payload = {
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
        {
            "role": "user",
            "content": "A sunlit coastal cliff at golden hour, wide angle, high detail",
        }
    ],
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=(10, 180),  # connect, read
)

response.raise_for_status()
data = response.json()
print(data)

Três detalhes merecem atenção:

Os timeouts são explícitos e assimétricos

A tupla (10, 180) define um timeout de conexão curto e um timeout de leitura mais generoso. A geração de imagens naturalmente leva tempo; um timeout único e plano copiado de um cliente de texto produziria falhas falsas. Mantenha o timeout de conexão curto para que problemas de rede falhem rápido.

Use json=payload, não data=

Passar o dicionário via json= cuida da serialização e define o content type para você. Se você passar uma string pré-serializada via data=, defina o cabeçalho manualmente.

Parsing defensivo

A resposta é JSON; antes de indexar, registre o corpo inteiro em caso de formato inesperado. Não presuma uma profundidade fixa de aninhamento antes de ver uma resposta real — e nunca presuma um formato de sucesso para status fora de 2xx.

Se você preferir uma biblioteca cliente configurada para o HiAPI, o payload enviado é exatamente o mesmo; só muda o local da chamada.

Enviando imagens de referência corretamente

Imagens de referência devem ser fornecidas dentro do conteúdo da mensagem, não como um campo temporário de nível superior. Esta é a parte da integração mais propensa a erros sutis, porque uma referência mal formatada normalmente não gera erro — a requisição simplesmente tem sucesso e a saída ignora sua imagem.

Mantenha a estrutura do payload consistente entre linguagens: a mensagem do usuário carrega um array de conteúdo, no qual a parte de texto contém o prompt e a parte de imagem carrega os dados de referência. O mesmo corpo JSON que você monta em Python deve ser expressável byte a byte no curl; se você não consegue escrever o equivalente curl do payload Python, a estrutura já divergiu.

Quando o resultado parecer ignorar sua imagem de referência, verifique nesta ordem:

1. Posição. A parte da imagem está dentro de messages[].content ou vazou para o nível superior do corpo da requisição? O modelo só vê o que está nas mensagens.
2. Codificação. A imagem de referência trafega na requisição como dados codificados. Confirme que os dados estão completos e no formato correto, e não truncados por concatenação manual ou por um copiar-e-colar malfeito.
3. Acoplamento com o prompt. A imagem de referência guia a geração; ela não substitui a instrução. Declare explicitamente o papel da imagem — estilo, composição, sujeito — em vez de supor que o modelo vai inferi-lo.
4. Tamanho. Referências muito grandes inflam a requisição e atrasam o ida-e-volta. Reduza-as ao tamanho que a tarefa realmente exige antes da codificação.

Um hábito prático de depuração

Monte uma vez um payload com imagem de referência, salve o corpo JSON exato que funciona e reutilize-o como amostra fixa. Quando uma chamada posterior se comportar de forma estranha, compare o corpo atual com a amostra fixa usando diff. A maioria das regressões com imagens de referência é estrutural, e o diff revela isso em segundos.

Tratando erros, timeouts e retentativas

Endpoints de imagem falham de forma diferente dos de texto: são mais lentos, então mais chamadas caem na janela de timeout, e retentativas cegas custam mais caro porque o trabalho é mais pesado.

Distinga erros de cliente de falhas transitórias

• 4xx (exceto 429) — payload mal formatado, ID de modelo errado, autenticação ausente. Repetir a mesma requisição falhará da mesma forma. Corrija a requisição.
• 401/403 — problema de credenciais. Verifique a chave e o formato do cabeçalho Authorization.
• 429 — limitado por taxa. Tente novamente, mas com backoff e jitter, não imediatamente.
• 5xx e erros de conexão — transitórios. Tente novamente.
• Timeout de leitura — ambíguo: a geração pode ter sido concluída no servidor. Trate o timeout como retentável apenas se seu fluxo de trabalho tolerar possíveis duplicatas.

Só repita o que é seguro

Use backoff exponencial com jitter e um limite pequeno de tentativas — três costuma bastar. Um padrão simples:

import time, random

def post_with_retry(session, url, payload, attempts=3):
    for i in range(attempts):
        try:
            r = session.post(url, json=payload, timeout=(10, 180))
            if r.status_code == 429 or r.status_code >= 500:
                raise RuntimeError(f"retryable: {r.status_code}")
            r.raise_for_status()
            return r.json()
        except (RuntimeError, requests.ConnectionError, requests.Timeout):
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.random())

Não repita erros de payload 4xx dentro deste laço — exponha-os imediatamente, para que uma requisição inválida falhe ruidosamente em vez de consumir tentativas.

Dimensione os timeouts conforme o modelo

O timeout de leitura para chamadas de imagem deve ser várias vezes o padrão de texto, e definido por chamada em vez de globalmente, para que o tráfego de texto não seja penalizado. Se sua plataforma tem um limite rígido de requisições, mantenha prompts de geração e imagens de referência dentro do orçamento que você consegue realmente cumprir.

Checklist de produção antes do lançamento

Uma lista curta que previne a maioria dos incidentes:

• ID do modelo em um único lugar. Defina gpt-image-2.5-sunburst/text-to-image como constante ou valor de configuração, não como literais de string espalhados.
• Chave vinda de variável de ambiente, nunca commitada. Rotacione-a como qualquer outro segredo.
• Timeouts explícitos, com janela de leitura generosa, definidos na requisição e não nos padrões da sessão.
• Retentativas apenas em 429/5xx/timeout, com backoff e jitter, e limite de tentativas.
• Registre a resposta completa em caso de falha — status, corpo da resposta e request ID antes do parsing, para que o suporte comece a conversa com evidências.
• Guarde amostras fixas de payload que funcionam, cobrindo o caso comum e o caso com imagem de referência, para usar em diff quando o comportamento mudar.
• Imagens de referência dentro do conteúdo da mensagem, reduzidas conforme a tarefa, com seu papel declarado no prompt.
• Smoke test no CI, fazendo uma chamada real contra o ID do modelo, para que um modelo renomeado ou desativado apareça antes que os usuários descubram.

Nenhum desses hábitos é específico de geração de imagens, mas cada um ataca um modo de falha que chamadas de imagem encontram com mais frequência que chamadas de texto. Configure-os uma vez e o endpoint se comportará como qualquer outra parte da sua stack. Para os parâmetros e limites atuais do modelo, consulte a página do modelo no HiAPI antes de finalizar a configuração.