API de imagen-4.0-fast: una solicitud de texto a imagen que funciona

Imagen 4 Fast es el nivel de velocidad de la serie Google Imagen 4, y en hiapi realiza la generación de texto a imagen mediante la misma API de tareas asíncronas unificada que todos los demás modelos de imagen. Esta guía te ofrece una solicitud que realmente funciona: una llamada curl real, un bucle de sondeo en Python, el esquema de entrada cerrado exacto y los casos de error verificados en ejecuciones en producción. Todo lo siguiente se ejecutó contra el endpoint de producción antes de la publicación; el taskId y las URL de salida de los ejemplos provienen de esa ejecución.

Lo que vas a implementar

Una llamada que convierte un prompt de texto en una imagen terminada: envía la tarea a POST /v1/tasks, sondea hasta que se complete y luego lee la URL de la imagen. Necesitas una clave de API de hiapi (crea una en la consola y mantén algo de crédito de pago por uso en la cuenta; consulta precios). No se necesita SDK; cada ejemplo aquí es HTTP puro.

Solicitud mínima funcional (curl)

Crea la tarea. El id del modelo es imagen-4.0-fast, y en este nivel aspect_ratio es obligatorio (se detalla más abajo):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "input": {
      "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
      "aspect_ratio": "16:9"
    }
  }'

La llamada de creación solo devuelve un identificador de tarea, no la imagen:

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

Sondeo del resultado (Python)

Una vez que tengas el taskId, sondea GET /v1/tasks/<id> hasta que el estado llegue a un estado terminal. Este es el bucle que ejecuté realmente:

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

# 1. create the task
created = requests.post(API, headers=HEADERS, json={
    "model": "imagen-4.0-fast",
    "input": {
        "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
        "aspect_ratio": "16:9",
    },
}).json()
task_id = created["data"]["taskId"]

# 2. poll until the task reaches a terminal state
while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
    status = data["status"]
    if status == "success":
        print(data["output"][0]["url"])   # the finished image
        break
    if status == "fail":
        raise RuntimeError(data)
    time.sleep(3)

En mi ejecución, el estado pasó por handling → archiving → success en aproximadamente 12 segundos, y la respuesta del estado terminal fue la siguiente:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A",
    "model": "imagen-4.0-fast",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5D4ZD2X353AHHW3SW8X8N0A-0.webp",
        "expireAt": 1793121346
      }
    ]
  },
  "message": "success"
}

Una tarea devuelve una imagen WebP. El estado archiving es normal: permanece brevemente y luego cambia a success.

Esquema de entrada (lo que el servidor acepta realmente)

El objeto input es un esquema cerrado. Solo acepta los siguientes campos:

Campo	Tipo	Obligatorio	Descripción
prompt	string	Sí	No vacío; una cadena vacía devuelve minLength: got 0, want 1.
aspect_ratio	enum	Sí	Uno de 1:1, 16:9, 9:16, 3:4, 4:3, auto. Sin valor predeterminado.
seed	integer	No	Para ejecuciones reproducibles. Debe ser un número JSON, no una cadena.
negative_prompt	string	No	Describe lo que se desea evitar en la imagen.

Este modelo no tiene campos resolution ni size: el tamaño de salida sigue a aspect_ratio. Cualquier campo fuera de esta tabla será rechazado.

Casos de error verificados (las trampas)

Estos no son suposiciones: cada uno es una respuesta 400 real capturada contra el endpoint en producción.

1. Falta aspect_ratio. Esta es la trampa número uno cuando copias fragmentos de código del nivel básico de Imagen 4 o del nivel Ultra, porque allí aspect_ratio tiene como valor predeterminado 1:1. En Fast no hay valor predeterminado:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: missing required field \"aspect_ratio\"; prompt: minLength: got 0, want 1" }

2. seed enviado como cadena. Pásalo como número:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: seed: got string, want integer" }

3. Campo desconocido (aquí resolution): el esquema cerrado rechaza cualquier contenido extra:

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

Fíjate en la forma: un fallo de validación es un HTTP 400 con error_code: "INVALID_REQUEST", sin taskId, y el message agrega todos los errores de campo en una sola cadena separada por ;, así que lee el contenido completo, no solo la primera frase.

Comparación de Fast con otros niveles de la serie Imagen 4

hiapi aloja tres niveles de Imagen 4 en exactamente la misma API de tareas; solo cambia el id de model, por lo que el cuerpo de la solicitud anterior sirve para todos los niveles:

• imagen-4.0-fast: el nivel de velocidad (página del modelo) y la opción de menor costo de la serie. Adecuado para iterar prompts, explorar conceptos y explorar direcciones en lote, es decir, generar muchos candidatos y quedarse con unos pocos.
• imagen-4.0: el nivel estándar de Imagen 4.
• imagen-4.0-ultra: el nivel de máximo detalle, para tomas finales de calidad de entrega.

Un flujo de trabajo práctico: prototipa en Fast y luego cambia la cadena de model a imagen-4.0-ultra para el renderizado final, sin modificar ningún otro código. Compara el precio actual por imagen en la página de precios.

Consideraciones para producción

• Sondeo vs. webhook. El bucle anterior es sondeo. En producción, la API de tareas de hiapi también admite webhooks: agrega un objeto callback de nivel superior (al mismo nivel que model/input) con url y when: "final", y hiapi enviará por POST los detalles de la tarea cuando esta llegue a un estado terminal. Antes de depender de ello, lee la documentación de la API asíncrona para conocer las convenciones de entrega y reintento.
• No reenvíes la solicitud cuando la red sea inestable. Cada creación de tarea devuelve un nuevo taskId: los prompts no se deduplican. Si una solicitud de sondeo falla brevemente, vuelve a sondear el taskId que ya guardaste; solo necesitas volver a hacer POST si nunca recibiste el taskId.
• Las URL de salida caducan. output[].url está en temp.hiapi.ai y su expireAt es aproximadamente 7 días después (el ejemplo anterior caduca el 2026-10-28). Descarga los bytes en tu propio almacenamiento de inmediato; no hagas hotlinking.

Contenido relacionado

• Página del modelo Imagen 4 Fast
• Imagen 4 Ultra: nivel de máximo detalle, misma estructura de solicitud
• Imagen 4 (básico)
• Documentación de la API de tareas asíncronas unificada
• Precios

Preguntas frecuentes

¿Imagen 4 Fast necesita un endpoint o SDK diferente? No. Es POST /v1/tasks con "model": "imagen-4.0-fast", el mismo endpoint que usan todos los modelos de imagen y vídeo de hiapi. Cambia de nivel cambiando el id del modelo.

¿Por qué mi solicitud devuelve 400 con el mensaje "missing required field aspect_ratio"? Fast no tiene relación de aspecto predeterminada (a diferencia de los niveles básico y Ultra). Envía siempre aspect_ratio desde la enumeración 1:1 | 16:9 | 9:16 | 3:4 | 4:3 | auto.

¿Puedo establecer la resolución o el tamaño de la imagen? No: este modelo no tiene campos resolution ni size; el tamaño de salida sigue a aspect_ratio. Enviar resolution devuelve additional properties 'resolution' not allowed.

¿seed es una cadena o un número? Un número. "seed": 7 funciona; "seed": "7" devuelve seed: got string, want integer.

¿Cuánto tiempo es válida la URL de salida? Aproximadamente 7 días (expireAt). Descárgala y guárdala de inmediato.