Skip to main content
POST
Создать chat completion
Поддерживает текстовые диалоги, мультимодальные запросы (текст + изображения + аудио + видео + файлы), вызов функций и потоковую передачу.

Возможности

  • Агрегация провайдеров — автоматический выбор оптимального провайдера
  • Биллинг в рублях — точный учет стоимости
  • Reasoning Tokens — поддержка моделей с рассуждениями
  • Streaming — потоковая передача через SSE
  • Tool Calling — вызов внешних функций
  • Мультимодальность — обработка текста, изображений, аудио, видео и файлов

Параметры запроса

Обязательные

Контент

Параметры генерации

Специальные возможности

Структура сообщений

Базовый формат

Мультимодальные сообщения

Другие типы контента

Системные сообщения с кешированием

Примеры

Ответ

Успешный ответ (200)

Streaming (SSE)

При stream: true ответ приходит в формате Server-Sent Events:

Tool Calling

Определение функций

Ответ модели с вызовом функции

Response Format

JSON Schema (структурированный вывод)

Поддерживаемые типы: text, json_object, json_schema, grammar (GBNF).

Reasoning Tokens

Для моделей с рассуждениями (o1, o3, DeepSeek-R1 и другие):

Параметры reasoning

Авторизации

Authorization
string
header
обязательно

API ключ передаётся в заголовке: Authorization: Bearer <POLZA_AI_API_KEY>

Тело

application/json
model
string
обязательно

Идентификатор модели. Для Chat Completions API поддерживается alias-формат @=&=. Поддерживаемые ключи: provider, reasoning_effort, allow_fallbacks, data_residency. При конфликте alias и обычных полей body API возвращает 400. Для некоторых провайдеров и моделей допустимые значения reasoning_effort отличаются; например, Yandex AI Studio поддерживает только low, medium и high.

Пример:

"openai/gpt-4o@provider=google&reasoning_effort=high&allow_fallbacks=false"

messages
object[]
обязательно

Массив сообщений для отправки модели (обязателен если не указан prompt)

Пример:
prompt
string

Текстовый промпт (альтернатива messages). Если указан, будет преобразован в messages с role=user

Пример:

"Напиши стихотворение про кота"

max_tokens
number

Максимальное количество токенов для генерации

Требуемый диапазон: x >= 1
Пример:

1000

max_completion_tokens
number

Максимальное количество токенов для completion (альтернатива max_tokens)

Требуемый диапазон: x >= 1
Пример:

1000

temperature
number

Температура сэмплинга (0-2). Более высокие значения делают вывод более случайным

Требуемый диапазон: 0 <= x <= 2
Пример:

1

top_p
number

Nucleus sampling: вероятностная масса для рассмотрения (0-1)

Требуемый диапазон: 0 <= x <= 1
Пример:

1

frequency_penalty
number

Штраф за частоту использования токенов (-2 до 2)

Требуемый диапазон: -2 <= x <= 2
Пример:

0

presence_penalty
number

Штраф за присутствие токенов (-2 до 2)

Требуемый диапазон: -2 <= x <= 2
Пример:

0

response_format
object

Формат ответа модели

provider
object

Настройки провайдера для роутинга и фильтрации

tools
object[]

Инструменты: функции (type: function) исполняет ваш код; серверные (type: polza:*) исполняет Polza внутри запроса

max_tool_calls
integer

Максимум вызовов серверных инструментов за запрос (по умолчанию 10, потолок 30; без polza:* игнорируется)

Требуемый диапазон: 1 <= x <= 30
Пример:

10

stop_server_tools_when
object[]

Условия остановки цикла серверных инструментов: step_count заменяет max_tool_calls (потолок 30), spend_cap добавляет мягкий потолок расходов на запрос: он проверяется перед каждым шагом модели, поэтому итог может превысить spend_cap на шаг, на котором потолок пройден, его инструменты и финальный ответ

stream_options
object

Опции стриминга

tool_choice
object

Выбор инструмента: none, auto, required или named function

Пример:

"auto"

reasoning
object

Настройки reasoning для reasoning моделей

plugins
array

Плагины для расширения функциональности

web_search_options
object

Включает веб-поиск для любой модели: поиск выполняет Polza (серверный инструмент polza:web_search, для модели без tool calling — поиск до вызова модели)

user
string

Уникальный идентификатор конечного пользователя для отслеживания и предотвращения злоупотреблений

Пример:

"user-123"

stop

Последовательности, при которых модель прекращает генерацию

Пример:
seed
number

Seed для детерминированной генерации (best-effort)

Пример:

42

n
number

Количество вариантов ответа (1-10)

Требуемый диапазон: 1 <= x <= 10
Пример:

1

stream
boolean

Включить потоковую передачу ответа

Пример:

false

logprobs
boolean

Возвращать log probabilities для output токенов

Пример:

false

top_logprobs
number

Количество наиболее вероятных токенов для возврата (0-20). Требует logprobs: true

Требуемый диапазон: 0 <= x <= 20
Пример:

5

logit_bias
object

Смещение вероятностей токенов по их ID (-100 до 100)

Пример:
parallel_tool_calls
boolean

Разрешить параллельный вызов нескольких tools

Пример:

true

image_config
object

Настройки обработки изображений

Пример:
media_resolution
string

Разрешение обработки медиа для google/gemini-* моделей (Gemini media_resolution). Допустимые значения: MEDIA_RESOLUTION_LOW, MEDIA_RESOLUTION_MEDIUM, MEDIA_RESOLUTION_HIGH, MEDIA_RESOLUTION_UNSPECIFIED. Для остальных моделей игнорируется.

Пример:

"MEDIA_RESOLUTION_LOW"

modalities
enum<string>[]

Типы вывода модели

Доступные опции:
text,
image,
audio
Пример:
audio
object

Настройки аудио выхода для моделей с поддержкой аудио (gpt-audio и др.)

Ответ

id
string
обязательно

Уникальный идентификатор генерации

Пример:

"gen_581761234567890123"

object
string
обязательно

Тип объекта

Пример:

"chat.completion"

created
number
обязательно

Временная метка создания (Unix timestamp)

Пример:

1703001234

model
string
обязательно

ID модели, которая сгенерировала ответ

Пример:

"openai/gpt-4o"

choices
object[]
обязательно

Массив вариантов ответа

provider
string

Провайдер обработавший запрос

Пример:

"openai-direct"

system_fingerprint
string

System fingerprint от провайдера

Пример:

"fp_29330a9688"

usage
object

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

polza
object

Есть, если модель вызывала серверные инструменты: parent_generation_id — id запроса в истории (GET /v1/history/generations/{id}), шаги — /children

Пример: