---

slug: flux-2-klein-9b-text-to-image-api-guide locale: en title: Como usar flux-2-klein-9b/text-to-image através da API hiapi category: tutorial summary:

• Exemplo mínimo em curl e Python para chamar flux-2-klein-9b/text-to-image através do endpoint unificado /v1/tasks da hiapi.
• 'Tabela completa de parâmetros: prompt, aspect_ratio, num_inference_steps, output_format e seed — o schema estrito rejeita campos desconhecidos.'
• 'Considerações de produção: callback.url versus polling, o cabeçalho Idempotency-Key e as duas estruturas de resposta de erro. takeaways:
• Crie uma tarefa com POST /v1/tasks e depois faça polling em GET /v1/tasks/{taskId} ou use callback.url para obter o resultado.
• num_inference_steps aceita apenas 4-8 (inteiro); este modelo não possui os campos size ou n.
• Reutilizar o mesmo cabeçalho Idempotency-Key ao tentar novamente retorna o mesmo taskId — seguro de reutilizar em caso de timeout.
• Erros 400 usam error_code; erros de autenticação 401 usam o error.code aninhado — verifique primeiro o código de status HTTP. meta_title: Guia da API de geração de imagem a partir de texto flux-2-klein-9b meta_description: Chame flux-2-klein-9b/text-to-image com curl e Python; crie tarefas, faça polling da imagem e trate callbacks, idempotência e erros em produção. keywords:
• api de geração de imagem a partir de texto flux-2-klein-9b
• exemplo de api flux-2-klein-9b
• api de geração de imagens hiapi
• flux klein api curl python tags:
• api-guide
• image-generation
• flux author_name: hiapi is_published: false cover_image: https://static.hiapi.ai/blog/_default/recipe-cover.jpg

---

Como usar flux-2-klein-9b/text-to-image através da API hiapi

O que você vai construir

Um script que envia um prompt para flux-2-klein-9b/text-to-image, aguarda a conclusão da geração da imagem e a baixa — além dos detalhes de produção necessários antes de uma execução não assistida (callbacks, idempotência, estruturas de erro).

Pré-requisitos: obtenha uma chave de API no console da hiapi. Todas as requisições abaixo se autenticam com Authorization: Bearer sk-<your-api-key>.

Exemplo mínimo executável

Os modelos de geração da hiapi rodam atrás de um endpoint assíncrono unificado: POST /v1/tasks cria uma tarefa e retorna imediatamente um taskId; em seguida, você faz polling em GET /v1/tasks/{taskId} até que ela atinja um estado final.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "a red fox walking through fresh snow, golden hour light",
      "aspect_ratio": "16:9"
    }
  }'

Resultado retornado:

{"code": 200, "data": {"taskId": "tk-hiapi-01K..."}, "message": "success"}

Faça polling na mesma tarefa até que data.status passe de handling para success (passando brevemente por archiving no meio):

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01K... \
  -H "Authorization: Bearer sk-<your-api-key>"

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../01K...-0.png", "expireAt": 1785941465}
    ]
  },
  "message": "success"
}

data.output[0].url é a imagem gerada. É um link temporário — nos testes, expira cerca de 7 dias após a geração — portanto baixe os bytes e armazene-os você mesmo, em vez de vincular diretamente a ele.

O mesmo fluxo em Python (com polling)

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE = "https://api.hiapi.ai/v1"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(f"{BASE}/tasks", headers=headers, json={
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
        "prompt": "a red fox walking through fresh snow, golden hour light",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{BASE}/tasks/{task_id}", headers=headers).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "failed":
        raise RuntimeError(f"generation failed: {task}")
    time.sleep(3)

image_bytes = requests.get(image_url).content
open("fox.png", "wb").write(image_bytes)

Parâmetros importantes

flux-2-klein-9b/text-to-image tem um schema de entrada estrito — enviar campos que ele não reconhece (size, n, negative_prompt ou qualquer outro campo aceito por outros modelos de imagem da hiapi) será rejeitado diretamente, portanto não copie parâmetros entre modelos sem antes consultar a página do modelo.

Campo	Obrigatório	Descrição
prompt	Sim	String que descreve a imagem.
aspect_ratio	Não	Um de 1:1, 4:3, 3:4, 16:9, 9:16. Padrão 4:3 quando omitido.
num_inference_steps	Não	Inteiro, 4–8. Padrão 4; valores maiores trocam velocidade por um pouco mais de detalhe.
output_format	Não	Um de jpeg, png, webp. Padrão png.
seed	Não	Inteiro. Reutilizar o seed torna os resultados de chamadas repetidas reproduzíveis.

A referência completa de parâmetros está na página do modelo; o preço atual por imagem está na página de preços — consulte lá em vez de codificar números fixos, pois as tarifas baseadas em uso mudam.

Considerações para produção

Use callbacks em vez de polling. Para qualquer cenário além de scripts rápidos, pule o loop de polling e adicione callback.url (e "when": "final") ao corpo da requisição de criação da tarefa — a hiapi fará POST do resultado para o seu endpoint quando a tarefa for concluída, com uma estrutura de payload idêntica à retornada por GET /v1/tasks/{taskId}. Para detalhes sobre os campos de callback e verificação de assinatura, consulte Criar tarefa.

{
  "model": "flux-2-klein-9b/text-to-image",
  "callback": {"url": "https://yourapp.com/hooks/hiapi", "when": "final"},
  "input": {"prompt": "a red fox walking through fresh snow, golden hour light"}
}

Idempotência. Defina o cabeçalho Idempotency-Key nas chamadas de POST /v1/tasks (máximo de 255 bytes). Repetir a mesma requisição com a mesma chave na mesma conta não cria uma segunda tarefa — você recebe de volta o taskId original. É justamente isso que torna seguro tentar novamente uma requisição que deu timeout do seu lado sem cobrança duplicada.

Tratamento de erros. Na prática, existem duas estruturas de falha diferentes, portanto verifique ambas:

• input inválido (prompt ausente, num_inference_steps fora do intervalo, campos não suportados) retorna HTTP 400 e {"error_code": "INVALID_REQUEST", "message": "..."}.
• Chave de API inválida ou não autorizada retorna HTTP 401, com uma estrutura de resposta diferente: {"error": {"code": "permission_denied", "message": "...", "request_id": "..."}}.

Primeiro ramifique pelo código de status HTTP, depois leia o campo de erro que realmente existe — não presuma que todas as falhas usam a mesma estrutura de resposta.

Recursos relacionados

• Obter detalhes da tarefa — referência completa de polling
• Autenticação — escopos de chave de API e formato dos cabeçalhos
• flux-2-klein-9b/image-to-image — mesma família, edita uma imagem de entrada em vez de gerar do zero
• flux-2-klein-4b/text-to-image — modelo menor e mais rápido da mesma família klein

Perguntas frequentes

flux-2-klein-9b/text-to-image suporta imagem para imagem? Não diretamente — isso é um modelo separado, flux-2-klein-9b/image-to-image, com seu próprio schema de entrada.

Qual é a diferença entre flux-2-klein-9b e flux-2-klein-4b? Ambos são endpoints de geração de imagem a partir de texto da mesma família FLUX.2 [klein]; o 9b é o maior dos dois, projetado para maior realismo, renderização de texto e detalhes. Antes de trocar, consulte a página do modelo 4b para ver seu preço e parâmetros atuais.

É possível solicitar várias imagens em uma única chamada? Não — o schema não aceita n ou campos de contagem. Envie uma requisição por imagem.

Quanto tempo dura a URL da imagem retornada? output[0].url é um link temporário com seu próprio timestamp expireAt; trate-o como de curta duração (cerca de uma semana nos testes) e baixe os bytes imediatamente após o sucesso da tarefa, em vez de armazenar a URL.

Por que recebo o erro 401 permission_denied? Sua chave está ausente, inválida ou não tem permissão para acessar este modelo. Confirme que você está enviando Authorization: Bearer sk-... com a chave do console, e não o placeholder.

É necessário rodar meu próprio servidor para usar esta API? Somente se você precisar de callbacks. Fazer polling em GET /v1/tasks/{taskId} a partir de um script, tarefa agendada ou função serverless funciona perfeitamente para baixo volume; quando a escala de geração aumentar, mude para callback.url.