HiAPI
Блог

Руководство по использованию

Руководство по интеграции Ideogram V3 Character Edit: как подготовить исходное изображение, маску и референс персонажа

Три типа входных изображений со своими ролями: отправляйте локальное редактирование по полям контракта и проверяйте по пунктам согласованность персонажа и границы

Nov 18, 2026
Обложка блога: на тёмно-зелёном фоне две группы широких плоских полос переплетаются в технологичную плетёную клетку, сквозь них вертикально проходят латунные полосы, геометрия сдержанна.
На этой странице

За что отвечает каждый из трёх типов изображений

Прежде чем интегрировать 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.

Рекомендации по выбору изображения

Назначение референса персонажа — передать стабильные признаки человека, поэтому:

  1. Выбирайте чёткое изображение анфас или почти анфас, без перекрытия лица;
  2. Избегайте сильной контровой подсветки, тяжёлых фильтров и групповых снимков (модель не сможет определить, на кого ориентироваться);
  3. У полного и поясного кадра есть свои компромиссы: для деталей одежды используйте кадр не меньше поясного, для общего образа — полный рост;
  4. Не используйте изображение со сложным фоном, чтобы «намекнуть» на сцену — сцену описывайте в 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. Только при правильно подготовленных материалах последующая оптимизация имеет смысл.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API