Руководство по Gemini Pro API: ключ, конечная точка, идентификаторы моделей и совместимость с OpenAI

Доступ к Gemini Pro API осуществляется через Gemini API с помощью ключа, созданного в Google AI Studio. Для прямого REST-запроса вызовите конечную точку generateContent модели; для существующей интеграции с OpenAI SDK укажите клиенту совместимый с OpenAI базовый URL Google и используйте текущий идентификатор модели Gemini, например gemini-3.1-pro-preview. Важная деталь: «Gemini Pro» — это поисковый термин для семейства продуктов, а не постоянный идентификатор API, поэтому в рабочих приложениях следует читать текущий список моделей Google перед фиксацией идентификатора.

Настройка Gemini Pro API одним взглядом

Для выполнения запроса вам понадобятся четыре значения:

Настройка	Значение
API-ключ	Создайте в Google AI Studio
Нативный базовый хост	https://generativelanguage.googleapis.com
Нативный путь API	/v1beta/models/{model}:generateContent
Базовый URL, совместимый с OpenAI	https://generativelanguage.googleapis.com/v1beta/openai/
Пример идентификатора модели	gemini-3.1-pro-preview

В кратком руководстве по Gemini API от Google описано создание ключа API и нативный шаблон запроса. В руководстве по совместимости с OpenAI документирован совместимый базовый URL для приложений, которые уже используют OpenAI Python или JavaScript SDK.

Используйте нативный Gemini SDK или REST API, когда вам нужны специфические для Gemini функции сразу после их появления в Google. Используйте уровень совместимости, если у вас уже есть клиент в стиле OpenAI и вы хотите сократить работу по миграции. Совместимость полезна, но она не гарантирует, что каждая опция, специфичная для провайдера, будет идеально отображаться между API.

Как получить ключ Google API для Gemini

Создайте ключ в Google AI Studio, затем сохраните его в переменной окружения вместо размещения в исходном коде:

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

Относитесь к этому как к серверному учетному данным. Не добавляйте его в Git, не печатайте в логах и не встраивайте в JavaScript браузера или мобильное приложение. Если фронтенду нужен вывод Gemini, отправьте запрос пользователя на ваш собственный бэкенд и позвольте бэкенду вызывать API Google.

Для рабочего сервиса также решите, кто владеет проектом Google Cloud, как ротируются ключи, какие среды получают отдельные учетные данные и где отслеживаются квоты запросов. В руководстве по ключам API Google объясняется, как ключи Gemini API связаны с проектами Google Cloud.

Как вызвать нативную конечную точку Gemini API

Нативный REST-маршрут помещает идентификатор модели в 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": "Create a seven-step checklist for migrating a Python API from one region to two regions. Include rollback checks."
          }
        ]
      }
    ]
  }'

Ответ содержит кандидатов со сгенерированным контентом. Реальные приложения должны обрабатывать пустой список кандидатов, заблокированный контент, тайм-ауты и ответы, отличные от 2xx, а не обращаться напрямую к первому объекту ответа.

В URL используется v1beta, потому что это маршрут, показанный в текущих примерах Gemini API от Google. Храните версию API в конфигурации, чтобы вы могли протестировать новую версию, не разбрасывая строки конечных точек по всей кодовой базе.

Анатомия нативной конечной точки

Путь состоит из трех частей:

/v1beta/models/{model}:generateContent

• v1beta — версия API.
• {model} — точный идентификатор модели со страницы моделей Gemini от Google.
• generateContent — метод генерации.

Ответ 404 часто означает, что идентификатор модели, версия API или метод не совпадают. Прежде чем изменять код аутентификации, сравните полный путь с текущей документацией по модели.

Как использовать Gemini с совместимым с OpenAI клиентом

Если ваше приложение уже использует пакет OpenAI Python, установите его и измените ключ API, базовый URL и идентификатор модели:

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": "You are a concise software architecture reviewer.",
        },
        {
            "role": "user",
            "content": "Review a queue worker design and list the top five failure modes.",
        },
    ],
)

print(response.choices[0].message.content)

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

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

Как выбирать и управлять идентификаторами моделей Gemini

Избегайте размещения маркетингового названия, такого как gemini-pro, непосредственно в логике приложения. Доступные идентификаторы моделей 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
}

Прежде чем перемещать новую модель в рабочую среду:

1. Убедитесь, что идентификатор присутствует в текущей документации по моделям Google или в API моделей.
2. Проверьте, является ли модель предварительной, стабильной или запланированной к выводу из эксплуатации.
3. Запустите собственный набор оценки для качества ответов и правильности вызовов инструментов.
4. Измерьте задержку, использование токенов и частоту отказов с помощью репрезентативных подсказок.
5. Добавьте резервную модель или четкий путь отказа перед переключением всего трафика.

Ограничения скорости не являются единым универсальным числом. Они зависят от модели и уровня использования, поэтому прочитайте документацию по ограничениям скорости Gemini API от Google и отслеживайте ограничения, применяемые к вашему проекту.

Как создать бэкенд с возможностью переключения провайдера

Интерфейс, совместимый с 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 и идентификатор модели. Приложение получает одну нормализованную строку, в то время как тесты для конкретных провайдеров могут охватывать более богатое поведение, такое как инструменты или мультимодальные входные данные.

Документация по LLM API Novita AI использует совместимую с OpenAI форму API для поддерживаемых моделей. Это может быть полезно, когда команда хочет сравнить Gemini с моделями с открытым исходным кодом без перестройки всего уровня клиента.

Как Gemini вписывается в бэкенд агента

Бэкенд агента имеет как минимум две отдельные обязанности:

1. Вывод: Модель решает, что сказать или какой инструмент вызвать.
2. Выполнение: Контролируемая среда выполнения выполняет действия с файлами, оболочкой, браузером или приложениями.

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

Novita Agent Sandbox предназначен для изолированных рабочих процессов выполнения агентов. Практическая архитектура может использовать Gemini для рассуждений, в то время как песочница обрабатывает код или задачи браузера отдельно:

Запрос пользователя
    -> Сервис агента
        -> Gemini API для рассуждений и выбора инструмента
        -> Проверки политики для предлагаемого действия
        -> Agent Sandbox для изолированного выполнения
        -> Результат инструмента возвращается в сервис агента
        -> Gemini API для финального ответа

Это разделение делает модель заменяемой и удерживает недоверенное выполнение вдали от сервера приложений. Это также дает бэкенду одно место для принудительного применения тайм-аутов, сетевой политики, ограничений на файлы, аудиторского логирования и авторизации пользователей.

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

Когда модель с открытым исходным кодом лучше подходит

Модели Gemini Pro являются сильным вариантом, когда вашему приложению нужны возможности модели Google и управляемый API. Модель с открытым исходным кодом может лучше подойти, когда вам нужен второй провайдер, вы хотите оценить поведение модели по сравнению с видимым вышестоящим релизом или предпочитаете модель, доступную через совместимую с OpenAI конечную точку вместе с другой инфраструктурой.

MiMo-V2.5-Pro — один из текущих вариантов на Novita AI. Карточка вышестоящей модели Xiaomi описывает ее как модель смеси экспертов с открытым исходным кодом, в то время как Novita AI предоставляет размещенный идентификатор модели xiaomimimo/mimo-v2.5-pro. Поскольку и конечная точка совместимости Google, и Novita AI могут быть вызваны с помощью клиента в стиле OpenAI, шаблон с возможностью переключения провайдера из предыдущего раздела может оценивать их с помощью одних и тех же подсказок и проверок приемки.

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

Распространенные ошибки Gemini API

400: Неверный запрос

Проверьте структуру JSON, роли сообщений, определения инструментов и имена параметров. Опция, принятая другим совместимым с OpenAI провайдером, может не приниматься уровнем совместимости Google.

401 или 403: Ошибка аутентификации или разрешения

Убедитесь, что GEMINI_API_KEY присутствует в окружении процесса и принадлежит предполагаемому проекту Google Cloud. Также проверьте, доступны ли проект и выбранная модель для учетной записи и региона.

404: Модель или метод не найден

Сравните точный идентификатор модели с текущим списком моделей Gemini. Для нативных REST-вызовов проверьте версию API и суффикс :generateContent. Для вызовов, совместимых с OpenAI, убедитесь, что базовый URL заканчивается на /v1beta/openai/.

429: Превышено ограничение скорости

Повторите попытку с экспоненциальной задержкой и джиттером, но не рассматривайте повторные попытки как замену планированию емкости. Ставьте в очередь пиковую работу, ограничивайте параллельные запросы и проверяйте текущий уровень использования проекта и лимиты, специфичные для модели.

SDK работает, но вывод отличается после переключения провайдера

Совместимость охватывает интерфейс запроса, а не идентичное поведение модели. Запускайте тесты подсказок, структурированного вывода и вызовов инструментов для каждого провайдера и версии модели.

Заключение

Начните с нативного Gemini API, когда вам нужен самый понятный путь к специфическим функциям Gemini. Начните с совместимой с OpenAI конечной точки, если у вас уже есть бэкенд в стиле OpenAI или вам нужна быстрая оценка провайдера. В обоих случаях храните ключ API на стороне сервера, помещайте идентификатор модели в конфигурацию, тестируйте точную версию модели и отделяйте рассуждения модели от выполнения агента.

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

Часто задаваемые вопросы

Существует ли еще идентификатор модели gemini-pro?

Не предполагайте, что gemini-pro является текущим идентификатором. «Gemini Pro API» обычно используется как поисковая фраза для моделей Gemini более высокой производительности от Google, но приложения должны использовать точный идентификатор с текущей страницы моделей 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 должны использовать текущую документацию Gemini API, конечные точки и идентификаторы моделей, а не старые примеры Bard.

Могу ли я использовать OpenAI SDK с Gemini?

Да. Google документирует конечную точку совместимости с OpenAI. Установите базовый URL клиента на URL совместимости Google, укажите свой ключ Gemini API и выберите поддерживаемый идентификатор модели Gemini. Тестируйте функции, специфичные для провайдера, прежде чем полагаться на полное поведенческое соответствие.

Может ли Gemini запускать код для AI-агента?

Gemini может рассуждать о коде и предлагать вызовы инструментов, но выполнение должно происходить в контролируемой среде выполнения. Держите вызов модели отдельно от изолированной среды, такой как Agent Sandbox, и проверяйте каждое запрошенное действие перед его запуском.

Рекомендуемые статьи

• Лучшая платформа LLM API для переключения провайдеров
• Что такое кодирующие агенты? Архитектура, инструменты и безопасность
• MiMo 2.5 API на Novita AI: совместимый с OpenAI чат-API