¿Cómo usar la API de Ideogram 3.0 Character? Genera tu primera imagen de personaje en 5 minutos

TL;DR

• Ideogram 3.0 Character es un modelo de generación de personajes a partir de una imagen de referencia: sube 1 imagen de referencia del personaje, escribe una frase de prompt de escena y la misma cara y el mismo conjunto de ropa aparecen en la nueva escena. Abre la página del modelo para probarlo en línea; los usuarios nuevos reciben 200 créditos al registrarse.
• El precio se calcula por imagen: TURBO $0.09, BALANCED $0.13, QUALITY $0.18; la imagen de referencia no se cobra y los fallos no se descuentan (consulta la página de precios).
• La llamada se hace a través de la API /v1/tasks de HiAPI: envía la tarea y obtén un taskId, luego úsalo para consultar el resultado y, tras el éxito, descarga la imagen desde output[0].url.

Qué puede hacer

• Generación con consistencia de personaje: una imagen de referencia fija el personaje, mantiene la forma de la cara y la ropa, y la escena se puede cambiar a voluntad.
• Sirve tanto para ilustración como para fotorrealismo: style admite AUTO / REALISTIC / FICTION; funciona tanto con personajes fotográficos como ilustrados.
• El formato sigue a la imagen de referencia: una referencia vertical genera 3:4 (864×1152); una referencia horizontal genera 16:9 (1328×752); no hace falta rellenar parámetros de tamaño.
• Endpoint de edición complementario: ideogram-v3-character/edit usa una máscara para dibujar el personaje en una zona concreta de una imagen existente, sin tocar el resto de la imagen.

La siguiente es una salida real (la referencia era una ilustración de personaje en formato horizontal):

The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs

(Significado en chino: este personaje explorador camina por un mercado nocturno lleno de faroles, sostiene un vaso de papel con fideos calientes, a ambos lados hay puestos con luz cálida, estilo ilustración de libro de cuentos, sin texto, sin carteles).

ideogram-v3-character, TURBO, 16:9, 1328×752, $0.09.

Generar con este prompt →

Cómo elegir entre los dos endpoints

	ideogram-v3-character	ideogram-v3-character/edit
Qué hace	Generar desde cero una nueva escena del personaje	Dibujar el personaje en la zona con máscara de una imagen existente
Entrada obligatoria	prompt + 1 imagen de referencia	prompt + imagen original + máscara + 1 imagen de referencia
Precio (TURBO / BALANCED / QUALITY)	$0.09 / $0.13 / $0.18	$0.09 / $0.13 / $0.18
Salida	WebP, el formato sigue a la imagen de referencia	WebP, el tamaño sigue a la imagen original
Ideal para	Pósteres, series, imágenes de escenas de una colección	Cambiar o añadir personajes en una imagen final

Convención de la máscara: negro = redibujar, blanco = conservar; la máscara y la imagen original deben tener la misma relación de aspecto. El endpoint de edición no acepta negative_prompt; si se envía, devuelve un 400.

Dos rutas para empezar

3 pasos en el navegador: abre la página del modelo → sube la imagen de referencia del personaje y pega el prompt → pulsa generar; una imagen TURBO cuesta $0.09.

3 pasos con la API: POST /v1/tasks para enviar → obtén taskId → consulta con GET /v1/tasks/<taskId> y, cuando llegue a success, 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": "ideogram-v3-character",
  "input": {
    "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

Para el endpoint de edición, cambia model por ideogram-v3-character/edit y añade en input image_url (imagen original) y mask_url (máscara):

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character/edit",
  "input": {
    "prompt": "The explorer character curled up in the armchair asleep under a knitted blanket",
    "image_url": "https://static.hiapi.ai/gallery/2026/10/8e1328c02f8edd33.jpg",
    "mask_url": "https://static.hiapi.ai/gallery/2026/10/0121b5b1d8af8697.png",
    "reference_image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
    ],
    "rendering_speed": "TURBO"
  }
}'

El taskId de la respuesta es el comprobante de consulta.

Python: enviar, sondear 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": "ideogram-v3-character",
    "input": {
        "prompt": "The explorer character walking through a lantern-lit night market, holding a paper cup of hot noodles, warm glowing stalls on both sides, storybook illustration, no text, no signs",
        "reference_image_urls": ["https://static.hiapi.ai/gallery/2026/10/156346d531f0b319.jpg"],
        "rendering_speed": "TURBO",
    },
}

# 提交：带 Idempotency-Key，网络重试不会重复建任务
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# 轮询：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"]   # 临时地址，尽快下载保存
    img = requests.get(image_url, timeout=60)
    with open("output.webp", "wb") as f:
        f.write(img.content)
    print("saved output.webp")

Tabla de parámetros (ideogram-v3-character)

Campo	Obligatorio	Valores	Descripción
prompt	Sí	1–5000 caracteres	Describe la escena en la que debe aparecer el personaje, no el aspecto del personaje (el aspecto se toma de la imagen de referencia)
reference_image_urls	Sí	Exactamente 1, JPEG / PNG / WebP, ≤10 MB	Imagen de referencia del personaje; su formato determina el formato de salida
rendering_speed	No	TURBO / BALANCED / QUALITY, por defecto BALANCED	Determina el nivel y el precio
style	No	AUTO / REALISTIC / FICTION, por defecto AUTO	REALISTIC tiende a la textura fotográfica; FICTION mantiene la sensación de ilustración
seed	No	Entero 0–2147483647	Con los mismos parámetros y el mismo seed se reproduce la imagen
expand_prompt	No	Por defecto true	Amplía automáticamente el prompt; si quieres respetar estrictamente el texto original, envía false
negative_prompt	No	≤5000 caracteres	Contenido que no quieres que aparezca

El endpoint de edición tiene dos campos obligatorios adicionales fuera de la tabla, image_url y mask_url, y no admite negative_prompt. Si el cuerpo de la petición incluye campos fuera de la tabla, devuelve directamente 400 (additional properties ... not allowed).

Errores que encontrarás (texto literal de la API)

Qué hiciste	Respuesta
No enviaste prompt	400 invalid input: prompt: missing required field "prompt"
Enviaste 2 imágenes de referencia	400 invalid input: reference_image_urls: maxItems: got 2, want 1
rendering_speed mal escrito	400 invalid input: rendering_speed: value must be one of 'TURBO', 'BALANCED', 'QUALITY'
Enviaste un campo que la API no reconoce	400 invalid input: <root>: additional properties 'foo' not allowed
Enviaste negative_prompt al endpoint de edición	400 invalid input: <root>: additional properties 'negative_prompt' not allowed
Saldo insuficiente	402 insufficient account balance; top up and retry

Reenviar con el mismo Idempotency-Key devuelve 409 (en proceso) o 422 (parámetros inconsistentes); prueba con una clave nueva.

Antes de lanzar a producción

• Callback: envía en el nivel superior del cuerpo de la petición "callback": {"url": "https://..."}; cuando la tarea llegue a un estado final, se notificará a tu servicio y te ahorras el sondeo.
• 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.
• Especifica el nivel y el formato: envía rendering_speed explícitamente en cada llamada (si no lo envías, se factura como BALANCED); el formato de salida lo determina la imagen de referencia; para escenas verticales, prepara una referencia vertical.
• Cada tarea por lotes con su propia clave de idempotencia: incluye un Idempotency-Key único en cada envío; un reintento de red con la misma clave solo apuntará a la misma tarea, sin crear tareas duplicadas ni descontar créditos dos veces.

Preguntas frecuentes

¿La imagen de referencia puede ser una URL?

Sí. Siempre que sea una dirección http/https accesible, sirve JPEG, PNG o WebP, con un máximo de 10 MB.

¿Cuántas imágenes de referencia se pueden enviar?

Exactamente 1; es una regla estricta: enviar dos devuelve directamente un 400. Si quieres cambiar de personaje, cambia la imagen de referencia.

¿Hay que enviar parámetros de tamaño?

No. El formato de salida sigue a la imagen de referencia: una referencia vertical genera 864×1152; una horizontal genera 1328×752.

¿Los dos endpoints se llaman igual?

Sí. Solo cambian model y los campos de input.

¿Se cobra si falla?

No; los créditos reservados se devuelven íntegramente cuando la tarea termina en estado de fallo.

Siguiente paso: usa el prompt del mercado nocturno de arriba para probar una imagen en la página del modelo y luego elige prompts según la escena consultando la guía completa de prompts; para los tres niveles de precio y la tabla de presupuesto, consulta la página de precios.