Текстовые запросы

Отправка запросов к текстовым моделям через Chat Completions API

Текстовые запросы

В этом гайде вы узнаете, как отправлять текстовые запросы к AI моделям и получать ответы.

Endpoint

POST https://api.usellm.ru/v1/chat/completions

Отправляет диалог (массив сообщений) в модель и получает ответ.

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

Параметр	Тип	Обязательный	Описание
`model`	string	Да	ID модели (например, `openai/gpt-6-astra`)
`messages`	array	Да*	Массив сообщений диалога
`prompt`	string	Да*	Текстовый промпт (альтернатива `messages`)
`temperature`	number	Нет	Креативность ответа (0.0-2.0, по умолчанию 1.0)
`max_tokens`	number	Нет	Максимальное количество токенов в ответе
`stream`	boolean	Нет	Включить потоковую передачу (SSE)

* Укажите messages или prompt. При передаче prompt он автоматически преобразуется в messages с ролью user.

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

Параметр	Тип	Описание
`max_completion_tokens`	number	Альтернатива `max_tokens`
`top_p`	number	Nucleus sampling (0.0-1.0)
`frequency_penalty`	number	Штраф за частоту токенов (-2.0 до 2.0)
`presence_penalty`	number	Штраф за присутствие токенов (-2.0 до 2.0)
`response_format`	object	Формат ответа (структурный вывод)
`tools`	array	Определения функций (tool calling)
`tool_choice`	string/object	Выбор инструмента: `none`, `auto`, `required`
`reasoning`	object	Настройки reasoning
`provider`	object	Выбор провайдера (подробнее)
`user`	string	ID конечного пользователя

Структура messages

Каждое сообщение содержит роль и содержимое:

Поле	Тип	Описание
`role`	string	Роль отправителя (см. ниже)
`content`	string \| 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" } }
  ]
}

О передаче медиа рассказано в гайде Передача медиа на вход.

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

curl -X POST "https://api.usellm.ru/v1/chat/completions" \
  -H "Authorization: Bearer <USELLM_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-astra",
    "messages": [
      {"role": "system", "content": "Ты полезный ассистент."},
      {"role": "user", "content": "Напиши хайку о программировании"}
    ],
    "temperature": 0.7,
    "max_tokens": 100
  }'

import OpenAI from 'openai'

const openai = new OpenAI({
  baseURL: 'https://api.usellm.ru/v1',
  apiKey: '<USELLM_API_KEY>'
})

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

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

from openai import OpenAI

client = OpenAI(
    base_url="https://api.usellm.ru/v1",
    api_key="<USELLM_API_KEY>"
)

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

print(completion.choices[0].message.content)

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

{
  "id": "gen_581761234567890123",
  "object": "chat.completion",
  "created": 1703001234,
  "model": "openai/gpt-6-astra",
  "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
  }
}

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

Поле	Тип	Описание
`id`	string	Уникальный идентификатор запроса
`provider`	string	Провайдер, обработавший запрос
`choices[0].message.content`	string	Текст ответа модели
`choices[0].finish_reason`	string	Причина завершения генерации
`usage.prompt_tokens`	number	Количество токенов во входных сообщениях
`usage.completion_tokens`	number	Количество токенов в ответе
`usage.total_tokens`	number	Общее количество токенов
`usage.cost_rub`	number	Стоимость запроса в рублях
`usage.cost`	number	Стоимость запроса в рублях (алиас `cost_rub`)

Значения finish_reason

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

Стриминг

Для получения ответа по мере генерации установите stream: true. Ответ приходит в формате Server-Sent Events (SSE):

curl -X POST "https://api.usellm.ru/v1/chat/completions" \
  -H "Authorization: Bearer <USELLM_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-astra",
    "messages": [{"role": "user", "content": "Напиши короткую историю"}],
    "stream": true
  }'

const stream = await openai.chat.completions.create({
  model: 'openai/gpt-6-astra',
  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)
  }
}

stream = client.chat.completions.create(
    model="openai/gpt-6-astra",
    messages=[{"role": "user", "content": "Напиши короткую историю"}],
    stream=True
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

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

Для ведения диалога передавайте историю сообщений:

curl -X POST "https://api.usellm.ru/v1/chat/completions" \
  -H "Authorization: Bearer <USELLM_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-astra",
    "messages": [
      {"role": "system", "content": "Ты помощник по программированию."},
      {"role": "user", "content": "Как создать массив в JavaScript?"},
      {"role": "assistant", "content": "В JavaScript массив создаётся так: const arr = [1, 2, 3];"},
      {"role": "user", "content": "А как добавить элемент?"}
    ]
  }'

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-6-astra',
  messages
})

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

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

completion = client.chat.completions.create(
    model="openai/gpt-6-astra",
    messages=messages
)

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

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

Используйте system message

Настройте temperature

Ограничивайте max_tokens

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

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

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

Tool Calling

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

Structured Output

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

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

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