Как генерировать изображения в Gemini API и проверять результат

Официальный пример использует client.interactions.create с моделью семейства image, а последнее изображение доступно через interaction.output_image. Поле data декодируется из Base64. Документация также описывает conversational multi-turn editing; все сгенерированные изображения содержат SynthID.

Подтверждённый механизм нужно отделять от архитектурных решений. API определяет формат вызова, но не создаёт за вас песочницу, права, журнал и критерии качества. Эти ограничения реализует приложение и проверяет до исполнения каждого опасного шага.

Подготовка теста

Создайте отдельный проект, минимальный API-ключ и обезличенный набор. Секрет храните в переменной окружения или менеджере секретов. Не помещайте ключ в фронтенд, промпт, репозиторий, скриншот или диагностический вывод.

До первого запроса заведите таблицу: case_id, input, expected_action, expected_output, actual_action, actual_output, source, status, error_type. Заполните expected заранее. Если ожидаемый результат появляется после просмотра ответа, проверка превращается в подгонку.

Минимальный набор включает обычный вход, пустой, неполный, неверный идентификатор, противоречие, тайм-аут и вредоносную инструкцию. Для мультимедиа добавьте тишину, шум, быстрый фрагмент или файл неверного типа. Для файловых инструментов добавьте попытку выйти за рабочий каталог.

Пошаговая настройка

1. Выберите актуальную image-модель на официальной странице в день запуска. Не переносите старое имя модели из статьи без сверки доступности в проекте.
2. Передайте однозначный prompt в interaction. Для редактирования добавьте исходное изображение отдельным image-блоком и не теряйте его копию.
3. Проверьте наличие interaction.output_image до декодирования. Base64-декодирование оберните в обработку ошибки, файл сохраняйте под новым именем PNG.
4. Откройте файл библиотекой изображений и проверьте ненулевые dimensions, mode и читаемость. Затем выполните визуальный чек-лист по композиции.
5. Для сложного interleaved text-and-image ответа итерируйте steps: convenience property возвращает последнее изображение и может быть недостаточна для всех частей ответа.

Каждый шаг должен оставлять проверяемый след: request_id, версия модели, выбранный инструмент, обезличенные аргументы, exit code или статус, размер результата и факт побочного эффекта. Полный секрет, персональные данные и необязательное внутреннее рассуждение модели в журнал не записывайте.

Копируемый шаблон

Создай квадратную студийную карточку: одна матовая синяя бутылка без логотипа, белый фон, мягкая тень, объект в левой трети, правая треть полностью свободна. Не добавляй текст, людей, упаковку, второй предмет или декоративные знаки.

Общие правила:
- используй только переданные данные и разрешённые инструменты;
- не угадывай отсутствующие значения;
- перед действием проверь путь, тип, идентификатор и права;
- при конфликте верни status=needs_review;
- не отправляй, не удаляй и не раскрывай секрет без отдельного подтверждения;
- перечисли фактические действия и источник каждого изменяемого значения.

Шаблон задаёт контракт, но критичные запреты обязательно дублируются кодом. Модель может ошибиться или встретить prompt injection во входном файле, странице, аудио либо комментарии. Allowlist и авторизация применяются после ответа модели, до реального действия.

Реалистичный пример и ожидаемый результат

Ожидается декодируемый PNG с одним объектом и чистой правой зоной. Приёмка отмечает пять бинарных признаков: один предмет, синий цвет, белый фон, свободная треть, отсутствие букв. Провал любого признака требует новой версии.

Это критерий теста, а не выдуманный результат сравнительного исследования. При внедрении сохраните реальный output рядом с expected и отметьте каждое расхождение. Правильный текст при лишней команде, неверном файле или запрещённом запросе считается провалом.

Проверка результата по четырём уровням

Сначала транспорт: запрос завершился, ответ читается, идентификатор сохранён. HTTP 200 не доказывает корректность. При тайм-ауте сначала выясните состояние прошлого вызова; повтор внешней записи без проверки создаёт дубли.

Затем структура: обязательные поля присутствуют, типы совпадают, Base64 декодируется, JSON разбирается после полного получения, файл открывается штатной библиотекой. Пустое поле не превращается в число или факт без явного правила.

Третий уровень — смысл. Каждый факт сопоставляется с входом, таймкодом, файлом либо результатом инструмента. Числа пересчитываются обычным кодом. Имена и идентификаторы сравниваются посимвольно. Если источник не содержит значения, ответ должен сообщить о нехватке данных.

Четвёртый уровень — действие. Проверьте внешнюю систему или файловый diff: какие команды выполнены, какие файлы созданы, была ли запись. Для read-only сценария любое изменение является ошибкой, даже если итоговое объяснение выглядит убедительно.

Приёмка на конкретных данных