API изображений Gemini через прокси
Выберите формат API, создайте изображение и продолжите работу после тайм-аута без повторного создания задачи.
Прокси для API изображений Gemini — это API-шлюз между вашим приложением и моделью генерации изображений Gemini. Для подключения нужны точный ID модели с выводом изображений, формат запроса сервиса и способ получить готовый файл. Замена базового URL в текстовом клиенте сама по себе не подтверждает поддержку генерации изображений.
В OmniaKey документирован следующий порядок: создать задачу → опрашивать её состояние → скачать результат, начиная с POST /v1/media/tasks. Ниже разобран весь процесс и его отличия от нативного API Google и интерфейсов, совместимых с OpenAI.
Документация проверена 14 октября 2026 года. Руководство OmniaKey основано на публичных документах Google и OmniaKey. Мы не запускали платную генерацию и не измеряли скорость или качество провайдеров. Наличие модели в каталоге не гарантирует права вашего ключа или доступный канал в момент запроса.
Какой именно прокси вам нужен
Здесь речь об API-сервисе, который обрабатывает запросы к модели, авторизацию и ответы. Сетевой прокси передаёт трафик, но сам по себе не преобразует один формат API изображений в другой. Ориентируйтесь на опубликованную спецификацию сервиса.
| Интерфейс | Формат запроса | Где искать изображение |
|---|---|---|
| Gemini GenerateContent | /v1beta/models/MODEL:generateContent, поля contents и поддерживаемые настройки generationConfig | Части изображения, например candidates[].content.parts[].inlineData |
| Прокси, совместимый с OpenAI | Эндпоинт и схема изображений, указанные провайдером | Данные или URL изображения в формате конкретного сервиса |
| Задачи изображений OmniaKey | /v1/media/tasks, поля model, type, operation, input, parameters | Сначала ID задачи, затем assets[] при статусе succeeded |
В текущем руководстве Google по изображениям примеры используют Interactions API. Справочник GenerateContent описывает отдельный контракт. Не смешивайте их поля и обработчики ответов и не считайте, что шлюз обязательно предоставляет оба интерфейса.
Распознавание и генерация изображений — тоже разные возможности. Модель может описывать фотографию, но выдавать только текст. Успешный текстовый вызов не проверяет генерацию или редактирование. Пометка «совместимо с OpenAI» также не подтверждает поддержку всех методов SDK для выбранного маршрута.
Выберите конкретную модель изображений
Google различает следующие ID:
- Nano Banana 2.1:
gemini-nano-banana-2.1— рекомендуемая Google отправная точка для новых универсальных сценариев работы с изображениями. - Nano Banana Pro:
gemini-3-pro-image— отдельная модель для более требовательных визуальных задач. - Nano Banana 2:
gemini-3.1-flash-image— предыдущее поколение, а не псевдоним 2.1.
Скопируйте ID из сервиса, к которому обращаетесь. Проверьте права, генерацию и редактирование, размеры и единицу тарификации. Для 2.1 в OmniaKey документированы parameters.aspect_ratio и parameters.image_size со значениями 1K, 2K, 4K. Их нельзя автоматически заменять на Google imageConfig или поля GPT Image size и quality.
Текущие условия смотрите на странице Nano Banana 2.1, а подробный выбор модели — в сравнении 2.1 и Pro.
Создайте изображение через OmniaKey
Потребуются Bash, cURL, jq и ключ OmniaKey в локальной переменной окружения OMNIAKEY_API_KEY. Выполняйте команды на сервере или машине разработчика, не помещайте ключ в браузерный код. Простой английский запрос в примере позволяет сначала проверить работу API, а уже затем оценивать качество.
1. Создайте и сохраните задачу
Выберите уникальный Idempotency-Key для этой логической операции. В примере указан демонстрационный ключ: замените его при создании новой задачи, а при повторах этой задачи сохраняйте ключ и тело неизменными. Запишите оба значения до отправки.
curl --fail-with-body --silent --show-error \
https://api.omniakey.com/v1/media/tasks \
-H "Authorization: Bearer $OMNIAKEY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: gemini-image-demo-20261014-001" \
-d '{
"model": "gemini-nano-banana-2.1",
"type": "image",
"operation": "generate",
"input": {"prompt": "A blue ceramic cup on a white studio table, no text"},
"parameters": {"aspect_ratio": "1:1", "image_size": "1K"}
}' -o task.json
Продолжайте только после успешного завершения cURL и появления id в task.json. Новая задача возвращает 202 Accepted; повтор того же ключа и тела возвращает исходную задачу с 200. Принятие запроса не означает готовность изображения. Подробнее — в документации жизненного цикла задач.
2. Опрашивайте сохранённый ID
Этот пример Bash ограничивает число проверок. После достижения лимита ID остаётся для дальнейшего опроса. Задача не отменяется, новая задача не создаётся.
TASK_ID="$(jq -er '.id' task.json)" || exit 1
for attempt in {1..60}; do
curl --fail-with-body --silent --show-error \
"https://api.omniakey.com/v1/media/tasks/$TASK_ID" \
-H "Authorization: Bearer $OMNIAKEY_API_KEY" \
-o result.json || exit 1
STATUS="$(jq -er '.status' result.json)" || exit 1
case "$STATUS" in
succeeded) break ;;
failed|canceled) jq '.error' result.json; exit 1 ;;
queued|processing) sleep 3 ;;
*) exit 1 ;;
esac
done
Если создание завершилось тайм-аутом до получения ID, повторите то же тело с тем же ключом идемпотентности. Если ID уже есть, запрашивайте существующую задачу. Новый ключ может создать вторую платную операцию. Восстановление ограничено сроком хранения: записи задач сохраняются 24 часа после создания.
3. Скачивайте только успешный результат
jq -e '.status == "succeeded"' result.json >/dev/null || exit 1
ASSET_URL="$(jq -er '.assets[0].url' result.json)" || exit 1
curl --fail --location --silent --show-error \
"$ASSET_URL" -o generated-image
Определите расширение файла по mime_type, затем проверьте, что изображение открывается и имеет ожидаемые размеры. Подписанные URL истекают. Пока задача и файл доступны, повторный запрос может выдать свежий URL. Скачайте результаты для хранения: подписанная ссылка не является постоянным хранилищем.
Редактирование по референсу
Укажите operation: "edit" и передайте встроенные Base64-данные в input.image. Для нескольких референсов используйте input.images, если это поддерживается. Инструкцию оставьте в input.prompt. Полная структура приведена в документации API изображений.
Лимит всего тела запроса составляет 1 MiB, включая Base64. При необходимости сожмите или уменьшите референс. Ограничения загрузки прямого API Google не заменяют лимиты шлюза. Начните с небольшого изображения и одного понятного изменения, затем проверьте детали, которые должны были сохраниться.
Другой запрос, референс, модель или параметр означает новую операцию и требует нового ключа. Прежний ключ с изменённым телом возвращает 409 idempotency_key_reused.
Определите, на каком уровне произошёл сбой
| Симптом | Что проверить | Действие |
|---|---|---|
401 / 403 | Ключ, хост, авторизацию, доступ к модели | Сначала исправьте учётные данные или права |
400 / 404 | Эндпоинт, ID, поля, владельца задачи | Сверьтесь со спецификацией, не угадывайте псевдонимы |
413 | Полный размер тела с Base64 | Уменьшите исходное изображение |
409 idempotency_key_reused | Один ключ с разными телами | Для восстановления верните исходное тело, для новой задачи смените ключ |
429 | Квоту, частоту запросов, параллелизм | Прочитайте ошибку, снизьте нагрузку и при необходимости ограниченно увеличивайте интервалы повторов |
503 | Настройки или временную нехватку мощности | worker_disabled и no_available_channel требуют проверки конфигурации и доступности |
| Только текст или пустой ответ | Поддержку вывода, фильтры безопасности, разбор ответа | В GenerateContent проверьте promptFeedback, finishReason и все части ответа |
| Тайм-аут опроса | Продолжается ли задача | Возобновите опрос по ID, не создавая новую задачу |
Руководство Google по ошибкам описывает поведение Google. Шлюз добавляет ещё один уровень. Записывайте HTTP-статус, код ошибки, ID и длительность без секретов и личных данных. Не сохраняйте в логах ключи и закрытые референсы. JSON с кодом 200 сам по себе не подтверждает пригодность изображения.
Сравните стоимость и проверьте интеграцию
Прямая тарификация Google и цена шлюза — разные предложения. Перед серией запросов проверьте актуальные цены OmniaKey и единицу тарификации модели. Не рассчитывайте изображения по цене текстовых токенов и не считайте, что пользовательская подписка Gemini оплачивает вызовы шлюза.
Полезная метрика: общая списанная сумма ÷ число принятых изображений. Учитывайте оплаченные повторы и результаты, отклонённые при проверке. Это формула для планирования, а не измеренный результат и не обещание самой низкой цены.
Перед ростом нагрузки проверьте пять небольших сценариев:
- Текстовый запрос возвращает открывающийся файл нужного формата и размера.
- Редактирование референса выполняет изменение и сохраняет важные детали.
- Повтор одного ключа и тела возвращает тот же ID задачи.
- После локального тайм-аута опрос продолжается по ID без новой задачи.
- Некорректный параметр или недоступная модель дают понятную ошибку, а не ложный успех.
Фиксируйте модель, параметры, время, конечное состояние, списание и результат проверки. Перед отправкой рабочих материалов изучите условия обработки запросов и референсов.
Частые вопросы
Достаточно заменить базовый URL в SDK?
Только если шлюз документирует нужный эндпоинт, поля и формат ответа с изображением. Проверять нужно саму операцию с изображением, а не только текстовый чат.
Прокси снимает ограничения Gemini?
Нет. Одновременно могут действовать ограничения провайдера, модели, шлюза и аккаунта. Шлюз не гарантирует безлимитную генерацию или доступность в конкретной стране.
С какой модели начать?
Проверьте текущий каталог и оцените поддерживаемую модель на небольшой задаче. Изменения модели разобраны в руководстве Nano Banana 2.1; здесь главное — подключение API и проверка результата.
Источники и следующий шаг
Основные источники: генерация изображений, справочник GenerateContent, устранение ошибок Google и документация OmniaKey по ссылкам выше. Ссылки Google ведут на английские материалы. Спецификации проверены 14 октября 2026 года; перед запуском подтвердите доступ к модели.