---

slug: flux-2-klein-4b-text-to-image-api-guide locale: en title: Como usar flux-2-klein-4b/text-to-image com a API hiapi category: tutorial summary:

• Exemplos mínimos em curl e Python para chamar flux-2-klein-4b/text-to-image pelo endpoint unificado /v1/tasks da hiapi.
• 'Tabela completa de parâmetros: prompt, valores do enum aspect_ratio e seed — o schema estrito rejeita campos desconhecidos.'
• 'Considerações para produção: a escolha entre callback.url e 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 receber o resultado.
• aspect_ratio aceita 11 proporções nomeadas; este modelo não tem os campos size nem n.
• Reenviar a mesma Idempotency-Key em uma nova tentativa retorna o mesmo taskId — pode ser reutilizada com segurança em caso de timeout.
• Erros 400 usam error_code; erros de autenticação 401 usam o error.code aninhado — verifique primeiro o status HTTP. meta_title: Guia da API de texto para imagem flux-2-klein-4b meta_description: 'Chame flux-2-klein-4b/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 texto para imagem flux-2-klein-4b
• exemplo de api flux-2-klein-4b
• api de geração de imagens hiapi
• flux 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-4b/text-to-image com a API hiapi

O que você vai construir

Um script que envia um prompt para flux-2-klein-4b/text-to-image, aguarda a geração da imagem e então baixa a imagem — além dos detalhes de produção que você precisa conhecer antes de rodar sem supervisão (callbacks, idempotência, estruturas de erro).

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

Exemplo mínimo funcional

Os modelos generativos da hiapi rodam atrás de um único endpoint assíncrono: POST /v1/tasks cria a tarefa e retorna imediatamente um taskId; em seguida você faz polling em GET /v1/tasks/{taskId} até ela atingir um estado terminal.

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-4b/text-to-image",
    "input": {
      "prompt": "a red fox walking through fresh snow, golden hour light",
      "aspect_ratio": "16:9"
    }
  }'

Retorno:

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

Faça polling da mesma tarefa até data.status mudar de handling para success (passando brevemente por archiving):

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.jpg", "expireAt": 1785939579}
    ]
  },
  "message": "success"
}

data.output[0].url é a imagem gerada. É um link temporário — nos testes ele expira cerca de 7 dias após a geração —, então baixe os bytes da imagem e armazene por conta própria, em vez de apontar diretamente para esse endereço.

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-4b/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.jpg", "wb").write(image_bytes)

Parâmetros importantes

flux-2-klein-4b/text-to-image usa 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) é rejeitado de imediato, 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 dos valores: 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 21:9, 9:21. Quando omitido, o padrão é 1:1.
seed	Não	Inteiro. Reutilizar o mesmo seed torna os resultados de chamadas sucessivas 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 — baseie-se nela em vez de fixar números no código, pois os preços por uso mudam.

Considerações para produção

Prefira callbacks ao polling. Fora de scripts rápidos, evite o laço de polling e adicione callback.url (e "when": "final") ao corpo da requisição de criação da tarefa — ao concluir, a hiapi faz POST do resultado para o seu endpoint, com exatamente a mesma estrutura de payload retornada por GET /v1/tasks/{taskId}. Para detalhes sobre os campos de callback e a verificação de assinatura, consulte Criar tarefa.

{
  "model": "flux-2-klein-4b/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 na chamada POST /v1/tasks (até 255 bytes). Repetir a mesma requisição com a mesma key na mesma conta não cria uma segunda tarefa — você recebe de volta o taskId original. É por isso que é seguro tentar novamente requisições que expiraram do seu lado sem cobrança duplicada.

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

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

Ramifique primeiro pelo status HTTP e depois leia o campo de erro que realmente existe — não presuma que todas as falhas usam a mesma estrutura de payload.

Recursos relacionados

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

Perguntas frequentes

flux-2-klein-4b/text-to-image aceita imagem para imagem? Não diretamente — isso é outro modelo, flux-2-klein-4b/image-to-image, que tem seu próprio schema de entrada.

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

É possível solicitar várias imagens em uma única chamada? Não — o schema não aceita n nem campos de quantidade. Cada imagem exige uma requisição.

Quanto tempo vale 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 (nos testes, cerca de uma semana) e baixe os bytes da imagem imediatamente após o sucesso da tarefa, em vez de armazenar a URL.

Por que recebo o erro 401 permission_denied? Sua key está ausente, é inválida ou não tem permissão para acessar esse modelo. Confirme que você envia Authorization: Bearer sk-... e que usa uma key do console, não um placeholder.

Preciso rodar meu próprio servidor para usar esta API? Só se você precisar de callbacks. Fazer polling em GET /v1/tasks/{taskId} a partir de um script, cron job ou função serverless funciona perfeitamente em cenários de baixo tráfego; quando o volume de geração crescer, migre para callback.url.