Blogue

Tutorial

Como chamar flux-3-image-klein pela API HiAPI: curl, Python e exemplos de requisição prontos para uso

Integração prática para desenvolvedores: da primeira requisição a chamadas em lote confiáveis

Nov 12, 2026
Uma imagem de capa quase preta com um campo de pontos verde-menta que aumentam em densidade da esquerda para a direita, com pontos azul-petróleo transbordando na borda.
Modelo
flux-3-image-klein
Nesta página

Os requisitos reais da integração com flux-3-image-klein

Antes de escrever a primeira linha de código, entenda quantas etapas separam seu script de uma imagem gerada. Para o flux-3-image-klein na HiAPI, a lista é curta: um endpoint, uma credencial, um corpo JSON de requisição e um objeto de resposta para analisar.

Este é o modelo mental que você deve ter em mente:

  • Endpoint — uma rota da HiAPI trata da geração de imagens desse modelo. Todas as requisições apontam para ela; o modelo é identificado no corpo da requisição, não por URLs diferentes.
  • Credencial — uma chave de API emitida pela sua conta HiAPI. Ela é enviada em cada chamada por meio de um cabeçalho HTTP. Trate-a como uma senha: leia de uma variável de ambiente, nunca a codifique diretamente em arquivos que possam ser commitados.
  • Corpo da requisição — um pequeno objeto JSON que descreve o modelo, o prompt e alguns parâmetros opcionais que afetam a saída (tamanho, dicas de estilo etc.).
  • Resposta — um objeto JSON que, após ser analisado, fornece a referência da imagem gerada e os metadados que a API retorna junto.

Há dois pré-requisitos que vale a pena verificar antes de começar. Primeiro, confirme que sua chave está ativa e tem permissão para geração de imagens — uma chave válida para um modal não é automaticamente válida para outro. Segundo, deixe a documentação atual da HiAPI aberta em uma aba. Nomes de parâmetros, tamanhos suportados e campos de resposta podem mudar, e a documentação é a única fonte de verdade com a qual você deve comparar, não a memória nem algum post de blog (incluindo este).

O restante deste guia monta uma requisição, porta para Python e depois a reforça para cargas reais. Se você acompanhar na ordem, cada etapa reaproveita a anterior, sem nada que precise ser reaprendido no meio do caminho.

Envie a primeira requisição funcional com curl

A forma mais rápida de confirmar que a integração funciona é fazer uma chamada curl no shell. Depois de obter uma resposta bem-sucedida aqui, tudo o mais é apenas empacotamento.

Primeiro exporte sua chave, para que ela nunca apareça literalmente no histórico do shell:

export HIAPI_API_KEY="your-api-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"

Em seguida, envie uma requisição mínima:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image-klein",
    "prompt": "Um farol desgastado em um penhasco ao crepúsculo, longa exposição, névoa suave"
  }'

Uma observação sobre a URL: o caminho base e a rota exatos são definidos pela documentação da HiAPI — use o endpoint da documentação, não copie um hostname de qualquer captura de tela de terceiros. Defina uma vez a variável HIAPI_BASE_URL no ambiente; todos os exemplos a seguir a reutilizam.

Agora veja o que cada campo faz:

  • model identifica qual modelo processa a tarefa. Use exatamente o valor da documentação; um erro de digitação aqui é a causa mais comum de uma requisição que parece válida mas não retorna algo útil.
  • prompt é sua descrição em linguagem natural. Seja específico sobre sujeito, composição, iluminação e atmosfera — o modelo responde a detalhes descritivos, e prompts vagos produzem resultados imprevisíveis e difíceis de depurar.
  • Os cabeçalhos não são negociáveis: o bearer token autentica e Content-Type: application/json informa ao servidor como analisar o corpo da requisição.

Em caso de sucesso, você recebe uma resposta JSON contendo a referência da imagem gerada (normalmente uma URL ou recurso hospedado) e metadados. Se quiser inspecionar também os cabeçalhos de resposta, use primeiro curl sem a supressão -sS para imprimir a resposta completa, entenda a estrutura e depois restrinja. Salve uma resposta real em arquivo — você a usará como fixture de teste ao escrever e testar o cliente Python.

Se falhar, não ceda à tentação de alterar o corpo da requisição ao acaso. Verifique primeiro o código de status e o corpo da mensagem de erro; a seção de solução de problemas mais adiante neste guia mapeia cada tipo de falha para a correção específica.

Porte a requisição para Python

Depois que o curl funcionar, porte para Python sem alterar a semântica. O objetivo não é montar um framework — é um cliente pequeno que se comporte exatamente como o comando de shell e seja fácil de estender.

A abordagem mais limpa é colocar o corpo da requisição em um único local compartilhado, para que as versões curl e Python nunca divergam. Defina-o como um dicionário, serialize-o e deixe um wrapper leve cuidar das questões de HTTP.

import json
import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def build_payload(prompt: str, **overrides) -> dict:
    payload = {
        "model": "flux-3-image-klein",
        "prompt": prompt,
    }
    payload.update(overrides)
    return payload


def generate_image(prompt: str, timeout: float = 60.0, **overrides) -> dict:
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        data=json.dumps(build_payload(prompt, **overrides)),
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = generate_image(
        "Um farol desgastado em um penhasco ao crepúsculo, longa exposição, névoa suave"
    )
    print(json.dumps(result, indent=2))

Por que essa estrutura compensa:

  • build_payload é o único lugar onde o corpo da requisição é montado. Adicione um parâmetro ali e tanto o script de exploração quanto o código de produção o obterão automaticamente.
  • raise_for_status() converte imediatamente falhas HTTP em exceções, então você nunca confunde acidentalmente um corpo de resposta de erro com um resultado de sucesso.
  • Um timeout explícito evita o clássico problema de travamento: uma conexão parada bloqueando indefinidamente uma thread de trabalho. Escolha um valor compatível com o orçamento de tempo da própria requisição do serviço.
  • Usar variáveis de ambiente para o base URL e a chave significa que o mesmo código roda em pré-produção e produção sem modificação.

Execute-o e compare a saída com a resposta curl salva anteriormente. Elas devem descrever a mesma estrutura. Se não, o porte introduziu um bug — corrija agora, pois as diferenças ficarão muito mais feias quando lotes e retentativas forem adicionados.

Trate parâmetros de tamanho e estilo

O prompt resolve a maior parte, mas os parâmetros que afetam a imagem — tamanho de saída e dicas de estilo — são onde a integração falha silenciosamente. Duas regras mantêm você seguro.

Coloque parâmetros opcionais em um bloco explícito

Nunca espalhe strings mágicas pelo código. Estenda o construtor de corpo de requisição com parâmetros nomeados e valide na fronteira:

def build_payload(prompt: str, size: str | None = None, style: str | None = None) -> dict:
    payload = {"model": "flux-3-image-klein", "prompt": prompt}
    if size:
        payload["size"] = size
    if style:
        payload["style"] = style
    return payload

Omitir o parâmetro completamente costuma ser melhor do que enviar uma string vazia ou um placeholder. Se você não precisa controlar o tamanho, omita-o e deixe o serviço aplicar o padrão documentado.

Valide segundo a documentação, não segundo suposições

Esta é a parte que a maioria dos tutoriais pula: não codifique diretamente uma lista de tamanhos ou valores de estilo “suportados” a partir de um post de blog. Os valores suportados podem mudar, e constantes desatualizadas viram erros 400 em tempo de execução difíceis de rastrear. Em vez disso:

  1. Leia a referência atual de parâmetros do flux-3-image-klein na documentação da HiAPI, registre os valores aceitáveis como uma constante no seu código e adicione um comentário com a página da documentação e a data da verificação.
  2. Antes de montar a requisição, valide a entrada do usuário ou do chamador com essa constante. Falhe rápido com uma mensagem de erro local clara, em vez de enviar pela rede uma requisição fadada ao fracasso.
  3. Quando uma requisição retornar erro de validação por um valor não suportado, atualize a constante a partir da documentação — não adivinhe um valor vizinho que “parece certo”.

Uma pequena tupla ALLOWED_SIZES e uma verificação de pertinência custam quase nada e eliminam toda uma classe de tickets de suporte. O mesmo vale para dicas de estilo: trate-as como um conjunto fechado que você verificou, não como uma string aberta que espera que o servidor tolere.

Requisições em lote e retentativas de falhas

Uma requisição em um script é só uma demonstração. Cargas reais significam dezenas ou milhares de imagens, e é aí que a disciplina na camada de cliente importa. Coloque a lógica de processamento em lote e de retentativa no módulo do cliente, não em um loop improvisado colado em um notebook — você quer um único lugar para observar e ajustar.

Concorrência com rastreabilidade

Um padrão simples é um pool de threads limitado, em que cada tarefa submetida retorna tanto a entrada quanto o resultado:

from concurrent.futures import ThreadPoolExecutor, as_completed

def run_batch(prompts: list[str], max_workers: int = 4) -> list[dict]:
    results = []
    with ThreadPoolExecutor(max_workers=max_workers) as pool:
        futures = {pool.submit(generate_image, p): p for p in prompts}
        for future in as_completed(futures):
            prompt = futures[future]
            try:
                results.append({"prompt": prompt, "ok": True, "data": future.result()})
            except Exception as exc:
                results.append({"prompt": prompt, "ok": False, "error": str(exc)})
    return results

Há duas características importantes aqui. Primeiro, cada resultado fica associado ao seu prompt, então falhas parciais são atribuíveis, não um mistério. Segundo, max_workers é o botão que você controla — comece com um valor conservador, observe a taxa de erro e só aumente a concorrência depois que execuções em lote estiverem limpas. Bombardear o endpoint com paralelismo ilimitado é a forma mais rápida de transformar uma integração saudável em um incidente de limite de taxa.

Retentativa com backoff

Só retente o que é seguro: erros transitórios de rede, timeouts e respostas de limite de taxa. Não retente erros de validação — a requisição falhará do mesmo jeito toda vez, e você só desperdiçará cota.

import time

def generate_with_retry(prompt: str, attempts: int = 3, **overrides) -> dict:
    delay = 1.0
    for attempt in range(1, attempts + 1):
        try:
            return generate_image(prompt, **overrides)
        except requests.HTTPError as exc:
            status = exc.response.status_code if exc.response is not None else None
            if status is not None and 400 <= status < 500 and status != 429:
                raise
            if attempt == attempts:
                raise
        except requests.Timeout:
            if attempt == attempts:
                raise
        time.sleep(delay)
        delay *= 2
    raise RuntimeError("unreachable")

Registre uma linha de log por tentativa, contendo o identificador do prompt, o número da tentativa e o status. Quando uma execução em lote der problema, é esse log que mostra se você encontrou uma instabilidade transitória ou um problema sistemático no corpo da requisição.

Solucione erros comuns de requisição

A maioria das falhas da primeira semana não é problema do modelo — é problema do encanamento. A seguir estão as categorias mais prováveis e a correção específica de cada uma.

401 / 403 — Autenticação e autorização

Sintoma: rejeição imediata antes de qualquer geração acontecer. Causa: cabeçalho Authorization ausente, bearer token mal formatado, chave expirada ou revogada, ou espaços em branco colados na variável de ambiente. Correção: imprima os primeiros e últimos caracteres da chave que você está realmente enviando (nunca a chave inteira), confirme que o formato do cabeçalho é Bearer <key> com exatamente um espaço, e verifique se a chave está ativa na conta HiAPI. Se a chave funciona no curl mas não no Python, a diferença quase sempre está na montagem do cabeçalho.

400 — Validação do corpo da requisição

Sintoma: a requisição é compreendida, mas rejeitada por algum campo. Causa: model com erro de digitação, prompt ausente, valor de size ou estilo não suportado, ou tipo errado (número enviado onde deveria ser string). Correção: compare caractere por caractere o corpo serializado — json.dumps(build_payload(...)) — com o schema da documentação. Valide localmente os parâmetros opcionais com constantes derivadas da documentação, para que valores inválidos nunca saiam do seu processo.

404 — Rota errada

Sintoma: o próprio endpoint não é encontrado. Causa: erro de digitação no caminho, base URL desatualizada, ou barras inicial/final incompatíveis ao concatenar fragmentos de URL. Correção: monte a URL a partir de uma única constante e confira com a referência de endpoints da documentação da HiAPI, não com um trecho de código copiado.

429 — Limite de taxa

Sintoma: as requisições começam a ter sucesso e depois falham em massa sob carga. Correção: reduza max_workers, respeite a estratégia de backoff já presente no wrapper de retentativa e trate o 429 como erro transitório. Se os 429 persistirem mesmo com baixa concorrência, é preciso verificar os limites ou o padrão de uso da sua conta — não alterar o código.

Timeouts e conexões redefinidas

Sintoma: chamadas travadas por muito tempo, ou exceções ReadTimeout no meio de um lote. Causa: timeout do cliente agressivo demais, rede instável, ou lote grande demais saturando o pool de conexões. Correção: defina um timeout explícito e realista por requisição, retente timeouts com backoff e mantenha a concorrência moderada. Nunca remova o timeout para “fazer funcionar” — isso transforma uma falha visível em um travamento invisível.

Sucesso, mas a imagem não está certa

Isso é problema de prompt, não de API. Prompts vagos, dicas de estilo conflitantes e prompts que contradizem um size explícito produzem saídas inesperadas. Refine primeiro a descrição do prompt; só depois reavalie os parâmetros.

Checklist antes de ir para produção

Antes de direcionar tráfego de produção para o flux-3-image-klein, percorra este checklist. Leva poucos minutos e captura as falhas que saem caro em produção.

  • Credenciais — a chave é carregada de variável de ambiente ou gerenciador de segredos, nunca commitada; confirme que ela pode gerar imagens na conta que você pretende faturar.
  • Endpoint — o base URL e a rota vêm literalmente da documentação atual da HiAPI e estão armazenados em uma única constante.
  • Estrutura do corpo da requisição — o nome do modelo está exatamente igual à documentação, o prompt está sempre presente e não vazio, parâmetros opcionais são omitidos quando não usados e validados localmente quando definidos.
  • Valores de parâmetros — suas constantes de size e estilo foram comparadas com a documentação na data anotada no comentário, com um plano para revisá-las após atualizações da API.
  • Estratégia de retentativa — erros transitórios e timeouts são retentados com backoff, erros do cliente falham rápido e o número de tentativas tem limite.
  • Concorrência — max_workers está definido de forma conservadora e só é aumentado após execuções em lote limpas.
  • Timeouts — definidos explicitamente em cada requisição; não existe caminho em que uma chamada travada bloqueie uma thread de trabalho para sempre.
  • Observabilidade — uma linha de log por tentativa, com identificador do prompt, número da tentativa, status e latência; cada resultado de requisição em um lote é atribuível.
  • Artefatos de falha — guarde pelo menos uma resposta real de sucesso e uma de erro real como fixtures de teste.

Se algum item não estiver marcado, corrigir agora sai mais barato do que depurar às duas da manhã. Com o checklist todo verde, você tem um cliente pequeno, observável e extensível, em vez de um script que dá medo de tocar. Para a referência autoritativa de parâmetros e quaisquer atualizações de endpoint, favorite a documentação da HiAPI e use-a como base final.

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