Blog

Guía de uso

Guía de integración de Ideogram V3 Character Edit: cómo preparar la imagen de origen, la máscara y la imagen de referencia del personaje

Cada uno de los tres tipos de entrada de imagen cumple su función: envíe la edición local según los campos del contrato y verifique punto por punto la coherencia del personaje y los límites

Nov 18, 2026
Imagen de portada del blog: sobre un fondo verde oscuro profundo, dos conjuntos de bandas anchas y planas se entrelazan formando una cuadrícula tejida de carácter técnico, con inserciones verticales en color latón y una geometría contenida.
En esta página

Qué gestiona cada uno de los tres tipos de entrada de imagen

Antes de integrar ideogram-v3-character/edit, conviene separar las responsabilidades de los tres campos de imagen; a partir de ahí, todas las acciones de preparación se vuelven claras.

  • Imagen de origen image_url: determina «qué escena se modifica». Proporciona la composición original, el fondo y la posición del sujeto; es la base de toda la operación de edición.
  • Máscara mask_url: determina «dónde se modifica». Delimita únicamente la región que debe redibujarse; el contenido fuera de esa región debe conservarse.
  • Imagen de referencia del personaje reference_image_urls: determina «cómo es el personaje». Proporciona los rasgos físicos del personaje para alinear el resultado del redibujado con el personaje de referencia.

No mezcle los límites de los tres: la imagen de origen no es la imagen de referencia del personaje, y la imagen de referencia del personaje no puede sustituir a la imagen de origen; la máscara es una restricción espacial, no una descripción de contenido. Delegar los rasgos del personaje a la imagen de referencia, escribir el contenido de la escena en prompt y delimitar el alcance de la modificación con la máscara es la forma de segmentación que menos errores genera. En cuanto se mezclan (por ejemplo, subir solo la imagen del personaje sin máscara, o usar la máscara para «sugerir» el aspecto del personaje), se pierde el criterio para diagnosticar problemas.

A nivel de contrato, la imagen de origen y la máscara son campos de URL de tipo cadena, mientras que la imagen de referencia del personaje es un campo de tipo array; los distintos tipos también indican distintos usos: los dos primeros forman un emparejamiento espacial uno a uno, y el último es una fuente independiente de descripción de la persona.

Las tres entradas no se superponen en paralelo: la imagen de origen, la máscara y la imagen de referencia del personaje se encargan cada una de una región distinta del fotograma de salida; la ilustración expresa esta división mediante tres líneas convergentes.

Puntos clave para preparar la imagen de origen y la máscara

image_url y mask_url son campos obligatorios, de formato URI, deben comenzar por http:// o https:// (patrón del contrato ^https?://) y tener una longitud mínima de 1.

La relación de aspecto debe coincidir

La única restricción geométrica estricta del contrato para ambos es: la máscara debe mantener la misma relación de aspecto que la imagen de origen. No es una recomendación sino un requisito previo; al preparar los materiales, lo más seguro es generar primero la máscara localmente con las dimensiones de la imagen de origen y subirlas juntas, sin esperar que el servidor las alinee.

Semántica de la máscara: solo delimita la región a redibujar

La máscara marca las posiciones «en las que se permite redibujar». Por lo tanto:

  • Las partes que deben conservarse no deben quedar dentro de la región de la máscara;
  • El sujeto que debe modificarse (por ejemplo, cambio de vestuario o de pose) debe quedar completamente dentro de la máscara, evitando que los bordes queden cortados;
  • La máscara no debe ser demasiado fragmentada; los pequeños fragmentos dispersos dificultan que el modelo entienda la intención de la edición.

Disponibilidad de las URL

Ambos campos son URL remotas; antes de enviar, asegúrese de que el enlace sea accesible de forma anónima, no tenga redirecciones inválidas y no requiera autenticación. Para la máscara se recomienda usar una imagen con canal alfa o con un contraste claro entre blanco y negro, para evitar ambigüedad en los bordes por degradados semitransparentes.

Especificaciones y limitaciones de la imagen de referencia del personaje

reference_image_urls es un campo de tipo array obligatorio, y el contrato establece restricciones claras: minItems: 1, maxItems: 1, es decir, se requiere exactamente una imagen. Enviar dos o cero se considerará entrada no válida; esto contradice la intuición de muchas personas acostumbradas a «múltiples imágenes de referencia» y es fácil de pasar por alto al integrar.

Formato y tamaño

  • Formatos admitidos: JPEG, PNG, WebP;
  • Tamaño máximo por imagen: 10 MB.

Recomendaciones para elegir la imagen

La imagen de referencia del personaje sirve para proporcionar rasgos estables de la persona; por lo tanto:

  1. Elija una imagen nítida, frontal o casi frontal, sin obstrucciones en el rostro;
  2. Evite contraluz intenso, filtros excesivos y fotos de grupo (el modelo no puede determinar a quién alinearse);
  3. Cuerpo entero y medio cuerpo tienen ventajas y desventajas: use medio cuerpo o más si necesita detalles de la ropa, y cuerpo entero si necesita la silueta completa;
  4. No use una imagen con un fondo complejo para «sugerir» la escena; la escena se describe en prompt.

Aunque el array solo admite un elemento, debe enviarse como array, por ejemplo, envolviendo una única URL en un elemento, en lugar de colocar la cadena directamente.

Cómo combinar los campos obligatorios y opcionales

Los campos obligatorios son cuatro: prompt, image_url, mask_url y reference_image_urls. Los ajustes opcionales incluyen expand_prompt, style, seed y rendering_speed.

prompt describe una escena nueva, no una instrucción de edición

La definición de prompt en el contrato es clave: «describe la escena en la que se encuentra el personaje de referencia, es decir, el contenido de la imagen que se va a generar en esta edición», con una longitud de 1 a 5000 caracteres. Es decir, no escriba instrucciones de operación como «cámbiale la ropa por una chaqueta roja», sino descripciones de imagen como «ella está de pie en una calle después de la lluvia, con una chaqueta roja, los neones se reflejan en el suelo mojado». El alcance de la edición lo gestiona la máscara; prompt se encarga del contenido de la imagen en sí.

expand_prompt está activado por defecto

expand_prompt es un interruptor booleano, por defecto true; cuando está activado, MagicPrompt amplía automáticamente el texto del prompt. Esto significa que la descripción breve que envíe será reprocesada por el modelo. En la fase de diagnóstico se recomienda mantener el valor por defecto y, tras comprobar la diferencia entre una descripción larga y el resultado de la ampliación, decidir si desactivarlo.

style y seed

  • La enumeración de style es AUTO, REALISTIC, FICTION, con valor predeterminado AUTO. Use REALISTIC para personas realistas, FICTION para ilustración estilizada, y AUTO si no está seguro.
  • seed es un entero, de 0 a 2147483647, que sirve para reproducir el resultado de generación de un mismo prompt. Si desea comparar «misma entrada con distintos parámetros», fijar el seed elimina la interferencia de la aleatoriedad.

Selección del nivel de rendering_speed

rendering_speed es una enumeración de cadenas, con valor predeterminado BALANCED, y tres niveles:

  • TURBO: generación más rápida, ideal para validar rápidamente el alcance de la máscara y si el personaje coincide en la fase de borrador;
  • BALANCED: nivel predeterminado, equilibrio entre velocidad y detalle, punto de partida para la integración diaria;
  • QUALITY: máximo detalle, adecuado para la ronda de definición final antes de la generación definitiva.

El criterio de selección es cambiar según la fase, no fijarlo de una vez: primero use TURBO para confirmar que la geometría y la dirección del personaje son correctas, y luego use BALANCED o QUALITY para refinar los detalles. Así, en la depuración iterativa no se consume tiempo en renderizados de alta calidad.

Cabe destacar: los tres niveles tienen diferencias en el criterio de facturación (se factura según el nivel de generación de imagen); consulte los precios concretos en el panel de precios del sitio; este artículo no entra en cifras. Al diagnosticar problemas de entrada de imagen, fijar primero el nivel predeterminado elimina una variable.

Los tres niveles son como cambios de densidad del mismo tejido: cuanto más arriba, más denso es el tejido, más detalles y más lento.

Lista de verificación antes del envío

Revisar cada punto según el contrato permite evitar la mayoría de los fallos antes del envío:

  • prompt no está vacío y no supera los 5000 caracteres; el contenido es una descripción de escena, no una instrucción de edición;
  • image_url es un enlace accesible de forma anónima que comienza por http:// o https://;
  • mask_url también es accesible y mantiene la misma relación de aspecto que la imagen de origen;
  • reference_image_urls es un array de longitud exactamente 1;
  • El formato de la imagen de referencia es JPEG/PNG/WebP y su tamaño no supera los 10 MB;
  • La ortografía y los valores de enumeración de los campos opcionales son correctos (style y rendering_speed usan los valores en mayúsculas listados en el contrato);
  • Si se estableció seed, confirme que es un entero de 0 a 2147483647;
  • Si se desactivó expand_prompt, confirme que el propio prompt ya es suficientemente completo.

Esta lista es también el primer punto de parada al diagnosticar: si algo no se cumple, corrija primero la entrada en lugar de ajustar repetidamente la descripción.

Enfoque de diagnóstico de desviaciones del personaje y problemas de límites

Cuando el resultado generado no es el esperado, clasifique primero el problema y luego ajuste de forma específica; es más eficaz que reenviar la imagen completa.

Tipo 1: el personaje no se parece

Se manifiesta como desviación en rasgos faciales, peinado o complexión respecto a la imagen de referencia. Direcciones de ajuste:

  • Cambiar la imagen de referencia: una imagen frontal más nítida, mejor iluminación, un solo sujeto;
  • Verificar si la imagen de referencia está recortada o comprimida en exceso;
  • Añadir en prompt una descripción del personaje (ropa, postura, edad, talante) para que texto e imagen se refuercen mutuamente;
  • Reducir la complejidad de la escena para evitar que los elementos del fondo acaparen los detalles del personaje.

Tipo 2: los límites están borrosos

Se manifiesta como contenido fuera de la máscara modificado accidentalmente, o aparición de costuras o fantasmas en el borde de la máscara. Direcciones de ajuste:

  • Confirmar primero que la relación de aspecto de la imagen de origen y la máscara coinciden estrictamente;
  • Verificar si la máscara incluye también partes que debían conservarse;
  • Hacer que el sujeto quede completamente dentro de la máscara, evitando cortes en los bordes;
  • Usar bordes de máscara más definidos, reduciendo las transiciones semitransparentes.

No mezcle ambos tipos de problemas en un mismo ajuste: los problemas de personaje se corrigen con la imagen de referencia y la descripción; los problemas de límites, con la máscara y la geometría. Modifique una sola variable a la vez para poder determinar cuál surtió efecto.

Del ejemplo a la integración

Llevar los requisitos del contrato anteriores a un flujo de trabajo son cuatro pasos: preparar la imagen de origen y la máscara con la misma relación de aspecto, elegir una imagen de referencia del personaje que cumpla las normas, describir la nueva imagen con un prompt contextualizado y verificar los campos según la lista antes de enviar.

El punto de entrada de la integración está en la página del modelo; las definiciones de campos y los valores de enumeración se rigen por la página, y puede compararlos punto por punto con la lista de este artículo: página del modelo Ideogram V3 Character Edit. Si los materiales están bien preparados, el ajuste posterior tiene sentido.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API