88API88API
Руководство пользователяAI-приложенияAPIПомощь и поддержка
Чат (Chat)

Формат разговора 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Внутренняя ошибка сервера

Подробное описание кода ошибки

Код ошибкиСтатусОписаниеРешение
400INVALID_ARGUMENTПараметр запроса недействителен или имеет неверный форматПроверьте формат параметров запроса и обязательные поля
400FAILED_PRECONDITIONЗапрошенные предварительные условия не выполненыУбедитесь, что предварительные условия для вызова API выполнены
401UNAUTHENTICATEDКлюч API недействителен, отсутствует или срок его действия истекПроверка действительности и формата ключа API
403PERMISSION_DENIEDНедостаточно разрешений или квота исчерпанаПроверьте разрешения ключа API или обновите квоту
404NOT_FOUNDУказанная модель или ресурс не существуетПроверьте имя модели и путь к ресурсу
413PAYLOAD_TOO_LARGEТело запроса слишком великоУменьшите размер входного содержимого или обработайте его пакетно
429RESOURCE_EXHAUSTEDЧастота запросов превышает лимит или квота недостаточнаУменьшите частоту запросов или дождитесь сброса квоты
500INTERNALВнутренняя ошибка сервераПовторите запрос, если он не исчезнет, ​​обратитесь в службу поддержки
503UNAVAILABLEУслуга временно недоступнаПожалуйста, подождите некоторое время и повторите попытку
504DEADLINE_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"
          }
        ]
      }
    ]
  }
}

Содержание

📝 Введение
💡 Пример запроса
Базовый текстовый разговор ✅
Диалог анализа изображения ✅
Вызов функции ✅
Ответ схемы JSON ✅
Обработка звука 🟡
Обработка видео 🟡
Обработка PDF 🟡
Разговор в чате ✅
Ответ в потоковом режиме ✅
Выполнение кода ✅
Генерация конфигурации ✅
Настройки безопасности ✅
Системные команды ✅
📮 Запрос
Конечная точка
Генерация контента
Потоковая передача сгенерированного контента
Метод аутентификации
Параметры пути
model
Параметры тела запроса
contents
tools
toolConfig
safetySettings
systemInstruction
generationConfig
cachedContent
📥 Ответ
GenerateContentResponse
candidates
promptFeedback
usageMetadata
modelVersion
responseId
Полный пример ответа
🔧 Расширенные функции
Рейтинг безопасности
Справочные метаданные
Выполнение кода
Функция заземления (Заземление)
Мультимодальная обработка
Функция мышления
Генерация речи
Результаты журналов проб
Функция поиска URL-адресов
Полная категория безопасности
🔍 Обработка ошибок
Распространенные коды ошибок
Подробное описание кода ошибки
Пример ответа об ошибке