Tutorial
Como chamar gpt-image-2.6-sunburst/text-to-image pela API HiAPI: guia com curl e Python
Autenticação, estrutura de requisição, exemplos executáveis em curl e Python, e solução de problemas
Nesta página
Como é essa integração de ponta a ponta
Toda chamada de geração de imagem a partir de texto na HiAPI segue o mesmo ciclo de vida, e vale a pena entendê-lo antes de escrever qualquer código. Sua aplicação monta um JSON descrevendo a imagem desejada, envia-o junto com as credenciais de API ao endpoint correspondente da HiAPI para gpt-image-2.6-sunburst/text-to-image e recebe uma resposta com dados da imagem gerada ou uma URL para obtê-la. Uma vez compreendidas essas três fases, o restante deste guia é apenas detalhamento.
As fases se dividem assim:
- Autenticação — anexe sua chave de API da HiAPI à requisição, normalmente como cabeçalho HTTP. Não há negociação de token por chamada.
- Montagem da requisição — monte um corpo JSON com seu prompt e, opcionalmente, parâmetros como tamanho e quantidade de imagens.
- Envio — faça POST do corpo para o endpoint. A chamada é síncrona, então o cliente espera a geração da imagem terminar.
- Tratamento da resposta — a API retorna JSON estruturado. Conforme a configuração do endpoint, os dados da imagem chegam como URL ou como conteúdo codificado que você precisa decodificar e gravar em disco.
Um detalhe a observar desde cedo: o identificador do modelo gpt-image-2.6-sunburst/text-to-image contém uma barra. Trate-o como string opaca. Não tente dividi-lo em nome de provedor e nome de modelo, nem codifique ou normalize a URL por conta própria. Copie-o exatamente como está na documentação e mantenha-o em um único lugar no código, para não precisar caçá-lo depois.
As seções a seguir percorrem cada fase em ordem. As partes de curl e Python usam deliberadamente o mesmo payload, para você comparar linha a linha; a parte de solução de problemas mapeia os erros mais prováveis de volta ao campo específico da requisição que precisa ser corrigido.
Autenticando requisições à HiAPI
A HiAPI usa um esquema de autenticação baseado em chave de API. Você obtém a chave no painel da conta e a envia em cada requisição. A forma padrão é um cabeçalho HTTP na requisição:
Authorization: Bearer YOUR_API_KEY
Alguns clientes preferem enviar a chave em um cabeçalho dedicado, mas, a menos que a documentação da sua conta indique o contrário, use o formato Authorization: Bearer, pois ele funciona de imediato com a maioria das ferramentas HTTP.
Mantenha a chave fora do código-fonte
O erro de segurança mais comum em primeiras integrações é codificar a chave diretamente no script e fazer commit. Evite isso desde o primeiro dia:
- Leia a chave de uma variável de ambiente, como
HIAPI_API_KEY, e falhe rapidamente na inicialização se ela estiver ausente. - Adicione o
.envlocal ao.gitignoreantes de criá-lo. - Em CI ou produção, injete a chave a partir do armazenamento de segredos da plataforma, não de um arquivo versionado.
Uma pequena função auxiliar que lê a chave uma vez e lança um erro claro quando ela falta poupará uma sessão de depuração confusa mais adiante:
import os
api_key = os.environ.get("HIAPI_API_KEY")
if not api_key:
raise RuntimeError("HIAPI_API_KEY is not set")
Trate a chave como segredo também na requisição
Ao diagnosticar chamadas com falha, não ceda à tentação de imprimir o objeto de requisição completo com os cabeçalhos. Em vez disso, registre o endpoint, o identificador do modelo e o código de status. Se precisar capturar cabeçalhos para depuração, mascare o valor de Authorization primeiro. Uma chave que vaza para um agregador de logs fica tão exposta quanto uma chave commitada no repositório.
Se você rotacionar a chave, a antiga deixa de funcionar imediatamente após a rotação, então trate a rotação como uma operação periódica planejada, não como uma emergência.
Anatomia de uma requisição de geração de imagem a partir de texto
O corpo da requisição é um objeto JSON. Para gpt-image-2.6-sunburst/text-to-image, os campos essenciais são poucos, e é justamente por isso que vale entender exatamente o que cada um faz em vez de copiar o payload às cegas.
O campo model
"model": "gpt-image-2.6-sunburst/text-to-image"
Esse campo seleciona o modelo e é obrigatório. Mantenha a string idêntica byte a byte ao identificador da documentação. Faltar a barra, sobrar um espaço ou mudar maiúsculas e minúsculas fará a requisição ser rejeitada por modelo desconhecido.
O campo prompt
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus"
É a descrição em linguagem natural da imagem, obrigatória. Dicas práticas sobre o prompt em si:
- Escreva primeiro o sujeito, depois o cenário e por fim as indicações de estilo ou iluminação.
- Prefira substantivos concretos a conceitos abstratos; "uma caneca de cerâmica vermelha sobre uma mesa de madeira" funciona melhor que "uma cena bacana de caneca".
- Se precisar de consistência entre chamadas, mantenha estável a redação das partes que não mudam e substitua programaticamente apenas as que variam.
Parâmetros opcionais
Dependendo do endpoint, você também pode enviar parâmetros que controlam a forma e a quantidade da saída, sendo os mais comuns:
- size — a dimensão da saída, no formato definido pela documentação, por exemplo
1024x1024. Se omitido, aplica-se o padrão; se enviar um valor não suportado, espere um erro de validação. - n — quantas imagens gerar para um prompt. Cada imagem gerada é cobrada separadamente, então mantenha o valor no mínimo que seu fluxo precisa.
Envie apenas os parâmetros que você realmente precisa. Campos desconhecidos podem disparar erros de validação rigorosa que apontam para um campo que você nem pretendia enviar.
Um exemplo completo de corpo de requisição
{
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1
}
É todo o contrato. O restante deste guia trata do envio, do tratamento de erros e do gerenciamento do ciclo de vida em torno desse payload.
Fazendo uma requisição funcional com curl
Antes de montar um cliente em Python, confirme com curl que o endpoint e as credenciais funcionam. Isso separa problemas de autenticação de problemas de código.
O comando de chamada
curl -sS -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.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1
}'
Algumas observações sobre essas flags:
-sSmantém a saída limpa, mas ainda mostra erros de transporte.-X POSTespecifica o método; o corpo vai via-d.- As aspas simples em volta do corpo JSON impedem que o shell o altere. No
cmddo Windows, as regras de aspas em JSON são diferentes, então usecurl.execom aspas duplas e escape as aspas internas, ou execute a chamada a partir de um script de shell ou do Python.
Se você usa o caminho exato de endpoint da documentação da sua conta, substitua aqui; a forma da requisição não muda.
Inspecione a resposta bruta
Quando algo dá errado, você precisa do código de status e do corpo da resposta. Adicione -i para incluir os cabeçalhos da resposta, ou -w "\nHTTP %{http_code}\n" para imprimir o status no final:
curl -sS -o response.json -w "HTTP %{http_code}\n" -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json
Vale a pena salvar o payload em payload.json e referenciá-lo com @payload.json: você evita erros de aspas do shell e pode editar o prompt sem reescrever o comando. Se o prompt contiver texto sensível, mantenha esse arquivo fora do controle de versão.
Fazendo a mesma chamada em Python
A versão em Python mantém o corpo JSON idêntico byte a byte. Só o transporte muda. Usar requests acrescenta uma dependência, mas mantém o código legível; vale instalá-la para qualquer uso que vá além de um script descartável.
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
"size": "1024x1024",
"n": 1,
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
response = requests.post(
"https://api.hiapi.ai/v1/images/generations",
headers=headers,
json=payload,
timeout=120,
)
print(response.status_code)
response.raise_for_status()
data = response.json()
print(data)
Por que usar json=payload em vez de data=json.dumps(payload): passar um dict ao parâmetro nomeado json o serializa e define o cabeçalho Content-Type automaticamente. Passar a string em data também funciona, mas é fácil esquecer o cabeçalho, o que depois se manifesta como um erro de validação confuso.
Se você preferir a biblioteca padrão
Para evitar dependências, use urllib.request da biblioteca padrão. O dicionário do payload permanece igual:
import json, os, urllib.request
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
}
request = urllib.request.Request(
"https://api.hiapi.ai/v1/images/generations",
method="POST",
headers={
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
},
data=json.dumps(payload).encode("utf-8"),
)
with urllib.request.urlopen(request, timeout=120) as response:
data = json.loads(response.read().decode("utf-8"))
De qualquer forma, a geração de imagem é mais lenta que uma chamada típica de API JSON. Defina o timeout com folga, senão você vai expirar em uma requisição prestes a dar certo e pagar duas vezes por ela ao tentar novamente.
Tratando a resposta e salvando a imagem
Uma resposta bem-sucedida é JSON. A saída da imagem geralmente chega como URL (que você busca separadamente) ou como conteúdo codificado no payload. Consulte a documentação do endpoint para confirmar qual forma se aplica e, então, trate ambas defensivamente, pois a forma exata pode variar com os parâmetros.
Lendo a estrutura da resposta
A resposta é um objeto JSON com a saída gerada e metadados. Antes de escrever código de parsing, inspecione-a uma vez de forma interativa:
print(json.dumps(data, indent=2)[:2000])
Localize onde a imagem está. Se houver um campo de URL, faça o download. Se houver conteúdo base64, decodifique. Evite supor que a URL seja permanente — trate-a como de validade curta e copie os bytes para o seu próprio armazenamento imediatamente.
Salvando um resultado baseado em URL
image_url = data["data"][0]["url"]
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
f.write(img.content)
Salvando um resultado codificado
import base64
encoded = data["data"][0].get("b64_json") or data["data"][0].get("image")
if encoded:
with open("output.png", "wb") as f:
f.write(base64.b64decode(encoded))
Em cargas de trabalho reais, use um nome de arquivo diferente por chamada — timestamp, ID da requisição ou um slug derivado do prompt. Se você pretende regenerar ou auditar saídas depois, guarde o prompt junto com a imagem em um arquivo JSON sidecar.
Centralize o tratamento de respostas bem-sucedidas
Encapsule o parsing da resposta em uma função que retorna uma lista de strings de bytes, uma por imagem. Assim, cada chamador só precisa gravar ou enviar os bytes, sem saber se vieram de URL ou de conteúdo codificado. Essa abstração compensa quando você trocar de modelo depois.
Diagnosticando erros comuns
A maioria das falhas em primeiras integrações se enquadra em poucas categorias. Antes de mudar qualquer outra coisa, associe o código de status e a mensagem à correção correspondente abaixo.
Falhas de autenticação
Uma requisição rejeitada por credenciais ausentes ou inválidas significa que o cabeçalho Authorization está faltando, mal formatado ou carrega uma chave revogada. Verifique nesta ordem:
- Confirme o nome e o formato do valor do cabeçalho, incluindo a palavra literal
Bearerseguida de um espaço. - Confirme se a variável de ambiente está realmente preenchida no shell ou processo que executa a chamada — uma chave definida em um terminal não existe em outro.
- Confirme se a chave não foi rotacionada ou truncada durante a cópia.
Erros de validação do corpo
A API rejeita corpos que não têm os campos obrigatórios ou que contêm valores inválidos. A mensagem normalmente aponta o campo problemático:
- model ou prompt ausentes — ambos são obrigatórios. Envie-os explicitamente em cada chamada, em vez de depender de padrões.
- Modelo desconhecido — reverifique o identificador
gpt-image-2.6-sunburst/text-to-image, incluindo a barra e as maiúsculas/minúsculas. Não insira espaços em branco ao redor dele. - Tamanho inválido — use uma string de tamanho suportado no formato definido pela documentação. Se você quer omitir size, remova-o em vez de enviar
null. - JSON malformado — geralmente problema de aspas do shell no curl ou de codificação de string no Python. Antes de enviar, valide com
json.dumps(payload)e confira o que realmente está sendo transmitido.
Limite de taxa e cota
Se você receber uma resposta de throttling, faça backoff e tente novamente com jitter, em vez de repetir imediatamente. Se a mensagem indicar problema de cota, verifique o plano da conta e o painel de uso, não o corpo da requisição — o payload provavelmente está correto.
Erros de servidor
Erros 5xx durante a geração costumam ser temporários. Tente novamente uma ou duas vezes com backoff exponencial. Se persistirem com prompts e payloads diferentes, o problema não está do seu lado; capture o corpo da resposta e contate o suporte com o horário da requisição e o identificador do modelo.
Erros de tipo de conteúdo
Enviar o corpo sem Content-Type: application/json pode produzir erros de validação confusos, porque o servidor não consegue interpretar o payload. No curl, defina o cabeçalho explicitamente; no Python, deixe o parâmetro json= cuidar disso.
Deixando a integração pronta para produção
A primeira chamada bem-sucedida é a parte fácil. Os ajustes a seguir mantêm a integração barata tanto em custo de execução quanto em custo de mudança.
Parametrize o identificador do modelo
Guarde o identificador do modelo em uma constante ou em um valor de configuração controlado por ambiente, nunca inline em vários pontos de chamada. Quando você for avaliar outro modelo depois, basta mudar um valor e rodar os testes novamente. Registre nos logs, por requisição, qual modelo gerou cada imagem, para comparar qualidade ao trocar de modelo sem precisar reexecutar tudo.
Retente com critério
Use backoff exponencial com jitter para erros de rede, timeouts e respostas 5xx. Nunca retente erros de validação ou autenticação — a requisição falhará do mesmo jeito e você só desperdiça limite de taxa. Limite o número de tentativas e registre o número de cada tentativa e o status final.
Escolha timeouts compatíveis com a carga de trabalho
A geração de imagem é lenta. Timeouts curtos demais derrubam requisições que teriam sucesso e, se você retentar, pode pagar por uma geração já concluída. Defina um timeout generoso por requisição e trate estouros acima do limite como sinal para investigar latência, não como motivo para retentar agressivamente.
Separe o cliente em camadas
Mantenha três partes separadas: um montador de payload que converte entradas da aplicação no dicionário da requisição; uma função de transporte que executa a chamada HTTP; e um tratador que decodifica a resposta em bytes. Testar o montador sem chamadas de rede é muito fácil; substituir o transporte por um mock também. Essa separação ainda faz com que uma troca de modelo seja a edição de um arquivo, em vez de uma busca pelo código inteiro.
Registre o que você vai precisar em um incidente
Registre timestamp, endpoint, identificador do modelo, status HTTP, uma versão truncada ou hash do prompt e a duração da requisição. Nunca registre chaves de API nem cabeçalhos completos. Se você armazenar as imagens geradas, organize o caminho de armazenamento pelo ID da requisição, para que um ticket de suporte consiga rastrear até a chamada real.
Com a autenticação tratada por variáveis de ambiente e o payload isolado em uma função montadora, o padrão que você praticou com gpt-image-2.6-sunburst/text-to-image é diretamente transferível para qualquer outro modelo de imagem no mesmo endpoint da HiAPI.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio