Blogue

Tutorial

Como chamar flux-2/text-to-image pela API HiAPI: tutorial com curl e Python

Exercício de requisição funcional: identificador de modelo, parâmetros de prompt e proporção de aspecto, campos da resposta e tratamento de erros

Nov 12, 2026
Imagem de capa: sobre um fundo azul-índigo profundo, setas largas aninhadas em camadas avançam sucessivamente para a direita, com a borda frontal em laranja-damasco, planas e precisas como um fluxograma de sinais.
Nesta página

O que flux-2/text-to-image expõe via API

Antes de escrever a primeira linha de código, é útil entender exatamente o que você está integrando. Na HiAPI, flux-2/text-to-image não é um SDK separado que você instala, nem um novo serviço que exige autenticação própria. É um identificador de modelo passado, junto com o prompt que descreve a imagem desejada, para o endpoint compartilhado de geração de imagens.

Esse modelo mental importa porque delimita as fronteiras da integração. Seu código precisa de três coisas:

  • Credenciais de autenticação para a API HiAPI.
  • O endpoint que aceita requisições de geração de imagens.
  • Um payload JSON contendo model (definido como flux-2/text-to-image) e prompt.

Todo o resto — proporção de aspecto, preferências de saída e quaisquer outros ajustes que o modelo exponha — existe como campos adicionais nesse payload. É por isso que trocar de outro modelo de texto para imagem para flux-2/text-to-image geralmente exige apenas alterar uma linha de configuração, em vez de reescrever o código: o envelope da requisição permanece o mesmo, só o valor de model muda.

O endpoint recebe sua requisição, executa-a pelo modelo e retorna uma resposta estruturada contendo a imagem gerada (normalmente uma URL ou um payload codificado) e metadados da tarefa. Para chamadas básicas, você não precisa consultar uma fila de tarefas separada — do ponto de vista do cliente, o ciclo requisição/resposta é síncrono, mas a geração subjacente ainda leva tempo, então o timeout do seu cliente HTTP deve ser generoso.

Guarde esta imagem mental: um endpoint, um payload, uma string de modelo. O restante deste tutorial preenche o payload e fortalece a chamada.

Construindo uma requisição funcional com curl

A forma mais rápida de confirmar que credenciais e estrutura do payload estão corretas é uma chamada curl. Obtenha uma resposta bem-sucedida no terminal antes de tocar em Python — isso isola problemas de autenticação e payload de bugs na camada da linguagem.

Primeiro, defina a chave como variável de ambiente, para que não fique em texto claro no histórico do shell:

export HIAPI_API_KEY="your_api_key_here"

Depois envie a requisição:

curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "prompt": "a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
    "aspect_ratio": "16:9"
  }'

Pontos a verificar ao executar:

  • O endpoint e a chave vêm do painel da sua conta HiAPI. Copiar o endpoint do painel em vez de digitá-lo novamente evita a falha silenciosa mais comum — a requisição indo para um lugar inesperado.
  • -sS mantém a saída limpa, mas ainda expõe erros no nível do curl, como falhas de DNS ou TLS.
  • O cabeçalho Authorization usa o esquema bearer padrão. Sem espaços à direita nem aspas em volta da expansão da variável.
  • Content-Type: application/json é obrigatório; sem ele, o corpo pode ser rejeitado antes mesmo de o modelo vê-lo.

Se a chamada tiver sucesso, você verá o corpo JSON da resposta no terminal. Canalize a saída por um formatador para melhor legibilidade:

curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-2/text-to-image","prompt":"a red fox in fresh snow, eye level","aspect_ratio":"1:1"}' \
  | python3 -m json.tool

Assim que isso funcionar, você tem uma linha de base comprovadamente boa. Qualquer falha posterior em Python pode ser comparada com esta chamada que você confirmou ser válida.

Parâmetros de prompt e proporção de aspecto

Dois campos da requisição têm o maior impacto na saída: prompt e aspect_ratio. Ajuste um de cada vez, caso contrário você não conseguirá saber qual deles causou a mudança que está vendo.

Prompt

O prompt é a descrição em linguagem natural da imagem. Escreva-o como uma descrição compacta de cena, não como uma lista de palavras-chave — aproximadamente na ordem de sujeito, cenário, iluminação e composição. Compare:

  • Vago: a lighthouse
  • Específico: a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot

Durante o experimento, mantenha a formulação explícita e estável. Se você reescrever o prompt e a proporção de aspecto na mesma rodada de iteração, terá duas variáveis e uma única observação. Congele o prompt, ajuste uma palavra por vez e registre a mudança real.

Hábitos práticos:

  • Coloque o sujeito mais importante no início da string.
  • Descreva iluminação e atmosfera com palavras concretas, não abstratas.
  • Mantenha um pequeno conjunto de prompts de referência na base de código e execute-os novamente ao mudar qualquer outra coisa, para que você possa distinguir mudanças de comportamento do modelo de mudanças de prompt.

Proporção de aspecto

aspect_ratio controla a forma da saída — ampla para paisagens e banners, quadrada para avatares e miniaturas, vertical para pôsteres e layouts mobile. O modelo aceita strings de proporção como 16:9, 1:1 ou equivalentes verticais; use as proporções documentadas na documentação do modelo, não invente.

Como a proporção de aspecto é um único campo discreto, é o parâmetro mais fácil de explorar. Escreva um loop que mantenha o prompt fixo, peça a mesma imagem em três proporções e compare as composições lado a lado. Você logo aprenderá quais proporções cortam o sujeito e quais dão espaço a ele.

Uma ressalva: a proporção de aspecto altera a composição efetiva, não apenas a tela. Um prompt escrito para um plano amplo pode parecer fraco em um enquadramento quadrado. Depois de fixar a proporção, revise o prompt uma vez para compensar.

Portando a chamada para Python

A chamada curl se traduz diretamente em Python. O objetivo é uma pequena função que recebe o prompt e a proporção de aspecto, lê a chave do ambiente e retorna o JSON analisado — uma forma pronta para produção, não um script descartável.

import os
import requests

IMAGE_ENDPOINT = os.environ["HIAPI_IMAGE_ENDPOINT"]
MODEL = "flux-2/text-to-image"


def generate_image(prompt: str, aspect_ratio: str = "1:1", timeout: int = 120) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # fail fast if unset
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "aspect_ratio": aspect_ratio,
    }
    response = requests.post(
        IMAGE_ENDPOINT,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()

Notas sobre por que foi escrito assim:

  • Use variáveis de ambiente, não literais. os.environ[...] lança KeyError imediatamente se a variável estiver ausente, o que é muito melhor do que enviar um bearer token vazio e depois decodificar um erro de autenticação confuso.
  • json=payload faz o requests serializar o corpo e definir o Content-Type por você. Não construa strings JSON manualmente.
  • Timeout explícito. A geração de imagens não é instantânea; o timeout padrão do cliente causa problemas sob carga. Defina-o intencionalmente.
  • raise_for_status() converte respostas não 2xx em exceções capturáveis e classificáveis, em vez de retornar silenciosamente um corpo de erro que parece dados.

Chame-a:

result = generate_image(
    "a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
    aspect_ratio="16:9",
)
print(result)

Se você preferir httpx, a forma é idêntica — troque o import e mantenha os mesmos cabeçalhos, payload em json= e parâmetro de timeout. O que importa é o payload, que permanece igual ao da versão curl.

Lendo a resposta

Uma chamada bem-sucedida retorna um objeto JSON. Em vez de adivinhar nomes de campos, inspecione primeiro uma resposta real e escreva o parser com base no que você realmente vê. Execute sua função e imprima as chaves de nível superior:

result = generate_image("a red fox in fresh snow, eye level", "1:1")
print(result.keys())

Os campos que você normalmente usará se dividem em dois grupos:

  • A própria imagem. A resposta carrega a imagem gerada — normalmente uma URL que você pode baixar ou servir, às vezes dados de imagem codificados. Leia o nome exato do campo na sua própria resposta, armazene o valor e trate-o conforme sua forma. Se for uma URL, trate-a como de curta duração: baixe ou copie para seu próprio armazenamento prontamente, em vez de guardar o link em um banco de dados e assumir que ainda será resolvível no mês que vem.
  • Metadados. Espere campos acompanhantes que descrevem a geração — o modelo usado, a proporção de aspecto ou dimensões solicitadas e um identificador da requisição. Registre-os junto com a imagem. Quando um usuário relatar que uma imagem "parece errada", os metadados dirão qual prompt e proporção a produziram, sem que você precise reconstruir isso a partir do estado da aplicação.

Um padrão de extração seguro:

image_ref = result.get("image") or result.get("data")
if not image_ref:
    raise ValueError(f"no image in response; keys={list(result.keys())}")

Isso é deliberadamente defensivo. Os nomes de campos são estáveis dentro do modelo, mas escrever o acessador de forma que falhe ruidosamente com a lista real de chaves evita que um None silencioso se propague para sua UI. Depois de confirmar os nomes de campos a partir de uma resposta real, aperte o código para lê-los diretamente.

Por fim, não descarte a resposta bruta. Armazene-a (ou registre em log para parte das requisições) até que sua integração esteja estável — quando algo der errado a jusante, ela é a fonte da verdade.

Erros comuns e como corrigi-los

A maioria das falhas na primeira execução se enquadra em poucas categorias. Trate-as pela classe de status HTTP, não por correspondência de texto de mensagem, que muda sem aviso.

Falhas de autenticação (401 / 403)

Chave ausente, malformada ou sem permissão de acesso. Verifique em ordem: HIAPI_API_KEY está realmente definida no ambiente visível ao seu processo; o cabeçalho é exatamente Authorization: Bearer <key>, sem espaços extras ou aspas envolventes; você não enviou por engano uma chave de outro ambiente. Se o curl funciona e o Python não, imprima o cabeçalho que está enviando e compare caractere por caractere.

Payload malformado (400)

O corpo é rejeitado antes da geração. Causas comuns: JSON inválido (strings construídas manualmente com vírgulas finais), prompt ausente ou Content-Type errado. A correção é usar json=payload em Python e -d com JSON válido no curl. Ecoe no log o payload que está prestes a enviar e leia-o como uma pessoa leria.

Parâmetros não suportados ou inválidos (400 / 422)

Nome de campo ou valor que o modelo não aceita — aspect_ratio com erro de digitação, uma proporção não documentada pelo modelo ou um campo extra copiado de um exemplo de outro modelo. Reduza o payload ao mínimo (model, prompt) e depois adicione campos um a um para localizar o problema.

Limite de taxa (429)

Você está enviando requisições mais rápido do que o limite da conta permite. Isso é temporário. Não tente novamente em um loop apertado — use backoff com atraso crescente e um limite de tentativas. Se estiver em lote, adicione pequenas pausas entre as chamadas em vez de disparar todas de uma vez.

Erros do lado do servidor (5xx) e timeouts

Estes são temporários e fora do seu controle. Tente novamente com backoff e garanta que o timeout seja longo o suficiente para que uma geração lenta não seja classificada erroneamente como falha. Um timeout de leitura disparado enquanto o modelo ainda está trabalhando gera uma nova tentativa e desperdiça uma requisição.

Manter a classificação em um só lugar preserva a manutenibilidade:

def classify(status: int) -> str:
    if status in (401, 403):
        return "auth"        # fix config, do not retry
    if status in (400, 422):
        return "payload"     # fix request, do not retry
    if status == 429:
        return "rate_limit"  # retry with backoff
    if status >= 500:
        return "server"      # retry with backoff
    return "other"

Encapsulando a chamada para produção

A função acima funciona, mas uma integração real precisa de três coisas que ela ainda não tem: novas tentativas que distingam falhas temporárias de permanentes, timeouts que reflitam a realidade e logs que permitam reconstruir o que aconteceu. Um pequeno wrapper cobre esses três pontos.

import logging
import time

log = logging.getLogger(__name__)

def generate_with_retry(prompt, aspect_ratio="1:1", attempts=3):
    delay = 1.0
    for attempt in range(1, attempts + 1):
        try:
            return generate_image(prompt, aspect_ratio)
        except requests.HTTPError as exc:
            status = exc.response.status_code
            kind = classify(status)
            log.warning("flux-2 call failed", extra={
                "attempt": attempt, "status": status,
                "kind": kind, "aspect_ratio": aspect_ratio,
            })
            if kind in ("auth", "payload"):
                raise  # retrying will not help
            if attempt == attempts:
                raise
            time.sleep(delay)
            delay *= 2

Por que cada parte tem valor:

  • Só repita o que é repetível. Erros de autenticação e payload são determinísticos — repeti-los desperdiça tempo e mascara bugs reais. Limite de taxa, erros de servidor e timeouts recebem backoff exponencial.
  • Registre campos estruturados, não texto corrido. Número da tentativa, status, classe de erro e parâmetros usados permitem agrupar falhas depois. Nunca registre a chave da API.
  • Limite o número de tentativas. Um loop de retentativas sem limite transforma uma falha em um worker travado.
  • Mantenha o timeout explícito e generoso. Passe-o pela configuração, para que você possa aumentá-lo em períodos conhecidos de lentidão sem alterar o código.

Mais dois hábitos que compensam: persistir um hash de (model, prompt, aspect_ratio) para cada imagem gerada, para que você possa reproduzir qualquer saída; e manter um pequeno conjunto de prompts de referência na suíte de testes, executando-os após qualquer alteração no wrapper. Juntos, eles transformam o trecho do tutorial em algo operável.

Com o formato da requisição definido e o tratamento de erros no lugar, trocar de modelo depois exige apenas uma alteração de uma linha no campo model — que é exatamente o ponto de chamar flux-2/text-to-image por meio de uma interface unificada.

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