ym88659208ym87991671
Обращение к встроенным функциям | Документация для разработчиков

Обращение к встроенным функциям

Обновлено 4 августа 2025

Встроенные функции — это функции, которые исполняются внутри сервиса GigaChat. Так, если после авторизации на giga.chat , вы попросите модель нарисовать картинку, она обратится к встроенной функции text2image. Модель покажет итоговое изображение, созданное этой функцией.

Моделям доступны функции:

  • text2image

    Генерация изображения в формате JPEG.

    Для работы с функцией передайте запрос с включенным автоматическим режимом "function_call": "auto". При этом в запросе не должно быть массива functions или он должен содержать название функции.

  • get_file_content

    Использование текстовых документов для генерации ответа.

    Функцию можно использовать, если передать в запросе массив functions и/или "function_call": "auto", а также идентификаторы файлов в массиве attachments. Посмотреть доступные в хранилище файлы можно с помощью метода GET /files. Подробнее — в разделе Обработка файлов.

  • text2model3d

    Генерация модели в формате FBX.

    Для обращения к функции генерации 3D-модели запрос должен содержать ее название в массиве functions, а также поле "function_call": "auto".

В этом разделе вы найдете примеры запросов для обращения к встроенным функциям, узнаете как сохранять контекст и использовать режим потоковой генерации токенов при работе со встроенными функциями.

Создание изображения

Чтобы модель сгенерировала изображение по описанию, переданному в промпте, запустите работу с функциями в авторежиме ("function_call": "auto"):

curl -L -X POST 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <токен_доступа>' \
--data-raw '{
"model": "GigaChat",
"messages": [
{
"role": "system",
"content": "Ты — Василий Кандинский"
},
{
"role": "user",
"content": "Нарисуй розового кота"
}
],
"function_call": "auto"
}'

Ответ модели будет содержать идентификатор получившегося изображения в формате uuid4. Идентификатор передается в поле message.content, в теге <img>, в атрибуте src:

{
"choices": [
{
"message": {
"content": "Запускаю генерацию изображения. Ожидайте результат <img src=\"b28fbd4f-105a-43e0-ba5a-2faa80b1f43c\" fuse=\"true\"/> — вот розовый кот, который у меня получился.",
"role": "assistant",
"functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003"
},
"index": 0,
"finish_reason": "stop"
}
],
"created": 1716367703,
"model": "GigaChat:3.1.25.3",
"object": "chat.completion",
"usage": {
"prompt_tokens": 372,
"completion_tokens": 48,
"total_tokens": 420
}
}

Для скачивания файла из хранилища используйте метод GET /files/{file_id}/content:

curl -L -X GET 'https://gigachat.devices.sberbank.ru/api/v1/files/<идентификатор_файла>/content' -o "<имя_файла>.jpeg" \
-H 'Accept: application/jpeg' \
-H 'Authorization: Bearer <токен_доступа>'

Создание 3D-модели

Для создания 3D-модели запустите работу с функциями в автоматическом режиме и передайте название функции в массиве functions:

curl -L -X POST 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <токен_доступа>' \
--data-raw '{
"model": "GigaChat",
"messages": [
{
"role": "user",
"content": "Сгенерируй 3D-модель шара"
}
],
"function_call": "auto",
"functions": [
{
"name": "text2model3d"
}
]
}'

Ответ модели будет содержать <div>-блок с атрибутом data-model-id, в котором передается идентификатор сгенерированной 3D-модели.

{
"choices": [
{
"message": {
"content": "<div data-model-id=\"2dc37408-f70a-4225-8e0a-8da749ceffac\" fuse=\"true\"/> получилась такая 3D модель шара.",
"role": "assistant",
"functions_state_id": "7421eccb-f732-483b-9018-755233d3f3b7"
},
"index": 0,
"finish_reason": "stop"
}
],
"created": 1716367703,
"model": "GigaChat:3.1.25.3",
"object": "chat.completion",
"usage": {
"prompt_tokens": 372,
"completion_tokens": 48,
"total_tokens": 420
}
}

Для скачивания файла из хранилища используйте метод GET /files/{file_id}/content:

curl -L -X GET 'https://gigachat.devices.sberbank.ru/api/v1/files/<идентификатор_3d_модели>/content' -o "<имя_файла>.fbx" \
-H 'Accept: application/jpeg' \
-H 'Authorization: Bearer <токен_доступа>'

Обработка документов

Модели могут обращаться к встроенной функции обработки документов, если массив attachments содержит идентификаторы документов, а работа с функциями запущена в авторежиме ("function_call": "auto").

Посмотреть доступные в хранилище файлы можно с помощью метода GET /files.

Подробнее — в разделе Обработка файлов.

Пример:

curl --location 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ключ_авторизации>' \
--data '{
"model": "GigaChat-2-Max",
"function_call": "auto",
"messages": [
{
"role": "user",
"content": "Сделай краткий пересказ документа",
"attachments": [
"e28a83b0-611c-4d15-930a-eb742385245b"
]
}
]
}'

Совместное использование встроенных и пользовательских функций

При работе с пользовательскими функциями, запрос всегда будет содержать массив functions.

Чтобы модели могли обращаться к встроенным функциям, их названия нужно обязательно передавать в массиве functions вместе с описанием пользовательских функций:

curl --location 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <токен_доступа>' \
--data '{
"model": "GigaChat-2-Pro",
"messages": [
{
"role": "user",
"content": "Нарисуй горы"
}
],
"function_call": "auto",
"functions": [
{
"name": "text2image"
},
{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы измерения температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть"
}
},
"required": [
"location",
"format"
]
}
}
]
}'

Сохранение контекста

Независимо от того, обратилась модель к встроенной функции или нет, ее ответ будет содержать идентификатор functions_state_id. Для сохранения контекста передавайте этот идентификатор в соответствующих сообщениях с ролью assistant:

{
"messages": [
{
"role": "user",
"content": "Нарисуй корову"
},
{
"content": "Добавил в очередь на генерацию изображения... <img src=\"4919dd7a-b97b-4ed9-8db0-5aa68f2bf24b\" fuse=\"true\"/> — вот такая корова у меня получилась.",
"role": "assistant",
"functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003"
},
{
"content": "А теперь нарисуй слона",
"role": "user"
}
],
"model": "GigaChat"
}

Потоковая генерация токенов

Работа встроенных функций может занимать продолжительное время. Вы можете обрабатывать ответ модели по мере его создания с помощью потоковой генерации токенов (параметр запроса "stream": true).

Пример запроса:

curl -L -X POST 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <токен_доступа>' \
--data-raw '{
"model": "GigaChat-Pro",
"messages": [
{
"role": "system",
"content": "Ты — Василий Кандинский"
},
{
"role": "user",
"content": "Нарисуй розового кота"
}
],
"function_call": "auto",
"stream": true,
}'

Пример ответа:

data: {"choices":[{"delta":{"content":"осталось 00:11","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401362,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"осталось 00:06","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401367,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"осталось 00:03","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401370,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"осталось 00:01","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401372,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"осталось 00:01","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401373,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"<img src=\"6fb0b045-e4c8-43b6-bd4d-06eb6cf267eb\" fuse=\"true\"/> вот иллюстрация Красной Шапочки.","role":"assistant"},"index":0}],"created":1733401374,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"","functions_state_id":"1a7f916c-053b-4649-9c7d-0ce0f4a0f515"},"index":0,"finish_reason":"stop"}],"created":1733401374,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion","usage":{"prompt_tokens":24,"completion_tokens":48,"total_tokens":72,"precached_prompt_tokens":0}}

data: [DONE]

Сообщения о запуске встроенной функции будут приходить с ролью function_in_progress. Они будут содержать данные о времени начала обработки, оставшемся времени до окончания работы функции и ее наименовании.

ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей. Вы можете запретить сохранение cookie в настройках своего браузера.