Tutorial

Cómo usar la API de texto a imagen krea-2-medium-turbo (curl + Python)

Oct 21, 2026

krea-2-medium-turbo es el nivel rápido y de bajo costo de texto a imagen que Krea ofrece en hiapi. Solo tienes que enviar un prompt, elegir una relación de aspecto y obtener una imagen renderizada a través de la API de tareas asíncrona. Esta guía proporciona ejemplos de solicitudes curl y Python listos para copiar y pegar dirigidos a /v1/tasks, junto con el esquema de entrada exacto, y los tiempos y comportamientos de error que medí en vivo el 2026-10-21 — uno de esos resultados contradice lo que dice la documentación.

Requisitos previos

Una clave de API de hiapi (sk-...). Créala en la consola de API Keys. Cada solicitud se autentica con Authorization: Bearer sk-<your-key>. Ese es el único requisito: el modelo se ejecuta del lado del servidor, así que no necesitas instalar nada más allá de un cliente HTTP.

Esquema de entrada

krea-2-medium-turbo acepta cinco campos. Solo prompt y model son obligatorios:

Campo	Obligatorio	Tipo	Por defecto	Descripción
`model`	Sí	string	—	Debe ser exactamente `krea-2-medium-turbo`.
`prompt`	Sí	string	—	De 1 a 5000 caracteres.
`aspect_ratio`	No	enum	`1:1`	Uno de `1:1`, `4:3`, `3:2`, `16:9`, `2.35:1`, `4:5`, `2:3`, `9:16`.
`creativity`	No	enum	`low`	`raw` (lo más literal) → `low` → `medium` → `high` (lo más creativo).
`seed`	No	integer	—	Opcional. Lee la advertencia sobre seed más abajo antes de confiar en él.

El objeto input es estricto (additionalProperties: false): cualquier campo que no esté en esta tabla se rechaza antes de que comience la generación. No hay n / num_images, ni resolution o size, ni campo de prompt negativo. Una solicitud devuelve exactamente una imagen, y el tamaño de salida lo determina por completo aspect_ratio. Si has usado otras APIs de imagen en hiapi que aceptan resolution (Seedream, Qwen-Image) o size, elimina esos campos aquí — devolverán 400.

Solicitud mínima funcional (curl)

Crear la tarea devuelve un taskId inmediatamente; la imagen se renderiza en segundo plano.

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2-medium-turbo",
    "input": {
      "prompt": "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
      "aspect_ratio": "2.35:1",
      "creativity": "medium",
      "seed": 42
    }
  }'

Respuesta:

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

Luego consulta la tarea por id hasta que alcance un estado terminal:

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

Una tarea completada se ve así (campos recortados por claridad):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A",
    "model": "krea-2-medium-turbo",
    "status": "success",
    "storage": "temp",
    "created": 1792549655,
    "completed": 1792549681,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/xxxxxxxx/01M5E4J4FQVJNSDKQ29BRSMD0A-0.png",
        "artifactId": "280334",
        "expireAt": 1793154481
      }
    ]
  },
  "message": "success"
}

La imagen está en data.output[0].url.

El mismo flujo en Python

import time
import requests

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

def generate(prompt, aspect_ratio="1:1", creativity="low", seed=None):
    body = {
        "model": "krea-2-medium-turbo",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "creativity": creativity},
    }
    if seed is not None:
        body["input"]["seed"] = seed

    created = requests.post(API, headers=HEADERS, json=body, timeout=30)
    created.raise_for_status()
    task_id = created.json()["data"]["taskId"]

    # Consulta hasta que la tarea alcance un estado terminal.
    while True:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":                 # Nota: sigue siendo HTTP 200, ver abajo
            raise RuntimeError(f"generation failed: {data}")
        time.sleep(3)

url = generate(
    "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
    aspect_ratio="2.35:1",
    creativity="medium",
)
print(url)

Consideraciones para producción

Consulta periódicamente o usa un callback. El bucle anterior consulta cada 3 segundos, lo cual está bien para un volumen bajo de concurrencia. En producción, adjunta callback.url con when: "final" al crear la solicitud y deja que hiapi te envíe por POST la tarea completada en lugar de consultar — consulta la documentación de la API de tareas para el contrato de callback.
Una generación fallida sigue devolviendo HTTP 200. El código de estado HTTP en el endpoint de consulta indica si la solicitud tuvo éxito, no si la imagen lo tuvo. Un fallo de renderizado se devuelve con 200 y data.status: "fail". Bifurca según data.status, no según el código de estado HTTP, o tratarás los fallos como éxitos.
Las URL de salida son temporales. Los resultados se almacenan en temp.hiapi.ai bajo "storage": "temp" con una marca de tiempo expireAt, y caducan en aproximadamente siete días (604,800 segundos en mi ejecución). Descarga los bytes y vuelve a alojarlos (tu propio bucket/CDN) en cuanto la tarea se complete — no enlaces en caliente directamente las URL de temp.hiapi.ai en páginas de producción.
El precio es una tarifa fija única por imagen, independientemente de la relación de aspecto o del nivel de creatividad — no hay niveles de resolución que considerar. Consulta las cifras actuales en la página de precios en lugar de codificarlas de forma fija.

Lo que probé realmente (2026-10-21)

Todo lo siguiente proviene de llamadas en vivo, no de la documentación:

Tiempos y resolución. Una solicitud 2.35:1 se completó en unos 26 segundos (la diferencia created → completed), y el PNG devuelto era de 1568 × 672 px — así que 2.35:1 es de verdad un recorte panorámico cinematográfico, no algo casi cuadrado. La tarea pasa por los estados intermedios handling → archiving → success mientras se renderiza y el archivo se mueve al almacenamiento temporal.
La validación de enum se aplica del lado del servidor. Enviar "aspect_ratio": "21:9" (un valor plausible pero no admitido) devuelve inmediatamente 400: invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:2', '16:9', '2.35:1', '4:5', '2:3', '9:16'. El mensaje de error nombra el campo y enumera los valores legales, lo que facilita el manejo programático.
Los campos desconocidos devuelven 400, no se ignoran. "resolution": "2K" devuelve invalid input: <root>: additional properties 'resolution' not allowed; "n": 2 devuelve el mismo error para n. Esa es la regla additionalProperties: false en acción — copiar un cuerpo de solicitud de otro modelo con campos sobrantes bloquea toda la llamada.
En mis pruebas, seed no reprodujo la misma imagen exacta. Envié dos veces seguidas el mismo prompt, seed: 42, aspect_ratio: 2.35:1 y creativity: medium. Ambas devolvieron una imagen válida de 1568 × 672, pero eran escenas claramente diferentes (una torre blanca frente a una torre con franjas rojas y blancas), con tamaños de archivo distintos (1.30 MB frente a 1.51 MB) y hashes distintos. El campo se acepta y la documentación lo describe como reproducible, pero considera la reproducción exacta de píxeles como un mejor esfuerzo y no una garantía — si necesitas una imagen concreta, guarda el resultado que obtengas en lugar de volver a solicitarla con seed.

Páginas relacionadas

Página del modelo krea-2-medium-turbo — playground en línea y referencia completa de parámetros.
Documentación de la API de krea-2-medium-turbo — detalles de endpoints y callbacks.
Krea 3 texto a imagen — el nivel de Krea más reciente y orientado a la calidad (con modos berry/jam); úsalo cuando quieras más detalle, y usa krea-2-medium-turbo cuando quieras velocidad y bajo costo.
APIs de generación de imágenes con IA en hiapi — otros modelos de texto a imagen detrás de la misma interfaz de tareas.

FAQ

¿Qué relaciones de aspecto puedo solicitar? Ocho: 1:1 (por defecto), 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3 y 9:16. Cualquier otro valor devuelve 400.

¿Puede una sola llamada generar varias imágenes? No. No hay campo n, y el esquema rechaza propiedades desconocidas, así que cada solicitud genera exactamente una imagen. Para generar por lotes, envía solicitudes en bucle (opcionalmente con seeds distintas).

¿Qué hace creativity? Controla cuán literalmente sigue el modelo el prompt: raw es lo más fiel a la redacción, high otorga la mayor libertad de interpretación, y low (por defecto) y medium quedan entre ambos.

¿krea-2-medium-turbo admite imagen a imagen o edición? No — solo admite texto a imagen. El esquema no tiene image_urls ni campo de imagen de entrada. Si necesitas transformar una imagen existente, usa un modelo dedicado de edición/imagen a imagen en hiapi.

¿Cuánto duran las URL de salida? Se sirven desde almacenamiento temporal y caducan (en mis pruebas, alrededor de siete días después). Descarga y vuelve a alojar la imagen en cuanto la tarea se complete.