Introducción
Ideogram Character es el modelo de consistencia que Ideogram lanzó el 29 de julio de 2025. Este endpoint es su modo de generación: subes un retrato, describes una escena que todavía no existe y el modelo dibuja a esa persona dentro. No se entrena ni se guarda nada entre solicitudes, así que cada llamada vuelve a leer el parecido en la foto que envías.
Funciones y aspectos destacados
Parecido a partir de una sola imagen
El modelo lee la forma de la cara, los ojos, el nacimiento del pelo y el corte en una sola referencia y los lleva a una luz, una ropa y unos ángulos de cámara nuevos. En nuestras pruebas, el retrato de una mujer con melena oscura a la altura del mentón y flequillo recto conservó ese corte y ese flequillo en un balcón de noche, frente a un espejo de camerino y en una portada pintada de novela pulp.
Tres niveles de velocidad y tres estilos
Turbo, Balanced y Quality cambian el tiempo de render, el detalle y el precio; Auto, Realistic y Fiction cambian el aspecto sin cambiar el precio. Nuestras imágenes Turbo llegaron en unos 20 a 35 segundos, una llamada Balanced de dos imágenes en unos 54 segundos y una imagen Quality en unos 62 segundos. Todos los resultados que recibimos fueron WebP de 992 por 992 píxeles.
Varias tomas por llamada
num_outputs devuelve hasta cuatro imágenes con el mismo prompt y el mismo retrato. El parecido varía un poco de toma a toma, así que pedir de dos a cuatro en Turbo es la forma más barata de encontrar la mejor antes del render final.
Parámetros de la solicitud
| Parámetro | Obligatorio | Descripción |
|---|---|---|
prompt | Sí | Describe la escena nueva en hasta 5000 caracteres: lugar, ropa, pose, luz y cámara. Llama a la persona simplemente the woman, the man o she. mínimo 1 caracteres · máximo 5000 caracteres |
reference_image_urls | Sí | Exactamente un retrato de la persona a conservar. Lo ideal es una foto nítida y frontal sin nada que tape el rostro; JPEG, PNG o WebP de hasta 10 MB. mínimo 1 elementos · máximo 1 elementos |
quality | No | turbo, balanced (predeterminado) o quality. Los niveles altos tardan más y cuestan más por imagen. |
style | No | auto (predeterminado) deja decidir al modelo; realistic apunta a la fotografía y fiction a la ilustración y el arte estilizado. No cambia el precio. |
num_outputs | No | De 1 a 4 imágenes con el mismo prompt y la misma referencia. Cada imagen se cobra. |
enable_prompt_expansion | No | MagicPrompt, activado por defecto, amplía un prompt corto antes del render. Desactívalo para que un prompt largo se siga al pie de la letra. Valor predeterminado: |
negative_prompt | No | Lista opcional de cosas que dejar fuera, hasta 5000 caracteres. Si hay conflicto, gana el prompt principal. máximo 5000 caracteres |
seed | No | Entero opcional. Reutilizado con las mismas entradas facilita comparar un solo cambio; no garantiza una imagen idéntica. |
Precios
Se cobra por imagen devuelta al nivel elegido (Turbo, Balanced o Quality); las solicitudes que el modelo rechaza o no termina no se cobran.
| Especificación | Precio |
|---|---|
| $0.08 / imagen |
| $0.12 / imagen |
| $0.16 / imagen |
Casos de uso
Personajes que se repiten
Viñetas de cómic, páginas dobles de un cuento y series para redes necesitan al mismo protagonista en cada imagen. Deja un retrato aprobado como referencia y cambia solo el texto de la escena de una imagen a otra.
Borradores de moda y estilismo
Coloca a una misma modelo con un vestido de noche, un traje a medida y un look urbano informal para comparar direcciones de estilismo antes de una sesión real, o para explicarle a un fotógrafo el ambiente y la luz.
Imágenes de pitch y storyboard
Convierte el retrato de un actor en momentos clave de un pitch de película: un balcón de noche, un bar lleno de humo, una calle con lluvia. Fiction sirve para tableros pintados y Realistic para imágenes de ambiente que deben parecer fotos fijas.
Guía de prompts y consejos prácticos
Usa las palabras en lo que cambia
El rostro ya viene de la foto, así que el prompt no necesita describirlo. Nombra en su lugar el escenario, la ropa, la pose, la expresión, la luz y el lente, y llama a la persona the woman, the man o she. Describir otro color de pelo u otra forma de cara choca con la referencia y suele debilitar el parecido.
Prepara una referencia limpia
Recorta a cabeza y hombros, mantén el rostro nítido y con luz pareja, y evita lentes de sol, mascarillas, manos o cabello sobre los ojos. Un detalle distintivo como un flequillo, pecas o un lunar pequeño te da algo que revisar en cada resultado.
Itera barato y luego sube de nivel
Genera de dos a cuatro imágenes en Turbo, quédate con el prompt y la semilla que mejor sostienen el rostro y vuelve a generar solo esa combinación en Balanced o Quality. MagicPrompt viene activado; desactívalo cuando hayas escrito un prompt largo y preciso que no quieras que se reescriba.
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/text-to-image",
"input": {
"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.





