- Настройка Gemini Pro API вкратце
- Как получить ключ Google API для Gemini
- Как вызвать нативный эндпоинт Gemini API
- Как использовать Gemini с клиентом, совместимым с OpenAI
- Как выбирать и управлять ID моделей Gemini
- Как создать бэкенд с переключаемым провайдером
- Когда открытая модель подходит лучше
- Распространенные ошибки Gemini API
- Заключение
- ЧЗВ
- Рекомендуемые статьи
Gemini Pro API доступен через Gemini API с ключом, созданным в Google AI Studio. Для прямого REST-запроса вызывайте эндпоинт generateContent модели; для существующей интеграции с OpenAI SDK направьте клиент на совместимый с OpenAI базовый URL Google и используйте текущий ID модели Gemini, например gemini-3.1-pro-preview. Важная деталь: «Gemini Pro» — это поисковый термин для семейства продуктов, а не постоянный идентификатор API, поэтому в production-приложениях перед закреплением ID следует сверяться с текущим списком моделей Google.
Настройка Gemini Pro API вкратце
Для выполнения запроса вам понадобятся четыре значения:
| Параметр | Значение |
|---|---|
| API-ключ | Создайте в Google AI Studio |
| Основной хост | https://generativelanguage.googleapis.com |
| Путь нативного API | /v1beta/models/{model}:generateContent |
| Совместимый с OpenAI базовый URL | https://generativelanguage.googleapis.com/v1beta/openai/ |
| Пример ID модели | gemini-3.1-pro-preview |
В кратком руководстве по Gemini API описано создание API-ключа и шаблон нативного запроса. В руководстве по совместимости с OpenAI описан совместимый базовый URL для приложений, которые уже используют OpenAI Python или JavaScript SDK.
Используйте нативный Gemini SDK или REST API, когда вам нужны специфические функции Gemini сразу после их появления. Используйте слой совместимости, если у вас уже есть клиент OpenAI и вы хотите сократить работу по миграции. Совместимость полезна, но она не гарантирует, что все параметры, специфичные для провайдера, будут идеально сопоставлены между API.
Как получить ключ Google API для Gemini
Создайте ключ в Google AI Studio, затем сохраните его в переменной окружения вместо размещения в исходном коде:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
Относитесь к этому как к серверным учётным данным. Не фиксируйте его в Git, не выводите в логи и не встраивайте в клиентский JavaScript или мобильное приложение. Если фронтенду нужен вывод Gemini, отправляйте запрос пользователя на свой бэкенд и пусть бэкенд вызывает Google API.
Для production-сервиса также решите, кому принадлежит проект Google Cloud, как ротируются ключи, какие среде получают отдельные учётные данные и где контролируются квоты запросов. В руководстве по API-ключам Google поясняется, как ключи Gemini API связываются с проектами Google Cloud.
Как вызвать нативный эндпоинт Gemini API
Нативный REST-маршрут помещает ID модели в URL. Этот пример зставляет текщую предварительную Pro-модель вернуть краткий чек-лист миграции:
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"parts": [
{
"text": "Составьте чек-лист из сем шагов для миграции Python API из одного региона в два. Включите проерки отката."
}
]
}
]
}'
Ответ сдержит candidates со сгенерированным сдержанием. Реальные приложения долны обабатывать пустой список candidates, заблокированное сдержание, таймауты и не-2xx ответы, а не обращаться напрямую к первому объекту ответа.
URL использует v1beta, потому что это маршрут, показанный в текщих примерах Gemini API от Google. Храните версию API в конфигурации, чтобы тестировать новую версию без разбрасывания строк эндпоинта по всей кодовой базе.
Анатомия нативного эндпоинта
Путь состоит из теёх частей:
/v1beta/models/{model}:generateContent
v1beta— версия API.{model}— точный ID модели со странцы моделей Gemini.generateContent— метод генеации.
Ответ 404 часто означат, что ID модели, версия API или метод не совпадают. Прежде чем менять код аутентификации, сравните полный путь с текщей документацией по модели.
Как использовать Gemini с клиентом, совместимым с OpenAI
Если ваше приложение уже использует пакет OpenAI Python, установите его и змените API-ключ, базовый URL и ID модели:
pip install openai
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
response = client.chat.completions.create(
model="gemini-3.1-pro-preview",
messages=[
{
"role": "system",
"content": "Вы — кракий рецензент программной архитектуры.",
},
{
"role": "user",
"content": "Проанлизируйте дизайн воркер ачередей и перечислите пяь осноных режимов отказа."
}
],
)
print(response.choices[0].message.content)
Это самый короткий путь для команд с существующей асракцией чат-завершений. Он также облегчает повторное использование тествой обвязки: оставляйте промпт и проверки ответа неизменными, затем меняйте конфигурацию провайдера.
Не преполагайте идентичного повеения только потому, что два провайдера принмают один и тот же вызов SDK. Системные инструкции, схемы инструментов, мультимодальные вводы, обработка безопасности, стримные события, учёт токенов и полезные нагрузки ошибок могут отличаться. Перед переключением production-трафика проводите тесты, сцифичные для провайдера.
Как выбирать и управлять ID моделей Gemini
Избегайте размещения маркетингового названия, такое как gemini-pro, напрямую в логике приложения. Достпные ID моделей Google меняются по мере того, как предварительные модели вводятся, продвигаются и выводятся из эксплуатации. На момент проверки этого руководства официальная страница моделей Google содержала gemini-3.1-pro-preview как идентификатор Pro-класса.
Используйте слой конфигурации:
import os
GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview")
Этот небольшой выбор делает обновление модели измнением конфигурации, а не перепиской кода. Для более крупного сервиса храните эти поля вместе:
{
"provider": "google",
"base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
"model": "gemini-3.1-pro-preview",
"timeout_seconds": 60
}
Прежде чем переносить новую модель в production:
- Убедитесь, что ID присустввует в текщей документации по моделям Google или модельном API.
- Проверьте, явояется ли модель предварительной, стабильной или намечаена к вывод из эксплуатации.
- Запустите собствнную оценчную выборку для качеств ответов и правильности вызвов инструментов.
- Измерте латентность, испльзование токнов и частоту отказов на репрезнтативных промптах.
- Добавьте запасную модель или чёткий путь отказа перед переключением всего трафика.
Ограничение скрости — это не единый универсальный номер. Они зависят от модели и тарифного уровня, поэтому изучите документацию по огранчениям скрости Gemini API и отслеживайте лимиты, применямые к вашему проекту.
Как создать бэкенд с переключаемым провайдером
Интерфейс, совместимый с OpenAI, может сокротить измнения кода, но переключение провайдера работает лучше всего, когда ваше собствнное приложение определяет конракт. Храните конфигурацию провайдера вне бизнес-логики и нормлизуйте вывод, который вам действительно нужен.
import os
from openai import OpenAI
PROVIDERS = {
"gemini": {
"api_key": os.environ["GEMINI_API_KEY"],
"base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
"model": os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview"),
},
"novita": {
"api_key": os.environ["NOVITA_API_KEY"],
"base_url": "https://api.novita.ai/openai",
"model": os.getenv("NOVITA_MODEL", "xiaomimimo/mimo-v2.5-pro"),
},
}
def generate(provider_name: str, prompt: str) -> str:
provider = PROVIDERS[provider_name]
client = OpenAI(
api_key=provider["api_key"],
base_url=provider["base_url"],
)
response = client.chat.completions.create(
model=provider["model"],
messages=[{"role": "user", "content": prompt}],
)
return response.choices[0].message.content or ""```
Этот пример намеренно раскрывает разичия вмест их скрытия. Каждый провайдер хранит своё учётное имя, базовый URL и ID модели. Приложение получает одну нормлизованную строку, в то время как тесты, сцифичные для провайдера, могут охватывать более богатое поведение, такое как инструменты или мультимодальные вводы.
В [документации по LLM API Novita AI](https://novita.ai/docs/guides/llm-api) использутся форма API, совместимого с OpenAI, для поддерживаемых моделей. Это может быть полезно, когда команда хочет сравнивать Gemini с открытыми моделями без перестройки всего клиентского слоя.
## Как Gemini вписывается в бэкенд агента
Бэкенд агента имеет по крайней мере две отдельные отвественности:
1. **Инференция:** Модель решает, что сказать или какой инструмент вызвать.
2. **Выполнение:** Контролиуемая среда выполняет действия с файами, шеллом, браузером или приложением.
API Gemini может обрабатывать сторону инференции. Его не следует рассматривать как границу выполнения. Если модель предлагает команду оболочки, ваше приложение всё равно должно проверить вызываемый инструмент, авторизовать его, выпустить в изолированной среде, зафиксировать результат и решить, какой контекст вернуть модели.
[Песочница агентов Novita AI](https://novita.ai/docs/guides/sandbox-overview) предназначена для изолированных раобчих процесов агентов. Практическая архектура может испльзовать Gemini для рассуждения, в то время как песочница обрабатывает кодовые или браузерные адачи отделно:
```text
Запрос пользователя
-> Сервис агента
-> Gemini API для рассуждения и выбора инструмента
-> Проверка политики для предложенного действия
-> Песочница агентов для изолированного выполнения
-> Результат инструмента возвращается сервису агента
-> Gemini API для итогового ответа
Это разделение делает модель заменимой и держит недовереное выполнение вдали от серверного приложения. Таже оно даёт бэкенду одно место для принудительного применения тайм-аутов, сетевой политики, ограничений на файлы, аудит-логов и авторизации пользователей.
Для первой версии предоставьте только несколько узких инструментов, определите JSON-схемы для их аргументов, отвергайте неизвесные поля и установите жёсткие лимиты на время выполнения и объём вывода. Добавляйте более широкие возможности управления компьютером или браузером только после того, как прояснится модель разрешений.
Когда открытая модель подходит лучше
Модели Gemini Pro — это сильный вариант, когда вашему приложению нужны возможности моделей Google и управляемый API. Открытая модель может подойти лучше, когда вам нужен второй провайдер, вы хотите оценить поведение модели по отношению к видимой вышестоящей версии или предпочитаете модель, доступную через совместимый с OpenAI эндпоинт наряду с другой инфраструктурой.
MiMo-V2.5-Pro — один из текщих вариантов на Novita AI. В картечке модели от Xiaomi она описывается как открытая модель смеси эксепртов (Mixture-of-Experts), в то время как Novita AI предоставляет хостированный ID модели xiaomimimo/mimo-v2.5-pro. Поскольку эндпоинт совместимости Google и Novita AI можно вызывать с помощью клиента стиля OpenAI, переключаемый провайдером патерн, показанный в преыдущем разделе, может оценивать их с одинаковыми прмптами и проверками принтия.
Не выбирайте только по ярлыку. Составьте небльшую выборку оценки из вашей реальной нагрузки: комментарии к ревю кода, вопросы подержки, ответы на основе поиска, вызовы инструментов или длинные документы. Сравните качество вывода, латентность, поведение при ошбках и стоимость, испльзуя текщие панели провайдера, прежде чем принять решение о маршрутизации.
Распространенные ошибки Gemini API
400: Неверный запрос
Проверьте форму JSON, роли сообщений, определенния инструментов и имена параметров. Параметр, принмаемый другим совместимым с OpenAI провайдером, может не принматься слом совместимости Google.
401 или 403: Ошибка аутентификации или разрешений
Убедитесь, что GEMINI_API_KEY присствует в окружении процесса и приналежит предполагаемому проекту Google Cloud. Также проверьте, доступны ли проект и выбранная модель для учётной записи и региона.
404: Модель или метод не найдены
Сравните точный ID модели с текщим списком моделей Gemini. Для нативных REST-вызовов проверьте версию API и суффикс :generateContent. Для вызовов, совместимых с OpenAI, проверьте, что базовый URL заканчивается на /v1beta/openai/.
429: Превышена квота запросов
Повторите попытку с экспоненциальным отступлением и джеером, но не расматривайте повторые попытки как замену пларивания ёмкости. Ставьте в очердь пакетные работы, ограничьте паралельные запросы и изучите текущий тарифный уровень проекта и лимиты, специфичные для модели.
SDK работает, но вывод отличается после переключения провайдера
Совместимость охватывает интерфейс запроса, но не идентичное поведение модели. Запускайте тесты промпта, структурированного вывода и вызовов инструментов для каждого провайдера и версии модели.
Заключение
Начинайте с нативного Gemini API, когда вам нужен самый понятный путь к специфическим функциям Gemini. Начинайте с эндпоинта, совместимого с OpenAI, если у вас уже есть бэкенд в стиле OpenAI или вам нужна быстрая оценка провайдера. В обоих случаях храните API-ключ на стороне сервера, поместите ID модели в конфигурацию, тестируйте точную версию модели и отделяйте рассуждение модели от выпоннения агентом.
Для отказоустойчивого прозводственного дизайна держите по крайней мере одну альернативную модель за тем же интерфейсом, принадлежащим приложению. Это даёт вашей команде прктический способ тестировать открытый вариант на Novita AI, обрабатывать жизненный цикл модели и направлять выполнение агента в изолированную песочницу вместо того, чтобы связывать каждую отвественность с одним вызовом API.
ЧЗВ
Существует ли ещё ID модели gemini-pro?
Не преполагайте, что gemini-pro — это текщий ID. «Gemini Pro API» часто использутся как посковый запрос для моделей Google более высокой категории, но приложения долны испльзовать точный ID с текщей страницы моделей Gemini. В этом руководств gemini-3.1-pro-preview использутся в качестве проверенного примера.
Где взять ключ Google API для Gemini?
Создайте ключ Gemini API в Google AI Studio. Храните его в серверном секрете, например GEMINI_API_KEY, а не в исходном коде или клиентском JavaScript.
Какой эндпоинт у Gemini API?
Основный хост: https://generativelanguage.googleapis.com. Запрос генерации контента использут /v1beta/models/{model}:generateContent. Совместимый с OpenAI базовый URL Google: https://generativelanguage.googleapis.com/v1beta/openai/.
Отличается ли Gemini Studio API от Gemini API?
Google AI Studio — это веб-интерфейс, который разрабочики испльзуют для экспериментов и создания ключа. Запросы приложения идут к Gemini API. Поиски «Gemini Studio API» обычно относятся к этому рабчему потоку от AI Studio к API.
Является ли Google Bard API тем же, что и Gemini API?
Gemini — это текщий брнд API и модели. Старые поиски Google Bard API долны испльзовать текущую документацию, эндпоинты и ID моделей Gemini вмест примеров старого Bard.
Могу ли я испльзовать OpenAI SDK с Gemini?
Да. Google документирует эндпоинт совместимости с OpenAI. Установите базовый URL клиента на URL совместимости Google, прдоставьте свой API-ключ Gemini и выберите поддерживаемый ID модели Gemini. Тестируйте сцифичные для провайдера функции, прежде чем полагаться на полную поведнческую паралель.
Может ли Gemini выпонять код для AI-агента?
Gemini может рассуждать о коде и предлагать вызовы инструментов, но выполнение долно происходить в контролируемой среде. Держите вызов модели отдельно от изолированной среде, такой как Песочница агентов, и проверяйте каждое запрошенное действие перед его выпонением.
Существует ли беплатный тариф для ценообразования Gemini API?
Да. Googleо заявлят, что новые учётные записи начинают с Беплатного тарифа, котрый предоствляет доступ к определёным моделям в Gemini API и AI Studio до лимитов скрости беплатного тарифа. Чтобы перейти на платный тариф, необхдимо натроить биллинг в AI Studio. За точными цнам токенов обратитесь к таблице ценообразования Google, поскольку стки зависят от модели; для gemini-3.1-pro-preview текуая таблица показывает платную стандртную цену и отсутствие оплаты токенов на беплатном тарифе.
