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
- 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:
modelidentifica 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/jsoninforma 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
timeoutexplí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:
- 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.
- 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.
- 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
sizee 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_workersestá 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 →-
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