POST Chat Completions

Создать chat completion

curl --request POST \
  --url https://polza.ai/api/v1/chat/completions \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "Ты полезный ассистент"
    },
    {
      "role": "user",
      "content": "Привет! Как дела?"
    }
  ],
  "prompt": "Напиши стихотворение про кота",
  "max_tokens": 1000,
  "max_completion_tokens": 1000,
  "temperature": 1,
  "top_p": 1,
  "frequency_penalty": 0,
  "presence_penalty": 0,
  "response_format": {},
  "provider": {
    "allow_fallbacks": true,
    "order": [
      "OpenAI",
      "Anthropic"
    ],
    "only": [
      "OpenAI",
      "Google"
    ],
    "ignore": [
      "DeepInfra"
    ],
    "sort": "price",
    "max_price": {
      "prompt": 10,
      "completion": 20,
      "image": 5,
      "audio": 15,
      "request": 1
    }
  },
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Получить текущую погоду для указанного местоположения",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "Название города"
            },
            "unit": {
              "type": "string",
              "enum": [
                "celsius",
                "fahrenheit"
              ]
            }
          },
          "required": [
            "location"
          ]
        },
        "strict": false
      }
    }
  ],
  "tool_choice": "auto",
  "reasoning": {
    "effort": "medium",
    "summary": "auto",
    "enabled": true,
    "max_tokens": 2000,
    "exclude": false
  },
  "plugins": "<array>",
  "web_search_options": {
    "search_context_size": "medium"
  },
  "user": "user-123",
  "stream": false,
  "image_config": {
    "quality": "high",
    "size": 512
  },
  "modalities": [
    "text",
    "audio"
  ],
  "audio": {
    "voice": "alloy",
    "format": "pcm16"
  }
}
'

{
  "id": "gen_581761234567890123",
  "object": "chat.completion",
  "created": 1703001234,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Я хорошо, спасибо что спросили. Чем могу помочь?",
        "name": "Ассистент",
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"Moscow\"}"
            }
          }
        ],
        "refusal": null,
        "reasoning": null,
        "audio": {
          "id": "<string>",
          "data": "<string>",
          "transcript": "<string>",
          "expires_at": 123
        }
      },
      "finish_reason": "stop",
      "reasoning_details": "<array>",
      "logprobs": {
        "content": [
          {
            "token": "hello",
            "logprob": -0.5,
            "bytes": [
              104,
              101,
              108,
              108,
              111
            ],
            "top_logprobs": [
              {
                "token": "hello",
                "logprob": -0.5,
                "bytes": [
                  104,
                  101,
                  108,
                  108,
                  111
                ]
              }
            ]
          }
        ],
        "refusal": [
          {
            "token": "hello",
            "logprob": -0.5,
            "bytes": [
              104,
              101,
              108,
              108,
              111
            ],
            "top_logprobs": [
              {
                "token": "hello",
                "logprob": -0.5,
                "bytes": [
                  104,
                  101,
                  108,
                  108,
                  111
                ]
              }
            ]
          }
        ]
      }
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 50,
    "total_tokens": 60,
    "completion_tokens_details": {
      "reasoning_tokens": 100,
      "audio_tokens": 0,
      "image_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0,
      "video_tokens": 0
    },
    "cost_rub": 0.04131306,
    "cost": 0.04131306
  }
}

POST

chat

completions

Создать chat completion

curl --request POST \
  --url https://polza.ai/api/v1/chat/completions \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "Ты полезный ассистент"
    },
    {
      "role": "user",
      "content": "Привет! Как дела?"
    }
  ],
  "prompt": "Напиши стихотворение про кота",
  "max_tokens": 1000,
  "max_completion_tokens": 1000,
  "temperature": 1,
  "top_p": 1,
  "frequency_penalty": 0,
  "presence_penalty": 0,
  "response_format": {},
  "provider": {
    "allow_fallbacks": true,
    "order": [
      "OpenAI",
      "Anthropic"
    ],
    "only": [
      "OpenAI",
      "Google"
    ],
    "ignore": [
      "DeepInfra"
    ],
    "sort": "price",
    "max_price": {
      "prompt": 10,
      "completion": 20,
      "image": 5,
      "audio": 15,
      "request": 1
    }
  },
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Получить текущую погоду для указанного местоположения",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "Название города"
            },
            "unit": {
              "type": "string",
              "enum": [
                "celsius",
                "fahrenheit"
              ]
            }
          },
          "required": [
            "location"
          ]
        },
        "strict": false
      }
    }
  ],
  "tool_choice": "auto",
  "reasoning": {
    "effort": "medium",
    "summary": "auto",
    "enabled": true,
    "max_tokens": 2000,
    "exclude": false
  },
  "plugins": "<array>",
  "web_search_options": {
    "search_context_size": "medium"
  },
  "user": "user-123",
  "stream": false,
  "image_config": {
    "quality": "high",
    "size": 512
  },
  "modalities": [
    "text",
    "audio"
  ],
  "audio": {
    "voice": "alloy",
    "format": "pcm16"
  }
}
'

{
  "id": "gen_581761234567890123",
  "object": "chat.completion",
  "created": 1703001234,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Я хорошо, спасибо что спросили. Чем могу помочь?",
        "name": "Ассистент",
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"Moscow\"}"
            }
          }
        ],
        "refusal": null,
        "reasoning": null,
        "audio": {
          "id": "<string>",
          "data": "<string>",
          "transcript": "<string>",
          "expires_at": 123
        }
      },
      "finish_reason": "stop",
      "reasoning_details": "<array>",
      "logprobs": {
        "content": [
          {
            "token": "hello",
            "logprob": -0.5,
            "bytes": [
              104,
              101,
              108,
              108,
              111
            ],
            "top_logprobs": [
              {
                "token": "hello",
                "logprob": -0.5,
                "bytes": [
                  104,
                  101,
                  108,
                  108,
                  111
                ]
              }
            ]
          }
        ],
        "refusal": [
          {
            "token": "hello",
            "logprob": -0.5,
            "bytes": [
              104,
              101,
              108,
              108,
              111
            ],
            "top_logprobs": [
              {
                "token": "hello",
                "logprob": -0.5,
                "bytes": [
                  104,
                  101,
                  108,
                  108,
                  111
                ]
              }
            ]
          }
        ]
      }
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 50,
    "total_tokens": 60,
    "completion_tokens_details": {
      "reasoning_tokens": 100,
      "audio_tokens": 0,
      "image_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0,
      "video_tokens": 0
    },
    "cost_rub": 0.04131306,
    "cost": 0.04131306
  }
}

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

Возможности

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

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

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

Параметр	Тип	Описание
`model`	string	ID модели из списка моделей

Контент

Параметр	Тип	Описание
`messages`	array	Массив сообщений диалога (рекомендуется)
`prompt`	string	Простой текстовый промпт (альтернатива messages)

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

Параметр	Тип	По умолчанию	Описание
`max_tokens`	integer	Без лимита	Максимум токенов в ответе
`max_completion_tokens`	integer	Без лимита	Альтернатива max_tokens
`temperature`	float (0-2)	1.0	Температура (0=детерминированный, 2=креативный)
`top_p`	float (0-1)	1.0	Nucleus sampling
`top_k`	integer	—	Top-K sampling
`frequency_penalty`	float (-2..2)	0	Штраф за повторение слов
`presence_penalty`	float (-2..2)	0	Штраф за повторение токенов
`stop`	string/array	—	Стоп-последовательности
`seed`	integer	—	Seed для воспроизводимости

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

Параметр	Тип	Описание
`stream`	boolean	Включить streaming (SSE)
`reasoning`	object	Настройки reasoning tokens
`tools`	array	Доступные функции для вызова
`tool_choice`	string/object	Выбор инструмента: “none”, “auto”, “required”
`response_format`	object	Формат ответа: text, json_object, json_schema, grammar
`web_search_options`	object	Встроенный веб-поиск
`provider`	object	Конфигурация роутинга по провайдерам
`plugins`	array	Подключение плагинов
`modalities`	array	Выходные модальности: “text”, “image”, “audio”
`audio`	object	Конфигурация аудио-вывода (voice, format)
`user`	string	Идентификатор конечного пользователя

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

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

{
  "role": "user|assistant|system|developer|tool",
  "content": "Текст сообщения"
}

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

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Что на этом изображении?"},
    {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
  ]
}

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

// Аудио вход
{"type": "input_audio", "input_audio": {"data": "base64...", "format": "mp3"}}

// Видео вход
{"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}

// Файл
{"type": "file", "file": {"filename": "doc.pdf", "file_data": "data:application/pdf;base64,..."}}

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

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "Длинная системная инструкция...",
      "cache_control": {"type": "ephemeral"}
    }
  ]
}

Примеры

curl -X POST "https://polza.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

Ответ

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

{
  "id": "gen_581761234567890123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "openai/gpt-4o",
  "provider": "OpenAI",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Текст ответа"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175,
    "cost_rub": 0.04131306,
    "cost": 0.04131306,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

Streaming (SSE)

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

data: {"id":"gen_123","object":"chat.completion.chunk","created":1703001234,"model":"openai/gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":"Привет"}}]}

data: {"id":"gen_123","object":"chat.completion.chunk","created":1703001234,"model":"openai/gpt-4o","choices":[{"index":0,"delta":{"content":" мир"}}]}

data: {"id":"gen_123","object":"chat.completion.chunk","created":1703001234,"model":"openai/gpt-4o","choices":[],"usage":{"prompt_tokens":10,"completion_tokens":20,"total_tokens":30,"cost_rub":0.015,"cost":0.015}}

data: [DONE]

Tool Calling

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

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Получить текущую погоду",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string"}
        },
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

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

{
  "tool_calls": [{
    "id": "call_123",
    "function": {"name": "get_weather", "arguments": "{\"city\": \"Москва\"}"}
  }]
}

Response Format

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

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "my_schema",
      "schema": {
        "type": "object",
        "properties": {
          "answer": {"type": "string"},
          "confidence": {"type": "number"}
        }
      },
      "strict": true
    }
  }
}

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

Reasoning Tokens

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

{
  "model": "openai/o1-preview",
  "messages": [{"role": "user", "content": "Реши: 2x + 5 = 13"}],
  "reasoning": {
    "effort": "high",
    "max_tokens": 1000
  }
}

Параметры reasoning

Параметр	Тип	Описание
`effort`	string	Уровень усилий: xhigh, high, medium, low, minimal, none
`max_tokens`	integer	Максимум токенов на рассуждения
`summary`	string	Детализация: auto, concise, detailed
`enabled`	boolean	Включить/выключить рассуждения
`exclude`	boolean	Скрыть рассуждения из ответа

Тело

application/json

model

string

обязательно

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

Пример:

"openai/gpt-4o"

messages

object[]

обязательно

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

Показать дочерние атрибуты

Пример:

[
  {
    "role": "system",
    "content": "Ты полезный ассистент"
  },
  {
    "role": "user",
    "content": "Привет! Как дела?"
  }
]

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[]

Определения инструментов (tools) для function calling

Показать дочерние атрибуты

tool_choice

object

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

Пример:

"auto"

reasoning

object

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

Показать дочерние атрибуты

plugins

array

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

web_search_options

object

Настройки встроенного веб-поиска (для моделей с нативной поддержкой)

Показать дочерние атрибуты

user

string

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

Пример:

"user-123"

stream

boolean

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

Пример:

false

image_config

object

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

Пример:

{ "quality": "high", "size": 512 }

modalities

enum<string>[]

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

Доступные опции:

text,

image,

audio

Пример:

["text", "audio"]

audio

object

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

Показать дочерние атрибуты

Ответ

string

обязательно

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

Пример:

"gen_581761234567890123"

object

string

обязательно

Тип объекта

Пример:

"chat.completion"

created

number

обязательно

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

Пример:

1703001234

model

string

обязательно

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

Пример:

"openai/gpt-4o"

choices

object[]

обязательно

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

Показать дочерние атрибуты

usage

object

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

Показать дочерние атрибуты

Введение в API POST Responses

Обзор

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

Изображения

Медиа

Аудио

Эмбеддинги

Модели

Хранилище

История

Другое

POST Chat Completions

Возможности

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

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

Контент

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

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

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

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

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

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

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

Примеры

Ответ

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

Streaming (SSE)

Tool Calling

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

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

Response Format

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

Reasoning Tokens

Параметры reasoning

Тело

Ответ

Обзор

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

Изображения

Медиа

Аудио

Эмбеддинги

Модели

Хранилище

История

Другое

​Возможности

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

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

​Контент

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

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

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

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

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

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

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

​Примеры

​Ответ

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

​Streaming (SSE)

​Tool Calling

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

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

​Response Format

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

​Reasoning Tokens

​Параметры reasoning

Тело

Ответ

Возможности

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

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

Контент

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

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

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

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

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

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

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

Примеры

Ответ

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

Streaming (SSE)

Tool Calling

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

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

Response Format

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

Reasoning Tokens

Параметры reasoning