Справочник по Gemini API
Генерация контента
Endpoint
POST https://api.rockapi.ru/google-ai-studio/v1beta/{model=models/*}:generateContent
Параметры пути
| Имя | Тип | Описание |
|---|---|---|
| model | string | Обязательный. Название модели, используемой для генерации контента. Формат: name=models/{model}. |
Тело запроса
Тело запроса содержит данные со следующей структурой:
Поля
| Имя | Тип | Описание |
|---|---|---|
| contents[] | object | Обязательный. Содержимое текущего разговора с моделью. Для одноразовых запросов это один экземпляр. Для многоразовых запросов это повторяющееся поле, содержащее историю разговора и последний запрос. |
| tools[] | object | Необязательный. Список инструментов, которые модель может использовать для генерации следующего ответа. Инструмент — это часть кода, которая позволяет системе взаимодействовать с внешними системами для выполнения действий за пределами знаний и возможностей модели. Единственный поддерживаемый инструмент на дан ный момент — это Функция. |
| toolConfig | object | Необязательный. Конфигурация инструментов для любого инструмента, указанного в запросе. |
| safetySettings[] | object | Необязательный. Список уникальных настроек безопасности для блокировки небезопасного контента. Эти настройки будут применяться к GenerateContentRequest.contents и GenerateContentResponse.candidates. В списке не должно быть более одной настройки для каждого типа категории безопасности. API будет блокировать любой контент и ответы, которые не соответствуют установленным порогам. Этот список переопределяет настройки по умолчанию для каждой указанной категории безопасности. Если в списке не указана настройка безопасности для данной категории, API будет использовать настройку безопасности по умолчанию для этой категории. Поддерживаемые категории вреда: HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT. |
| systemInstruction | object | Необязательный. Инструкция разработчика для системы. На данный момент, только текст. |
| generationConfig | object | Необязательный. Настройки конфигурации для генерации модели и выходных данных. |
| cachedContent | string | Необязательный. Название кэшированного контента, используемого как контекст для предсказания. Примечание: используется только в явном кэшировании, когда пользователи могут контролировать кэширование (например, что кэшировать) и экономить расходы. Формат: cachedContents/{cachedContent}. |
Пример запроса
import google.generativeai as genai
from google.api_core.client_options import ClientOptions
genai.configure(
api_key='$ROCKAPI_API_KEY',
transport='rest',
client_options=ClientOptions(api_endpoint='https://api.rockapi.ru/google-ai-studio')
)
model = genai.GenerativeModel("gemini-1.5-flash")
response = model.generate_content("Напиши историю о волшебном рюкзаке.")
print(response.text)
Тело ответа
В случае успеха тело ответа содержит экземпляр GenerateContentResponse.
Потоковая генерация контента
Endpoint
POST https://api.rockapi.ru/google-ai-studio/v1beta/{model=models/*}:streamGenerateContent
Параметры пути
| Имя | Тип | Описание |
|---|---|---|
| model | string | Обязательный. Название модели, используемой для генерации контента. Формат: name=models/{model}. |
Тело запроса
Тело запроса содержит данные со следующей структурой:
Поля
| Имя | Тип | Описание |
|---|---|---|
| contents[] | object | Обязательный. Содержимое текущего разговора с моделью. Для одноразовых запросов это один экземпляр. Для многоразовых запросов это повторяющееся пол е, содержащее историю разговора и последний запрос. |
| tools[] | object | Необязательный. Список инструментов, которые модель может использовать для генерации следующего ответа. Инструмент — это часть кода, которая позволяет системе взаимодействовать с внешними системами для выполнения действий за пределами знаний и возможностей модели. Единственный поддерживаемый инструмент на данный момент — это Функция. |
| toolConfig | object | Необязательный. Конфигурация инструментов для любого инструмента, указанного в запросе. |
| safetySettings[] | object | Необязательный. Список уникальных настроек безопасности для блокировки небезопасного контента. Эти настройки будут применяться к GenerateContentRequest.contents и GenerateContentResponse.candidates. В списке не должно быть более одной настройки для каждого типа категории безопасности. API будет блокировать любой контент и ответы, которые не соответствуют установленным порогам. Этот список переопределяет настройки по умолчанию для каждой указанной категории безопасности. Если в списке не указана настройка безопасности для данной категории, API будет использовать настройку безопасности по умолчанию для этой категории. Поддерживаемые категории вреда: HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT. |
| systemInstruction | object | Необязательный. Инструкция разработчика для системы. На данный момент, только текст. |
| generationConfig | object | Необязательный. Настройки конфигурации для генерации модели и выходных данных. |
| cachedContent | string | Необязательный. Название кэшированного контента, используемого как контекст для предсказания. Примечание: используется только в явном кэшировании, когда пользователи могут контролировать кэширование (например, что кэшировать) и экономить расходы. Формат: cachedContents/{cachedContent}. |
Пример запроса
import google.generativeai as genai
from google.api_core.client_options import ClientOptions
genai.configure(
api_key='$ROCKAPI_API_KEY',
transport='rest',
client_options=ClientOptions(api_endpoint='https://api.rockapi.ru/google-ai-studio')
)
model = genai.GenerativeModel("gemini-1.5-flash")
response = model.generate_content("Напиши историю о волшебном рюкзаке.", stream=True)
for chunk in response:
print(chunk.text)
print("_" * 80)
Тело ответа
В случае успеха тело ответа содержит поток экземпляров GenerateContentResponse.
GenerateContentResponse
Ответ от модели, поддерживающей несколько кандидатов.
Представление JSON
Примечание о рейтингах безопасности и фильтрации контента. Они сообщаются как для запроса в GenerateContentResponse.prompt_feedback, так и для каждого кандидата в finishReason и в safetyRatings. Контракт API заключается в следующем: - либо все запрошенные кандидаты возвращаются, либо не возвращается ни один - кандидаты не возвращаются только в том случае, если что-то не так с запросом (см. promptFeedback) - отзывы по каждому кандидату сообщаются в finishReason и safetyRatings.
{
"candidates": [
{
object (Candidate)
}
],
"promptFeedback": {
object (PromptFeedback)
},
"usageMetadata": {
object (UsageMetadata)
}
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| candidates[] | object | Ответы-кандидаты от модели. |
| promptFeedback | object | Возвращает отзывы о запросе, связанные с фильтрами контента. |
| usageMetadata | object | Метаданные о использовании токенов в запросе на генерацию. |
PromptFeedback
Набор метаданных отзывов о запросе, указанных в GenerateContentRequest.content.
Представление JSON
{
"blockReason": "enum (BlockReason)",
"safetyRatings": [
{
"object": "SafetyRating"
}
]
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| blockReason | enum | Необязательный. Если установлено, запрос был заблокирован и кандидаты не возвращаются. Переформулируйте ваш запрос. |
| safetyRatings[] | object | Рейтинги безопасности запроса. В каждой категории может быть не более одного рейтинга. |
BlockReason
Указывает, по какой причине запрос был заблокирован.
Перечисления
| Имя | Описание |
|---|---|
| BLOCK_REASON_UNSPECIFIED | Значение по умолчанию. Это значение не используется. |
| SAFETY | Запрос был заблокирован по соображениям безопасности. Вы можете изучить safetyRatings, чтобы понять, какая категория безопасности его заблокировала. |
| OTHER | Запрос был заблокирован по неизвестным причинам. |
UsageMetadata
Метаданные об использовании токенов в запросе на генерацию.
Представление JSON
{
"promptTokenCount": "integer",
"cachedContentTokenCount": "integer",
"candidatesTokenCount": "integer",
"totalTokenCount": "integer"
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| promptTokenCount | integer | Количество токенов в запросе. Когда установлено cachedContent, это все равно общее количество токенов запроса. |
| cachedContentTokenCount | integer | Количество токенов в кэшированной части запроса, то есть в кэшированном контенте. |
| candidatesTokenCount | integer | Общее количество токенов среди сгенерированных кандидатов. |
| totalTokenCount | integer | Общее количество токенов для запроса на генерацию (запрос + кандидаты). |
Candidate
Ответ-кандидат, сгенерированный моделью.
Представление JSON
{
"content": {
"object": "Content"
},
"finishReason": "enum (FinishReason)",
"safetyRatings": [
{
"object": "SafetyRating"
}
],
"citationMetadata": {
"object": "CitationMetadata"
},
"tokenCount": "integer",
"groundingAttributions": [
{
"object": "GroundingAttribution"
}
],
"index": "integer"
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| content | object | Сгенерированный контент, возвращенный моделью. |
| finishReason | enum | Необязательный. Причина, по которой модель прекратила генерацию токенов. |
| safetyRatings[] | object | Список рейтингов безопасности для ответа-кандидата. В каждой категории может быть не более одного рейтинга. |
| citationMetadata | object | Информация о цитировании для сгенерированного кандидата. |
| tokenCount | integer | Количество токенов для этого кандидата. |
| groundingAttributions[] | object | Информация об источниках, которые внесли вклад в создание ответа. |
| index | integer | Индекс кандидата в списке кандидатов. |
FinishReason
Определяет причину, по которой модель прекратила генерацию токенов.
Перечисления
| Имя | Описание |
|---|---|
| FINISH_REASON_UNSPECIFIED | Значение по умолчанию. Это значение не используется. |
| STOP | Естественная точка остановки модели или предоставленная последовательность остановки. |
| MAX_TOKENS | Достигнуто максимальное количество токенов, указанное в запросе. |
| SAFETY | Контент кандидата был помечен по соображениям безопасности. |
| RECITATION | Контент кандидата был помечен по причинам пересказа. |
| LANGUAGE | Контент кандидата был помечен за использование неподдерживаемого языка. |
| OTHER | Неизвестная причина. |
GroundingAttribution
Атрибуция для источника, который внес вклад в ответ.
Представление JSON
{
"sourceId": {
"object": "AttributionSourceId"
},
"content": {
"object": "Content"
}
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| sourceId | object | Идентификатор источника, внесшего вклад в этот ответ. |
| content | object | Контент источника, внесший вклад в этот ответ. |
AttributionSourceId
Идентификатор источника, внесшего вклад в этот ответ.
Представление JSON
{
"groundingPassage": {
"object": "GroundingPassageId"
},
"semanticRetrieverChunk": {
"object": "SemanticRetrieverChunk"
}
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| groundingPassage | object | Идентификатор для встроенного отрывка. |
| semanticRetrieverChunk | object | Идентификатор для Чанка, извлеченного с помощью Semantic Retriever. |
GroundingPassageId
Идентификатор части в GroundingPassage.
Представление JSON
{
"passageId": "string",
"partIndex": "integer"
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| passageId | string | Идентификатор отрывка, соответствующего GenerateAnswerRequest GroundingPassage.id. |
| partIndex | integer | Индекс части в контенте GenerateAnswerRequest GroundingPassage. |
SemanticRetrieverChunk
Идентификатор Чанка, извлеченного с помощью Semantic Retriever, указанного в GenerateAnswerRequest с использованием SemanticRetrieverConfig.
Представление JSON
{
"source": "string",
"chunk": "string"
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| source | string | Название источника, соответствующего SemanticRetrieverConfig.source в запросе. Пример: corpora/123 или corpora/123/documents/abc. |
| chunk | string | Название Чанка, содержащего атрибутированный текст. Пример: corpora/123/documents/abc/chunks/xyz. |
CitationMetadata
Коллекция источников атрибуции для части контента.
Представление JSON
{
"citationSources": [
{
"object": "CitationSource"
}
]
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| citationSources[] | object | Цитаты источников для конкретного ответа. |
CitationSource
Цитата источника для части конкретного ответа.
Представление JSON
{
"startIndex": "integer",
"endIndex": "integer",
"uri": "string",
"license": "string"
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| startIndex | integer | Необязательный. Начало сегмента ответа, который атрибутируется этому источнику. Индекс указывает начало сегмента, измеряется в байтах. |
| endIndex | integer | Необязательный. Конец атрибутированного сегмента, исключительно. |
| uri | string | Необязательный. URI, который атрибути руется как источник для части текста. |
| license | string | Необязательный. Лицензия для проекта на GitHub, который атрибутируется как источник для сегмента. Лицензионная информация требуется для цитирования кода. |
GenerationConfig
Настройки конфигурации для генерации модели и выходных данных. Не все параметры могут быть настраиваемыми для каждой модели.
Представление JSON
{
"stopSequences": [
"string"
],
"responseMimeType": "string",
"responseSchema": {
"object": "Schema"
},
"candidateCount": "integer",
"maxOutputTokens": "integer",
"temperature": "number",
"topP": "number",
"topK": "integer"
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| stopSequences[] | string | Необязательный. Набор последовательностей символов (до 5), которые остановят генерацию ответа. Если указано, API остановится при первом появлении последовательности остановки. Последовательность остановки не будет включена в ответ. |
| responseMimeType | string | Необязательный. MIME-тип ответа сгенерированного текста. Поддерживаемые MIME-типы: text/plain (по умолчанию), application/json (JSON-ответ в кандидатах). |
| responseSchema | object | Необязательный. Схема ответа сгенерированного текст а, когда MIME-тип ответа может иметь схему. Схема может быть объектами, примитивами или массивами и является подмножеством схемы OpenAPI. Если установлено, также должен быть установлен совместимый MIME-тип ответа. Совместимые MIME-типы: application/json (Схема для JSON-ответа). |
| candidateCount | integer | Необязательный. Количество сгенерированных ответов для возврата. На данный момент это значение может быть установлено только на 1. Если не установлено, по умолчанию будет 1. |
| maxOutputTokens | integer | Необязательный. Максимальное количество токенов, которые будут включены в кандидата. Примечание: значение по умолчанию зависит от модели, см. атрибут Model.output_token_limit модели, возвращенной функцией getModel. |
| temperature | number | Необязательный. Управляет случайностью выхода. Примечание: значение по умолчанию зависит от модели, см. атрибут Model.temperature модели, возвращенной функцией getModel. Значения могут варьироваться от [0.0, 2.0]. |
| topP | number | Необязательный. Максимальная совокупная вероятность токенов для рассмотрения при выборке. Модель использует комбинированную выборку Top-k и выборку ядра. Токены сортируются на основе их вероятностей, так что рассматриваются только наиболее вероятные токены. Выборка Top-k напрямую ограничивает максимальное количество рассматриваемых токенов, в то время как выборка ядра ограничивает количество токенов на основе совокупной вероятности. Примечание: значение по умолчанию зависит от модели, см. атрибут Model.top_p модели, возвращенной функцией getModel. |
| topK | integer | Необязательный. Максимальное количество токенов для рассмотрения при выборке. Модели используют выборку ядра или комбинированную выборку Top-k и выборку ядра. Выборка Top-k рассматривает набор из topK наиболее вероятных токенов. Модели, работающие с выборкой ядра, не позволяют устанавливать topK. Примечание: значение по умолчанию зависит от модели, см. атрибут Model.top_k модели, возвращенной функцией getModel. Пустое поле topK в модели указывает на то, что модель не применяет выборку top-k и не позволяет устанавливать topK в запросах. |
HarmCategory
Категория рейтинга. Эти категории охватывают различные виды вреда, которые разработчики могут хотеть регулировать.
Перечисления
| Имя | Описание |
|---|---|
| HARM_CATEGORY_UNSPECIFIED | Категория не указана. |
| HARM_CATEGORY_DEROGATORY | Негативные или вредные комментарии, направленные на личность и/или защищенный атрибут. |
| HARM_CATEGORY_TOXICITY | Содержит грубый, неуважительный или непристойный контент. |
| HARM_CATEGORY_VIOLENCE | Описывает сценарии, изображающие насилие против человека или группы, или общие описания жестокости. |
| HARM_CATEGORY_SEXUAL | Содержит ссылки на сексуальные действия или другой непристойный контент. |
| HARM_CATEGORY_MEDICAL | Продвигает непроверенные медицинские советы. |
| HARM_CATEGORY_DANGEROUS | Опасный контент, который продвигает, способствует или поощряет вредоносные действия. |
| HARM_CATEGORY_HARASSMENT | Контент, содержащий домогательства. |
| HARM_CATEGORY_HATE_SPEECH | Контент, содержащий ненависть. |
| HARM_CATEGORY_SEXUALLY_EXPLICIT | Сексуально откровенный контент. |
| HARM_CATEGORY_DANGEROUS_CONTENT | Опасный контент. |
SafetyRating
Рейтинг безопасности для части контента. Рейтинг безопасности содержит категорию вреда и вероятность этого вреда для части контента. Контент классифицируется по безопасности в различных категориях вреда, и вероятность классификации вреда включена здесь.
Представление JSON
{
"category": "enum (HarmCategory)",
"probability": "enum (HarmProbability)",
"blocked": "boolean"
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| category | enum | Обязательный. Категория для этого рейтинга. |
| probability | enum | Обязательный. Вероятность вреда для этого контента. |
| blocked | boolean | Был ли этот контент заблокирован из-за этого рейтинга? |
HarmProbability
Вероятность того, что часть контента является вредной. Система классификации указывает вероятность того, что контент является небезопасным. Это не указывает на степень серьезности вреда для части контента.
Перечисления
| Имя | Описание |
|---|---|
| HARM_PROBABILITY_UNSPECIFIED | Вероятность не указана. |
| NEGLIGIBLE | Контент имеет незначительную вероятность быть небезопасным. |
| LOW | Контент имеет низкую вероятность быть небезопасным. |
| MEDIUM | Контент имеет среднюю вероятность быть небезопасным. |
| HIGH | Контент имеет высокую вероятность быть небезопасным. |
SafetySetting
Настройки безопасности, влияющие на поведение блокировки. Передача настройки безопасности для категории изменяет допустимую вероятность того, что контент будет заблокирован.
Представление JSON
{
"category": "enum (HarmCategory)",
"threshold": "enum (HarmBlockThreshold)"
}
Поля
| Имя | Тип | Описание |
|---|---|---|
| category | enum | Обязательный. Категория для этой настройки. |
| threshold | enum | Обязательный. Контролирует порог вероятности, при котором вред блокируется. |
HarmBlockThreshold
Блокировка при и выше указанного порога вероятности вреда.
Перечисления
| Имя | Описание |
|---|---|
| HARM_BLOCK_THRESHOLD_UNSPECIFIED | Порог не указан. |
| BLOCK_LOW_AND_ABOVE | Контент с незначительной вероятностью вреда будет разрешен. |
| BLOCK_MEDIUM_AND_ABOVE | Контент с незначительной и низкой вероятностью вреда будет разрешен. |
| BLOCK_ONLY_HIGH | Контент с незначительной, низкой и средней вероятностью вреда будет разрешен. |
| BLOCK_NONE | Весь контент будет разрешен. |