Перейти к основному содержанию
В этом гайде вы узнаете как отправлять текстовые запросы к AI моделям и получать ответы.
Полная документация endpoint доступна в API Reference.

​
Endpoint

POST https://polza.ai/api/v1/chat/completions
Отправляет диалог (массив сообщений) в модель и получает ответ.

​
Базовые параметры

ПараметрТипОбязательныйОписание
modelstringДаID модели (например, openai/gpt-4o)
messagesarrayДа*Массив сообщений диалога
promptstringДа*Текстовый промпт (альтернатива messages)
temperaturenumberНетКреативность ответа (0.0-2.0, по умолчанию 1.0)
max_tokensnumberНетМаксимальное количество токенов в ответе
streambooleanНетВключить потоковую передачу (SSE)
* Укажите messages или prompt. При передаче prompt он автоматически преобразуется в messages с ролью user.

​
Дополнительные параметры

ПараметрТипОписание
max_completion_tokensnumberАльтернатива max_tokens
top_pnumberNucleus sampling (0.0-1.0)
frequency_penaltynumberШтраф за частоту токенов (-2.0 до 2.0)
presence_penaltynumberШтраф за присутствие токенов (-2.0 до 2.0)
response_formatobjectФормат ответа (structured output)
toolsarrayОпределения функций (tool calling)
tool_choicestring/objectВыбор инструмента: none, auto, required
reasoningobjectНастройки reasoning (reasoning)
web_search_optionsobjectВстроенный веб-поиск
providerobjectВыбор провайдера (подробнее)
userstringID конечного пользователя

​
Структура messages

Каждое сообщение содержит роль и содержимое:
ПолеТипОписание
rolestringРоль отправителя (см. ниже)
contentstring | array | nullТекст, массив content parts или null

​
Роли сообщений

РольОписание
systemСистемное сообщение, задающее контекст и поведение модели
developerИнструкции разработчика (аналог system для некоторых моделей)
userСообщение от пользователя
assistantОтвет модели (для продолжения диалога). content может быть null, если есть tool_calls
toolРезультат вызова инструмента. Требуется поле tool_call_id

​
Типы content

Поле content может быть строкой или массивом content parts для передачи медиа: 
// Строка
{ "role": "user", "content": "Привет!" }

// Массив content parts (для медиа)
{
  "role": "user",
  "content": [
    { "type": "text", "text": "Что на картинке?" },
    { "type": "image_url", "image_url": { "url": "https://example.com/img.jpg" } }
  ]
}
Подробнее о передаче медиа — в гайде Передача медиа на вход.

​
Простой пример

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://polza.ai/api/v1',
  apiKey: '<POLZA_AI_API_KEY>'
});

const completion = await openai.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [
    { role: 'system', content: 'Ты полезный ассистент.' },
    { role: 'user', content: 'Напиши хайку о программировании' }
  ],
  temperature: 0.7,
  max_tokens: 100
});

console.log(completion.choices[0].message.content);

​
Структура ответа

{
  "id": "gen_581761234567890123",
  "object": "chat.completion",
  "created": 1703001234,
  "model": "openai/gpt-4o",
  "provider": "openai-direct",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Код течёт рекой\nБаги тают на рассвете\nРелиз близко..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 20,
    "total_tokens": 45,
    "cost_rub": 0.15,
    "cost": 0.15
  }
}

​
Описание полей ответа

ПолеТипОписание
idstringУникальный идентификатор запроса
providerstringПровайдер, обработавший запрос
choices[0].message.contentstringТекст ответа модели
choices[0].finish_reasonstringПричина завершения генерации
usage.prompt_tokensnumberКоличество токенов во входных сообщениях
usage.completion_tokensnumberКоличество токенов в ответе
usage.total_tokensnumberОбщее количество токенов
usage.cost_rubnumberСтоимость запроса в рублях
usage.costnumberСтоимость запроса в рублях (алиас cost_rub)

​
Значения finish_reason

ЗначениеОписание
stopМодель завершила генерацию естественным образом
lengthДостигнут лимит max_tokens
tool_callsМодель запросила вызов функции
content_filterКонтент заблокирован модерацией

​
Стриминг

Для получения ответа по мере генерации установите stream: true. Ответ приходит в формате Server-Sent Events (SSE): 
const stream = await openai.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: 'Напиши короткую историю' }],
  stream: true
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}

​
Пример диалога

Для ведения диалога передавайте историю сообщений: 
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://polza.ai/api/v1',
  apiKey: '<POLZA_AI_API_KEY>'
});

const messages = [
  { role: 'system', content: 'Ты помощник по программированию.' },
  { role: 'user', content: 'Как создать массив в JavaScript?' },
  { role: 'assistant', content: 'В JavaScript массив создаётся так: const arr = [1, 2, 3];' },
  { role: 'user', content: 'А как добавить элемент?' }
];

const completion = await openai.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: messages
});

// Модель ответит с учётом контекста диалога
console.log(completion.choices[0].message.content);

​
Советы по использованию

System message задаёт контекст и поведение модели. Например:
  • «Ты опытный Python-разработчик»
  • «Отвечай кратко, в 2-3 предложениях»
  • «Всегда приводи примеры кода»
  • Низкая (0.0-0.3) — для точных, детерминированных ответов (код, факты)
  • Средняя (0.5-0.7) — баланс между точностью и разнообразием
  • Высокая (0.8-1.0) — для креативных задач (тексты, идеи)
Установка max_tokens помогает:
  • Экономить средства на коротких ответах
  • Ускорять время ответа
  • Контролировать длину генерации

​
Следующие шаги

Передача медиа

Изображения, документы, аудио и видео на вход

Tool Calling

Вызов функций из модели

Structured Output

JSON-ответы с гарантированной структурой

Выбор провайдера

Управление роутингом между провайдерами