API flux-2-klein-9b: guia com curl e Python

Gerar uma imagem com flux-2-klein-9b no hiapi exige apenas uma chamada POST /v1/tasks mais polling — exatamente o mesmo padrão de tarefa assíncrona usado por todos os modelos da plataforma. Este guia registra uma requisição e uma resposta reais (criação da tarefa, polling e URL final da imagem), então o código abaixo pode ser copiado e executado diretamente, e não é código meramente ilustrativo.

O que você precisa ter em mãos

1. Uma chave de API do hiapi — crie uma no console. Ela é enviada como Bearer token em cada requisição.
2. O ID completo do modelo, incluindo o sufixo do endpoint. flux-2-klein-9b só é acessível via flux-2-klein-9b/text-to-image — enviar apenas flux-2-klein-9b retorna 400 (veja abaixo).

Requisição mínima funcional (curl)

Crie a tarefa:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "a weathered lighthouse on a rocky coast at sunset, cinematic lighting",
      "aspect_ratio": "16:9"
    }
  }'

Resposta:

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

Faça polling da tarefa até ela concluir:

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

Resposta quando concluída:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T23CG2GNPENYQV4WEKZJTM",
    "status": "success",
    "model": "flux-2-klein-9b/text-to-image",
    "created": 1787581018,
    "completed": 1787581030,
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T23CG2GNPENYQV4WEKZJTM-0.png",
        "artifactId": "96193",
        "expireAt": 1788185830
      }
    ]
  },
  "message": "success"
}

output[0].url é o PNG em questão. No teste, a tarefa levou cerca de 12 segundos desde o envio até o status success. Observe o expireAt — antes de construir qualquer funcionalidade que dependa da disponibilidade contínua dessa URL, leia a nota sobre armazenamento abaixo.

O mesmo fluxo em Python

import time
import requests

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


def create_image(prompt: str, aspect_ratio: str = "1:1") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "flux-2-klein-9b/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio},
        },
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_image(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image("a weathered lighthouse on a rocky coast at sunset, cinematic lighting", "16:9")
    image_url = wait_for_image(task_id)
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print(f"saved output.png from task {task_id}")

Os parâmetros que o flux-2-klein-9b realmente valida

O schema de entrada é bastante estrito — se algum campo não listado for enviado, a API rejeita a requisição inteira antes mesmo de ela entrar na fila:

• prompt (string, obrigatório) — o único campo obrigatório.
• aspect_ratio (string, opcional) — um de 1:1, 4:3, 3:4, 16:9, 9:16. Qualquer outro valor retorna 400 com value must be one of ....
• seed (inteiro, opcional) — passar o mesmo seed com o mesmo prompt produz resultados reproduzíveis.
• output_format (string, opcional) — um de jpeg, png, webp.

Esse é todo o schema. Não há campos size, quality, strength ou n — enviar qualquer um deles falha:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'size' not allowed"}

O flux-2-klein-9b suporta apenas texto para imagem. Ele também não aceita image_urls — para imagem para imagem, use o ID de modelo separado flux-2-klein-9b/image-to-image, que aceita uma estrutura de entrada diferente.

O ID do modelo precisa incluir o sufixo do endpoint

Alguns modelos no hiapi podem ser resolvidos pelo ID puro (como gpt-image-2), mas o flux-2-klein-9b não é um deles. Sem o sufixo, a tarefa nunca é criada:

{"code":400,"data":null,"error_code":"MODEL_UNAVAILABLE","message":"model not available via /v1/tasks"}

Sempre envie a string completa flux-2-klein-9b/text-to-image como model.

Considerações para produção

• Duas estruturas de erro diferentes. Erros de validação (campo ausente, valor de enum inválido, chave desconhecida) retornam no formato de nível superior {"code":400,"error_code":"INVALID_REQUEST","message":"..."}. Erros de autenticação/permissão retornam como {"error":{"code":"permission_denied","message":"...","request_id":"..."}} — um objeto error aninhado, com HTTP 401. O tratamento de erros deve verificar ambas as estruturas; código que só verifica resp["code"] deixará passar os casos de 401.
• permission_denied refere-se à chave, não à requisição. Se o prompt existe e está com o tipo correto, mas você ainda recebe 401 permission_denied, significa que a própria chave de API não tem esse modelo habilitado — verifique no console em vez de revisar seu JSON repetidamente.
• O armazenamento das saídas é temporário. storage: "temp", e cada saída traz um timestamp unix expireAt — no exemplo capturado, cerca de uma semana após a criação. Baixe o arquivo ou envie-o para o seu próprio armazenamento imediatamente após a tarefa concluir; não guarde a URL de temp.hiapi.ai como endereço permanente.
• Para tarefas em lote, use callback. Fazer polling de uma imagem não é problema; fazer polling de cinquenta são cinquenta idas e voltas repetidas. Defina callback: {"url": "...", "when": "final"} no nível superior da requisição de criação para que o hiapi envie o resultado de uma vez quando a tarefa realmente concluir. Atualmente when só aceita o valor "final".
• Repita a tentativa antes de obter o taskId, não depois. Erros de rede ou 5xx no POST /v1/tasks inicial podem ser repetidos com segurança — nada foi criado ainda. Depois de obter o taskId, reenviar o mesmo prompt cria uma segunda imagem não relacionada; nesse momento, faça polling ou aguarde o callback.

Conteúdo relacionado

• Página do modelo flux-2-klein-9b — preços atuais e área de teste online.
• Referência de documentação do flux-2-klein-9b — a entrada de referência específica deste modelo.
• Preços do hiapi — tarifas dos modelos do catálogo.
• Documentação da API de tarefas assíncronas — o contrato completo de criação/polling compartilhado por todos os modelos do hiapi.

Perguntas frequentes

Por que recebo MODEL_UNAVAILABLE ao chamar flux-2-klein-9b? O ID do modelo precisa incluir o sufixo do endpoint. Use flux-2-klein-9b/text-to-image, e não o flux-2-klein-9b puro.

Quais proporções o flux-2-klein-9b suporta? Cinco: 1:1, 4:3, 3:4, 16:9, 9:16. Qualquer outro valor retorna 400 com a mensagem value must be one of listando esses cinco valores.

Posso controlar a qualidade ou a resolução da saída? Não — o schema aceita apenas prompt, aspect_ratio, seed e output_format. Não há parâmetros size ou quality; enviar um deles retorna um erro 400 de additional properties.

Posso fazer edição de imagem para imagem com o flux-2-klein-9b? Não com este ID de modelo. Use flux-2-klein-9b/image-to-image, que tem seu próprio schema de entrada independente.

Por quanto tempo a URL de saída é válida? storage é "temp", e cada saída traz um timestamp unix expireAt, na prática cerca de uma semana depois. Baixe ou reenvie o arquivo imediatamente após a tarefa concluir — não trate a URL como endereço permanente.

Por que uma chave que funciona em outros modelos retorna 401 neste modelo? O acesso ao modelo é concedido por chave. Um 401 com error_code: "permission_denied" significa que essa chave específica ainda não foi autorizada para flux-2-klein-9b — habilite-a no console; não é um bug no corpo da sua requisição.