Как получать удовлетворительные изображения

Получить неудовлетворительное изображение с первой попытки — это нормально — неудовлетворительное ≠ плохая модель, и уж точно ≠ плохой шлюз. На этой странице разбирается реальный случай клиента, чтобы объяснить, почему одна и та же модель ведет себя по-разному в веб-приложении и через API, откуда на самом деле возникает вариативность и какие четыре стратегии заметно повышают вероятность успеха.

​

Разбор случая: правка, в которой цвет получился неверным

Задача: карточка товара игрушечного чайного набора с двумя чашками в левом нижнем углу, выделенными красной рамкой. prompt: Клиент вызвал gemini-3.1-flash-image (Nano Banana 2) через API и получил следующее: Цвет получился неверным — был запрошен чёрный, но результат показывает две зелёные чашки, а красная рамка всё еще на месте. Тем временем клиент выполнил ту же правку с той же моделью в веб-приложении Gemini (gemini.google.com), и там всё сработало хорошо. Их отзыв:

Результат API совершенно отличается от официального (web) результата — кажется, что API просто понимает хуже.

Фрустрация понятна, но с выводом нужно быть аккуратнее. Разберем это по шагам.

​

Сначала поймите: веб-приложение — это агент; API — это один атомарный вызов

Сравнивать результаты gemini.google.com напрямую с сырым API-вызовом — это не сопоставление яблок с яблоками: Одна и та же модель, две формы продукта. Веб-приложение превращает вашу неформальную инструкцию в форму, которую модель выполняет надежнее — в случае API эта доработка лежит на вас (и именно в этом ценность API: все контролируемо, воспроизводимо и легко интегрируется).

​

Вариативность одного вызова присуща генеративным моделям

Мы повторили задачу с тем же самым prompt + image в тестовом инструменте imagen.apiyi.com: с первого раза сработало — чашки стали чёрными, красная коробка была удалена, всё остальное осталось без изменений. Одинаковый ввод, одна и та же модель, один и тот же шлюз — один сбой, один успех. Что это нам говорит? Отдельные выходы генеративной модели по своей природе стохастичны. Каждый вызов — это независимый проход выборки, и составные инструкции (найти по коробке + перекрасить + удалить коробку + сохранить все остальное) — как раз тот тип задач, где в отдельной выборке иногда возникают промахи. Это не проблема шлюза и не API, который стал «упрощённым» — это естественная вариативность модели. Когда вы понимаете, откуда берётся эта вариативность, стратегии становятся очевидны — вот четыре, в порядке эффективности по затратам.

​

Стратегия 1: Улучшите prompt

Чем менее неоднозначен и чем более исполним prompt, тем выше вероятность успеха за один вызов. Рассмотрим этот случай в качестве примера: Исходный prompt (разговорный, полагается на то, что модель сделает выводы):

Измените объекты в красной рамке на черный цвет, удалите красную рамку, все остальное оставьте без изменений

Улучшения: Пример улучшенного полного prompt:

Отредактируйте это изображение и выполните две вещи: ① перекрасьте две чашки внутри красной рамки в матовый чисто черный цвет, сохранив их исходную текстуру материала и форму; ② удалите саму красную рамку. Оставьте цвета, расположение, размерные подписи и текст всех остальных объектов на изображении полностью без изменений.

​

Не знаете, как это улучшить? Попросите ИИ переписать это за вас

Улучшение prompt — это тоже задача, которую можно поручить ИИ: просто отправьте вместе три вещи в известный, надежный чат-сервис с ИИ (например, chatgpt.com или gemini.google.com):

1. Исходный prompt (вставленный дословно);
2. Описание проблемы (например: “попросили черный, а получили зеленый, и красная рамка не была удалена”);
3. Сравнение до/после (загрузите оригинальное изображение и фактический результат вместе).

Затем попросите его “переписать это в более точный, менее неоднозначный prompt для редактирования изображения на основе этого неудачного результата” — обычно за один раунд получается заметно лучшая версия. Если вы не можете открыть эти сайты, APIYI так же хорошо закрывает потребность в чат-общении с ИИ: подключите наш API к чат-клиенту вроде Cherry Studio или Chatbox — см. руководства в разделе «Сценарии - Чат» в документации:

• Руководство по настройке Cherry Studio
• Руководство по настройке Chatbox

​

Стратегия 2: Повторная попытка при сбое

Поскольку сбои возникают из-за дисперсии единичной выборки, повторная попытка сама по себе является эффективным способом устранения проблемы — повторная отправка того же самого запроса часто просто срабатывает (именно это и произошло в данном случае).

• Закладывайте 1–2 автоматические повторные попытки в ваш бизнес-код для случая «результат не соответствует ожиданиям»;
• Различайте два типа сбоев: «изображение вернулось, но правка неверна» и «изображение вообще не вернулось». Второй случай (HTTP 200, но без изображения) обычно означает блокировку из-за модерации контента — см. Руководство по обработке ошибок Gemini Image API.

​

Стратегия 3: Переключение моделей

Для этого случая мы протестировали другие модели с тем же самым prompt + image — все сработали с первой попытки: Разные модели хорошо справляются с разными типами инструкций. Задача, которая постоянно не проходит на одной модели, может сразу пройти на другой. В едином шлюзе APIYI переключение моделей означает изменение только параметра model (тот же ключ, тот же эндпоинт) — почти без дополнительных затрат. Сделайте «переключение моделей» полноценным шагом в вашем image workflow — это легитимная стратегия для достижения цели, а не компромисс. На практике выстройте «сначала быстро, потом мощно» лестницу:

1. По умолчанию используйте быструю и недорогую модель (например, gemini-3.1-flash-image) для рутинных задач;
2. Когда задача точного редактирования не удается 1–2 раза, автоматически переходите к gemini-3-pro-image или серии gpt-image-2 и повторяйте попытку;
3. Если ничего не помогает, вернитесь назад и доработайте prompt.

​

Стратегия 4: Сначала изолируйте проблему с помощью тестового инструмента

Когда вы отлаживаете «почему вывод неверный», сначала изолируйте переменные. imagen.apiyi.com позволяет быстро проверить комбинацию «prompt + image» без написания кода:

• Не работает и в инструменте → скорее всего, проблема в prompt/задаче; вернитесь к Стратегии 1 или переключите модели по Стратегии 3;
• Работает в инструменте, но не в вашем коде → проверьте код: полностью ли загружено изображение, корректны ли параметры, не обрезан ли prompt и не искажён ли он экранированием;
• То работает, то нет → это вариативность sampling; добавьте повторные попытки по Стратегии 2.

Так вы не перепутаете проблему prompt с проблемой шлюза и сэкономите много лишних обходных шагов.

​

Краткая справка

• Web app ≠ API: веб-приложение — это полноценный агент с переписыванием prompt и многошаговой оркестрацией; API — это один атомарный вызов с вашим prompt без изменений — кажущийся разрыв в основном связан с конвейером, а не с тем, что «API понимает хуже».
• Случайная вариативность одного вызова неотъемлема для генеративных моделей — один сбой ничего не говорит ни о модели, ни о шлюзе.
• Стратегия 1, улучшите prompt: конкретные существительные, точные цвета, перечисляйте, что нужно сохранить, нумеруйте действия — меняйте за раз только одну категорию вещей.
• Стратегия 2, повторите попытку: закладывайте 1–2 повторных попытки для «неправильного редактирования»; «нет изображения» — это другая проблема (см. руководство по обработке ошибок).
• Стратегия 3, переключите модели: в этом случае gemini-3-pro-image, gemini-3.1-flash-lite-image и серия gpt-image-2 все сработали с первого раза; на унифицированном шлюзе это изменение одного параметра.
• Стратегия 4, используйте тестовый инструмент, чтобы изолировать проблему: сначала проверьте «prompt + image» на imagen.apiyi.com, чтобы отделить проблемы prompt, проблемы кода и вариативность сэмплирования друг от друга.

​

Связанные документы

• Руководство по обработке ошибок API изображений Gemini
• Сжатие изображений и выходное разрешение
• Руководство разработчика по серии Nano Banana