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-интерфейсы Gen Media: конечные точки для создания медиаконтента с помощью наших специализированных моделей, таких как 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 с использованием Gemini SDK см. в руководстве Использование ключей 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 .
    • Для больших файлов или файлов, которые вы хотите повторно использовать в разных запросах, используйте 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"
}

Live API (BidiGenerateContent) API WebSockets

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

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

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

API платформы

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

Что дальше?

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

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