Google Gemini API

Google Gemini API — это нативный протокол генеративного ИИ от Google. Если ваш клиент уже разработан в соответствии со спецификациями SDK Google GenAI, просто переключите Base URL и API Key на RouteAPI для прямого использования без переписывания структуры запросов.

Обзор протокола

Gemini API использует уникальный дизайн, где имя модели встроено в путь URL. Тело запроса использует массив contents для выражения разговоров, каждое сообщение имеет роль user или model (обратите внимание: не assistant). Структура ответа использует обертку массива candidates, поддерживая фильтрацию безопасности и генерацию нескольких кандидатов.

Сценарии использования:

Сценарий	Описание
SDK Google GenAI	SDK Python / Node.js google-generativeai, измените только base_url
Клиент REST Gemini	Приложения, уже разработанные для REST API Gemini
Мультимодальные приложения	Сценарии, требующие нативной поддержки ввода изображений, видео, аудио
Экспорт Google AI Studio	Код, экспортированный из AI Studio, можно напрямую мигрировать

Если ваш клиент поддерживает только протокол OpenAI, используйте вместо этого Chat Completions. RouteAPI выполнит необходимую адаптацию формата внутри, но приоритет протоколу, нативно поддерживаемому вашим клиентом, обеспечивает лучшую совместимость.

Формат конечных точек

Дизайн конечных точек Gemini API отличителен: имя модели напрямую встроено в путь URL.

POST /v1beta/models/{model}:generateContent

Пример полного адреса:

https://api.routeapi.ai/v1beta/models/gemini-1.5-pro:generateContent

Потоковая конечная точка:

https://api.routeapi.ai/v1beta/models/gemini-1.5-pro:streamGenerateContent

Замените часть {model} фактическим именем модели, таким как gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash-exp и т.д. Обратите внимание, что между именем модели перед двоеточием и именем метода после него нет пробела.

Заголовки запроса:

Authorization: Bearer sk-your-routeapi-token
Content-Type: application/json

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

Формат запроса

Поле	Тип	Обязательно	Описание
contents	array	Да	Список контента разговора, минимум одна запись
generationConfig	object	Нет	Параметры конфигурации генерации
safetySettings	array	Нет	Настройки фильтрации безопасности
systemInstruction	object	Нет	Системная инструкция, независимое поле
tools	array	Нет	Определения инструментов вызова функций
toolConfig	object	Нет	Конфигурация вызова инструментов

Пример базового запроса:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Пожалуйста, представьте RouteAPI в одном предложении" }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 1024
  }
}

Уникальная структура contents

Gemini API использует трехуровневую вложенную структуру:

1. Массив contents содержит несколько сообщений
2. Каждое сообщение имеет поля role и parts
3. Массив parts содержит фактические блоки контента

Ключевые отличия:

• role может быть только user или model (не assistant)
• Контент должен быть размещен в массиве parts, каждый элемент является объектом part
• Поддерживает мультимодальные parts: текст, изображения, видео, аудио могут быть смешаны в parts одного сообщения

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Проанализируйте это изображение" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "данные изображения в кодировке base64..."
          }
        }
      ]
    },
    {
      "role": "model",
      "parts": [
        { "text": "Это изображение, показывающее..." }
      ]
    }
  ]
}

Параметры generationConfig

Параметр	Тип	Описание
temperature	number	Температура сэмплирования, диапазон 0 до 2, по умолчанию 1.0
topP	number	Параметр nucleus sampling, по умолчанию 0.95
topK	integer	Сэмплировать только из K токенов с наивысшей вероятностью
maxOutputTokens	integer	Максимальное количество выходных токенов
stopSequences	array	Пользовательские последовательности остановки, максимум 5
candidateCount	integer	Количество кандидатов для генерации, по умолчанию 1
responseMimeType	string	Формат ответа, например "application/json"
responseSchema	object	JSON Schema для ограничения структуры вывода

Пример:

{
  "generationConfig": {
    "temperature": 0.9,
    "topP": 0.95,
    "topK": 40,
    "maxOutputTokens": 2048,
    "stopSequences": ["END", "STOP"]
  }
}

systemInstruction

Системная инструкция — независимое поле, не в contents:

{
  "systemInstruction": {
    "parts": [
      { "text": "Вы строгий технический помощник, который даёт краткие ответы." }
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "Объясните, что такое API-шлюз" }]
    }
  ]
}

safetySettings

Управляет уровнями фильтрации безопасности контента:

{
  "safetySettings": [
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
      "category": "HARM_CATEGORY_HATE_SPEECH",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    }
  ]
}

Общие категории: HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT.

Варианты порогов: BLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH.

Мультимодальный контент

Gemini API нативно поддерживает мультимодальный ввод через различные типы в массиве parts.

Текст

{ "text": "Это текстовый контент" }

Встроенное изображение (base64)

{
  "inlineData": {
    "mimeType": "image/jpeg",
    "data": "/9j/4AAQSkZJRgABAQAAAQ..."
  }
}

Поддерживаемые форматы изображений: image/jpeg, image/png, image/webp, image/heic, image/heif.

URL изображения (fileData)

{
  "fileData": {
    "mimeType": "image/jpeg",
    "fileUri": "https://example.com/image.jpg"
  }
}

Видео и аудио

{
  "fileData": {
    "mimeType": "video/mp4",
    "fileUri": "gs://bucket-name/video.mp4"
  }
}

Поддержка видео: video/mp4, video/mpeg, video/mov и т.д. Поддержка аудио: audio/wav, audio/mp3, audio/aac и т.д.

Пример смешанного мультимодального контента

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Проанализируйте связь между этим видео и этим изображением" },
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://my-bucket/video.mp4"
          }
        },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "base64..."
          }
        }
      ]
    }
  ]
}

Формат ответа

Стандартный ответ

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "RouteAPI — это API-шлюз, который объединяет управление несколькими поставщиками моделей ИИ."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 18,
    "totalTokenCount": 30
  }
}

Описание полей ответа

Поле	Описание
candidates	Массив ответов-кандидатов, по умолчанию один
candidates[].content	Сгенерированный контент, та же структура, что и элемент contents в запросе
candidates[].content.role	Всегда "model"
candidates[].finishReason	Причина завершения
candidates[].safetyRatings	Детали оценки безопасности
usageMetadata	Статистика использования токенов

Значения finishReason

Значение	Значение
STOP	Модель завершилась естественно
MAX_TOKENS	Достигнут лимит maxOutputTokens
SAFETY	Заблокировано из-за срабатывания фильтра безопасности
RECITATION	Заблокировано из-за обнаружения повторяющегося контента
OTHER	Другие причины

Поля usageMetadata

Поле	Описание
promptTokenCount	Количество входных токенов
candidatesTokenCount	Количество выходных токенов (сумма всех кандидатов)
totalTokenCount	Общее количество токенов
cachedContentTokenCount	Количество кэшированных токенов (если используется кэширование контекста)

Потоковый вывод

Используйте конечную точку streamGenerateContent для реализации потокового ответа:

POST /v1beta/models/{model}:streamGenerateContent

Потоковый ответ использует формат SSE (Server-Sent Events), каждое событие является объектом JSON:

data: {"candidates":[{"content":{"parts":[{"text":"RouteAPI"}],"role":"model"},"finishReason":""}],"usageMetadata":{"promptTokenCount":12,"candidatesTokenCount":1,"totalTokenCount":13}}

data: {"candidates":[{"content":{"parts":[{"text":" это"}],"role":"model"},"finishReason":""}],"usageMetadata":{"promptTokenCount":12,"candidatesTokenCount":3,"totalTokenCount":15}}

data: {"candidates":[{"content":{"parts":[{"text":" API-шлюз"}],"role":"model"},"finishReason":""}],"usageMetadata":{"promptTokenCount":12,"candidatesTokenCount":5,"totalTokenCount":17}}

data: {"candidates":[{"content":{"parts":[{"text":""}],"role":"model"},"finishReason":"STOP","safetyRatings":[{"category":"HARM_CATEGORY_HARASSMENT","probability":"NEGLIGIBLE"}]}],"usageMetadata":{"promptTokenCount":12,"candidatesTokenCount":18,"totalTokenCount":30}}

Характеристики потока:

• Каждый chunk — это полный объект JSON, содержащий полную структуру candidates
• finishReason — пустая строка для продолжения, имеет значение для указания завершения
• Последний chunk содержит полные safetyRatings и финальные usageMetadata
• Потоковый ответ не имеет явного маркера [DONE], полагается на finishReason для определения завершения

Вызов функций (Function Calling)

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

Определение инструмента

{
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "Запросить текущую погоду для указанного города. Используйте полное название города.",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "Название города, например Москва"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"]
              }
            },
            "required": ["city"]
          }
        }
      ]
    }
  ]
}

Ответ вызова функции

Модель возвращает запрос вызова функции:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "get_weather",
              "args": {
                "city": "Москва",
                "unit": "celsius"
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ]
}

Возврат результатов функции

Вернуть результаты выполнения функции как новое сообщение user:

{
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "Какая сейчас погода в Москве?" }]
    },
    {
      "role": "model",
      "parts": [
        {
          "functionCall": {
            "name": "get_weather",
            "args": { "city": "Москва", "unit": "celsius" }
          }
        }
      ]
    },
    {
      "role": "user",
      "parts": [
        {
          "functionResponse": {
            "name": "get_weather",
            "response": {
              "content": "Москва, солнечно, температура 23 градуса Цельсия, влажность 45%."
            }
          }
        }
      ]
    }
  ]
}

Сравнение с форматом OpenAI

Таблица сравнения структур

Элемент	Gemini API	OpenAI Chat Completions
Формат конечной точки	/v1beta/models/{model}:generateContent	/v1/chat/completions
Указание модели	В пути URL	Поле model тела запроса
Поле массива разговора	contents	messages
Структура сообщения	role + массив parts	role + строка/массив content
Имена ролей	user / model	user / assistant / system
Системная инструкция	Объект systemInstruction	role: "system" в messages
Обертка ответа	Массив candidates	Массив choices
Расположение контента ответа	candidates[0].content.parts[0].text	choices[0].message.content
Поле причины завершения	finishReason	finish_reason
Поле статистики использования	usageMetadata	usage

Таблица сопоставления параметров

Gemini API	OpenAI Chat Completions	Примечания
generationConfig.temperature	temperature	Gemini макс 2, OpenAI тоже 2
generationConfig.topP	top_p	Разный стиль именования
generationConfig.topK	Нет эквивалента	OpenAI не поддерживает
generationConfig.maxOutputTokens	max_tokens / max_completion_tokens	Разное имя поля
generationConfig.stopSequences	stop	Разное имя
generationConfig.candidateCount	n	Та же семантика
generationConfig.responseMimeType	response_format.type	Разный метод управления
generationConfig.responseSchema	response_format.json_schema	Разная иерархия
safetySettings	Нет эквивалента	OpenAI использует API модерации контента
tools[].functionDeclarations	tools[].function	Разный уровень обертки
toolConfig	tool_choice	Разное имя поля и структура

Соображения при миграции

При миграции с OpenAI на Gemini API проверьте в следующем порядке:

1. Переместить имя модели в путь URL: /v1beta/models/gemini-1.5-pro:generateContent
2. Переименовать messages в contents, изменить структуру каждого сообщения на role + массив parts
3. Изменить все роли assistant на model
4. Изменить поле content на массив parts, обернуть текстовый контент как { "text": "..." }
5. Переместить системный промпт из массива messages в объект systemInstruction
6. Обернуть параметры генерации в объект generationConfig и отрегулировать имена полей (например maxOutputTokens, stopSequences)
7. Изменить парсинг ответа для извлечения контента из candidates[0].content.parts[0].text
8. Изменить потоковую конечную точку на streamGenerateContent, каждый chunk — полный JSON
9. Изменить определение инструмента на обертку functionDeclarations, поле параметров на parameters

Сопоставление имен ролей

Gemini	OpenAI	Claude
user	user	user
model	assistant	assistant
Нет независимой роли	system	Нет независимой роли
Нет независимой роли	tool	Нет независимой роли

Gemini и Claude оба поднимают системную инструкцию на поле верхнего уровня, не обрабатывая её как роль сообщения.

Полные примеры

Базовый разговор (Python SDK)

Используя Python SDK Google GenAI, измените только client_options:

import os
import google.generativeai as genai
from google.api_core.client_options import ClientOptions

# Настроить конечную точку RouteAPI
genai.configure(
    api_key=os.environ["ROUTEAPI_KEY"],
    transport="rest",
    client_options=ClientOptions(
        api_endpoint="https://api.routeapi.ai/v1beta"
    )
)

model = genai.GenerativeModel("gemini-1.5-pro")

response = model.generate_content(
    "Пожалуйста, представьте RouteAPI в одном предложении",
    generation_config={
        "temperature": 0.7,
        "max_output_tokens": 1024
    }
)

print(response.text)
print(f"Входные токены: {response.usage_metadata.prompt_token_count}")
print(f"Выходные токены: {response.usage_metadata.candidates_token_count}")

Пример ввода изображения (Python SDK)

import os
import google.generativeai as genai
from google.api_core.client_options import ClientOptions
from PIL import Image

genai.configure(
    api_key=os.environ["ROUTEAPI_KEY"],
    transport="rest",
    client_options=ClientOptions(
        api_endpoint="https://api.routeapi.ai/v1beta"
    )
)

model = genai.GenerativeModel("gemini-1.5-pro")

image = Image.open("screenshot.jpg")

response = model.generate_content(
    ["Какие элементы управления пользовательского интерфейса есть на этом изображении?", image],
    generation_config={"max_output_tokens": 2048}
)

print(response.text)

Пример потокового вывода (Python SDK)

import os
import google.generativeai as genai
from google.api_core.client_options import ClientOptions

genai.configure(
    api_key=os.environ["ROUTEAPI_KEY"],
    transport="rest",
    client_options=ClientOptions(
        api_endpoint="https://api.routeapi.ai/v1beta"
    )
)

model = genai.GenerativeModel("gemini-1.5-pro")

response = model.generate_content(
    "Объясните пошагово, что такое API-шлюз",
    stream=True
)

for chunk in response:
    print(chunk.text, end="", flush=True)

print()

Примечания о совместимости

• Фактическая поддержка параметров зависит от выбранной модели и возможностей upstream-сервиса. Некоторые продвинутые функции (такие как кэширование контекста, выполнение кода) следует сначала проверить в тестовой среде.
• Необязательные параметры, явно переданные как 0 или false, обрабатываются как значения, установленные пользователем, а не как значения по умолчанию, которые нужно отбросить.
• Производственные среды должны фиксировать ID моделей и не полагаться на временные псевдонимы или отображаемые имена.
• Записывайте ID модели, код состояния и использование токенов для каждого запроса, чтобы облегчить устранение аномалий задержки и стоимости.
• При использовании fileUri с протоколом gs:// убедитесь, что файл доступен upstream, или используйте inlineData для прямой передачи.
• Формат ответа об ошибке может отличаться от OpenAI/Claude, см. Обработка ошибок.