Tutorial
Como chamar gpt-image-2.6-flare/text-to-image pela API HiAPI: curl, Python e uma requisição executável
Nesta página
O que este tutorial constrói
A maioria dos tutoriais de texto para imagem para em uma captura de tela de uma resposta bem-sucedida. Isso não basta para colocar nada em produção. Este tutorial leva você do zero a uma integração reutilizável e funcional com o modelo gpt-image-2.6-flare/text-to-image pela API unificada da HiAPI.
Ao final, você terá três coisas:
- Uma requisição confirmada como funcional, apresentada primeiro como comando
curle depois como script Python equivalente. - Um modelo mental claro de como a HiAPI organiza chamadas de texto para imagem — caminho do endpoint, cabeçalho de autenticação, payload do prompt e corpo da resposta — para que você adapte o exemplo aos seus próprios prompts em vez de decorar.
- Padrões para estender essa chamada única para processamento em lote, além de um método para decidir quais falhas devem ser tentadas novamente e quais devem ser corrigidas.
Vamos manter o código enxuto e com mínimas dependências. Os exemplos Python usam apenas a biblioteca padrão, então você pode executá-los em qualquer ambiente com Python instalado; quando estiver familiarizado com a estrutura da requisição, adapte para requests ou um cliente assíncrono. Se quiser ir direto para a chamada executável, pule para a seção curl e volte depois para ler as explicações.
Pré-requisitos e credenciais
Antes da primeira chamada, confirme que você tem os seguintes itens:
- Uma conta HiAPI. Faça login no painel para gerar e gerenciar credenciais.
- Uma chave de API. Crie uma na área de chaves de API do painel. Trate-a como uma senha: ela autoriza cada requisição cobrada na sua conta.
- Uma forma de enviar requisições HTTP. Ou um shell com
curlinstalado, ou Python 3 com biblioteca padrão (urllibejsonvêm junto com o Python).
Manipulando a chave via variáveis de ambiente
Nunca cole a chave diretamente em arquivos de código que serão versionados. Em vez disso, exporte-a no shell:
export HIAPI_API_KEY="your-api-key-here"
No Windows PowerShell, use $env:HIAPI_API_KEY = "your-api-key-here". Em CI, injete-a como segredo. Em serviços de longa duração, carregue-a do gerenciador de segredos na inicialização.
Saiba onde fica a URL base
A HiAPI oferece uma superfície de API unificada única, então a URL base se mantém estável entre os modelos. Guarde-a em um valor de configuração — variáveis de ambiente são uma boa opção — em vez de espalhá-la pelo código. Assim, alternar entre staging e produção, ou apontar testes para um servidor mock, exige apenas uma linha de mudança.
O identificador de modelo que você vai chamar é gpt-image-2.6-flare/text-to-image. Note que ele contém uma barra; mantenha o identificador completo e deixe-o na posição do caminho que o construtor de requisições espera, exatamente como nos exemplos abaixo.
Com a chave exportada e a URL base anotada, você pode examinar a requisição em si.
Anatomia de uma requisição de texto para imagem
Toda chamada de texto para imagem da HiAPI tem os mesmos quatro componentes. Uma vez que você os entende, trocar modelos ou prompts se torna mecânico.
1. Caminho do endpoint
A requisição usa o identificador do modelo como parte do caminho: gpt-image-2.6-flare/text-to-image, anexado após sua URL base. Este é o endereço que roteia sua chamada para o modelo correto por trás da interface unificada.
2. Cabeçalho de autenticação
A autenticação é um token bearer no cabeçalho Authorization:
Authorization: Bearer $HIAPI_API_KEY
Todo request deve incluir este cabeçalho. Ausência ou formato incorreto é a causa mais comum de falha na primeira chamada.
3. Corpo da requisição
Uma chamada de texto para imagem é um POST com corpo JSON. O núcleo é o prompt — a descrição em linguagem natural da imagem que você deseja. O corpo também carrega configurações de geração. Como a HiAPI normaliza a estrutura de requisição entre modelos, você pode reutilizar o construtor de requisições e apenas mudar o identificador de modelo quando quiser comparar saídas.
4. Corpo da resposta
Uma resposta bem-sucedida retorna a imagem gerada (ou uma referência a ela) junto com metadados sobre a geração. Seu cliente deve verificar o status HTTP antes de tentar interpretar a imagem. Trate a resposta como dados, não como algo para inspecionar visualmente — para automação, você precisa dos bytes ou da URL da imagem, e precisa armazenar qualquer identificador de requisição junto com eles para associar o arquivo de volta à chamada que o produziu.
Esse é o modelo completo. Tudo o que vem depois é uma instanciação concreta desses quatro componentes.
Enviando uma requisição executável com curl
Esta é a chamada completa. Substitua o prompt pelo seu próprio texto e execute:
curl -X POST "$HIAPI_BASE_URL/gpt-image-2.6-flare/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A quiet library at dusk, warm lamp light, deep shadows, cinematic"
}' \
--output response.json
Explicação linha a linha:
-X POST— geração é uma chamada que altera estado, portanto use POST.- URL — a URL base vinda da variável de ambiente, seguida pelo identificador do modelo e
/text-to-image. As aspas evitam que o shell interprete caracteres especiais erroneamente. Authorization: Bearer ...— a credencial. A forma$HIAPI_API_KEYmantém a chave literal fora do histórico do shell.Content-Type: application/json— informa ao servidor para interpretar o corpo como JSON. Omitir isso é uma causa comum de erros 4xx confusos.-d '{...}'— o payload JSON. O campoprompté o que você mais vai alterar; adicione configurações de geração aqui ao refinar a saída.--output response.json— grava o corpo da resposta em arquivo, para que um payload binário de imagem não inundem o terminal. Abra-o, ou, se a resposta for codificada em JSON, canalize parajq.
Verificação rápida de sanidade
Se o comando retornar rapidamente e response.json não estiver vazio, você tem uma integração funcional. Se em vez disso receber 4xx, verifique o corpo da resposta — a HiAPI retorna erros descritivos, e a seção de tratamento de erros abaixo cobre os suspeitos habituais.
Assim que isso funcionar, salve o comando em um script shell ao lado do seu projeto. É a forma mais rápida de testar mudanças de credenciais ou confirmar se uma falha está do seu lado.
Fazendo a mesma requisição em Python
A chamada curl se traduz diretamente para Python. Este script usa apenas a biblioteca padrão, lê a chave de variáveis de ambiente e grava a resposta de imagem em disco:
import json
import os
import urllib.error
import urllib.request
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
MODEL = "gpt-image-2.6-flare/text-to-image"
def generate_image(prompt: str, settings: dict | None = None) -> bytes:
payload = {"prompt": prompt}
if settings:
payload.update(settings)
request = urllib.request.Request(
f"{BASE_URL}/{MODEL}",
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
try:
with urllib.request.urlopen(request, timeout=120) as response:
return response.read()
except urllib.error.HTTPError as exc:
detail = exc.read().decode("utf-8", errors="replace")
raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc
if __name__ == "__main__":
body = generate_image("A quiet library at dusk, warm lamp light, deep shadows, cinematic")
with open("output.bin", "wb") as f:
f.write(body)
print(f"wrote {len(body)} bytes")
Algumas escolhas intencionais:
- Timeout generoso. Geração de imagem é mais lenta que completação de texto; um limite de 120 segundos evita travar para sempre, mas ainda tolera chamadas lentas que têm sucesso.
- A função retorna bytes, não um caminho. Isso a torna reutilizável — você pode enviar os bytes para um armazenamento de objetos ou retorná-los de um handler web.
- Erros são encapsulados com o corpo da resposta. Em caso de erro, a mensagem informa o que o servidor disse, não apenas o código de status.
- O construtor de payload aceita configurações opcionais. Ao adicionar parâmetros de geração, estenda o dicionário
settingsem vez de codificar valores fixos na função.
Após exportar as duas variáveis de ambiente, execute com python generate.py. Se preferir requests, substitua a construção da requisição por requests.post(url, json=payload, headers=headers); a estrutura é idêntica.
Padrões de processamento em lote e concorrência
Um prompt é demonstração; muitos prompts são trabalho. Essa transição introduz dois problemas: throughput e depurabilidade.
Iterando prompts a partir de um arquivo
Coloque os prompts em um arquivo separado por quebras de linha ou em um array JSON. Atribua um ID a cada prompt (slug, índice ou hash) e nomeie o arquivo de saída com esse ID. Quando um lote de centenas de imagens estiver concluído, você poderá mapear cada arquivo de volta ao seu prompt sem adivinhação.
prompts = [
("lib-001", "A quiet library at dusk, warm lamp light, cinematic"),
("lib-002", "A lighthouse in fog, long exposure, muted palette"),
]
for prompt_id, text in prompts:
body = generate_image(text)
with open(f"out/{prompt_id}.bin", "wb") as f:
f.write(body)
Controle explícito de concorrência
Chamadas de geração são intensivas em I/O, então concorrência ajuda no throughput — mas concorrência ilimitada dispara limites de taxa e te afunda em erros. Comece serial, meça o tempo de uma chamada e então aumente a concorrência com um pool de trabalho limitado. Um pool de threads simples com um número fixo pequeno de threads de trabalho (quatro a oito para começar) costuma ser suficiente.
Para tarefas maiores, use um cliente assíncrono ou uma fila com workers. A disciplina principal é a mesma: paralelismo limitado, um arquivo de saída por prompt ID, uma linha de log por requisição registrando ID, status e duração.
Mantenha um manifesto
Escreva um pequeno manifesto JSON durante a execução do lote, registrando cada prompt ID e seu resultado. Se o processo morrer no meio, o manifesto te diz de onde retomar, em vez de recobrar o lote inteiro. Essa prática economiza mais tempo do que qualquer otimização esperta.
Tratamento de erros e retentativas
Falhas se dividem em duas categorias: as que você corrige e as que você tenta novamente. Confundi-las desperdiça tempo e, em tempestades de retentativas, também dinheiro.
Corrija estas
- 401 / 403 — autenticação. Chave ausente, expirada ou sem permissão de acesso. Verifique se
HIAPI_API_KEYestá realmente exportada no shell que executa o comando — uma armadilha comum é exportar em um terminal e rodar o script em outro. - 400 — payload malformado. JSON inválido,
promptausente ou tipo de campo inesperado. O corpo do erro geralmente aponta o campo problemático. Cuide das aspas do seu JSON na chamada curl. - 404 — caminho errado. Verifique se a grafia do identificador de modelo corresponde exatamente à documentação e se sua URL base não tem segmentos de caminho duplicados ou ausentes.
Tente novamente estas, com backoff
- 429 — limite de taxa atingido. Diminua a velocidade. Respeite qualquer indicação de retry-after na resposta e use backoff exponencial com jitter. A longo prazo, limite sua concorrência.
- 5xx — erro do servidor. Geralmente transitório. Tente novamente um número limitado de vezes (três é um padrão razoável), com atraso crescente, e então falhe ruidosamente.
Um wrapper mínimo de retentativa
import random, time
def with_retries(fn, attempts=3):
for i in range(attempts):
try:
return fn()
except RuntimeError as exc:
if i == attempts - 1:
raise
time.sleep((2 ** i) + random.uniform(0, 0.5))
Envolva generate_image com ele. O ponto crítico é tornar a operação idempotente do seu lado: como os arquivos de saída são indexados pelo prompt ID, retentativas sobrescrevem em vez de duplicar. Registre cada falha com o prompt ID e a mensagem do servidor — quando você realmente precisar escalar, esse log é exatamente o que a equipe de suporte precisa para reproduzir o problema.
Próximos passos
Você agora tem uma requisição funcional, uma função Python que vale a pena manter e padrões para executá-la em escala. Para endurecer para produção, adicione logging estruturado com request IDs, persista o manifesto em armazenamento durável para que jobs em lote se recuperem de falhas e valide prompts antes do envio, para que entradas malformadas falhem rápido e barato.
O próximo passo mais útil é reutilizar exatamente este cliente em outros modelos da API HiAPI. Como o caminho do endpoint, o cabeçalho de autenticação e a estrutura do payload são compartilhados, adaptar o script para um novo modelo geralmente significa mudar o identificador do modelo e, ocasionalmente, uma ou duas configurações — uma pequena mudança de código que produz saídas significativamente diferentes.
Comece com um prompt, confirme a geração do arquivo e então deixe o executor em lote cuidar do resto.
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