Формат разговора Google Gemini (создание контента)
Официальная документация
📝 Введение
API Google Gemini поддерживает создание контента с использованием изображений, аудио, кода, инструментов и многого другого. GenerateContentRequest генерирует ответ модели на основе введенных данных. Поддерживает генерацию текста, визуальное понимание, обработку звука, длинный контекст, выполнение кода, схему JSON, вызов функций и другие функции.
💡 Пример запроса
Базовый текстовый разговор ✅
curl "https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[{"text": "Write a story about a magic backpack."}]
}]
}' 2> /dev/nullДиалог анализа изображения ✅
# Используйте временные файлы для сохранения данных изображения в кодировке Base64.
TEMP_B64=$(mktemp)
trap 'rm -f "$TEMP_B64"' EXIT
base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"
# Используйте временный файл для сохранения полезных данных JSON.
TEMP_JSON=$(mktemp)
trap 'rm -f "$TEMP_JSON"' EXIT
cat > "$TEMP_JSON" `<< EOF
{
"contents": [{
"parts":[
{"text": "Tell me about this instrument"},
{
"inline_data": {
"mime_type":"image/jpeg",
"data": "$(cat "$TEMP_B64")"
}
}
]
}]
}
EOF
curl "https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d "@$TEMP_JSON" 2>` /dev/nullВызов функции ✅
cat > tools.json `<< EOF
{
"function_declarations": [
{
"name": "enable_lights",
"description": "Turn on the lighting system."
},
{
"name": "set_light_color",
"description": "Set the light color. Lights must be enabled for this to work.",
"parameters": {
"type": "object",
"properties": {
"rgb_hex": {
"type": "string",
"description": "The light color as a 6-digit hex string, e.g. ff0000 for red."
}
},
"required": [
"rgb_hex"
]
}
},
{
"name": "stop_lights",
"description": "Turn off the lighting system."
}
]
}
EOF
curl "https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-d @<(echo '
{
"system_instruction": {
"parts": {
"text": "You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks."
}
},
"tools": ['$(cat tools.json)'],
"tool_config": {
"function_calling_config": {"mode": "auto"}
},
"contents": {
"role": "user",
"parts": {
"text": "Turn on the lights please."
}
}
}
') 2>`/dev/null |sed -n '/"content"/,/"finishReason"/p'Ответ схемы JSON ✅
curl "https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [{
"parts":[
{"text": "List 5 popular cookie recipes"}
]
}],
"generationConfig": {
"response_mime_type": "application/json",
"response_schema": {
"type": "ARRAY",
"items": {
"type": "OBJECT",
"properties": {
"recipe_name": {"type":"STRING"},
}
}
}
}
}' 2> /dev/null | headОграничения на загрузку файлов
Обработка звука 🟡
Поддерживает загрузку аудио только в режиме Base64 через inline_data, file_data.file_uri не поддерживается.
или файловый API.
# Используйте base64 inline_data для загрузки аудиоданных в запросы API.
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
AUDIO_B64=$(base64 $B64FLAGS "$AUDIO_PATH")
curl "https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Please describe this audio file."},
{"inline_data": {"mime_type": "audio/mpeg", "data": "'$AUDIO_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"Ограничения на загрузку файлов
Обработка видео 🟡
Поддерживает загрузку видео только в режиме Base64 через inline_data, file_data.file_uri не поддерживается.
или файловый API.
# Используйте base64 inline_data для загрузки видеоданных в запрос API.
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
VIDEO_B64=$(base64 $B64FLAGS "$VIDEO_PATH")
curl "https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Transcribe the audio from this video and provide visual descriptions."},
{"inline_data": {"mime_type": "video/mp4", "data": "'$VIDEO_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"Ограничения на загрузку файлов
Обработка PDF 🟡
Поддерживает загрузку PDF только в режиме base64 через inline_data, file_data.file_uri не поддерживается.
или файловый API.
MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
# Загрузка PDF-файлов в запросы API с использованием base64 inline_data
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
PDF_B64=$(base64 $B64FLAGS "$PDF_PATH")
echo $MIME_TYPE
curl "https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Can you add a few more lines to this poem?"},
{"inline_data": {"mime_type": "application/pdf", "data": "'$PDF_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"Разговор в чате ✅
curl https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{"role":"user",
"parts":[{
"text": "Hello"}]},
{"role": "model",
"parts":[{
"text": "Great to meet you. What would you like to know?"}]},
{"role":"user",
"parts":[{
"text": "I have two dogs in my house. How many paws are in my house?"}]},
]
}' 2> /dev/null | grep "text"Ответ в потоковом режиме ✅
curl "https://api.88api.ai/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse&key=$API_KEY" \
-H 'Content-Type: application/json' \
--no-buffer \
-d '{
"contents": [{
"parts": [{"text": "Написать рассказ о волшебном рюкзаке"}]
}]
}'Выполнение кода ✅
curl "https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [{"text": "Вычислить последовательность Фибоначчи10элемент"}]
}],
"tools": [{
"codeExecution": {}
}]
}'Генерация конфигурации ✅
curl https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"text": "Explain how AI works"}
]
}],
"generationConfig": {
"stopSequences": [
"Title"
],
"temperature": 1.0,
"maxOutputTokens": 800,
"topP": 0.8,
"topK": 10
}
}' 2> /dev/null | grep "text"Настройки безопасности ✅
echo '{
"safetySettings": [
{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH"},
{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE"}
],
"contents": [{
"parts":[{
"text": "'I support Martians Soccer Club and I think Jupiterians Football Club sucks! Write a ironic phrase about them.'"}]}]}' > request.json
curl "https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d @request.json 2> /dev/nullСистемные команды ✅
curl "https://api.88api.ai/v1beta/models/gemini-3.5-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "system_instruction": {
"parts":
{ "text": "You are a cat. Your name is Neko."}},
"contents": {
"parts": {
"text": "Hello there"}}}'📮 Запрос
Конечная точка
Генерация контента
POST https://api.88api.ai/v1beta/{model=models/*}:generateContentПотоковая передача сгенерированного контента
POST https://api.88api.ai/v1beta/{model=models/*}:streamGenerateContentМетод аутентификации
Включите ключ API в параметры URL-адреса запроса:
?key=$API_KEYГде $API_KEY — ваш токен 88API.
Параметры пути
model
- Тип: строка
- Обязательно: Да
Имя модели, используемой для создания завершений.
Формат: models/{model}, например models/gemini-3.5-flash.
Параметры тела запроса
contents
- Тип: массив
- Обязательно: Да
Содержание текущего разговора с моделью. Для одного раундового запроса это один экземпляр. Для многораундовых запросов, таких как чат, это повторяющееся поле, содержащее историю разговоров и последний запрос.
Свойства объекта контента:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
parts | Массив | Да | Упорядоченная часть контента, составляющая одно сообщение |
role | Строка | Нет | Производитель контента в разговоре. user, model, function или tool |
Свойства объекта детали:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
text | Строка | Нет | Простое текстовое содержимое |
inlineData | Объект | Нет | Встроенные медиабайтовые данные |
functionCall | Объект | Нет | Запрос вызова функции |
functionResponse | Объект | Нет | Ответ на вызов функции |
executableCode | Объект | Нет | Исполняемый код |
codeExecutionResult | Объект | Нет | Результат выполнения кода |
Свойства объекта InlineData:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
mimeType | Строка | Да | MIME-тип носителя |
data | Строка | Да | Медиа-данные в кодировке Base64 |
Параметр fileData (file_data.file_uri) и File API не поддерживаются: изображения, аудио, видео и PDF передавайте через inlineData.
tools
- Тип: массив
- Обязательно: Нет
Список инструментов, которые модель может использовать для генерации следующего ответа. Поддерживаемые инструменты включают выполнение функций и кода.
Свойства объекта инструмента:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
functionDeclarations | Массив | Нет | Необязательный список объявлений функций |
codeExecution | Объект | Нет | Включить код выполнения модели |
Свойства объекта FunctionDeclaration:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | Строка | Да | Имя функции |
description | Строка | Нет | Описание функции |
parameters | Объект | Нет | Параметры функции, формат схемы JSON |
Свойства объекта FunctionCall:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | Строка | Да | Имя вызываемой функции |
args | Объект | Нет | Пары ключ-значение для параметров функции |
Свойства объекта FunctionResponse:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | Строка | Да | Имя вызываемой функции |
response | Объект | Да | Данные ответа на вызов функции |
Свойства объекта ExecutableCode:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
language | Перечисление | Да | Язык программирования для кода |
code | Строка | Да | Код для выполнения |
Свойства объекта CodeExecutionResult:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
outcome | Перечисление | Да | Статус результата выполнения кода |
output | Строка | Нет | Вывод содержимого выполнения кода |
Свойства объекта CodeExecution:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
| Пустой объект | - | Пустой объект конфигурации, обеспечивающий выполнение кода |
toolConfig
- Тип: Объект
- Обязательно: Нет
Конфигурация инструмента для любых инструментов, указанных в запросе.
Свойства объекта ToolConfig:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
functionCallingConfig | Объект | Нет | Конфигурация вызова функции |
Свойства объекта FunctionCallingConfig:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
mode | Перечисление | Нет | Определяет режим вызова функции |
allowedFunctionNames | Массив | Нет | Список имен функций, которые разрешено вызывать |
Значение перечисления FunctionCallingMode:
MODE_UNSPECIFIED: режим по умолчанию, модель определяет, вызывать ли функцию.AUTO: модель автоматически решает, когда вызывать функцию.ANY: модель должна вызвать функциюNONE: модель не может вызывать функции.
safetySettings
- Тип: массив
- Обязательно: Нет
Список экземпляров SafetySetting, используемых для блокировки небезопасного содержимого.
Свойства объекта SafetySetting:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
category | Перечисление | Да | Класс безопасности |
threshold | Перечисление | Да | Порог маскировки |
Значение перечисления HarmCategory:
HARM_CATEGORY_HARASSMENT: оскорбительный контент.HARM_CATEGORY_HATE_SPEECH: разжигание ненависти и контент.HARM_CATEGORY_SEXUALLY_EXPLICIT: контент откровенно сексуального характера.HARM_CATEGORY_DANGEROUS_CONTENT: Опасный контент.HARM_CATEGORY_CIVIC_INTEGRITY: Контент, который может быть использован для подрыва целостности граждан.
Значение перечисления HarmBlockThreshold:
BLOCK_LOW_AND_ABOVE: разрешить контент с рейтингом НЕЗНАЧИТЕЛЬНЫЙ.BLOCK_MEDIUM_AND_ABOVE: разрешить контент с рейтингом НЕЗНАЧИТЕЛЬНЫЙ и НИЗКИЙ.BLOCK_ONLY_HIGH: разрешает контент с уровнями риска НЕБОЛЬШОЙ, НИЗКИЙ и СРЕДНИЙ.BLOCK_NONE: разрешить весь контент.OFF: отключить фильтр безопасности.
HarmBlockThreshold полное перечисление:
HARM_BLOCK_THRESHOLD_UNSPECIFIED: пороговое значение не указано.BLOCK_LOW_AND_ABOVE: блокировать вредоносный контент с низкой вероятностью и выше и разрешать только контент НЕзначительного уровня.BLOCK_MEDIUM_AND_ABOVE: блокирует вредоносный контент со средней вероятностью и выше и разрешает контент НЕзначительного и НИЗКОГО уровня.BLOCK_ONLY_HIGH: блокирует только вредоносный контент с высокой вероятностью, допуская контент НЕзначительного, НИЗКОГО и СРЕДНЕГО уровня.BLOCK_NONE: не блокирует контент, разрешает все уровни контента.OFF: полностью отключить фильтр безопасности.
systemInstruction
- Тип: Объект (Содержимое)
- Обязательно: Нет
Системные команды, заданные разработчиками. В настоящее время поддерживается только текст.
generationConfig
- Тип: Объект
- Обязательно: Нет
Параметры конфигурации для создания и вывода модели.
Свойства объекта GenerationConfig:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
stopSequences | Массив | Нет | Набор последовательностей символов (до 5), используемых для остановки генерации вывода |
responseMimeType | Строка | Нет | MIME-тип сгенерированного текста-кандидата |
responseSchema | Объект | Нет | Выходная схема сгенерированного текста-кандидата |
responseModalities | Массив | Нет | Запрошенный режим ответа |
candidateCount | Целое число | Нет | Количество сгенерированных ответов для возврата |
maxOutputTokens | Целое число | Нет | Максимальное количество токенов, включенных в ответ кандидата |
temperature | Номер | Нет | Управляет случайностью вывода, диапазон [0.0, 2.0] |
topP | Номер | Нет | Верхний предел кумулятивной вероятности токенов, которые следует учитывать при выборке |
topK | Целое число | Нет | Максимальное количество токенов, которые следует учитывать при выборке |
seed | Целое число | Нет | Начальное значение, используемое при декодировании |
presencePenalty | Номер | Нет | Экзистенциальное наказание |
frequencyPenalty | Номер | Нет | Штраф за частоту |
responseLogprobs | Логическое | Нет | Экспортировать ли результаты logprobs в ответе |
logprobs | Целое число | Нет | Число возвращенных самых популярных лог-проб |
enableEnhancedCivicAnswers | Логическое | Нет | Включить расширенные городские службы Ответ |
speechConfig | Объект | Нет | Конфигурация генерации речи |
thinkingConfig | Объект | Нет | Подумайте о настройке функции |
mediaResolution | Перечисление | Нет | Указанное медиа-разрешение |
Поддерживаемые типы MIME:
text/plain: текстовый вывод (по умолчанию).application/json: ответ JSON.text/x.enum: ENUM как строковый ответ.
Значение перечисления модальности:
TEXT: указывает, что модель должна возвращать текст.IMAGE: указывает, что модель должна возвращать изображения.AUDIO: указывает, что модель должна возвращать звук.
Свойства объекта схемы:
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
type | Перечисление | Да | Тип данных |
description | Строка | Нет | Описание поля |
enum | Массив | Нет | Список значений перечисления (если типом является строка) |
example | Любой тип | Нет | Пример значения |
nullable | Логическое значение | Нет | Может быть нулевым |
format | Строка | Нет | Строковый формат (например, дата, дата и время и т. д.) |
items | Объект | Нет | Схема элементов массива (когда типом является массив) |
properties | Объект | Нет | Отображение схемы свойств объекта (когда типом является объект) |
required | Массив | Нет | Список названий необходимых свойств |
minimum | Номер | Нет | Минимальное значение числа |
maximum | Номер | Нет | Максимальное значение числа |
minItems | Целое число | Нет | Минимальная длина массива |
maxItems | Целое число | Нет | Максимальная длина массива |
minLength | Целое число | Нет | Минимальная длина строки |
maxLength | Целое число | Нет | Максимальная длина строки |
Введите значение перечисления:
TYPE_UNSPECIFIED: неопределенный типSTRING: строковый тип.NUMBER: числовой тип.INTEGER: целочисленный тип.BOOLEAN: логический тип.ARRAY: тип массиваOBJECT: тип объекта
Поддерживаемые языки программирования (ExecutableCode):
LANGUAGE_UNSPECIFIED: язык не указан.PYTHON: язык программирования Python.
Перечисление результатов выполнения кода (Результат):
OUTCOME_UNSPECIFIED: Неизвестный результатOUTCOME_OK: выполнение кода выполнено успешно.OUTCOME_FAILED: выполнение кода не выполнено.OUTCOME_DEADLINE_EXCEEDED: тайм-аут выполнения кода.
cachedContent
- Тип: строка
- Обязательно: Нет
Имя кэшированного контента, используемого в качестве контекста для предоставления прогнозов. Формат: cachedContents/{cachedContent}
📥 Ответ
GenerateContentResponse
Ответы для моделей, поддерживающих несколько вариантов ответа. Рейтинги безопасности и фильтрация контента отображаются для запроса и для каждого кандидата.
candidates
- Тип: массив
- Описание: Список возможных ответов для модели.
Свойства объекта-кандидата:
| Свойство | Тип | Описание |
|---|---|---|
content | Объект | Сгенерированный контент, возвращаемый моделью |
finishReason | Перечисление | Причина, по которой модель перестала генерировать токены |
safetyRatings | Массив | Список рейтингов безопасности ответов кандидатов |
citationMetadata | Объект | Справочная информация кандидатов, генерируемая моделью |
tokenCount | Целое число | Количество токенов для этого кандидата |
groundingAttributions | Массив | Информация о поставщике, к которой можно обратиться для получения обоснованного ответа |
groundingMetadata | Объект | Справочные метаданные для объекта-кандидата |
avgLogprobs | Номер | Средний логарифмический балл вероятности кандидата |
logprobsResult | Объект | Логарифмическая оценка правдоподобия токена ответа и добавленного токена |
urlRetrievalMetadata | Объект | Метаданные, относящиеся к инструменту контекстного поиска URL |
urlContextMetadata | Объект | Метаданные, относящиеся к инструменту контекстного поиска URL |
index | Целое число | Индекс кандидата в списке ответивших кандидатов |
| Значение перечисления FinishReason: |
STOP: естественная точка остановки модели или предусмотренная последовательность остановки.MAX_TOKENS: достигнуто максимальное количество токенов, указанное в запросе.SAFETY: В целях безопасности система пометила кандидатов на ответ.RECITATION: в целях запоминания содержимое варианта ответа помечается.LANGUAGE: кандидат на ответ помечен как написанный на неподдерживаемом языке.OTHER: неизвестная причина.BLOCKLIST: операция создания токена остановлена, поскольку содержимое содержит запрещенные слова.PROHIBITED_CONTENT: операция создания токена остановлена из-за возможного запрещенного контента.SPII: операция создания токена остановлена, поскольку содержимое может содержать конфиденциальную личную информацию.MALFORMED_FUNCTION_CALL: неверный вызов функции, сгенерированный моделью.IMAGE_SAFETY: создание токена остановлено, поскольку созданное изображение нарушает правила безопасности.
promptFeedback
- Тип: Объект
- Описание: Оперативная обратная связь, связанная с фильтрами контента.
Свойства объекта PromptFeedback:
| Свойство | Тип | Описание |
|---|---|---|
blockReason | Перечисление | Причина закрытия этого запроса |
safetyRatings | Массив | Рейтинг защищенности вопросов |
Значение перечисления BlockReason:
BLOCK_REASON_UNSPECIFIED: значение по умолчанию, это значение не используется.SAFETY: по соображениям безопасности система блокирует запросOTHER: запрос заблокирован по неизвестным причинам.BLOCKLIST: это приглашение было заблокировано, поскольку оно содержит термин, включенный в список заблокированных терминов.PROHIBITED_CONTENT: это приглашение заблокировано, поскольку оно содержит запрещенный контент.IMAGE_SAFETY: изображение-кандидат заблокировано за создание небезопасного контента.
usageMetadata
- Тип: Объект
- Описание: Метаданные о сумме, использованной для генерации токена запроса.
Свойства объекта UsageMetadata:
| Свойство | Тип | Описание |
|---|---|---|
promptTokenCount | Целое число | Количество токенов в подсказке |
cachedContentTokenCount | Целое число | Количество токенов в кэшированной части приглашения |
candidatesTokenCount | Целое число | Общее количество токенов во всех сгенерированных ответах кандидатов |
totalTokenCount | Целое число | Общее количество токенов, сгенерированных для запроса |
toolUsePromptTokenCount | Целое число | Количество токенов в советах по использованию инструментов |
thoughtsTokenCount | Целое число | Количество токенов идей модели мышления |
promptTokensDetails | Массив | Список модальностей для обработки при вводе запроса |
candidatesTokensDetails | Массив | Список модальностей, возвращаемых в ответе |
cacheTokensDetails | Массив | Модальный список кэшированного контента при вводе запроса |
toolUsePromptTokensDetails | Массив | Список модальностей для обработки ввода запроса на использование инструмента |
modelVersion
- Тип: строка
- Описание: версия модели, использованная для генерации ответа.
responseId
- Тип: строка
- Описание: идентификатор, используемый для идентификации каждого ответа.
Полный пример ответа
{
"candidates": [
{
"content": {
"parts": [
{
"text": "你好!我是 Gemini,一个由 Google 开发的人工智能助手。我可以帮助您解答问题、提供信息、协助写作、代码编程等多种任务。请告诉我有什么可以为您效劳的!"
}
],
"role": "model"
},
"finishReason": "STOP",
"index": 0,
"safetyRatings": [
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_HARASSMENT",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"probability": "NEGLIGIBLE",
"blocked": false
}
],
"tokenCount": 47
}
],
"promptFeedback": {
"safetyRatings": [
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE"
}
]
},
"usageMetadata": {
"promptTokenCount": 4,
"candidatesTokenCount": 47,
"totalTokenCount": 51,
"promptTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 4
}
],
"candidatesTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 47
}
]
},
"modelVersion": "gemini-3.5-flash",
"responseId": "response-12345"
}🔧 Расширенные функции
Рейтинг безопасности
Свойства объекта SafetyRating:
| Свойство | Тип | Описание |
|---|---|---|
category | Перечисление | Категории для этого рейтинга |
probability | Перечисление | Вероятность того, что этот контент является вредоносным |
blocked | Логическое значение | Будет ли этот контент заблокирован из-за этого рейтинга |
Значение перечисления HarmProbability:
NEGLIGIBLE: вероятность того, что контент небезопасен, незначительна.LOW: контент с меньшей вероятностью будет небезопасным.MEDIUM: существует средняя вероятность того, что контент небезопасен.HIGH: существует высокая вероятность того, что контент небезопасен.
Справочные метаданные
Свойства объекта CitationMetadata:
| Свойство | Тип | Описание |
|---|---|---|
citationSources | Массив | Ссылка на источник для конкретного ответа |
Свойства объекта CitationSource:
| Свойство | Тип | Описание |
|---|---|---|
startIndex | Целое число | Начальный индекс фрагментов ответа, приписываемых этому источнику |
endIndex | Целое число | Конечный индекс сегмента атрибуции (эксклюзивный) |
uri | Строка | URI, присвоенный источнику текстовой части |
license | Строка | Лицензия проекта GitHub, указанная как источник фрагмента |
Выполнение кода
Когда инструменты выполнения кода включены, модель может генерировать и выполнять код для решения проблемы.
Пример ответа на выполнение кода:
{
"candidates": [
{
"content": {
"parts": [
{
"text": "我来计算斐波那契数列的第10项:"
},
{
"executableCode": {
"language": "PYTHON",
"code": "def fibonacci(n):\n if n <= 1:\n return n\n else:\n return fibonacci(n-1) + fibonacci(n-2)\n\nresult = fibonacci(10)\nprint(f'Нет.10Термин число Фибоначчи: {result}')"
}
},
{
"codeExecutionResult": {
"outcome": "OK",
"output": "Нет.10Термин число Фибоначчи: 55"
}
},
{
"text": "所以斐波那契数列的第10项是55。"
}
],
"role": "model"
},
"finishReason": "STOP"
}
]
}Функция заземления (Заземление)
Свойства объекта GroundingMetadata:
| Свойство | Тип | Описание |
|---|---|---|
groundingChunks | Массив | Список подтверждающих ссылок, полученных из указанного наземного источника |
groundingSupports | Массив | Список наземной поддержки |
webSearchQueries | Массив | Поисковый запрос в Интернете для последующего поиска в Интернете |
searchEntryPoint | Объект | Условия поиска Google для последующего поиска в Интернете |
retrievalMetadata | Объект | Метаданные, связанные с поиском в базовом процессе |
Свойства объекта GroundingAttribution:
| Свойство | Тип | Описание |
|---|---|---|
sourceId | Объект | Идентификатор источника, который способствовал этой атрибуции |
content | Объект | Исходное содержание, составляющее данное указание |
Атрибут объекта AttributionSourceId:
| Свойство | Тип | Описание |
|---|---|---|
groundingPassage | Объект | Идентификатор встроенного абзаца |
semanticRetrieverChunk | Объект | Идентификатор чанка, извлеченный Semantic Retriever |
Свойство объекта GroundingPassageId:
| Свойство | Тип | Описание |
|---|---|---|
passageId | Строка | Идентификатор абзаца, который соответствует GroundingPassage.id GenerateAnswerRequest |
partIndex | Целое число | Индекс раздела в GroundingPassage.content GenerateAnswerRequest |
Свойства объекта SemanticRetrieverChunk:
| Свойство | Тип | Описание |
|---|---|---|
source | Строка | Имя источника, соответствующее запрошенному SemanticRetrieverConfig.source |
chunk | Строка | Имя чанка, содержащего текст атрибуции |
Свойства объекта SearchEntryPoint:
| Свойство | Тип | Описание |
|---|---|---|
renderedContent | Строка | Фрагмент кода веб-контента, который можно внедрить в веб-страницу или приложение. WebView |
sdkBlob | Строка | JSON в кодировке Base64, массив, представляющий поисковый запрос и кортежи поисковых URL |
Свойства объекта сегмента:
| Свойство | Тип | Описание |
|---|---|---|
partIndex | Целое число | Индекс объекта Part в его родительском объекте Content |
startIndex | Целое число | Начальный индекс в данной части, в байтах |
endIndex | Целое число | Конечный индекс в данном фрагменте, в байтах |
text | Строка | Текст, соответствующий фрагменту ответа |
Свойства объекта RetrivalMetadata:
| Свойство | Тип | Описание |
|---|---|---|
googleSearchDynamicRetrievalScore | Номер | Оценка вероятности того, что информация в поиске Google поможет ответить на вопрос, диапазон [0,1] |
Свойства объекта GroundingChunk:
| Свойство | Тип | Описание |
|---|---|---|
web | Объект | Блок заземления от сети |
Свойства веб-объекта:
| Свойство | Тип | Описание |
|---|---|---|
uri | Строка | Ссылка на фрагментированный URI |
title | Строка | Название блока данных |
Свойства объекта GroundingSupport:
| Свойство | Тип | Описание |
|---|---|---|
groundingChunkIndices | Массив | Список указателей с указанием цитат, имеющих отношение к заявлению об авторских правах |
confidenceScores | Массив | Поддерживает оценку достоверности справочного документа в диапазоне от 0 до 1 |
segment | Объект | Фрагмент контента, к которому принадлежит этот запрос на поддержку |
Мультимодальная обработка
Gemini API поддерживает обработку ввода и вывода нескольких модальностей:
Поддерживаемые модальные окна ввода:
TEXT: обычный текстIMAGE: изображения (JPEG, PNG, WebP, HEIC, HEIF)AUDIO: аудио (WAV, MP3, AIFF, AAC, OGG, FLAC)VIDEO: видео (MP4, MPEG, MOV, AVI, FLV, MPG, WEBM, WMV, 3GPP)DOCUMENT: Документация (PDF)
Свойства объекта ModalityTokenCount:
| Свойство | Тип | Описание |
|---|---|---|
modality | Перечисление | Модальное окно, связанное с этим номером токена |
tokenCount | Целое число | Количество токенов |
Значение перечисления MediaResolution:
MEDIA_RESOLUTION_LOW: низкое разрешение (64 токена)MEDIA_RESOLUTION_MEDIUM: среднее разрешение (256 токенов)MEDIA_RESOLUTION_HIGH: Высокое разрешение (256 токенов для рефрейминга масштабирования)
Функция мышления
Свойства объекта ThinkingConfig:
| Свойство | Тип | Описание |
|---|---|---|
includeThoughts | Логическое значение | Включать ли в ответ размышления |
thinkingBudget | Целое число | Количество токенов идей, которые должна сгенерировать модель |
Генерация речи
Подробности о синтезе речи, список голосов и примеры — в разделе API для речи.
Свойства объекта SpeechConfig:
| Свойство | Тип | Описание |
|---|---|---|
voiceConfig | Объект | Настройка одного голоса |
multiSpeakerVoiceConfig | Объект | Настройка нескольких говорящих |
languageCode | Строка | Код языка, используемый для синтеза речи |
Свойства объекта VoiceConfig:
| Свойство | Тип | Описание |
|---|---|---|
prebuiltVoiceConfig | Объект | Конфигурация встроенного голоса для использования |
Свойства объекта PrebuiltVoiceConfig:
| Свойство | Тип | Описание |
|---|---|---|
voiceName | Строка | Имя предустановленного голоса, который будет использоваться |
| Свойства объекта MultiSpeakerVoiceConfig: |
| Свойство | Тип | Описание |
|---|---|---|
speakerVoiceConfigs | Массив | Голоса каждого говорящего (не более 2) |
Свойства объекта SpeakerVoiceConfig:
| Свойство | Тип | Описание |
|---|---|---|
speaker | Строка | Имя говорящего |
voiceConfig | Объект | Настройка используемого голоса |
Поддерживаемые коды языков:
zh-CN: китайский (упрощенный)en-US: английский (США)ja-JP: японскийko-KR: корейскийfr-FR: французскийde-DE: немецкийes-ES: испанскийpt-BR: португальский (Бразилия)hi-IN: хиндиar-XA: арабскийit-IT: итальянскийtr-TR: турецкийvi-VN: вьетнамскийth-TH: Тайскийru-RU: Русскийpl-PL: польскийnl-NL: голландский
Результаты журналов проб
Свойства объекта LogprobsResult:
| Свойство | Тип | Описание |
|---|---|---|
topCandidates | Массив | Длина равна общему количеству шагов декодирования |
chosenCandidates | Массив | Длина равна общему количеству шагов декодирования, выбранный кандидат не обязательно находится в topCandidates |
Свойства объекта TopCandidates:
| Свойство | Тип | Описание |
|---|---|---|
candidates | Массив | Кандидаты отсортированы в порядке убывания логарифмической вероятности |
Свойства объекта-кандидата (Logprobs):
| Свойство | Тип | Описание |
|---|---|---|
token | Строка | Строковое значение токена кандидата |
tokenId | Целое число | Значение идентификатора токена кандидата |
logProbability | Номер | Логарифм вероятности кандидата |
Функция поиска URL-адресов
Свойства объекта UrlRetrivalMetadata:
| Свойство | Тип | Описание |
|---|---|---|
urlRetrievalContexts | Массив | Список ситуаций с получением URL-адресов |
Свойства объекта UrlRetrivalContext:
| Свойство | Тип | Описание |
|---|---|---|
retrievedUrl | Строка | URL-адрес, полученный инструментом |
Свойства объекта UrlContextMetadata:
| Свойство | Тип | Описание |
|---|---|---|
urlMetadata | Массив | Список контекстов URL |
Свойства объекта UrlMetadata:
| Свойство | Тип | Описание |
|---|---|---|
retrievedUrl | Строка | URL-адрес, полученный инструментом |
urlRetrievalStatus | Перечисление | Статус получения URL |
Значение перечисления UrlRetrivalStatus:
URL_RETRIEVAL_STATUS_SUCCESS: URL-адрес получен успешно.URL_RETRIEVAL_STATUS_ERROR: не удалось получить URL-адрес из-за ошибки.
Полная категория безопасности
Полное перечисление HarmCategory:
HARM_CATEGORY_UNSPECIFIED: Категория не указана.HARM_CATEGORY_DEROGATORY: PaLM - Негативные или вредные комментарии об личности и/или защищенных свойствах.HARM_CATEGORY_TOXICITY: PaLM - Грубый, неуважительный или оскорбительный контент.HARM_CATEGORY_VIOLENCE: PaLM - описывает сцены, изображающие насилие против отдельного человека или группы людей.HARM_CATEGORY_SEXUAL: PaLM - Содержит ссылки на сексуальные действия или другой непристойный контент.HARM_CATEGORY_MEDICAL: PaLM - Пропаганда непроверенных медицинских советов.HARM_CATEGORY_DANGEROUS: PaLM - Опасный контент пропагандирует, пропагандирует или поощряет вредное поведение.HARM_CATEGORY_HARASSMENT: Gemini — Контент с оскорблениямиHARM_CATEGORY_HATE_SPEECH: Gemini — разжигание ненависти и контентHARM_CATEGORY_SEXUALLY_EXPLICIT: Gemini — Контент сексуального характераHARM_CATEGORY_DANGEROUS_CONTENT: Gemini — Опасный контентHARM_CATEGORY_CIVIC_INTEGRITY: Gemini - Контент, который может быть использован для подрыва неприкосновенности граждан.
Полное перечисление HarmProbability:
HARM_PROBABILITY_UNSPECIFIED: вероятность не указанаNEGLIGIBLE: вероятность того, что контент небезопасен, незначительна.LOW: контент с меньшей вероятностью будет небезопасным.MEDIUM: существует средняя вероятность того, что контент небезопасен.HIGH: существует высокая вероятность того, что контент небезопасен.
Полное значение модальности:
MODALITY_UNSPECIFIED: модальное окно не указано.TEXT: обычный текстIMAGE: ИзображениеVIDEO: ВидеоAUDIO: АудиоDOCUMENT: документ, например PDF.
Полное значение перечисления MediaResolution:
MEDIA_RESOLUTION_UNSPECIFIED: разрешение носителя не установлено.MEDIA_RESOLUTION_LOW: разрешение мультимедиа установлено на низкое (64 токена).MEDIA_RESOLUTION_MEDIUM: разрешение мультимедиа установлено на среднее (256 токенов).MEDIA_RESOLUTION_HIGH: высокое разрешение мультимедиа (используйте 256 токенов для изменения масштаба)
Полное значение перечисления UrlRetrivalStatus:
URL_RETRIEVAL_STATUS_UNSPECIFIED: значение по умолчанию, это значение не используется.URL_RETRIEVAL_STATUS_SUCCESS: URL-адрес получен успешно.URL_RETRIEVAL_STATUS_ERROR: не удалось получить URL-адрес из-за ошибки.
🔍 Обработка ошибок
Распространенные коды ошибок
| Код ошибки | Описание |
|---|---|
400 | Неправильный формат запроса или неверные параметры |
401 | Неверный или отсутствующий ключ API |
403 | Недостаточно разрешений или ограничений квот |
429 | Частота запросов слишком высока |
500 | Внутренняя ошибка сервера |
Подробное описание кода ошибки
| Код ошибки | Статус | Описание | Решение |
|---|---|---|---|
400 | INVALID_ARGUMENT | Параметр запроса недействителен или имеет неверный формат | Проверьте формат параметров запроса и обязательные поля |
400 | FAILED_PRECONDITION | Запрошенные предварительные условия не выполнены | Убедитесь, что предварительные условия для вызова API выполнены |
401 | UNAUTHENTICATED | Ключ API недействителен, отсутствует или срок его действия истек | Проверка действительности и формата ключа API |
403 | PERMISSION_DENIED | Недостаточно разрешений или квота исчерпана | Проверьте разрешения ключа API или обновите квоту |
404 | NOT_FOUND | Указанная модель или ресурс не существует | Проверьте имя модели и путь к ресурсу |
413 | PAYLOAD_TOO_LARGE | Тело запроса слишком велико | Уменьшите размер входного содержимого или обработайте его пакетно |
429 | RESOURCE_EXHAUSTED | Частота запросов превышает лимит или квота недостаточна | Уменьшите частоту запросов или дождитесь сброса квоты |
500 | INTERNAL | Внутренняя ошибка сервера | Повторите запрос, если он не исчезнет, обратитесь в службу поддержки |
503 | UNAVAILABLE | Услуга временно недоступна | Пожалуйста, подождите некоторое время и повторите попытку |
504 | DEADLINE_EXCEEDED | Запросить тайм-аут | Уменьшите размер ввода или повторите запрос |
Пример ответа об ошибке
{
"error": {
"code": 400,
"message": "Invalid argument: contents",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "contents",
"description": "contents is required"
}
]
}
]
}
}