¿Cómo usar la API de Recraft V4.1? Genera imágenes con paleta de colores en 5 minutos

TL;DR

• La serie Recraft V4.1 es un par de modelos de texto a imagen con parámetros idénticos: recraft-v4.1/text-to-image produce el resultado final con más detalle ($0.05/imagen), recraft-v4.1-flash/text-to-image para borradores rápidos ($0.01/imagen, consulta la página de precios para el detalle completo); solo difieren en el campo model. Abre la página del modelo para probarlo; los nuevos usuarios reciben 200 créditos al registrarse.
• Su característica destacada es la paleta de marca: pasa un conjunto de valores RGB en colors y la imagen se ajustará lo máximo posible a esos colores (no disponible en Playground, solo vía API).
• La llamada se hace a través de la interfaz /v1/tasks de HiAPI: envía la tarea y obtén el taskId, luego consulta el resultado y, tras el éxito, descarga desde output[0].url.

Qué puede hacer

• Fotografía, ilustración y carteles: imágenes de producto realistas, ilustraciones vectoriales planas o carteles con titular, todo con una sola descripción.
• Color controlable: colors define la paleta y background_color el color de fondo, ideal para material de marca alineado con la identidad visual.
• 6 tamaños predefinidos: square_hd (predeterminado), square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9; no hay ancho y alto personalizados.
• Flash para pruebas + V4.1 para el resultado final: mismos parámetros, solo cambia model; 10 borradores más 1 final cuestan $0.15.

Aquí tienes un resultado real de V4.1:

Minimalist brand poster for a specialty coffee brand, huge bold headline "NORTH BEAN" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout

(Significado: cartel minimalista de marca para una cafetería de especialidad, enorme titular en negrita sans-serif "NORTH BEAN", paleta de terracota cálido y crema, ilustración de un solo grano de café, mucho espacio negativo, maquetación en cuadrícula suiza. Tamaño: portrait_4_3.)

recraft-v4.1/text-to-image, portrait_4_3, imagen de ejemplo de este artículo 896×1216, $0.05.

Generar con este prompt →

Cómo elegir entre los dos modelos

	recraft-v4.1-flash/text-to-image	recraft-v4.1/text-to-image
Por imagen	$0.01	$0.05
Enfoque	Borradores rápidos, elegir dirección	Resultado final con más detalle
Parámetros	Idénticos (prompt / image_size / colors / background_color)	Igual que a la izquierda
Ideal para	Exploración masiva, imágenes para redes sociales, rondas de borradores	Entregables, material de marca

Ambos modelos usan el mismo flujo: Flash genera 10 direcciones por $0.10, cambias model en la elegida y la vuelves a ejecutar como resultado final de V4.1 por $0.05; total $0.15. Si solo necesitas bocetos, usa Flash en todo el proceso: 1,000 imágenes cuestan solo $10.00. Para elegir prompts según el caso, consulta la guía completa de prompts.

Dos formas de empezar

3 pasos en el navegador: abre la página del modelo → pega el prompt y elige el tamaño → pulsa generar; una imagen con V4.1 cuesta $0.05. (colors y background_color requieren la API). La primera vez conviene generar una imagen en el navegador para confirmar que el estilo es el esperado antes de escribir código.

3 pasos con la API: POST /v1/tasks para enviar → obtén taskId → GET /v1/tasks/<taskId> hasta obtener success y descarga.

curl: primera imagen (con paleta de marca)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "recraft-v4.1-flash/text-to-image",
  "input": {
    "prompt": "Flat vector illustration of a cozy reading nook with an armchair, a tall plant and a round window showing a city skyline at dusk, clean geometric shapes, gentle grain",
    "image_size": "landscape_4_3",
    "colors": [
      {"r": 28, "g": 61, "b": 90},
      {"r": 240, "g": 128, "b": 60},
      {"r": 245, "g": 222, "b": 179}
    ],
    "background_color": {"r": 250, "g": 246, "b": 238}
  }
}'

Este ejemplo usa los parámetros reales del caso Flash: paleta de tres tonos (azul profundo, naranja y trigo) con fondo blanco crema. Para el resultado final, cambia model a recraft-v4.1/text-to-image y deja el resto igual.

Python: enviar, consultar y descargar

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "recraft-v4.1/text-to-image",
    "input": {
        "prompt": "Minimalist brand poster for a specialty coffee brand, huge bold headline \"NORTH BEAN\" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout",
        "image_size": "portrait_4_3",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # dirección temporal, descarga y guarda cuanto antes
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:
        f.write(img.content)
    print("saved")

Tabla de parámetros (idénticos en ambos modelos)

Campo	Obligatorio	Valores	Descripción
prompt	Sí	1–10000 caracteres	Descripción de la imagen
image_size	No	square_hd (predeterminado) / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9	6 presets, sin ancho ni alto personalizados
colors	No	Array de objetos RGB, cada canal 0–255	Guía fuerte de paleta: la imagen se ajusta lo máximo posible a ese conjunto de colores; no disponible en Playground
background_color	No	Un único objeto RGB	Color de fondo; no disponible en Playground

Cada objeto RGB debe incluir obligatoriamente las tres claves r/g/b, cada una entre 0 y 255, y no puede tener claves adicionales. Si el cuerpo de la petición incluye campos fuera de la tabla, devuelve directamente 400.

Errores que encontrarás (texto original de la interfaz)

Qué hiciste	Respuesta
No enviaste prompt	400 invalid input: prompt: missing required field "prompt"
image_size con un objeto de ancho y alto	400 invalid input: image_size: got object, want string
Un canal de colors con 256	400 invalid input: colors.0.r: maximum: got 256, want 255
colors sin la clave b	400 invalid input: colors.0.b: missing required field "b"
colors como cadena	400 invalid input: colors: got string, want array
Objeto RGB con una clave extra	400 invalid input: colors.0: additional properties 'a' not allowed
Saldo insuficiente	402 insufficient account balance; top up and retry
Reenviar con el mismo Idempotency-Key devuelve 409 o 422; usa una clave nueva y reintenta.

Antes de publicar

• Callback: pasa "callback": {"url": "https://..."} en el nivel superior del cuerpo de la petición para recibir una notificación automática al estado final.
• Guarda cuanto antes: output[0].url es una dirección temporal; descárgala en cuanto la recibas y guárdala en tu propio almacenamiento; no la uses como enlace permanente.
• La paleta es una guía, no un bloqueo: si el prompt menciona colores que entran en conflicto con colors, el resultado puede mezclar ambos; si necesitas colores estrictos, no menciones otros colores en el prompt.
• De Flash a V4.1 solo cambia model: el resto de parámetros se mantienen igual y puedes reutilizar directamente el enfoque de composición.

Preguntas frecuentes

¿Los parámetros de los dos modelos son iguales?

Completamente. Solo cambia el campo model; el código no requiere ninguna modificación.

¿Dónde se configura el parámetro colors?

Solo mediante la API. Playground no ofrece por ahora los parámetros colors ni background_color.

¿colors garantiza que solo se usen los colores indicados?

No. Es una guía fuerte: la imagen se ajusta lo máximo posible a esa gama, pero no es un bloqueo estricto.

¿Cuántas imágenes se generan por vez?

Una por vez. Para más, envía varias tareas o ponlas en cola.

¿Cuántas imágenes se generan con $10?

Flash cuesta $0.01 por imagen, así que $10 generan 1,000. Los fallos no se cobran.

Siguiente paso: usa el prompt de NORTH BEAN para generar una imagen en la página del modelo; cuando necesites colores de marca, añade colors a la petición de la API; para plantillas por caso, consulta la guía completa de prompts.