Введение
Ideogram Character — модель согласованности, которую Ideogram выпустила 29 июля 2025 года. Этот эндпоинт — её режим генерации: вы загружаете портрет, описываете сцену, которой ещё нет, и модель рисует в ней этого человека. Между запросами ничего не обучается и не сохраняется, поэтому каждый вызов заново считывает сходство с отправленного фото.
Ключевые возможности и особенности
Сходство по одному снимку
Модель считывает с одного референса форму лица, глаза, линию роста волос и стрижку и переносит их в новый свет, новые наряды и ракурсы камеры. В наших тестах портрет женщины с тёмным каре до подбородка и прямой чёлкой сохранил эту стрижку и чёлку на ночном балконе, у зеркала в гримёрке и на рисованной обложке пальп-романа.
Три уровня скорости и три стиля
Turbo, Balanced и Quality меняют время рендеринга, детализацию и цену; Auto, Realistic и Fiction меняют облик, не меняя цену. Наши изображения в Turbo приходили примерно за 20–35 секунд, вызов Balanced на два изображения — примерно за 54 секунды, одно изображение Quality — примерно за 62 секунды. Все полученные результаты были WebP размером 992 на 992 пикселя.
Несколько вариантов за вызов
num_outputs возвращает до четырёх изображений по одному промпту и портрету. Сходство немного различается от варианта к варианту, поэтому два-четыре изображения в Turbo — самый дешёвый способ найти лучшее перед финальным рендером.
Параметры запроса
| Параметр | Обязательно | Описание |
|---|---|---|
prompt | Да | Опишите новую сцену до 5000 символов: место, одежду, позу, свет и камеру. Человека достаточно называть the woman, the man или she. Не менее 1 символов · Не более 5000 символов |
reference_image_urls | Да | Ровно один портрет человека, которого нужно сохранить. Лучше всего резкое фото анфас без помех на лице; JPEG, PNG или WebP до 10 МБ. Не менее 1 элементов · Не более 1 элементов |
quality | Нет | turbo, balanced (по умолчанию) или quality. Старшие уровни работают дольше и стоят дороже за изображение. |
style | Нет | auto (по умолчанию) оставляет выбор модели; realistic стремится к фотографии, fiction — к иллюстрации и стилизованному арту. На цену не влияет. |
num_outputs | Нет | От 1 до 4 изображений по одному промпту и референсу. Каждое изображение оплачивается. |
enable_prompt_expansion | Нет | MagicPrompt включён по умолчанию и расширяет короткий промпт перед рендерингом. Выключите его, чтобы длинный промпт выполнялся дословно. По умолчанию: |
negative_prompt | Нет | Необязательный список того, чего не должно быть, до 5000 символов. При конфликте побеждает основной промпт. Не более 5000 символов |
seed | Нет | Необязательное целое число. Повторное использование с теми же входными данными упрощает сравнение одного изменения, но идентичное изображение не гарантируется. |
Стоимость
Оплата за каждое возвращённое изображение по выбранному уровню (Turbo, Balanced или Quality); отклонённые моделью или незавершённые запросы не оплачиваются.
| Спецификация | Стоимость |
|---|---|
| $0.08 / изображение |
| $0.12 / изображение |
| $0.16 / изображение |
Сценарии использования
Повторяющиеся персонажи
Кадры комикса, развороты детской книги и серии для соцсетей требуют одного и того же героя в каждом изображении. Держите один утверждённый портрет как референс и меняйте от изображения к изображению только текст сцены.
Черновики моды и стилизации
Поместите одну модель в вечернее платье, костюм по фигуре и повседневный уличный образ, чтобы сравнить направления стилизации до настоящей съёмки или объяснить фотографу настроение и свет.
Кадры для питча и раскадровки
Превратите портрет актёра в ключевые моменты питча фильма: балкон ночью, прокуренный бар, улица под дождём. Fiction подходит для рисованных досок, Realistic — для настроенческих кадров, которые должны выглядеть как фото со съёмок.
Руководство по промптам и практические советы
Тратьте слова на изменения
Лицо уже приходит с фото, описывать его в промпте не нужно. Вместо этого называйте обстановку, одежду, позу, выражение, свет и объектив, а человека — the woman, the man или she. Другой цвет волос или иная форма лица спорят с референсом и обычно ослабляют сходство.
Подготовьте чистый референс
Обрежьте до головы и плеч, держите лицо резким и равномерно освещённым, избегайте солнечных очков, масок, рук или волос на глазах. Характерная деталь — чёлка, веснушки или маленькая родинка — даёт ориентир, который можно проверить в каждом результате.
Сначала дёшево, потом качество
Сгенерируйте два-четыре изображения в Turbo, выберите промпт и сид, которые лучше всего держат лицо, и перерендерьте только эту комбинацию в Balanced или Quality. MagicPrompt включён по умолчанию; выключите его, если написали длинный точный промпт и не хотите, чтобы его переписывали.
Быстрый старт 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"
Аутентификация, полная схема, опрос статуса и обработка ошибок описаны в справочнике API.





