Введение
Это часть Ideogram Character, отвечающая за редактирование по маске; саму модель согласованности по одному фото Ideogram выпустила в июле 2025 года. Вместо того чтобы придумывать сцену по тексту, она начинает с уже имеющегося изображения и перерисовывает только отмеченную область, помещая туда человека с вашего портрета-референса. Всё за пределами маски остаётся прежним.
Ключевые возможности и особенности
Перерисовать одну область, сохранить остальное
Чёрное в mask_url перерисовывается, белое сохраняется. В нашем тесте с джаз-клубом мы закрасили голову певицы: золотое платье в пайетках, микрофон, оркестр и красный занавес вернулись нетронутыми, а лицо и волосы стали как у женщины с тёмным каре из референса.
Исходное изображение задаёт кадр
Отредактированное изображение сохраняет пропорции image_url; наш вертикальный снимок сцены вернулся размером 866 на 1154 пикселя. Поэтому этот эндпоинт — способ получить неквадратный результат с вашим персонажем, ведь генерация сцен всегда возвращает квадрат.
Те же уровни и стили, что и при генерации
Turbo, Balanced и Quality задают скорость и цену за изображение, Auto, Realistic и Fiction — облик, а один вызов может вернуть до четырёх перерисованных вариантов. Наши правки в Turbo занимали примерно от 25 до 50 секунд.
Параметры запроса
| Параметр | Обязательно | Описание |
|---|---|---|
prompt | Да | Опишите только то, что заполняет чёрную область: человека, выражение, одежду и свет, до 5000 символов. Не менее 1 символов · Не более 5000 символов |
image_url | Да | Изображение для правки в JPEG, PNG или WebP до 10 МБ. Результат сохраняет его пропорции. |
reference_image_urls | Да | Ровно один портрет человека для замаскированной области, лицо хорошо видно, до 10 МБ. Не менее 1 элементов · Не более 1 элементов |
mask_url | Да | Чёрное — область для перерисовки, белое сохраняется. Используйте те же пропорции, что у |
quality | Нет | turbo, balanced (по умолчанию) или quality. Старшие уровни работают дольше и стоят дороже за изображение. |
style | Нет | auto (по умолчанию), realistic или fiction. Меняет облик, но не цену. |
num_outputs | Нет | От 1 до 4 перерисованных вариантов за запрос; каждое изображение оплачивается. |
enable_prompt_expansion | Нет | MagicPrompt включён по умолчанию и переписывает короткие промпты перед рендерингом. Для длинных точных промптов выключите его. По умолчанию: |
seed | Нет | Необязательное целое число для повторяемых сравнений; идентичное изображение не гарантируется. |
Стоимость
Оплата за каждое возвращённое изображение по выбранному уровню, по тем же ценам, что и генерация сцен; отклонённые и неудачные запросы не оплачиваются.
| Спецификация | Стоимость |
|---|---|
| $0.08 / изображение |
| $0.12 / изображение |
| $0.16 / изображение |
Сценарии использования
Замена лица в готовом макете
Эскиз постера, обложка альбома или рекламный макет часто приходят с временным лицом. Замаскируйте голову и перерисуйте её утверждённым человеком — все остальные части дизайна останутся нетронутыми.
Исправление согласованности в серии
Если персонаж «поплыл» на одном изображении серии, замаскируйте лицо и перерисуйте его по тому же портрету, что и везде, вместо того чтобы генерировать кадр заново.
Человек на снимке локации
Сначала снимите или найдите локацию, замаскируйте место, где должен стоять человек, и дайте модели вписать его со светом этой сцены.
Руководство по промптам и практические советы
Делайте маску с запасом
Закрасьте голову и немного волос и шеи вокруг, чтобы новая линия роста волос слилась со сценой. Держите маску в тех же пропорциях, что image_url; всё, что осталось белым, гарантированно сохраняется. На странице маску можно нарисовать прямо поверх загруженного изображения.
Описывайте только содержимое маски
Промпт — о том, что появится внутри маски, например женщина с тёмным каре поёт с закрытыми глазами под красным сценическим светом. Повторять всю сцену не нужно, а просьбы об изменениях за пределами маски не действуют.
Меняйте одежду сдержанно
Большие маски на теле подходят для правки одежды и позы, но в наших тестах этот режим смягчал запросы для взрослых, а не рисовал их. Для сцен с большей свободой используйте эндпоинт генерации с тем же портретом.
Быстрый старт 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"
Аутентификация, полная схема, опрос статуса и обработка ошибок описаны в справочнике API.





