Blogue

Tutorial

Como chamar gpt-image-2.6-flare/text-to-image pela API HiAPI: curl, Python e uma requisição executável

Nov 10, 2026
Arte de capa abstrata com folhas de vidro translúcido sobrepostas que transformam um campo pálido em faixas de azul frio, fosco e arquitetônico, sem texto.
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 curl e 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:

  1. Uma conta HiAPI. Faça login no painel para gerar e gerenciar credenciais.
  2. 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.
  3. Uma forma de enviar requisições HTTP. Ou um shell com curl instalado, ou Python 3 com biblioteca padrão (urllib e json vê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_KEY manté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 campo prompt é 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 para jq.

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 settings em 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_KEY está 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, prompt ausente 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 →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API