¿Cómo usar la API de Ideogram 4.5? Generación, edición y consulta de tareas

TL;DR

• Ideogram 4.5 es una familia de texto a imagen con prioridad en la tipografía: ideogram-v4.5/text-to-image genera carteles, logotipos y envases bilingües, es decir, imágenes con texto; ideogram-v4.5/image-to-image permite cambiar texto con precisión mediante Precise Edit, cambiar el estilo con imágenes de referencia y retocar zonas con máscara. Puedes elegir la tarea desde la página del modelo o llamar a la interfaz como se describe a continuación.
• El precio se calcula por imagen y varía según el nivel de calidad: LOW 0,043 USD, MEDIUM (predeterminado) 0,086 USD, HIGH 0,3145 USD; el nivel de edición VERY_LOW parte de 0,0115 USD; actualmente cada solicitud produce 1 imagen y num_images solo puede ser 1. Consulta la página de precios para más detalles.
• La llamada se realiza a través de la API /v1/tasks de HiAPI: tras el envío, lee data.taskId y luego consulta data.status; cuando tenga éxito, descarga desde data.output la URL con type=image.

Qué puede hacer

• Organizar la jerarquía del texto en la imagen: coloca entre comillas el texto que debe aparecer e indica por separado la posición del título, subtítulo, fecha y alineación; revisa letra por letra la imagen generada.
• Explorar composiciones con tareas de una sola imagen: cada solicitud produce 1 imagen; ajusta el prompt o la semilla y envía varias tareas para comparar enfoques.
• Interfaz de edición complementaria: Precise Edit (edit_precision=high) sirve para modificaciones pequeñas como nombres de marca o fechas; compara con la imagen de origen para comprobar las zonas conservadas.
• Imágenes de referencia + máscara: hasta 4 imágenes de referencia (3 si se usa máscara); en la máscara, negro = repintar, blanco = conservar.

A continuación se muestra un resultado real generado (nivel LOW):

Minimal modern brand poster for a design conference. Huge bold headline text "DESIGN FORWARD" centered, smaller subtitle "Typography Summit 2026" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering

(En español: cartel de marca minimalista y moderno para una conferencia de diseño, con un enorme titular en negrita centrado "DESIGN FORWARD", un subtítulo más pequeño debajo "Typography Summit 2026", maquetación de cuadrícula suiza, paleta de naranja cálido y azul marino profundo, formas geométricas y letras nítidas y definidas. Tamaño elegido: landscape_16_9.)

ideogram-v4.5/text-to-image, LOW, landscape_16_9, 1280×720, 0,043 USD.

Generar con este prompt →

Cómo elegir entre las dos interfaces

	ideogram-v4.5/text-to-image	ideogram-v4.5/image-to-image
Qué hace	Generar imágenes con maquetación a partir de texto	Editar una imagen existente
Entrada obligatoria	prompt	image_url + prompt
Nivel de calidad	low / medium / high	very_low / low / medium / high
Parámetros destacados	num_images: 1, enable_prompt_expansion	edit_precision (Preciso), reference_image_urls, mask_url
Tamaño	6 preajustes, predeterminado square_hd	auto (predeterminado) o 6 preajustes; con máscara o Precise, solo auto
Ideal para	Carteles, logotipos, envases y rótulos nuevos	Cambiar texto, cambiar colores, versiones de temporada, repintado local

Flujo típico: generar un cartel de marca y luego usar Edit para cambiar el nombre de la marca o la fecha a la versión del cliente. Generar en LOW cuesta 0,043 USD por imagen y un cambio de texto con Precise LOW cuesta 0,043 USD; el conjunto, 0,086 USD.

Dos rutas para empezar

3 pasos en el navegador: abre la página del modelo → pega el prompt y elige el nivel de calidad → haz clic en generar.

3 pasos con la API: POST /v1/tasks para enviar → lee data.taskId → consulta data.status con GET /v1/tasks/<taskId> y, cuando llegue a success, descarga.

curl: la primera imagen

Primero configura en la terminal HIAPI_IDEMPOTENCY_KEY con el identificador único de esta operación comercial y reutiliza ese valor al reintentar la misma solicitud. El ejemplo usa explícitamente LOW, tamaño horizontal y expansión de prompt activada.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/text-to-image",
  "input": {
    "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
    "quality": "low",
    "image_size": "landscape_16_9",
    "enable_prompt_expansion": true,
    "num_images": 1
  }
}'

Interfaz de edición: cambia model por ideogram-v4.5/image-to-image y pasa la imagen de origen y la instrucción. A continuación se usa Precise Edit para solicitar el cambio de texto y la conservación de la maquetación; aun así, hay que comprobar el resultado con la imagen de origen:

Esta tarea de edición configura además HIAPI_EDIT_IDEMPOTENCY_KEY; no reutilices la clave de la tarea de generación.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $HIAPI_EDIT_IDEMPOTENCY_KEY" \
  -d '{
  "model": "ideogram-v4.5/image-to-image",
  "input": {
    "prompt": "Change the logo text from \"Ember & Oak\" to \"Maple & Co\", keep the same serif lettering style, emblem, tagline, colors and layout exactly unchanged",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/88567ad2baf46b32.png",
    "edit_precision": "high",
    "quality": "low",
    "image_size": "auto",
    "num_images": 1
  }
}'

Python: enviar, consultar y descargar

Primero instala requests y configura HIAPI_API_KEY; en el primer envío también debes configurar HIAPI_IDEMPOTENCY_KEY, con un valor independiente para cada nueva operación comercial y manteniéndolo igual al reintentar el mismo envío. El programa imprimirá primero el ID de la tarea; si se interrumpe, puedes configurar HIAPI_TASK_ID para continuar consultando y descargando sin volver a enviar la generación.

import os
import time
from pathlib import Path

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
headers = {"Authorization": "Bearer " + os.environ["HIAPI_API_KEY"]}
payload = {
    "model": "ideogram-v4.5/text-to-image",
    "input": {
        "prompt": "Minimal modern brand poster for a design conference. Huge bold headline text \"DESIGN FORWARD\" centered, smaller subtitle \"Typography Summit 2026\" below, clean Swiss grid layout, warm orange and deep navy palette, geometric shapes, crisp sharp lettering",
        "quality": "low",
        "image_size": "landscape_16_9",
        "enable_prompt_expansion": True,
        "num_images": 1,
    },
}
# Set HIAPI_TASK_ID to resume polling without creating another task.
task_id = os.environ.get("HIAPI_TASK_ID")
if not task_id:
    # Use one unique key per business operation; keep it for retries.
    submission_key = os.environ["HIAPI_IDEMPOTENCY_KEY"]
    response = requests.post(
        BASE, headers={**headers, "Idempotency-Key": submission_key},
        json=payload, timeout=30,
    )
    response.raise_for_status()
    created = response.json()
    if created.get("code") != 200:
        raise RuntimeError(created)
    task_id = created["data"]["taskId"]
print("Keep this task ID:", task_id, flush=True)

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{BASE}/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result.get("code") != 200:
        raise RuntimeError(result)
    task = result["data"]
    if task["status"] in ("fail", "failed"):
        raise RuntimeError(task.get("error", task))
    if task["status"] == "success":
        image_url = next(
            (item["url"] for item in task.get("output", [])
             if item.get("type") == "image" and item.get("url")), None,
        )
        if not image_url:
            raise RuntimeError("Successful task has no image URL")
        # Do not forward API authorization to the media download host.
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        media_type = image.headers.get("Content-Type", "").split(";", 1)[0].lower()
        suffix = {"image/png": ".png", "image/jpeg": ".jpg",
                  "image/webp": ".webp"}.get(media_type)
        if not suffix:
            raise RuntimeError("Unexpected image content type: " + media_type)
        target = Path(task_id + suffix)
        partial = target.with_suffix(suffix + ".part")
        partial.write_bytes(image.content)
        partial.replace(target)
        print("Saved:", target)
        break
    time.sleep(3)
else:
    raise TimeoutError(f"Polling timed out; keep checking task {task_id}")

Si se produce un error de red al consultar o descargar, conserva el ID de tarea ya impreso y reanuda; el script no reenvía automáticamente la solicitud de creación. El ejemplo limita la consulta a 600 segundos, con una espera de 3 segundos entre intentos; la descarga escribe primero un archivo .part y solo lo renombra al nombre definitivo cuando termina.

Tabla de parámetros

Generación ideogram-v4.5/text-to-image

Campo	Obligatorio	Valores	Descripción
prompt	Sí	1–10000 caracteres	Estructura en cuatro partes: qué imagen → texto y colores → maquetación → textura y restricciones
quality	No	low / medium / high, predeterminado medium	low para exploración por lotes, medium para el día a día, high para versiones finales con mucho texto pequeño
image_size	No	6 preajustes, predeterminado square_hd	Sin ancho y alto personalizados
num_images	No	Fijo en 1	Cada tarea produce 1 imagen
enable_prompt_expansion	No	Predeterminado true	Expansión del prompt; false la desactiva, pero aun así hay que revisar el texto del resultado
seed	No	Entero	Reproducir con los mismos parámetros

Edición ideogram-v4.5/image-to-image

Campo	Obligatorio	Valores	Descripción
image_url	Sí	URL de imagen	Imagen de origen
prompt	Sí	1–10000 caracteres	Instrucción de edición; indica claramente qué cambiar y qué conservar
edit_precision	No	regular / high, predeterminado regular	high = Precise Edit, adecuado para cambios pequeños de texto
quality	No	very_low / low / medium / high, predeterminado medium	very_low solo puede combinarse con regular
image_size	No	auto o 6 preajustes, predeterminado auto	Con máscara o Precise, solo auto
reference_image_urls	No	Máximo 4	Con máscara, máximo 3
mask_url	No	URL de imagen	Negro = repintar, blanco = conservar
num_images	No	Fijo en 1	Cada tarea produce 1 imagen
seed	No	Entero

Si dentro de input aparece un campo que no está en la tabla de parámetros de este modelo, se devuelve 400; el model, callback y otros campos de nivel superior se rellenan según el formato de la interfaz de tareas.

Errores que encontrarás

Código de estado	Significado	Cómo resolverlo
400 INVALID_REQUEST	Cuerpo de solicitud no válido (falta prompt o image_url, valor de enumeración incorrecto, 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 reintenta
429 RATE_LIMITED	Se ha activado el límite de velocidad	Reduce la frecuencia de envío
409 IDEMPOTENCY_KEY_PROCESSING	Se está creando una tarea con la misma clave	Espera y reintenta con la misma clave y el mismo cuerpo de solicitud
422 IDEMPOTENCY_KEY_MISMATCH	La misma clave se usó con un cuerpo de solicitud diferente	Restaura el cuerpo original; solo cambia de clave para una nueva tarea comercial

El fallo en estado final de una tarea puede incluir códigos de error como CONTENT_POLICY_VIOLATION, TASK_FAILED o TASK_TIMEOUT. Conserva el taskId y el mensaje de error, y verifica la liquidación con el estado final de la tarea y los registros de la cuenta; no confundas un fallo de consulta o de descarga con un fallo de generación.

Antes de publicar

• Callback: pasa "callback": {"url": "https://..."} en el nivel superior del cuerpo de la solicitud para recibir notificación automática en el estado final.
• Guarda los resultados a tiempo: los enlaces de resultado en data.output tienen período de validez; descárgalos en cuanto tengas éxito.
• Tareas de una sola imagen e idempotencia: cada ejecución produce 1 imagen; si la misma solicitud comercial se reintenta por tiempo de espera, usa la misma clave de idempotencia; solo las nuevas tareas comerciales usan una clave nueva.
• Texto pequeño en chino: compara los niveles de calidad con el texto real; revisa letra por letra antes de entregar; medium o high no sustituyen la revisión.

Preguntas frecuentes

¿Cuántas imágenes se pueden generar como máximo en una solicitud?

Actualmente, tanto la generación como la edición producen 1 imagen por ejecución y num_images solo puede ser 1. Envía tareas por separado para cada enfoque.

¿El nivel de calidad predeterminado es LOW?

No. El predeterminado es MEDIUM, 0,086 USD por imagen; si necesitas LOW a 0,043 USD por imagen, pasa explícitamente quality: "low".

¿Qué modo se usa para cambiar solo el nombre de la marca y la fecha?

Puedes usar Precise Edit, pasando explícitamente edit_precision: "high", quality: "low" y image_size: "auto"; 0,043 USD por imagen.

¿Qué representan las zonas blancas y negras de la máscara?

Las zonas negras se repintan y las blancas se conservan. La máscara debe tener el mismo tamaño que la imagen de origen; al usar máscara, elige auto en image_size.

¿Hay que cambiar la clave de idempotencia tras un tiempo de espera al enviar?

No cambies la clave al reintentar la misma solicitud comercial; usa el mismo Idempotency-Key y el mismo cuerpo de solicitud; solo usa una clave nueva cuando realmente necesites una tarea nueva.

Siguiente paso: toma el prompt del cartel DESIGN FORWARD y genera una imagen en la página del modelo, y luego usa una instrucción Precise para cambiar el titular por el nombre de tu propio evento. Lectura complementaria: Tres niveles de precio y presupuesto · 4 casos de prompts de edición.

Si quieres empezar directamente a crear logotipos o carteles de eventos, puedes copiar esta colección de ejemplos de prompts.