Introducción
Esta es la parte de edición con máscara de Ideogram Character, el modelo de consistencia de una sola foto que Ideogram lanzó en julio de 2025. En lugar de inventar una escena a partir de texto, parte de una imagen que ya tienes y redibuja solo la zona que marcas, colocando ahí a la persona de tu retrato de referencia. Todo lo que queda fuera de la máscara se mantiene.
Funciones y aspectos destacados
Repintar una zona y conservar el resto
El negro de mask_url se redibuja y el blanco se preserva. En nuestra prueba de club de jazz pintamos de negro la cabeza de la cantante: el vestido de lentejuelas doradas, el micrófono, la banda y el telón rojo volvieron intactos, y el rostro y el cabello pasaron a ser los de la mujer de melena oscura de la referencia.
La imagen original define el encuadre
La imagen editada conserva las proporciones de image_url; nuestra foto vertical del escenario volvió en 866 por 1154 píxeles. Por eso este endpoint es el camino para obtener un resultado no cuadrado con tu personaje, ya que la generación de escenas siempre devuelve un cuadrado.
Mismos niveles y estilos que la generación
Turbo, Balanced y Quality fijan la velocidad y el precio por imagen, Auto, Realistic y Fiction fijan el aspecto, y una llamada puede devolver hasta cuatro versiones repintadas. Nuestras ediciones en Turbo tardaron entre 25 y 50 segundos aproximadamente.
Parámetros de la solicitud
| Parámetro | Obligatorio | Descripción |
|---|---|---|
prompt | Sí | Describe solo lo que llena la zona negra: la persona, la expresión, la ropa y la luz, hasta 5000 caracteres. mínimo 1 caracteres · máximo 5000 caracteres |
image_url | Sí | La imagen a editar, en JPEG, PNG o WebP de hasta 10 MB. El resultado conserva sus proporciones. |
reference_image_urls | Sí | Exactamente un retrato de la persona que va en la zona enmascarada, con el rostro bien visible, hasta 10 MB. mínimo 1 elementos · máximo 1 elementos |
mask_url | Sí | El negro marca la zona a redibujar y el blanco se conserva. Usa las mismas proporciones que |
quality | No | turbo, balanced (predeterminado) o quality. Los niveles altos tardan más y cuestan más por imagen. |
style | No | auto (predeterminado), realistic o fiction. Cambia el aspecto, no el precio. |
num_outputs | No | De 1 a 4 versiones repintadas por solicitud; cada imagen se cobra. |
enable_prompt_expansion | No | MagicPrompt, activado por defecto, reescribe los prompts cortos antes del render. Desactívalo para prompts largos y exactos. Valor predeterminado: |
seed | No | Entero opcional para comparaciones repetibles; no garantiza una imagen idéntica. |
Precios
Se cobra por imagen devuelta al nivel elegido, con las mismas tarifas que la generación de escenas; las solicitudes rechazadas o fallidas no se cobran.
| Especificación | Precio |
|---|---|
| $0.08 / imagen |
| $0.12 / imagen |
| $0.16 / imagen |
Casos de uso
Cambiar el rostro de un diseño terminado
Una maqueta de póster, una portada de álbum o una maqueta de anuncio suelen llegar con un rostro provisional. Enmascarar la cabeza y repintarla con la persona aprobada mantiene intacto todo lo demás del diseño.
Corregir la continuidad de una serie
Cuando un personaje se desvía en una imagen de una serie, enmascara el rostro y repíntalo con el mismo retrato que usas en las demás, en lugar de regenerar toda la imagen.
Poner a una persona en una foto de locación
Fotografía o consigue primero la locación, enmascara el lugar donde debe estar la persona y deja que el modelo la dibuje con la luz de esa escena.
Guía de prompts y consejos prácticos
Haz la máscara generosa
Pinta de negro la cabeza más un pequeño margen de cabello y cuello para que el nuevo nacimiento del pelo se integre en la escena. Mantén la máscara con las mismas proporciones que image_url; lo que dejes en blanco se conserva con seguridad. La página te permite dibujar la máscara directamente sobre la imagen subida.
Describe solo el contenido enmascarado
El prompt trata de lo que aparece dentro de la máscara, por ejemplo la mujer de melena oscura que canta con los ojos cerrados bajo una luz roja de escenario. No hace falta repetir toda la escena, y pedir cambios fuera de la máscara no tiene efecto.
Mantén moderados los cambios de vestuario
Las máscaras grandes sobre el cuerpo sirven para ajustar ropa y pose, pero en nuestras pruebas este modo suavizó las solicitudes para adultos en lugar de dibujarlas. Para escenas con más libertad, usa el endpoint de generación con el mismo retrato.
Inicio rápido de la API
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "ideogram/character/edit",
"input": {
"image_url": "https://example.com/reference.png",
"mask_url": "https://example.com/reference.png",
"num_outputs": 1,
"prompt": "A ceramic teapot on a linen cloth, soft window light, muted palette",
"quality": "balanced",
"reference_image_urls": [
"https://example.com/reference.png"
],
"style": "auto"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Consulta la referencia de la API para autenticación, el esquema completo, sondeo y gestión de errores.





