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

Imagen 4 Ultra es la versión con el mayor nivel de detalle de la serie Google Imagen 4. En hiapi, al igual que todos los demás modelos de imagen, ejecuta la generación de texto a imagen mediante la misma API unificada de tareas asíncronas. Esta guía presenta una solicitud que realmente funciona: una llamada real con curl, un bucle de sondeo en Python, los parámetros que el servidor acepta realmente y los casos de error verificados mediante solicitudes reales. Todo lo siguiente se ejecutó y verificó en el endpoint de producción antes de publicarse; el taskId de ejemplo y la URL de salida provienen de esa ejecución.

Lo que vas a construir

Una sola llamada convierte un prompt de texto en una imagen final: se envía la tarea a POST /v1/tasks, se sondea hasta que se completa y luego se lee la URL de la imagen desde output[0].url. Necesitas una clave de API de hiapi: obténla desde tu panel y expórtala:

export HIAPI_API_KEY="your-hiapi-key"

Ejemplo mínimo funcional (curl)

El modelo acepta prompt y el opcional aspect_ratio. Crea la tarea:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-ultra",
    "input": {
      "prompt": "Macro product photo of a matte ceramic coffee mug on a pale oak table, soft window light from the left, shallow depth of field, a few coffee beans in the foreground, no text, no logos",
      "aspect_ratio": "4:3"
    }
  }'

La llamada de creación devuelve de inmediato un id de tarea; la generación continúa en segundo plano:

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

Sondea la tarea con el id devuelto:

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Cuando status es success, la imagen está en output[0].url:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61",
    "model": "imagen-4.0-ultra",
    "status": "success",
    "storage": "temp",
    "created": 1792506471,
    "completed": 1792506479,
    "output": [
      {
        "artifactId": "279760",
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5CVC8R62M0Z7CCM8WB38B61-0.webp",
        "expireAt": 1793111279
      }
    ]
  },
  "message": "success"
}

Esa ejecución se completó en aproximadamente 8 segundos y devolvió un WebP (no PNG/JPEG). La URL está en almacenamiento temporal ("storage": "temp"), con expireAt establecido a 7 días: descárgala a tiempo, no la enlaces en caliente.

Producción: Python con bucle de sondeo

La respuesta de creación no contiene la imagen, solo el taskId. Una integración real primero envía y luego sondea (o usa un callback). Este script realiza el ciclo completo y descarga el resultado de inmediato, ya que la URL es temporal:

import os, time, requests

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

def generate(prompt, aspect_ratio="1:1", negative_prompt=None, seed=None):
    body = {"model": "imagen-4.0-ultra", "input": {"prompt": prompt, "aspect_ratio": aspect_ratio}}
    if negative_prompt:
        body["input"]["negative_prompt"] = negative_prompt
    if seed is not None:
        body["input"]["seed"] = str(seed)  # seed is a STRING, not a number

    r = requests.post(API, headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    created = r.json()
    if created.get("code") != 200:
        raise RuntimeError(f"create rejected: {created}")
    task_id = created["data"]["taskId"]

    # Poll. Statuses other than success/fail (e.g. queued, running, archiving) mean "keep waiting".
    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # tolerate a transient read; re-poll the same id
        status = d.get("status")
        if status == "success":
            return d["output"][0]["url"]
        if status in ("fail", "failed", "error"):
            raise RuntimeError(f"task failed: {d}")
    raise TimeoutError(f"task {task_id} did not finish in time")

url = generate(
    "A high-detail aerial landscape of terraced rice fields at golden hour, long shadows",
    aspect_ratio="16:9",
)
img = requests.get(url, timeout=60).content
open("out.webp", "wb").write(img)
print(f"saved {len(img)} bytes from {url}")

Consideraciones importantes en producción:

• Sondeo vs callback. Lo anterior muestra el sondeo. Para evitar el sondeo, adjunta un objeto callback de nivel superior ({"url": "...", "when": "final"}); hiapi enviará una solicitud POST a tu servidor cuando la tarea alcance un estado terminal. El contrato del callback se detalla en la documentación de la API asíncrona unificada.
• Vuelve a sondear el id guardado, no lo vuelvas a crear. Leer una tarea es idempotente; ante una desconexión, reintenta GET /v1/tasks/<id>, nunca vuelvas a hacer POST (eso factura otra imagen).
• Descarga en cuanto tengas éxito. output[0].url es temporal (en esta ejecución el TTL fue de 7 días). Obtén los bytes y súbelos a tu propio almacenamiento.

Parámetros que este modelo acepta realmente

imagen-4.0-ultra solo admite texto a imagen: no admite imágenes de referencia (confirmado en la página del modelo; esta ejecución solo probó texto a imagen). El schema de entrada es cerrado: los campos desconocidos se rechazan, por lo que no es posible colar parámetros adicionales.

Campo	Tipo	Obligatorio	Descripción
prompt	string	Sí	De 1 a 5,000 caracteres. Una cadena vacía falla (minLength: got 0, want 1).
aspect_ratio	enum	No	Uno de 1:1, 16:9, 9:16, 3:4, 4:3, auto. Por defecto 1:1.
negative_prompt	string	No	Máximo 5,000 caracteres; describe lo que se debe excluir.
seed	string	No	Máximo 500 caracteres. Es una cadena: pasar un número se rechaza.

Una solicitud genera exactamente una imagen.

Casos de error verificados

Estos se produjeron en el endpoint real, por lo que tu manejo de errores puede confiar en ellos. Las solicitudes rechazadas devuelven HTTP 400, con un sobre plano y sin taskId:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: aspect_ratio: value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'"}

Algunos comportamientos que conviene tener en cuenta en el código:

• El validador reporta todos los errores de campo a la vez, unidos por ; . Si pasas un número en seed y un aspect_ratio no válido, obtendrás ambos en un solo mensaje: invalid input: seed: got number, want string; aspect_ratio: value must be one of .... No asumas que cada respuesta contiene un solo error.
• Los campos desconocidos hacen fallar toda la solicitud, con el error <root>: additional properties '<name>' not allowed. El schema es cerrado.
• Un prompt vacío falla con el error prompt: minLength: got 0, want 1.
• Un create exitoso devuelve code: 200 con data.taskId; un rechazo devuelve data: null. Ramifica según esto antes de intentar leer el id de la tarea.

¿Qué nivel de Imagen 4 deberías usar?

imagen-4.0-ultra es el nivel más alto de los tres; elige según la tarea, no por costumbre (la relación de aspecto, el prompt negativo y la semilla no afectan lo que pagas; consulta precios):

• Imagen 4 Fast: el más económico, ideal para borradores rápidos y exploración masiva de direcciones.
• Imagen 4: el nivel intermedio para el día a día, adecuado para imágenes de producto, estilo de vida y contenido.
• Imagen 4 Ultra (este modelo): el más caro de los tres, orientado al detalle de nivel final: texturas macro, renderizado de materiales y composición tipográfica, para escenarios en los que la imagen final debe resistir el escrutinio. Elige Ultra cuando la salida sea entregable directamente; usa Fast o el nivel básico durante la iteración.

Enlaces relacionados

• Página del modelo Imagen 4 Ultra: schema en vivo, ejemplos y precios.
• Documentación de la API asíncrona unificada: creación, listado y obtención de tareas, y el contrato de callback.
• Inicio rápido: autentícate y ejecuta tu primera tarea en pocos minutos.
• Precios: coste por imagen de cada nivel de Imagen 4.

Preguntas frecuentes

¿Cuántas imágenes devuelve una solicitud? Una. En la ejecución verificada, el array output contiene un solo elemento.

¿En qué formato está la salida? WebP. El archivo devuelto es .webp en temp.hiapi.ai.

¿Cuánto dura la URL de salida? Unos 7 días: expireAt se establece a 7 días después de la finalización. Trátala como un recurso temporal y descárgala de inmediato.

¿Puedo enviar imágenes de referencia? No. imagen-4.0-ultra solo admite texto a imagen; la página del modelo indica que las imágenes de referencia no son compatibles.

¿Por qué mi solicitud da el error "additional properties not allowed"? El schema de entrada es cerrado. Envía solo prompt, aspect_ratio, negative_prompt y seed; cualquier otra clave hace fallar toda la solicitud.

¿El prompt negativo, la semilla o la relación de aspecto cambian el precio? No. La facturación es por imagen; estos parámetros no afectan al coste.