API de flux-2-klein-9b: guía de curl y Python

Generar una imagen con flux-2-klein-9b en hiapi requiere una sola llamada POST /v1/tasks más sondeo: exactamente el mismo patrón de tarea asíncrona que usan todos los modelos de la plataforma. Esta guía documenta una solicitud y una respuesta reales (creación de la tarea, sondeo y URL final de la imagen), por lo que el código de abajo se puede copiar y ejecutar directamente, no es código ilustrativo.

Qué necesitas preparar

1. Una clave de API de hiapi: créala en la consola. Cada solicitud la envía como Bearer token.
2. El ID de modelo completo, incluido el sufijo del endpoint. flux-2-klein-9b solo es accesible mediante flux-2-klein-9b/text-to-image; escribir solo flux-2-klein-9b devuelve un 400 (ver más abajo).

Solicitud mínima funcional (curl)

Crear la tarea:

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": "un faro desgastado en una costa rocosa al atardecer, iluminación cinematográfica",
      "aspect_ratio": "16:9"
    }
  }'

Respuesta:

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

Sondear la tarea hasta que termine:

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

Respuesta al completarse:

{
  "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 es ese PNG. En las pruebas, la tarea tardó unos 12 segundos desde el envío hasta success. Fíjate en expireAt: antes de construir cualquier funcionalidad que dependa de que esa URL siga disponible, lee la nota sobre almacenamiento que aparece más abajo.

El mismo flujo en 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("un faro desgastado en una costa rocosa al atardecer, iluminación cinematográfica", "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}")

Los parámetros que flux-2-klein-9b valida realmente

El esquema de entrada es muy estricto: basta con enviar un campo no listado para que la API rechace toda la solicitud antes de que entre en la cola:

• prompt (cadena, obligatorio): el único campo obligatorio.
• aspect_ratio (cadena, opcional): uno de los valores 1:1, 4:3, 3:4, 16:9, 9:16. Cualquier otro valor devuelve un 400 con value must be one of ....
• seed (entero, opcional): con el mismo prompt, pasar el mismo seed permite obtener resultados reproducibles.
• output_format (cadena, opcional): uno de los valores jpeg, png, webp.

Eso es todo el esquema. No hay campos size, quality, strength ni n: enviar cualquiera de ellos falla:

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

flux-2-klein-9b solo admite texto a imagen. Tampoco acepta image_urls: para imagen a imagen, usa el ID de modelo independiente flux-2-klein-9b/image-to-image, que acepta una estructura de entrada distinta.

El ID de modelo debe incluir el sufijo del endpoint

Algunos modelos de hiapi se resuelven con el ID sin sufijo (como gpt-image-2), pero flux-2-klein-9b no es uno de ellos. Si quitas el sufijo, la tarea nunca se crea:

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

Envía siempre la cadena completa flux-2-klein-9b/text-to-image como model.

Consideraciones para producción

• Dos estructuras de error distintas. Los errores de validación (campo faltante, valor de enumeración incorrecto, clave desconocida) se devuelven con la forma de nivel superior {"code":400,"error_code":"INVALID_REQUEST","message":"..."}. Los errores de autenticación/permisos se devuelven como {"error":{"code":"permission_denied","message":"...","request_id":"..."}}, es decir, un objeto error anidado, con HTTP 401. El manejo de errores debe comprobar ambas estructuras; el código que solo comprueba resp["code"] se perderá los casos de 401.
• permission_denied se refiere a la clave, no a la solicitud. Si prompt está presente y tiene el tipo correcto pero aun así recibes un 401 permission_denied, significa que la propia clave de API no tiene habilitado este modelo: revísalo en la consola en lugar de revisar una y otra vez tu JSON.
• El almacenamiento de las salidas es temporal. storage: "temp", y cada salida lleva una marca de tiempo unix expireAt: en el ejemplo capturado, aproximadamente una semana después de la creación. Descarga el archivo o súbelo a tu propio almacenamiento en cuanto la tarea tenga éxito; no guardes la URL de temp.hiapi.ai como una dirección permanente.
• Para tareas por lotes, usa callbacks. Sondear una imagen está bien; sondear cincuenta son cincuenta idas y vueltas repetidas. En el nivel superior de la solicitud de creación, establece callback: {"url": "...", "when": "final"} para que hiapi te envíe el resultado de una sola vez cuando la tarea termine realmente. Actualmente when solo admite el valor "final".
• Reintenta antes de obtener el taskId, no después. Si el POST /v1/tasks inicial da un error de red o un 5xx, es seguro reintentar: todavía no se ha creado nada. Una vez que tengas el taskId, volver a enviar el mismo prompt crea una segunda imagen sin relación; en ese punto, sondea o espera el callback.

Contenido relacionado

• Página del modelo flux-2-klein-9b: precios actuales y zona de prueba en línea.
• Referencia de documentación de flux-2-klein-9b: la entrada de referencia específica de este modelo.
• Precios de hiapi: tarifas de los modelos del catálogo.
• Documentación de la API de tareas asíncronas: la convención completa de creación y sondeo que comparten todos los modelos de hiapi.

Preguntas frecuentes

¿Por qué recibo MODEL_UNAVAILABLE al llamar a flux-2-klein-9b? El ID de modelo necesita el sufijo del endpoint. Usa flux-2-klein-9b/text-to-image, no el flux-2-klein-9b sin sufijo.

¿Qué relaciones de aspecto admite flux-2-klein-9b? Cinco: 1:1, 4:3, 3:4, 16:9, 9:16. Cualquier otro valor devuelve un 400 con el mensaje value must be one of que enumera esos cinco valores.

¿Puedo controlar la calidad o la resolución de la salida? No: el esquema solo acepta prompt, aspect_ratio, seed y output_format. No hay parámetros size ni quality; enviar uno de ellos devuelve un error 400 de additional properties.

¿Puedo usar flux-2-klein-9b para edición de imagen a imagen? No con este ID de modelo. Usa flux-2-klein-9b/image-to-image, que tiene su propio esquema de entrada independiente.

¿Cuánto tiempo es válida la URL de salida? storage es "temp" y cada salida lleva una marca de tiempo unix expireAt, en la práctica aproximadamente una semana después. Descarga o vuelve a subir el archivo en cuanto la tarea tenga éxito; no trates la URL como una dirección permanente.

¿Por qué una clave que funciona con otros modelos devuelve 401 con este? El acceso a los modelos se concede por clave. Un 401 con error_code: "permission_denied" significa que esa clave concreta todavía no tiene autorización para flux-2-klein-9b: habilítala en la consola; no es un fallo de tu cuerpo de solicitud.