Tutorial
Como usar o flux-3 pela API da HiAPI: curl, Python e exemplos de requisição executáveis
Nesta página
O que você ganha ao usar o flux-3 pela HiAPI
O flux-3 é um modelo de geração de imagens que lida tanto com texto para imagem quanto com imagem para imagem. Se você está construindo funcionalidades de produto, ferramentas de design ou pipelines internos, a parte realmente interessante muitas vezes não é o modelo em si — mas sim a limpeza com que você consegue colocá-lo por trás de uma interface estável e previsível, e manter esse estado quando os requisitos mudam.
É exatamente aí que reside o valor de uma plataforma de API agregadora. Chamar o flux-3 pela HiAPI significa que você:
- Integra apenas uma vez. Uma única URL base, uma única forma de autenticação e uma estrutura de requisição e resposta consistente entre os modelos que você usa. Depois, trocar ou comparar modelos é só mudar configuração, não reescrever código.
- Elimina o trabalho de infraestrutura. Sem hospedar modelos, sem planejar capacidade de GPU, sem gerenciar cold start do seu lado. Você envia uma requisição HTTP e trata a resposta.
- Centraliza as credenciais. Uma única API key para emitir, rotacionar e restringir permissões, em vez de estabelecer relacionamento separado com cada provedor upstream.
- Obtém semântica de erro unificada. Independentemente do modelo por trás da chamada, os códigos de status e os envelopes de erro são os mesmos, o que permite reutilizar a lógica de retry e de alerta.
Especificamente com o flux-3, isso significa que você pode migrar de um protótipo no notebook direto para um endpoint de produção sem mudar a estrutura do código cliente. Os dois modos de geração — texto para imagem e imagem para imagem — compartilham a mesma estrutura de requisição, de modo que suportar ambos depende apenas de quais campos você preenche, e não de qual SDK você importa.
Ao longo deste artigo, adotamos as seguintes convenções:
- URL base: o endpoint da API da HiAPI registrado no console da sua conta.
- Autenticação: um bearer token no cabeçalho
Authorization. - Tipo de conteúdo: o corpo da requisição usa
application/json; as imagens de entrada, conforme o limite de tamanho do seu payload, são fornecidas como URL ou como dados codificados em base64.
Mantenha as chaves em variáveis de ambiente — nunca as versione no controle de código. Os exemplos abaixo leem a chave de HIAPI_API_KEY e o identificador do modelo de FLUX_MODEL, para que você ajuste sem modificar o código.
Feita a preparação, a próxima seção detalha o corpo da requisição em si.
Anatomia da requisição: texto para imagem e imagem para imagem
Uma chamada ao flux-3 se divide logicamente em três partes: o caminho do endpoint, o cabeçalho de autenticação e um corpo JSON. É no corpo que os dois modos divergem; entender essa diferença permite que um único cliente sirva para ambos.
Estrutura compartilhada
Toda requisição contém, em alguma forma, os seguintes campos:
- model — o modelo a chamar; aqui, o seu identificador do flux-3.
- input — o objeto que carrega as instruções de geração.
- input.prompt — descreve em linguagem natural o que você quer. Obrigatório nos dois modos.
- Configurações opcionais de geração — como tamanho de saída, proporção ou número de passos, conforme as capacidades expostas pelo modelo. Defina apenas o que precisar; os valores padrão costumam ser razoáveis.
- Controles opcionais de assincronia — flags ou callbacks que alteram como a tarefa é executada e entregue (detalhados na próxima seção).
Texto para imagem
No modo texto para imagem, prompt é o único campo substancial. Você descreve a imagem, opcionalmente restringe a geometria da saída e envia. Não há imagem de origem, então o modelo tem liberdade máxima — o que também significa que a qualidade do prompt domina a qualidade da saída.
Um hábito útil: escreva o prompt como se estivesse briefando um ilustrador humano. Ordene por assunto, composição, iluminação, estilo e quaisquer restrições rígidas (como "sem texto na imagem" ou "assunto centralizado"). Prompts vagos produzem resultados medíocres, não importa quantos passos você use.
Imagem para imagem
No modo imagem para imagem, você adiciona um campo de imagem de origem além do prompt; agora o prompt descreve a transformação em relação a essa entrada, em vez de uma cena construída do zero. Dependendo da interface do modelo, isso pode significar fornecer uma URL de imagem ou um payload de imagem codificado, além de quaisquer parâmetros de intensidade ou de orientação que controlem o quanto a saída se afasta da imagem de origem.
Para o seu cliente de API, o impacto prático é mínimo: mesmo endpoint, mesma autenticação, mesmo objeto input — apenas um campo a mais. Esse é justamente o objetivo do design. Sua função generate() deve aceitar uma imagem de origem opcional e tratar a ramificação internamente, para que quem chama nunca precise saber qual modo disparou.
Estrutura da resposta
A resposta deve conter um identificador de tarefa e, quando concluída, a localização da imagem gerada. Trate essa localização como um valor opaco: pode buscá-la ou armazená-la, mas não faça suposições sobre o conteúdo dela. Algumas respostas retornam imediatamente, outras são um handle de tarefa — e é exatamente por isso que o tratamento assíncrono precisa estar no design desde o primeiro dia.
Parâmetros e o modo assíncrono
Escolhendo as configurações de geração
Configurações de geração são um trade-off entre qualidade, latência e custo. Alguns princípios valem para a maioria dos modelos de imagem, incluindo o flux-3:
- Resolução e proporção afetam tanto a utilidade da saída quanto o consumo computacional. Gere no tamanho em que você realmente entrega; reduzir uma imagem grande desperdiça orçamento, e ampliar uma pequena desperdiça renderização.
- Passos ou controle de qualidade aumentam a fidelidade até certo ponto e depois estabilizam. Meça com um prompt fixo para encontrar esse ponto de inflexão e pare ali.
- Controle de determinismo (se disponível) é importante para reprodutibilidade. Se você precisa re-renderizar o mesmo resultado para QA ou suporte ao usuário, registre as configurações junto com a saída.
Não adivinhe nomes de parâmetros nem intervalos aceitáveis — leia a documentação do modelo no console e use-a como fonte de verdade. Se um campo for rejeitado, a resposta de erro dirá exatamente qual.
Síncrono vs. assíncrono
Geração de imagens não é uma operação instantânea. Há dois modos de execução:
Síncrono (bloqueante). Você envia a requisição e mantém a conexão até a imagem ficar pronta. É simples, adequado para tarefas curtas, scripts e ferramentas interativas em que o usuário observa um indicador de carregamento. Mas também é frágil: funções serverless, balanceadores de carga e clientes móveis têm limites de timeout, e renderizações longas inevitavelmente esbarram em um deles.
Assíncrono (baseado em tarefas). Você envia a requisição, recebe imediatamente um identificador e então consulta o endpoint de status ou recebe um callback até a tarefa reportar conclusão. Escolha esse modo quando:
- Houver runtimes serverless e de borda com limites rígidos de tempo de execução.
- For um processamento em lote que precisa enviar muitos renders em paralelo.
- Qualquer fluxo de interação com o usuário em que você quer devolver o controle imediatamente e transmitir o progresso.
Projete o cliente em torno do assíncrono e envolva os casos simples em um método de conveniência síncrono. Fazer o contrário — enfiar o assíncrono à força num cliente bloqueante — raramente termina bem.
Ao consultar o status, use backoff exponencial com limite em vez de um loop fixo e apertado, defina um teto de tempo total de espera e trate tarefas que nunca chegam a um estado terminal como um erro que merece alerta.
Uma requisição curl executável
Comece pelo terminal; uma vez que a troca HTTP bruta esteja clara, a versão em código fica simples.
1. Configure o ambiente
export HIAPI_API_KEY="your-key-here"
export FLUX_MODEL="your-flux-3-model-id"
export HIAPI_BASE="https://your-hiapi-endpoint"
Coloque o identificador do modelo em uma variável — trocar de modelo depois é só mudar uma linha.
2. Envie uma requisição de texto para imagem
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "A minimal studio photograph of a ceramic mug on a concrete surface, soft side light, shallow depth of field"
}
}'
A flag -sS mantém a saída limpa e ainda mostra erros. Antes de executar, confirme o caminho exato contra o endpoint registrado no console — os caminhos têm versão, então use a documentação como fonte de verdade.
3. Leia o retorno
Passe a resposta por um formatador para torná-la legível:
... | python -m json.tool
Preste atenção em dois pontos: o identificador da tarefa e a localização da imagem ou o campo de status que indica que a tarefa ainda está em execução. Se você vê um status em vez de uma imagem, está no caminho assíncrono — anote o identificador e passe para a consulta periódica.
4. Experimente imagem para imagem
Adicione a imagem de origem ao objeto input e mantenha o resto igual:
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "Reinterpret as a watercolor painting, keep the composition and shadows intact",
"image": "https://example.com/source.jpg"
}
}'
Como as requisições diferem em apenas um campo, sua primeira chamada bem-sucedida já validou a maior parte da integração. O resto — retries, armazenamento, UI — é trabalho comum de aplicação.
A mesma requisição em Python
A chamada curl pode ser traduzida diretamente. Abaixo está um cliente pequeno e reutilizável, em vez de um script descartável.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE"]
MODEL = os.environ["FLUX_MODEL"]
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
def generate(prompt, image=None, timeout=60):
"""Submit a flux-3 generation job. Pass image= for image-to-image."""
payload = {"model": MODEL, "input": {"prompt": prompt}}
if image:
payload["input"]["image"] = image
resp = requests.post(
f"{BASE}/v1/images/generations",
headers=HEADERS,
json=payload,
timeout=timeout,
)
resp.raise_for_status()
return resp.json()
Algumas escolhas intencionais:
- Uma função, dois modos. O parâmetro
imagealterna o comportamento, sem ramificação para quem chama. - Timeout explícito. O padrão do
requests— espera infinita — é exatamente o que trava um pool de threads de trabalho. raise_for_status(). Faz as falhas da camada HTTP surgirem como exceção, para você capturá-las em um único lugar.
Adicionando um helper de consulta periódica
Quando a resposta traz um identificador de tarefa em vez da imagem pronta, espere por ele:
def wait_for(job_id, timeout=300, initial=1.0, factor=1.6, cap=15.0):
deadline = time.monotonic() + timeout
delay = initial
while time.monotonic() < deadline:
r = requests.get(
f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30
)
r.raise_for_status()
data = r.json()
if data.get("status") in ("succeeded", "failed"):
return data
time.sleep(delay)
delay = min(delay * factor, cap)
raise TimeoutError(f"job {job_id} did not finish in {timeout}s")
Ajuste o nome do campo de status conforme a estrutura de resposta documentada. A estrutura em si — backoff com limite, prazo máximo, verificação de estado terminal — é o que importa e se aplica sem alterações quando você troca de modelo.
Juntando tudo
if __name__ == "__main__":
result = generate(
"A minimal studio photograph of a ceramic mug, soft side light"
)
if "id" in result and not result.get("output"):
result = wait_for(result["id"])
print(result)
Em seguida, envolva generate com sua própria camada de retry e logging, e a integração estará pronta para produção.
Controle de custos e erros comuns
Mantenha os gastos previsíveis
A geração de imagens é cobrada por requisição, com valor que depende do modelo e das configurações — consulte o painel de preços ao vivo no console em vez de codificar suposições. A disciplina de engenharia é o que protege o orçamento:
- Defina limites por usuário e por tarefa no seu próprio código. A plataforma aplica limites no nível da conta; seu aplicativo deve aplicar limites no nível do produto, para que um único cliente descontrolado não esgote a conta.
- Faça cache agressivamente. Calcule o hash do prompt normalizado mais as configurações e reutilize saídas já armazenadas. Requisições idênticas são comuns em editores e cenários de pré-visualização.
- Gere na resolução de entrega. Renderize no tamanho em que vai exibir; evite o padrão caro de "renderizar grande e reduzir depois".
- Coloque a regeneração atrás de uma ação explícita do usuário. Regenerar automaticamente a cada tecla digitada no campo de prompt é o multiplicador de custo acidental mais comum.
- Registre o modelo, as configurações e a latência de cada chamada. Sem isso, você não consegue saber qual funcionalidade custa caro.
- Valide a entrada antes de enviar. Rejeite prompts vazios ou excessivamente longos no cliente, para nunca pagar por requisições fadadas ao fracasso.
Depurando as falhas que você realmente vai encontrar
Percorra a lista abaixo em ordem; ela resolve a maioria dos incidentes.
- 401 / 403 — autenticação. A chave foi carregada no ambiente em que a requisição realmente roda? Uma chave disponível no seu shell pode não existir no contêiner. Confirme que o prefixo
Bearere o nome do cabeçalho estão exatamente corretos. - 404 — caminho ou modelo errado. Caminhos versionados e identificadores de modelo mudam. Compare caractere por caractere com o endpoint documentado.
- 422 / 400 — payload rejeitado. O corpo do erro indica o campo problemático. Suspeitos comuns: tipo errado,
promptausente ou parâmetro não suportado. Remova as configurações opcionais e reenvie para isolar o problema. - 429 — rate limit acionado. Faça backoff com jitter e tente de novo; não repita imediatamente em loop. Distinga de esgotamento de cota no nível da conta, caso em que repetir não adianta.
- Timeout. Se a requisição demora demais, você está bloqueando onde deveria consultar periodicamente. Mude para o fluxo assíncrono e defina timeouts de cliente conscientemente.
- Tarefa presa em pending. Consulte com prazo limite e trate o timeout como falha que gera alerta, não como espera infinita.
Um hábito amarra a lista inteira: registre o corpo completo do erro, não apenas o código de status. O corpo do erro normalmente diz exatamente qual campo ou limite falhou, o que transforma meia hora de investigação em uma correção de uma linha.
Faça a chamada curl funcionar, porte para o cliente acima, centralize a consulta periódica e o tratamento de erros em um único lugar — o resto da integração é código comum de aplicação. Para as capacidades atuais do modelo e os preços, consulte a documentação do flux-3 e o painel de preços no console da HiAPI.
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