Ideogram

Ideogram V3 Character

ideogram-v3-character/edit

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/edit

Entrada

Creaciones

Ver todas las creaciones

Salida

image

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

Precios

ideogram-v3-character/edit per image

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

Descripción general

ideogram-v3-character/edit es un modelo de imágenes orientado a la edición con consistencia de personaje: sube una imagen de origen y una máscara, especifica la región que deseas redibujar y usa exactamente una imagen de referencia del personaje como ancla visual para reescribir partes de la escena conservando el rostro, el peinado, la ropa y la complexión. Es adecuado para desarrolladores que necesitan reutilizar el mismo personaje, mascota o avatar en series de materiales, especialmente en escenarios de producción por lotes donde se busca una identidad visual del personaje uniforme y, al mismo tiempo, escenas y textos variables.

Aspectos destacados

Redibujado local con anclaje de personaje: la imagen de origen y la máscara definen la región de edición, y la imagen de referencia fija la identidad del personaje para cambiar la escena sin cambiar el rostro.
Escena variable con apariencia intacta: mediante el prompt se reemplazan la postura, la iluminación y el fondo, mientras los rasgos centrales del personaje siguen condicionados por la imagen de referencia.
Producción por lotes reproducible: admite una semilla aleatoria fija y, junto con los ajustes de estilo y de velocidad de renderizado, facilita la reproducción estable de series de materiales.

Descripción de capacidades

Edición dirigida por máscara: recibe una imagen de origen y una máscara con la misma relación de aspecto, y solo redibuja la zona cubierta por la máscara; el resto de la imagen permanece sin cambios, lo que resulta adecuado para sustituir fondos o elementos locales.

Fijación de personaje con una sola referencia: se limita a una imagen de referencia (JPEG, PNG o WebP, máximo 10MB), a partir de la cual se restringen los rasgos de apariencia del personaje en el resultado del redibujado.

Escena controlable mediante prompt: un prompt de hasta 5000 caracteres describe la escena objetivo, y se puede activar la expansión de prompt para completar automáticamente detalles de la descripción.

Ajustes de estilo y velocidad: el estilo puede ser AUTO, REALISTIC o FICTION, y la velocidad de renderizado se divide en TURBO, BALANCED y QUALITY, con distintos niveles de detalle según el ajuste.

Casos de uso

Iteración por lotes de materiales de una serie de personajes: los equipos de operaciones y diseño usan la misma imagen de referencia con distintas máscaras para producir por lotes ilustraciones del mismo personaje en múltiples escenas, destinadas a redes sociales y páginas de campaña.
Cambio local de escenario en carteles y gráficos promocionales: se sustituyen el fondo y la iluminación conservando el sujeto del personaje, para obtener gráficos promocionales listos para publicar y materiales con maquetación de texto.
Consistencia de personaje en cómics y storyboards: el autor redibuja con la imagen de referencia de caracterización las posturas y escenas de las viñetas, y produce secuencias visuales coherentes para el storyboard.

Limitaciones y recomendaciones de selección

La consistencia del personaje no es absoluta: en escenas complejas o con posturas y expresiones extremas aún pueden aparecer desviaciones visibles; la imagen de referencia debe tener el rostro nítido, buena iluminación y pocas oclusiones, de lo contrario el resultado empeora. La máscara y la imagen de origen deben mantener la misma relación de aspecto, y solo se acepta una imagen de referencia. Si la tarea es la generación creativa de una imagen independiente y no se necesita fijar el mismo personaje, es más adecuado usar la vía de texto a imagen; los ajustes de detalle QUALITY y superiores alargan el tiempo de generación, por lo que hay que sopesar velocidad y calidad.

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/edit

routestringOpcional

Valor fijo actual: default

inputobjectObligatorio

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

seedintegerOpcionalmin 0max 2147483647

Semilla aleatoria de tipo entero, utilizada para que el resultado de generación de un mismo prompt sea reproducible; su forma de valor es un número entero.

stylestringOpcionalPredeterminado: "AUTO"

Especifica el tipo de estilo empleado en la generación; por defecto, AUTO.

Opciones:AUTOREALISTICFICTION

promptstringObligatoriominLength 1maxLength 5000

Describe la escena en la que se encuentra el personaje de referencia, es decir, el contenido visual que se va a generar en esta edición; longitud máxima de 5000 caracteres.

mask_urlstringObligatoriominLength 1pattern ^https?://

URL de la imagen de máscara que especifica la región que debe redibujarse; la máscara debe mantener la misma relación de aspecto que la imagen de origen.

image_urlstringObligatoriominLength 1pattern ^https?://

URL de la imagen de origen que se va a editar; dicha imagen debe mantener la misma relación de aspecto que la máscara.

expand_promptbooleanOpcionalPredeterminado: true

Interruptor booleano que controla si se usa MagicPrompt para ampliar automáticamente el prompt; por defecto, true.

rendering_speedstringOpcionalPredeterminado: "BALANCED"

Especifica el nivel de velocidad de renderizado: TURBO es el más rápido y económico, QUALITY ofrece el mayor detalle, y cada nivel tiene un precio distinto; por defecto, BALANCED.

Opciones:TURBOBALANCEDQUALITY

reference_image_urlsarrayObligatoriominItems 1maxItems 1

Arreglo de imágenes de referencia del personaje; se requiere 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/edit",
  "input": {
    "style": "AUTO",
    "prompt": "…",
    "mask_url": "…",
    "image_url": "…",
    "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/edit",
    input: {
      "style": "AUTO",
      "prompt": "…",
      "mask_url": "…",
      "image_url": "…",
      "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/edit",
        "input": {
          "style": "AUTO",
          "prompt": "…",
          "mask_url": "…",
          "image_url": "…",
          "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"
    }
  }
}