Руководство по использованию
Руководство по интеграции Ideogram V3 Character Edit: как подготовить исходное изображение, маску и референс персонажа
Три типа входных изображений со своими ролями: отправляйте локальное редактирование по полям контракта и проверяйте по пунктам согласованность персонажа и границы
На этой странице
За что отвечает каждый из трёх типов изображений
Прежде чем интегрировать ideogram-v3-character/edit, разделите зоны ответственности трёх полей изображений — и все последующие действия по подготовке станут понятнее.
- Исходное изображение
image_url: определяет, «какую сцену менять». Оно задаёт исходную композицию, фон и положение субъекта и служит основой всей операции редактирования. - Маска
mask_url: определяет, «где менять». Она выделяет только область, подлежащую перерисовке; содержимое за её пределами должно сохраниться. - Референс персонажа
reference_image_urls: определяет, «как выглядит персонаж». Он передаёт внешние признаки персонажа, чтобы результат перерисовки соответствовал референсу.
Не смешивайте границы этих трёх полей: исходное изображение — не референс персонажа, и референс персонажа не может заменить исходное изображение; маска — это пространственное ограничение, а не описание содержимого. Наименее подверженный ошибкам способ разделения таков: признаки персонажа — в референс, содержимое сцены — в prompt, область изменений — в маску. Как только вы смешаете их (например, загрузите только изображение персонажа без маски или попытаетесь «намекнуть» маской на внешность персонажа), при поиске проблем у вас не останется точки опоры для суждения.
На уровне контракта исходное изображение и маска — строковые поля URL, а референс персонажа — поле-массив; различие типов тоже подсказывает различие назначения: первые два образуют пространственную пару «один к одному», последний — независимый источник описания человека.

Ключевые моменты подготовки исходного изображения и маски
image_url и mask_url — обязательные поля формата URI, должны начинаться с http:// или https:// (pattern контракта ^https?://), минимальная длина — 1.
Соотношение сторон должно совпадать
Единственное жёсткое геометрическое ограничение контракта для этих двух полей: маска должна иметь то же соотношение сторон, что и исходное изображение. Это не рекомендация, а предпосылка. При подготовке материалов надёжнее всего сначала локально привести маску к размерам исходного изображения, а затем загружать их вместе — не рассчитывайте, что сервер выровняет их за вас.
Семантика маски: выделять только область перерисовки
Маска отмечает места, «допустимые для перерисовки». Следовательно:
- части, которые нужно сохранить, не должны попадать в область маски;
- субъект, который нужно изменить (например, переодеть или изменить позу), должен целиком попадать в маску, чтобы его края не обрезались;
- маску не стоит делать слишком дробной: разрозненные мелкие фрагменты затрудняют понимание моделью замысла редактирования.
Доступность URL
Оба поля — удалённые URL, поэтому перед отправкой обязательно убедитесь, что ссылка доступна анонимно, не имеет неработающих перенаправлений и не требует авторизации для входа. Для маски рекомендуется использовать изображение с альфа-каналом или с чётким чёрно-белым контрастом, чтобы избежать неоднозначности границ из-за полупрозрачных градиентов.
Характеристики и ограничения референса персонажа
reference_image_urls — обязательное поле-массив с явными ограничениями контракта: minItems: 1, maxItems: 1, то есть требуется ровно одно изображение. Передача двух или нуля изображений будет признана недопустимым вводом; это противоречит интуиции многих, кто привык к «референсу из нескольких изображений», и при интеграции здесь легко ошибиться.
Формат и размер
- Поддерживаемые форматы: JPEG, PNG, WebP;
- Максимальный размер одного изображения — 10 MB.
Рекомендации по выбору изображения
Назначение референса персонажа — передать стабильные признаки человека, поэтому:
- Выбирайте чёткое изображение анфас или почти анфас, без перекрытия лица;
- Избегайте сильной контровой подсветки, тяжёлых фильтров и групповых снимков (модель не сможет определить, на кого ориентироваться);
- У полного и поясного кадра есть свои компромиссы: для деталей одежды используйте кадр не меньше поясного, для общего образа — полный рост;
- Не используйте изображение со сложным фоном, чтобы «намекнуть» на сцену — сцену описывайте в
prompt.
Хотя массив вмещает только один элемент, в запросе его всё равно нужно передавать как массив, например обернуть единственный URL в элемент, а не помещать строку напрямую.
Как сочетать обязательные и необязательные поля
Обязательных полей четыре: prompt, image_url, mask_url, reference_image_urls. Необязательные параметры настройки включают expand_prompt, style, seed, rendering_speed.
prompt описывает новую сцену, а не команду редактирования
Определение prompt в контракте очень важно: «опишите сцену, в которой находится референсный персонаж, то есть содержимое изображения, которое нужно сгенерировать в ходе данного редактирования», длина 1–5000 символов. То есть не пишите команды вроде «замени её одежду на красное пальто», а пишите описание сцены вроде «она стоит на улице после дождя в красном пальто, неоновые огни отражаются в мокром асфальте». Область редактирования задаёт маска, prompt отвечает за само содержимое сцены.
expand_prompt включён по умолчанию
expand_prompt — булев переключатель, по умолчанию true; при включении MagicPrompt автоматически расширяет подсказку. Это значит, что ваш краткий запрос будет ещё раз обработан моделью. На этапе отладки рекомендуется сначала оставить значение по умолчанию, а решение о его отключении принимать, лишь поняв разницу между длинным описанием и результатом расширения.
style и seed
- Перечисление
style:AUTO,REALISTIC,FICTION, по умолчаниюAUTO. Для реалистичных людей используйтеREALISTIC, для стилизованных иллюстраций —FICTION, если не уверены — оставляйтеAUTO. seed— целое число в диапазоне от 0 до 2147483647, служит для воспроизведения результата генерации по одной и той же подсказке. Если нужно сравнить «один и тот же ввод с разными параметрами», фиксированный seed исключает влияние случайности.
Выбор уровня rendering_speed
rendering_speed — строковое перечисление, по умолчанию BALANCED, всего три уровня:
- TURBO: самая быстрая генерация, подходит для быстрой проверки на черновом этапе — области маски и соответствия персонажа;
- BALANCED: уровень по умолчанию, компромисс между скоростью и детализацией, отправная точка для повседневной интеграции;
- QUALITY: максимальная детализация, подходит для финальных раундов перед итоговой генерацией.
Подход к выбору — переключение по этапам, а не раз и навсегда: сначала с помощью TURBO убедитесь, что геометрия и направление персонажа в порядке, затем с BALANCED или QUALITY доводите детали. Так при многократной отладке вы не будете тратить время на дорогостоящий рендеринг высокого качества.
Важно подчеркнуть: три уровня различаются по тарификации (оплата по уровню генерации); конкретные цены смотрите на панели цен сайта, в этой статье цифры не приводятся. При поиске проблем с входными изображениями фиксация уровня по умолчанию позволяет убрать одну переменную.

Чек-лист самопроверки перед отправкой
Проверка по пунктам контракта позволяет отсечь большинство ошибок ещё до отправки:
-
promptне пуст и не превышает 5000 символов, его содержимое — описание сцены, а не команда редактирования; -
image_url— анонимно доступная ссылка, начинающаяся сhttp://илиhttps://; -
mask_urlтакже доступна, и её соотношение сторон совпадает с исходным изображением; -
reference_image_urls— массив длиной ровно 1; - формат этого референсного изображения — JPEG/PNG/WebP, размер не превышает 10 MB;
- написание необязательных полей и значения перечислений верны (для
style,rendering_speedиспользуются значения в верхнем регистре, перечисленные в контракте); - если задан
seed, убедитесь, что это целое число 0–2147483647; - если
expand_promptотключён, убедитесь, что самpromptдостаточно полон.
Этот чек-лист также является первой остановкой при устранении неполадок: если какой-либо пункт не выполнен, в первую очередь исправляйте ввод, а не многократно корректируйте описание.
Подход к диагностике отклонений персонажа и проблем с границами
Если результат генерации не соответствует ожиданиям, сначала классифицируйте проблему, а затем целенаправленно корректируйте — это эффективнее, чем повторно отправлять всё изображение.
Тип первый: персонаж не похож
Проявляется в отклонении черт лица, причёски, телосложения от референса. Направления корректировки:
- замените референс: более чёткое изображение анфас, лучшее освещение, один субъект;
- проверьте, не обрезано ли референсное изображение и не сжато ли оно чрезмерно;
- дополните описание персонажа в
prompt(одежда, телосложение, возрастная фактура), чтобы текст и изображение взаимно подтверждали друг друга; - снизьте сложность сцены, чтобы фоновые элементы не отвлекали детали персонажа.
Тип второй: границы размыты
Проявляется в том, что содержимое вне маски непреднамеренно изменено, или на краях маски появляются швы и двоение. Направления корректировки:
- сначала убедитесь, что соотношение сторон исходного изображения и маски строго совпадает;
- проверьте, не попали ли в маску части, которые нужно сохранить;
- добейтесь, чтобы субъект целиком попадал в маску, без обрезания краёв;
- замените маску на вариант с более чёткими краями, сократив полупрозрачные переходы.
Не смешивайте две категории проблем: проблемы персонажа решаются заменой референса и описания, проблемы границ — изменением маски и геометрии. Меняйте только одну переменную за раз, чтобы понять, что именно сработало.
От примера к интеграции
Если превратить требования контракта в процесс, получится четыре шага: подготовить исходное изображение и маску с одинаковым соотношением сторон, выбрать соответствующее требованиям референсное изображение персонажа, описать новую сцену в prompt в формате сцены и проверить поля по чек-листу перед отправкой.
Точка входа для интеграции — на странице модели; определения полей и значения перечислений приведены там же, их можно сверять с чек-листом этой статьи по пунктам: страница модели Ideogram V3 Character Edit. Только при правильно подготовленных материалах последующая оптимизация имеет смысл.
Похожие статьи
Все статьи →-
Руководство по использованию
Руководство по началу работы с gpt-6.2-sol: границы возможностей, интеграция через API и тарификация токенов
Ключевые моменты принятия решений и практики интеграции для инженерных команд
-
Руководство по использованию
Руководство по началу работы с gpt-6.2-astra: границы возможностей текстовой модели, ключевые моменты интеграции и контроль затрат
-
Руководство по использованию
Руководство по началу работы с Tripo H3.1: три способа ввода, параметры и как выбрать тариф
Практическое руководство для разработчиков по принятию решений и контролю затрат при интеграции генерации 3D