> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Реальный кейс по редактированию изображений, который объясняет принципиальную разницу между веб-приложением и API, откуда берется вариативность одного вызова и четыре практические стратегии: более удачные prompt, повторные попытки, смена моделей и изоляция проблем с помощью тестового инструмента.

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

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

Задача: карточка товара игрушечного чайного набора с двумя чашками в левом нижнем углу, выделенными красной рамкой. prompt:

<Frame caption="Input image: a red box marks the two cups (one gray, one green) in the lower left; the request is to make them black and remove the box">
  <img src="https://mintcdn.com/apiyillc/YlApNMokaLGR-mkl/images/image-edit-case-teaset-original.jpg?fit=max&auto=format&n=YlApNMokaLGR-mkl&q=85&s=f5b3a4848c8d8256c574ffa72a0fc88a" alt="Карточка товара игрушечного чайного набора с двумя чашками в левом нижнем углу, выделенными красной рамкой" width="1024" height="1021" data-path="images/image-edit-case-teaset-original.jpg" />
</Frame>

Клиент вызвал `gemini-3.1-flash-image` (Nano Banana 2) через API и получил следующее:

<Frame caption="Failed result from a single API call: both cups turned green, and the red box was not removed">
  <img src="https://mintcdn.com/apiyillc/LihN1TRFUvEsZ0oh/images/image-edit-case-teaset-api-result.jpg?fit=max&auto=format&n=LihN1TRFUvEsZ0oh&q=85&s=ba1ec09f532b9266ad0e6012384a98d0" alt="Результат неудачной правки: две чашки в красной рамке стали зелёными вместо запрошенного чёрного, и красная рамка по-прежнему на месте" width="1024" height="1024" data-path="images/image-edit-case-teaset-api-result.jpg" />
</Frame>

**Цвет получился неверным** — был запрошен чёрный, но результат показывает две зелёные чашки, а красная рамка всё еще на месте. Тем временем клиент выполнил ту же правку с той же моделью в веб-приложении Gemini (`gemini.google.com`), и там всё сработало хорошо. Их отзыв:

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

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

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

Сравнивать результаты `gemini.google.com` напрямую с сырым API-вызовом — это не сопоставление яблок с яблоками:

|                | Gemini web app                                                                     | Прямой API-вызов                            |
| -------------- | ---------------------------------------------------------------------------------- | ------------------------------------------- |
| Форма продукта | **Полноценный агент**                                                              | **Один атомарный вызов**                    |
| Ваш prompt     | Может быть **переписан, расширен, улучшен** системой до того, как достигнет модели | Поступает в модель **дословно**             |
| Выполнение     | Возможна многошаговая оркестрация, внутренние повторы/выбор                        | Один sampling-проход, возвращается напрямую |
| Базовая модель | gemini-3.1-flash-image                                                             | gemini-3.1-flash-image (идентична)          |

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

<Info>
  Поэтому «веб-приложение работает лучше» в основном связано с **различиями в pipeline** — это не доказывает, что «API понимает меньше». API получает ваш сырой, необработанный prompt, поэтому результат естественным образом сильнее зависит от качества самого prompt.
</Info>

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

Мы повторили задачу с тем же самым **prompt + image** в тестовом инструменте [imagen.apiyi.com](https://imagen.apiyi.com): **с первого раза сработало** — чашки стали чёрными, красная коробка была удалена, всё остальное осталось без изменений.

<Info>
  Чтобы было понятно: единственное отличие между imagen.apiyi.com и прямым вызовом API — встроенный prompt с намерением «сгенерировать изображение». Он помогает модели зафиксироваться на создании изображения, но никак не влияет на то, успешно ли сработает точное редактирование в этом случае — **инструмент не сработал не потому, что он «добавил секретный соус»**.
</Info>

Одинаковый ввод, одна и та же модель, один и тот же шлюз — один сбой, один успех. Что это нам говорит?

**Отдельные выходы генеративной модели по своей природе стохастичны.** Каждый вызов — это независимый проход выборки, и составные инструкции (найти по коробке + перекрасить + удалить коробку + сохранить все остальное) — как раз тот тип задач, где в отдельной выборке иногда возникают промахи. Это не проблема шлюза и не API, который стал «упрощённым» — это естественная вариативность модели.

Когда вы понимаете, откуда берётся эта вариативность, стратегии становятся очевидны — вот четыре, в порядке эффективности по затратам.

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

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

**Исходный prompt** (разговорный, полагается на то, что модель сделает выводы):

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

**Улучшения**:

| Техника                                              | Исходный вариант                       | Улучшенный вариант                                                                                          |
| ---------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Используйте конкретные существительные вместо ссылок | "объекты в красной рамке"              | "две **чашки** внутри красной рамки"                                                                        |
| Будьте точны в описании цвета                        | "измените на черный"                   | "измените на **матовый чисто черный**, сохранив исходную текстуру материала"                                |
| Перечисляйте, что нужно сохранить                    | "все остальное оставьте без изменений" | "оставьте цвета, расположение и текстовые подписи **всех остальных объектов** на изображении без изменений" |
| Явно нумеруйте действия                              | Все слито в одно предложение           | "Сделайте две вещи: ① перекрасьте две чашки в черный цвет; ② удалите саму красную рамку"                    |

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

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

<Tip>
  Общий принцип: **меняйте за один раз только один тип элементов**. Если правка включает много действий (перекрасить + заменить фон + добавить текст), разбейте ее на несколько раундов редактирования — вероятность успеха в каждом раунде будет значительно выше, чем у одной составной инструкции.
</Tip>

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

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

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

Затем попросите его "переписать это в более точный, менее неоднозначный prompt для редактирования изображения на основе этого неудачного результата" — обычно за один раунд получается заметно лучшая версия.

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

* [Руководство по настройке Cherry Studio](/ru/scenarios/chat/cherry-studio)
* [Руководство по настройке Chatbox](/ru/scenarios/chat/chatbox)

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

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

* Закладывайте 1–2 автоматические повторные попытки в ваш бизнес-код для случая «результат не соответствует ожиданиям»;
* Различайте два типа сбоев: «изображение вернулось, но правка неверна» и «изображение вообще не вернулось». Второй случай (HTTP 200, но без изображения) обычно означает блокировку из-за модерации контента — см. [Руководство по обработке ошибок Gemini Image API](/ru/api-capabilities/gemini-image-error-handling).

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

Для этого случая мы протестировали другие модели с тем же самым prompt + image — **все сработали с первой попытки**:

| Модель                                 | Результат                |
| -------------------------------------- | ------------------------ |
| `gemini-3-pro-image` (Nano Banana Pro) | ✅ Успех с первой попытки |
| `gemini-3.1-flash-lite-image`          | ✅ Успех с первой попытки |
| `gpt-image-2` series                   | ✅ Успех с первой попытки |

Разные модели хорошо справляются с разными типами инструкций. Задача, которая постоянно не проходит на одной модели, может сразу пройти на другой. В едином шлюзе 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](https://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](/ru/api-capabilities/gemini-image-error-handling)
* [Сжатие изображений и выходное разрешение](/ru/api-capabilities/image-compression-resolution)
* [Руководство разработчика по серии Nano Banana](/ru/api-capabilities/nano-banana-dev-guide)