Gemini 3 Flash уже здесь. Попробуйте бесплатно в Google AI Studio .

Эта страница переведена с помощью Cloud Translation API.

Gemini API reference

В этом справочнике API описаны стандартные, потоковые и API реального времени, которые вы можете использовать для взаимодействия с моделями Gemini. Вы можете использовать REST API в любой среде, поддерживающей HTTP-запросы. Инструкции по началу работы с первым вызовом API см. в руководстве по быстрому запуску . Если вам нужны справочные материалы по нашим библиотекам и SDK для конкретных языков программирования, перейдите по ссылке для соответствующего языка в левой панели навигации в разделе «Справочные материалы по SDK» .

Основные конечные точки

API Gemini построен вокруг следующих основных конечных точек:

Генерация стандартного контента ( generateContent ): стандартная REST-конечная точка, которая обрабатывает ваш запрос и возвращает полный ответ модели в одном пакете. Это лучше всего подходит для неинтерактивных задач, где вы можете дождаться полного результата.
Генерация потокового контента ( streamGenerateContent ): использует события, отправляемые сервером (SSE), для отправки вам фрагментов ответа по мере их генерации. Это обеспечивает более быструю и интерактивную работу для таких приложений, как чат-боты.
Live API ( BidiGenerateContent ): API на основе WebSocket с сохранением состояния для двусторонней потоковой передачи данных, разработанный для сценариев использования в режиме реального времени в диалоговых приложениях.
Пакетный режим ( batchGenerateContent ): стандартная REST-точка доступа для отправки пакетов запросов generateContent .
Встраивание текста ( embedContent ): стандартная REST-точка доступа, которая генерирует вектор встраивания текста из входного Content .
API для генерации медиаконтента: конечные точки для генерации медиафайлов с использованием наших специализированных моделей, таких как Imagen для генерации изображений и Veo для генерации видео . Gemini также имеет встроенные возможности, к которым вы можете получить доступ с помощью API generateContent .
API платформы: Вспомогательные конечные точки, поддерживающие основные возможности, такие как загрузка файлов и подсчет токенов .

Аутентификация

Все запросы к API Gemini должны включать заголовок x-goog-api-key с вашим API-ключом. Создайте его всего за несколько кликов в Google AI Studio .

Ниже приведён пример запроса, в заголовок которого включён API-ключ:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Инструкции по передаче ключа в API с помощью SDK Gemini см. в руководстве « Использование ключей API Gemini» .

Создание контента

Это центральная точка отправки запросов модели. Существует две точки для генерации контента, ключевое различие заключается в способе получения ответа:

generateContent (REST) : Принимает запрос и предоставляет единственный ответ после завершения генерации модели.
streamGenerateContent (SSE) : Получает тот же самый запрос, но модель возвращает фрагменты ответа по мере их генерации. Это обеспечивает лучший пользовательский опыт в интерактивных приложениях, поскольку позволяет немедленно отображать частичные результаты.

Структура тела запроса

Тело запроса представляет собой JSON-объект, идентичный как для стандартного, так и для потокового режимов, и состоит из нескольких основных объектов:

Объект Content : Представляет собой отдельный ход в разговоре.
Part объекта: фрагмент данных внутри элемента Content (например, текст или изображение).
inline_data ( Blob ): Контейнер для необработанных медиабайтов и их MIME-типа.

На самом высоком уровне тело запроса содержит объект contents , который представляет собой список объектов Content , каждый из которых соответствует репликам в диалоге. В большинстве случаев для базовой генерации текста вам понадобится один объект Content , но если вы хотите сохранить историю диалога, вы можете использовать несколько объектов Content .

Ниже представлен типичный текст запроса generateContent :

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

Структура ответного тела

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

Стандартный режим: Тело ответа содержит экземпляр GenerateContentResponse .
Потоковая передача: Тело ответа содержит поток экземпляров GenerateContentResponse .

На высоком уровне тело ответа содержит объект candidates , который представляет собой список объектов Candidate . Объект Candidate содержит объект Content , в котором находится сгенерированный ответ, возвращенный моделью.

Примеры запросов

Следующие примеры показывают, как эти компоненты объединяются для обработки различных типов запросов.

Текстовая подсказка

Простая текстовая подсказка состоит из массива contents , содержащего один объект Content . Массив parts этого объекта, в свою очередь, содержит один объект Part с text полем.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a single paragraph."
          }
        ]
      }
    ]
  }'

Мультимодальная подсказка (текст и изображение)

Чтобы в подсказке отображались и текст, и изображение, массив parts должен содержать два объекта Part : один для текста, а другой для изображения inline_data ).

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

Многоэтапные диалоги (чат)

Для построения диалога с несколькими вариантами ответа необходимо определить массив contents , содержащий несколько объектов Content . API будет использовать всю эту историю в качестве контекста для следующего ответа. role каждого объекта Content должна чередоваться между user и model .

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

Основные выводы

Content — это оболочка: это верхний уровень контейнера для передачи сообщения, независимо от того, исходит ли оно от пользователя или от модели.
Part обеспечивает мультимодальность: используйте несколько объектов Part в рамках одного объекта Content для объединения различных типов данных (текст, изображение, URI видео и т. д.).
Выберите способ передачи данных:
- Для небольших, непосредственно встраиваемых медиафайлов (например, большинства изображений) используйте Part с inline_data .
- Для больших файлов или файлов, которые вы хотите использовать повторно в разных запросах, используйте File API для загрузки файла и укажите его в части file_data .
Управление историей переписки: для чат-приложений, использующих REST API, создавайте массив contents , добавляя объекты Content для каждого хода, чередуя роли "user" и "model" . Если вы используете SDK, обратитесь к документации SDK для получения информации о рекомендуемом способе управления историей переписки.

Примеры ответов

Следующие примеры показывают, как эти компоненты объединяются для обработки различных типов запросов.

Ответ только в текстовом формате

Простой текстовый ответ представляет собой массив candidates , содержащий один или несколько объектов content , в которых представлен ответ модели.

Ниже приведён пример стандартного ответа:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

Ниже представлена последовательность потоковых ответов. Каждый ответ содержит responseId , который связывает весь ответ воедино:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

API в реальном времени (BidiGenerateContent) API WebSockets

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

Специализированные модели

Помимо семейства моделей Gemini, API Gemini предлагает конечные точки для специализированных моделей, таких как Imagen , Lyria и модели встраивания . С руководствами по этим темам можно ознакомиться в разделе «Модели».

API платформы

Остальные конечные точки обеспечивают дополнительные возможности, которые можно использовать с основными конечными точками, описанными ранее. Подробнее см. разделы «Пакетный режим» и «API файлов» в разделе «Руководства».

Что дальше?

Если вы только начинаете, ознакомьтесь со следующими руководствами, которые помогут вам понять модель программирования API Gemini:

Возможно, вам также будет полезно ознакомиться с руководствами по возможностям, в которых описаны различные функции API Gemini и приведены примеры кода: