По состоянию на 24 марта 2026 года правильный native base URL для Gemini image generation — https://generativelanguage.googleapis.com/v1beta, а первый path, который большинству разработчиков стоит проверить, — POST /models/gemini-3.1-flash-image-preview:generateContent. https://generativelanguage.googleapis.com/v1beta/openai/ имеет смысл только тогда, когда вы сознательно сохраняете OpenAI-compatible слой.
В этом и состоит реальная проблема запроса. Текущие image-generation docs, API reference и OpenAI compatibility docs показывают части ответа, но не дают одной короткой support-страницы, которая прямо говорит: какой host сейчас считать default для Gemini image generation.
Самый безопасный порядок действий простой. Сначала запустите одну native generateContent request, убедитесь, что она действительно возвращает изображение, и только потом решайте, нужен ли вам OpenAI-compatible route, другой model или проблема вообще находится на уровне quota. Если потом понадобится более широкий контекст, логичнее перейти к Gemini Image Generation Tutorial и примерам кода Gemini image generation.
Что нужно запомнить сразу:
- Новый Gemini image generation лучше начинать с
https://generativelanguage.googleapis.com/v1beta. - Первый полный path для проверки —
/models/gemini-3.1-flash-image-preview:generateContent. https://generativelanguage.googleapis.com/v1beta/openai/нужен только тогда, когда ваш стек реально завязан на OpenAI-compatible client behavior.
Краткое содержание
| Ситуация | Base URL | Какой path держать в голове первым | Когда использовать | Главный caveat |
|---|---|---|---|---|
| Новый native Gemini image generation | https://generativelanguage.googleapis.com/v1beta | /models/gemini-3.1-flash-image-preview:generateContent | Нужен самый прямой текущий Gemini image contract | Image generation по-прежнему живет под generateContent, а не под отдельным /images host |
| Уже есть OpenAI SDK или OpenAI-style tooling | https://generativelanguage.googleapis.com/v1beta/openai/ | Методы вроде images.generate() | Вы хотите минимально менять существующий OpenAI client surface | Image surface уже и некоторые дополнительные параметры могут тихо игнорироваться |
| В AI Studio или app работает, а в коде нет | Чаще это не вопрос base URL как такового | Проверяйте project, key, model и quota | Вы переносите UI-ожидания на API contract | App, AI Studio и API не эквивалентны |
| На самом деле вы в Vertex AI | Не подставляйте Gemini Developer API host по умолчанию | Смотрите Vertex AI endpoint family | Ваш проект живет в Vertex AI | Неверный host тратит время даже при правильной model |
Если оставить одну базовую рекомендацию, она такая: новый Gemini image generation стартует с native Gemini route, а не с OpenAI-compatible host.
На практике полезно добавить еще одно правило порядка. Сначала докажите, что host и model path правильные, потом проверяйте image controls, project quota и только после этого решайте, нужна ли совместимость с OpenAI. Такой порядок резко уменьшает количество ложных гипотез о том, что «сломана сама base URL».
Для native Gemini image generation используйте этот base URL
Официальный Gemini API reference до сих пор описывает image generation внутри семейства generateContent. Поэтому native ответ кажется немного непривычным, если вы ожидаете классический endpoint вида /images/generations. В native Gemini host остается обычным Gemini Developer API host, а image-generation intent определяется связкой model path плюс generateContent.
Базовый host такой:
texthttps://generativelanguage.googleapis.com/v1beta
А первый полный image-generation path, который стоит проверить, такой:
texthttps://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent
Текущие Google docs продолжают ставить gemini-3.1-flash-image-preview в роль fast default, а gemini-3-pro-image-preview — в роль premium branch. Именно поэтому эта страница не стартует со старых 2.5-era image примеров. Для нового интеграционного сценария важнее спросить не “что еще кое-как живо”, а “какой current path Google сейчас реально учит использовать”.
Есть и второй важный аргумент в пользу native route: feature surface. imageSize, aspectRatio, image editing, multi-turn behavior — все это заметно понятнее в native docs. Если вам нужен именно текущий Gemini-native image workflow, native host остается самым ясным default.
Есть и чисто operational плюс. В reference видно, что ключ можно передать либо через ?key=, либо через x-goog-api-key, и это помогает быстрее отделить authentication mistake от ошибки в endpoint family. Сам контракт от этого не меняется, но дебажить становится проще.
Когда /v1beta/openai/ действительно правильный ответ
OpenAI-compatible base URL реален и официально документирован. Google по-прежнему показывает:
texthttps://generativelanguage.googleapis.com/v1beta/openai/
Когда этот вариант действительно уместен? Когда у вас уже есть OpenAI-style SDK, wrapper или внутренняя tooling-обвязка, и вы хотите сохранить существующий client surface с минимальными изменениями. В таком случае compatibility layer имеет смысл.
Но делать этот URL default answer для любого Gemini image question — плохая идея. Google сама пишет: если вы не пользуетесь OpenAI libraries уже сейчас, лучше вызывать Gemini API напрямую. Для image generation это особенно важно. Совместимая документация описывает image flow в основном через gemini-2.5-flash-image и gemini-3-pro-image-preview, а также предупреждает, что неподдерживаемые дополнительные параметры могут silently ignored.
Отсюда и возникает большая часть путаницы. То, что compatibility URL valid, не означает, что он лучший default для вашего кейса. Если вам нужны native image controls или вы хотите идти по текущему Gemini-native docs path, безопаснее начинать с native route.
Практическое правило такое:
- Новый проект, raw REST debugging, current Gemini docs: native route.
- Осознанное сохранение OpenAI-based stack: compatibility route.
- Не смешивайте обе семьи endpoints в одном сеансе отладки без четкого понимания, что именно сравниваете.
Сначала скопируйте одну working REST request
Не стройте сложный workflow до того, как проверите базовый path. Сначала достаточно доказать, что host, model и image response вообще работают.
bashcurl -s -X POST \ "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contents": [{ "parts": [ { "text": "Create a clean 16:9 product hero image of a matte black travel mug on a light concrete surface with soft studio lighting." } ] }], "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" } } }'
Эта request полезна тем, что одновременно подтверждает host, model и native image controls. Если вам нужен premium branch, меняйте model path на:
text/models/gemini-3-pro-image-preview:generateContent
Переходить туда стоит только тогда, когда text rendering внутри изображения, более сложная композиция или более дорогой asset действительно оправдывают это изменение. Если ваш следующий вопрос уже не про URL, а про cost, логичнее идти в Gemini image generation API pricing.
Troubleshooting
Не каждая ошибка image generation — это ошибка base URL. Последние forum threads по Gemini это хорошо показывают. Разработчики видят 404, model not found или ignored parameters и сразу думают, что сломан весь host. На практике причина часто уже и конкретнее.
| Что вы видите | Что это обычно значит | Что делать дальше |
|---|---|---|
| 404 или model not found на OpenAI-compatible image path | Вы используете compatibility endpoint family для модели или поведения, которое лучше ложится на native generateContent | Попробуйте тот же сценарий на native Gemini host |
imageSize или aspectRatio будто не работают | Вы остались на compatibility layer, а нужные image controls не входят в явно поддерживаемый surface | Если эти controls важны, возвращайтесь к native Gemini API |
| В AI Studio или app работает, а в коде нет | UI behavior и API project behavior — не одно и то же | Перед сменой host проверьте API key, project и model availability |
| После исправления URL вы упираетесь в 429 | Host правильный, но bottleneck находится в quota или project tier | Смотрите project-level limits |
| Все выглядит похоже, но результат все равно странный | Вы смешали старые 2.5 examples, native docs и OpenAI-compatible assumptions в одном debugging loop | Зафиксируйте один route, одну model и одну request shape |
Самая недооцененная часть здесь — quota. Текущие rate-limits docs прямо говорят: limits оцениваются per project, а не per API key; requests per day сбрасываются в полночь по Pacific time; preview models имеют более жесткие ограничения. Это значит, что даже при правильном URL request может падать из-за project context.
Вторая ловушка — compatibility behavior. На Google forum уже есть примеры, где OpenAI-compatible image request дает 404, а native generateContent для того же семейства задач работает. Из этого не следует, что compatibility docs бессмысленны. Вывод другой: safest debugging order — сначала доказать native route, а уже потом рассматривать compatibility как migration layer, а не как universal default.
Если ваша проблема уже вышла за рамки URL и превратилась в 429, 400 или 500, следующая полезная страница — Gemini API error fix 2026: 429, 400, 500.
Надежный рабочий ритуал выглядит так: одна native request, один model path, один project context. Только когда этот минимальный сценарий возвращает изображение, имеет смысл сравнивать поведение compatibility layer, прокси, wrapper-обвязки или более дорогих моделей.
Что проверить перед первой request
Если вы хотите сэкономить себе и команде несколько часов на ровном месте, полезно зафиксировать несколько boring, но критичных вещей еще до первой полноценной image request. Большая часть споров про base URL на практике возникает не из-за того, что документация совсем непонятна, а из-за того, что разные люди параллельно тестируют разные hosts, разные models и даже разные project contexts.
Сначала отделите Gemini Developer API от Vertex AI. Эти продукты рядом по тематике, но endpoint family у них разная. Пока это не проговорено вслух, любой 404 или model-not-found легко превращается в ложную гипотезу о том, что «неверен сам host», хотя проблема в том, что тест вообще идет по другому продуктовому контракту.
Дальше удерживайте минимальный debugging surface. Одна model, один host, один способ передачи ключа, одна короткая request shape. Не смешивайте ?key= и x-goog-api-key, native route и OpenAI-compatible layer, старые 2.5 examples и текущие 3.x image models в одном цикле проверки. Чем меньше меняющихся частей, тем быстрее вы понимаете, какая именно переменная реально ломает ответ.
Полезно также сразу записать в repo или внутренний runbook точный endpoint, который уже возвращал картинку. Это звучит слишком просто, но именно здесь команды регулярно теряют время: кто-то копирует path из старого issue, кто-то берет пример из forum thread, кто-то вспоминает прошлую migration attempt, и через неделю одна и та же дискуссия про “правильный base URL” начинается заново.
Последний practical checkpoint — не добавляйте прокси, SDK abstraction, retries и compatibility wrappers до тех пор, пока одна native request не станет стабильно работать в чистом виде. Когда базовый вызов уже подтвержден, каждая следующая надстройка проверяется изолированно. Это намного дешевле, чем одновременно гадать, сломан ли URL, модель, проект, библиотека или собственная обвязка.
Не смешивайте Gemini Developer API, AI Studio и app behavior
Этот keyword сбивает с толку потому, что Google показывает на page one несколько связанных, но разных products.
Gemini Developer API — это тот самый контракт, к которому относится host generativelanguage.googleapis.com. Именно его и разбирает эта страница.
AI Studio — это UI и project surface рядом с API, но оно не превращает задачу в простое “скопировать то, что видно в интерфейсе”. Billing, project и model availability все равно влияют на итог. Официальный billing FAQ говорит, что AI Studio остается бесплатной до подключения paid API key для paid features, но это не меняет того, какой host правильный для native image request.
Gemini app еще дальше от вопроса про base URL. Для ручной генерации и редактирования изображений она полезна, но поведение app — это не тот API contract, который потом будет вызываться вашим кодом. Поэтому app помогает понять product boundary, но не заменяет ответ на endpoint question.
Если вы на самом деле работаете через Vertex AI, это нужно отделить в самом начале. У Vertex AI своя endpoint family, и переносить туда host Gemini Developer API — значит сразу дебажить не тот слой.
Итог
Для текущего Gemini image generation через Gemini Developer API используйте:
texthttps://generativelanguage.googleapis.com/v1beta
И начинайте с:
text/models/gemini-3.1-flash-image-preview:generateContent
Переходить на:
texthttps://generativelanguage.googleapis.com/v1beta/openai/
стоит только тогда, когда ваш проект действительно должен остаться на OpenAI-compatible layer.
Это по-прежнему самый безопасный default, потому что он совпадает с текущими native Gemini docs, лучше сохраняет image contract и предотвращает главную ошибку по этому keyword: считать OpenAI-compatible host универсальным ответом для всех Gemini image requests.
Если нужен предельно короткий internal answer для команды, он звучит так: сначала ставим native host https://generativelanguage.googleapis.com/v1beta, потом проверяем gemini-3.1-flash-image-preview:generateContent, и только если стек осознанно живет на OpenAI semantics, обсуждаем /v1beta/openai/.