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
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.

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:
- Elija una imagen nítida, frontal o casi frontal, sin obstrucciones en el rostro;
- Evite contraluz intenso, filtros excesivos y fotos de grupo (el modelo no puede determinar a quién alinearse);
- 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;
- 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
styleesAUTO,REALISTIC,FICTION, con valor predeterminadoAUTO. UseREALISTICpara personas realistas,FICTIONpara ilustración estilizada, yAUTOsi no está seguro. seedes 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.

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:
-
promptno 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_urles un enlace accesible de forma anónima que comienza porhttp://ohttps://; -
mask_urltambién es accesible y mantiene la misma relación de aspecto que la imagen de origen; -
reference_image_urlses 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 (
styleyrendering_speedusan 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 propiopromptya 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
promptuna 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 →-
Guía de uso
Guía de inicio con gpt-6.2-sol: límites de capacidad, integración vía API y consideraciones sobre el precio por token
Puntos clave de decisión e implementación de la integración para equipos de ingeniería
-
Guía de uso
Guía de inicio de gpt-6.2-astra: límites de capacidad del modelo de texto, puntos clave de integración y control de costes
-
Guía de uso
Guía de inicio de Tripo H3.1: cómo elegir entre tres modos de entrada, parámetros y precios
Guía práctica de decisiones de integración y control de costes de la generación 3D para desarrolladores