Ideogram

Ideogram V3 Character

ideogram-v3-character

Utiliza una imagen de referencia para fijar el mismo personaje, manteniendo la coherencia del rostro y la vestimenta a través de cambios de escena, pose e iluminación, y conservando las ventajas de composición tipográfica dentro de la imagen de Ideogram

ideogram-v3-character ideogram-v3-character/edit

Probar ideogram-v3-character

Entrada

Expand Prompt

Creaciones

Ver todas las creaciones

Salida

image

Rellena los parámetros y genera: los resultados aparecerán aquí.

Precios

ideogram-v3-character per image

Especificaciones	Precio unitario
TURBO	$0.090
BALANCED	$0.130
QUALITY	$0.180

Descripción general

ideogram-v3-character es un modelo de generación de imágenes que utiliza una imagen de referencia como ancla visual del personaje: al proporcionar una foto clara del personaje, mantiene sus rasgos faciales, peinado, vestimenta y proporciones corporales a lo largo de varias generaciones, mientras permite cambiar la escena, la pose, la iluminación y el fondo mediante prompts. Es adecuado para desarrolladores y equipos creativos que necesitan reutilizar un mismo personaje en viñetas de cómic, ilustraciones seriadas para redes sociales o extensiones de mascotas de marca, y además conserva la capacidad de Ideogram para la composición tipográfica dentro de la imagen.

Puntos clave

Fijar el personaje con una sola imagen de referencia: basta con una imagen del personaje en JPEG, PNG o WebP como entrada para que el modelo la use como ancla visual y mantenga la apariencia consistente del personaje.
Cambiar la escena sin cambiar al personaje: mientras se fija la apariencia del personaje, se pueden ajustar considerablemente la escena, la pose, la iluminación y el fondo mediante el prompt.
Control de parámetros reproducible: admite seed, prompts negativos y niveles de velocidad de renderizado, lo que facilita una generación estable por lotes y el ajuste de detalles y ritmo según sea necesario.

Descripción de capacidades

Consistencia del personaje con imagen de referencia: toma una imagen de referencia del personaje como entrada y el resultado generado conserva su rostro, peinado, vestimenta y proporciones corporales, ideal para contenido seriado que requiere reutilizar una misma figura en varias imágenes.

Transformación de escena guiada por prompt: con el personaje fijado, se describe la nueva escena y pose con un prompt de hasta 5000 caracteres, y se pueden excluir elementos no deseados con prompts negativos.

Generación reproducible: admite establecer una semilla aleatoria, lo que facilita reproducir el mismo resultado durante la depuración o la producción por lotes y reduce el coste de selección.

Selección de nivel de renderizado: ofrece tres niveles de velocidad de renderizado, TURBO, BALANCED y QUALITY, para que los desarrolladores equilibren velocidad y calidad según el ritmo de generación y los requisitos de detalle.

Casos de uso

Autores de cómic y guion gráfico: escenas consecutivas de un mismo personaje: con una imagen de diseño del personaje más la descripción de una viñeta, se generan viñetas con una figura coherente que pasan directamente al proceso de maquetación y posproducción.
Gestión de redes sociales: imagen unificada del personaje en contenido seriado: se generan por lotes ilustraciones de distintos temas a partir de una imagen de referencia fija del personaje, manteniendo coherente al protagonista visual de varias entregas.
Equipos de marca: extensión de la mascota en distintos escenarios: se generan materiales derivados de la mascota en diferentes campañas, estaciones o escenarios de carteles para su uso en materiales de marketing.

Limitaciones y recomendaciones de selección

La consistencia del personaje no es absoluta: en escenas complejas, poses exageradas y cambios de expresión todavía pueden aparecer desviaciones visibles en el rostro y los detalles. La calidad de la imagen de referencia influye directamente en el resultado; se recomienda usar imágenes del personaje con rostro nítido, iluminación uniforme y pocas obstrucciones. Si solo se necesita una imagen creativa independiente y no un personaje fijo, es más adecuado un modelo convencional de texto a imagen. Para proyectos comerciales con requisitos muy altos de fidelidad del personaje, se recomienda validar la consistencia con una pequeña muestra antes de generar por lotes.

Novedades

Ver el registro de cambios →

Nuevo modelo Se añade la generación con consistencia de personaje ideogram-v3-character y ideogram-v3-character/edit… Oct 17, 2026

Preguntas frecuentes

Ver todas las preguntas →

¿Qué requisitos tiene la máscara?

La máscara debe tener la misma relación de aspecto que la imagen original; las zonas negras se redibujarán y las blancas se conservarán. Que la zona sea un poco más grande que el contorno del personaje resulta más natural.
¿Cuál es el tamaño de salida?

La salida mantiene el tamaño de la imagen original; por ejemplo, una imagen original de 1024×768 produce un resultado de 1024×768.
¿Se pueden reemplazar las personas que ya aparecen en la imagen original?

Sí, pinta en la máscara a las personas que quieras reemplazar y describe en el prompt la acción del nuevo personaje; las personas y el fondo fuera de la máscara se conservarán.
¿En qué formato se usa la máscara?

Usa una imagen con la misma relación de aspecto que la imagen original, pinta de negro sobre fondo blanco la zona que se va a redibujar; el caso de esta página utiliza una máscara PNG.

Crear una tarea de generación

POST https://api.hiapi.ai/v1/tasks

Encabezados

AuthorizationstringObligatorio

Clave API de la cuenta. Obligatoria en cada solicitud. Ejemplo: Bearer YOUR_HIAPI_API_KEY. Obtener clave API

Content-TypestringOpcional

El cuerpo de la solicitud siempre se analiza como JSON; si se envía, solo se acepta application/json (charset opcional) — cualquier otro valor devuelve 415. Ejemplo: application/json.

Idempotency-KeystringOpcional

Clave de idempotencia, hasta 255 bytes. Los reintentos con la misma clave de la misma cuenta crean la tarea una sola vez; las repeticiones devuelven el taskId original.

Clave de idempotencia

Ante timeouts de red o reintentos automáticos del cliente, la misma clave crea la tarea una sola vez, sin doble cobro (alcance = la cuenta de la clave API). Usa un identificador de negocio único (p. ej. "order-42"); las repeticiones devuelven el taskId original y las claves caducan 24 h después de la primera solicitud. La matriz completa de escenarios está en la introducción de la API asíncrona unificada.

Cuerpo

modelstringObligatorio

Valor fijo actual: ideogram-v3-character

routestringOpcional

Valor fijo actual: default

inputobjectObligatorio

Objeto de parámetros de negocio para ideogram-v3-character y la ruta default; consulta la tabla de parámetros a continuación.

seedintegerOpcionalmin 0max 2147483647

Semilla aleatoria para obtener resultados de generación reproducibles; su valor es un número entero y la misma semilla reproduce la misma salida.

stylestringOpcionalPredeterminado: "AUTO"

Tipo de estilo que controla el estilo general de la imagen generada; por defecto AUTO.

Opciones:AUTOREALISTICFICTION

promptstringObligatoriominLength 1maxLength 5000

Prompt de escena que describe el personaje de referencia; longitud máxima de 5000 caracteres.

expand_promptbooleanOpcionalPredeterminado: true

Indica si se habilita MagicPrompt para expandir el prompt; por defecto true.

negative_promptstringOpcionalmaxLength 5000

Prompt negativo que especifica el contenido que se desea excluir de la imagen; longitud máxima de 5000 caracteres.

rendering_speedstringOpcionalPredeterminado: "BALANCED"

Nivel de velocidad de renderizado: TURBO es el más rápido y económico, QUALITY ofrece el mayor detalle y cada nivel tiene una facturación distinta; por defecto BALANCED.

Opciones:TURBOBALANCEDQUALITY

reference_image_urlsarrayObligatoriominItems 1maxItems 1

Array de imágenes de referencia del personaje; debe contener exactamente una imagen de referencia del personaje, en formato JPEG, PNG o WebP, con un máximo de 10 MB por imagen.

Array [ string ]

callbackobjectOpcional

Configuración de notificación de estado terminal. Si se omite, no hay callback: consulta la tarea por tu cuenta.

Callbacks (Webhook)

Indica callback.url al crear y HiAPI hará POST a tu servicio en el estado terminal, sin necesidad de sondeo. El cuerpo del callback replica la estructura del detalle de la tarea; firma, reintentos e idempotencia se detallan en la introducción de la API asíncrona unificada.

urlstringObligatorio

Obligatorio si se incluye callback. Al estado terminal se envía un POST a esta URL; debe ser una URL http(s) válida.

whenstringOpcionalPredeterminado: "final"

Actualmente solo se admite final: notifica tanto en success como en fail.

Opciones:final

storagestringOpcionalPredeterminado: "temp"

Nivel de almacenamiento de artefactos: temp (por defecto, ~7 días) o persistent (largo plazo, facturado por tamaño). Saldo insuficiente o exceso de límite ⇒ degradación silenciosa a temp; el nivel efectivo se muestra en la respuesta del detalle.

Opciones:temppersistent

Ejemplos de solicitud

# Envía una tarea asíncrona; devuelve un taskId de inmediato (sin esperar la generación)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character",
  "input": {
    "style": "AUTO",
    "prompt": "…",
    "expand_prompt": true,
    "rendering_speed": "BALANCED",
    "reference_image_urls": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "ideogram-v3-character",
    input: {
      "style": "AUTO",
      "prompt": "…",
      "expand_prompt": true,
      "rendering_speed": "BALANCED",
      "reference_image_urls": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "ideogram-v3-character",
        "input": {
          "style": "AUTO",
          "prompt": "…",
          "expand_prompt": True,
          "rendering_speed": "BALANCED",
          "reference_image_urls": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

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

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Obtener el detalle de la tarea

GET https://api.hiapi.ai/v1/tasks/:id

Campos de respuesta

taskIdstringObligatorio

ID de tarea, siempre con prefijo tk-hiapi-.

modelstringObligatorio

Nombre completo resuelto del modelo. Las tareas enviadas con el parámetro route devuelven base@route (p. ej. gpt-image-2/text-to-image@ext); si no, coincide con el nombre enviado.

routestringOpcional

Solo aparece si se usó el parámetro route explícito; repite el valor enviado.

statusstringObligatorio

Estado de la tarea.

Valores de estado

queued En cola, sin iniciar. handling Procesando. archiving Proceso terminado, preparando artefactos. success Terminal: completado, artefactos disponibles (se devuelve output). fail Terminal: error (se devuelve error). Tras el envío, guíate por status: success y fail son terminales; el resto, no. Sondea cada 1–3 s hasta el estado terminal. Con éxito, descarga los artefactos desde output[].url y transfiérelos antes de expireAt; para retención larga usa storage: "persistent" al crear.

creatednumberObligatorio

Hora de creación de la tarea (segundos Unix).

completednumberObligatorio

Segundos Unix al alcanzar estado terminal; 0 mientras no sea terminal.

outputarrayOpcional

Solo con status == success. Lista de artefactos — siempre un array; una tarea puede devolver varios types a la vez (p. ej. video + first_frame).

Array [ object ]

Elementos del array

urlstringObligatorio

URL del artefacto, descargable directamente.

typestringObligatorio

Valores posibles actuales: video, image, audio, first_frame, last_frame, thumbnail; podrían ampliarse más adelante.

expireAtnumberObligatorio

Segundos Unix hasta los que el artefacto es accesible; descárgalo o transfiérelo antes.

errorobjectOpcional

Solo con status == fail.

codestringObligatorio

Código de error de negocio.

messagestringObligatorio

Descripción del error.

Ejemplos de respuesta

Éxito

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

En proceso (no terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Fallido

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}