¿Cómo usar la API de Imagen 4? Genera tu primera imagen en 5 minutos

TL;DR

• Imagen 4 (imagen-4.0) es un modelo de texto a imagen, $0.06 por imagen: escribes un prompt, eliges la relación de aspecto y obtienes la imagen; ideal para fotografía de retrato, primeros planos de naturaleza y bodegones de producto. Abre la página del modelo para probarlo en línea; los nuevos usuarios reciben 200 créditos al registrarse.
• La misma familia tiene dos niveles más: imagen-4.0-fast a $0.03 por imagen para hacer muchas pruebas de borradores, e imagen-4.0-ultra a $0.09 por imagen para obtener detalles de acabado final.
• La llamada se hace a través de la interfaz /v1/tasks de HiAPI: envías la tarea, obtienes el taskId y luego consultas el resultado; cuando tiene éxito, descargas la imagen desde output[0].url.

Qué puede hacer

• Imagen directamente a partir de texto: no acepta imágenes de referencia, toda la escena se describe con el prompt y aspect_ratio es obligatorio (seis opciones: 1:1, 16:9, 9:16, 3:4, 4:3, auto).
• Tres perfiles en una misma familia: Fast para pruebas de borradores, el nivel estándar para producción diaria y Ultra para mejorar detalles; los tres ID de modelo se usan por fases en el mismo proyecto.
• Siempre 1 imagen por ejecución: no hay parámetros de cantidad, tamaño en píxeles ni formato de salida; para volver a generar, cambia el seed.

Este es un resultado real del nivel estándar:

Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography

(En español: salón escandinavo con mucha luz solar, sofá de lino, estantes de roble y una planta de monstera; fotografía de interiores con estilo de revista. Relación de aspecto elegida: 16:9).

imagen-4.0, 16:9, 1280×720, $0.06.

Generar con este prompt →

Cómo elegir entre los tres modelos

	imagen-4.0-fast	imagen-4.0 (estándar)	imagen-4.0-ultra
Por imagen	$0.03	$0.06	$0.09
Perfil	Muchas pruebas de borradores, elegir dirección	Producción diaria	Detalles de acabado final, materiales y composición tipográfica
Con $10 aprox.	333 imágenes	166 imágenes	111 imágenes
Ideal para	Reuniones de selección, rondas de bocetos	Entregas de generación habituales	Versión final, imágenes sensibles al detalle

Referencia de presupuesto: usando solo el nivel estándar, 1,000 imágenes al mes cuestan aproximadamente $60.00; cuanto más muevas el volumen de pruebas a Fast, más baja la factura, y deja el volumen de versiones finales para Ultra.

Los tres modelos se invocan igual, solo cambia el campo model; la estructura de parámetros es la misma, solo difiere el tipo de seed (ver tabla de parámetros). Fast y Ultra tienen cada uno un tutorial de integración en inglés: Imagen 4 Fast API guide e Imagen 4 Ultra API guide. Para elegir prompts según el caso, consulta la guía completa de prompts; para la tabla de precios completa de los tres niveles y el presupuesto mensual, consulta la página de precios, y para la comparación de dos conjuntos de prompts idénticos con Nano Banana 2.1, consulta la página comparativa.

Dos rutas para empezar

3 pasos en el navegador: abre la página del modelo → pega el prompt, elige la relación de aspecto → haz clic en generar; el nivel estándar cuesta $0.06 por imagen. La primera vez se recomienda generar una imagen en el navegador para confirmar que el estilo visual cumple lo esperado y luego escribir el código.

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

curl: la primera imagen

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": "imagen-4.0",
  "input": {
    "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
    "aspect_ratio": "16:9"
  }
}'

Para cambiar de nivel solo modifica model: imagen-4.0-fast o imagen-4.0-ultra. El taskId de la respuesta es el comprobante de consulta.

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": "imagen-4.0",
    "input": {
        "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
        "aspect_ratio": "16:9",
    },
}

# Enviar: con Idempotency-Key, los reintentos de red no crean tareas duplicadas
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# Consultar: queued -> handling -> archiving -> success / fail
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:  # nombra la extensión según el formato real devuelto
        f.write(img.content)
    print("saved")

Tabla de parámetros

Campo	Obligatorio	Valores	Descripción
prompt	Sí	1–5000 caracteres	Descripción del contenido de la imagen
aspect_ratio	Sí	1:1 / 16:9 / 9:16 / 3:4 / 4:3 / auto	Relación de aspecto de salida, obligatorio
negative_prompt	No	≤5000 caracteres	Contenido que no deseas que aparezca
seed	No	Estándar y Ultra: cadena (≤500 caracteres); Fast: entero	Con los mismos parámetros y seed se reproduce la imagen

Los tres modelos comparten la misma tabla de parámetros. Si en el cuerpo de la solicitud aparece un campo fuera de la tabla, devuelve directamente 400.

Errores que encontrarás

Código de estado	Significado	Cómo resolverlo
400 INVALID_REQUEST	Cuerpo de la solicitud no válido (falta prompt o aspect_ratio, valor de enumeración incorrecto o campo fuera de la tabla)	Corrige el cuerpo de la solicitud según la tabla de parámetros
402 INSUFFICIENT_QUOTA	Saldo insuficiente (no se cobra)	Recarga y vuelve a intentarlo
429 RATE_LIMITED	Se activó el límite de velocidad	Reduce la frecuencia de envío
409 / 422 IDEMPOTENCY_KEY_*	Envío duplicado con la misma clave de idempotencia (en proceso / parámetros inconsistentes)	Usa un nuevo Idempotency-Key
415 UNSUPPORTED_MEDIA_TYPE	Formato de solicitud incorrecto	Verifica Content-Type: application/json

Si la tarea termina en estado fallido, los códigos de error también incluyen CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT, etc.; los fallos no se cobran y los créditos reservados se reembolsan en su totalidad.

A tener en cuenta antes de producción

• Callback: pasa "callback": {"url": "https://..."} en el nivel superior del cuerpo de la solicitud; cuando la tarea llegue a su estado final, se notificará a tu servicio y te ahorras la consulta periódica.
• Guarda cuanto antes: output[0].url es una dirección temporal; descárgala en cuanto la obtengas y guárdala en tu propio almacenamiento.
• Indica la relación de aspecto explícitamente: aspect_ratio es obligatorio, no dependas del valor predeterminado; para contenido vertical para redes sociales elige 9:16.
• El tipo de seed depende del modelo: Fast recibe un entero; estándar y Ultra reciben una cadena.

Preguntas frecuentes

¿Los tres modelos se invocan igual?

Sí, solo cambia el campo model; el resto del código no se modifica.

¿Se puede especificar el tamaño en píxeles o el formato de salida?

No. No hay parámetros de tamaño en píxeles ni de formato; la relación de aspecto de salida la determina aspect_ratio y cada ejecución genera 1 imagen.

¿Se cobra si falla?

No. Los créditos reservados se reembolsan en su totalidad tras el estado final de fallo.

¿Es fiable el texto dentro de la imagen?

Hay que ampliarlo y verificarlo. En imágenes tipo póster a veces sobra una letra o falta un trazo; antes de publicar, amplía y revisa la parte del texto.

¿Se pueden mezclar imágenes de los tres niveles en un mismo proyecto?

Sí. La lógica de prompts y relación de aspecto es común.

Siguiente paso: copia el prompt del salón de arriba y pruébalo en la página del modelo, luego elige plantillas de la guía completa de prompts según el caso para generar imágenes en lote.