Разделы документации

Начало

Текст

Изображения

Генерация изображенийскоро

Видео

Генерация видеоскоро

Голос

Обзорскоро

Инструменты

Обзорскоро

Режимы обработки

Справочник

Документация API

Генерация текста

Эндпоинт chat/completions: роли, параметры и то, что игнорируется молча

Генерация текста работает через один эндпоинт — POST /v1/chat/completions. Формат запроса и ответа совпадает с OpenAI Chat Completions, поэтому подходят официальные библиотеки openai для Python и Node.js: достаточно поменять базовый адрес и ключ.

Параметр	Значение
Базовый адрес	https://api.librachat.kz/v1
Эндпоинт	POST /v1/chat/completions
Заголовок	Authorization: Bearer sk-libra-…
Модели	libra-fast, libra-pro
Ответ	Content-Type: application/json; charset=utf-8

Поле messages и роли

messages — список сообщений диалога по порядку. У каждого сообщения есть роль и текст.

system — инструкция модели: как отвечать, в каком тоне, в каком формате. Обычно первым сообщением.
user — то, что пишет пользователь.
assistant — предыдущие ответы модели. Передавайте их, если хотите, чтобы модель помнила контекст диалога: сервис не хранит историю, весь контекст вы отправляете сами в каждом запросе.

Контекст модели — 1 млн токенов, в него входят и ваши сообщения, и ответ.

Какие параметры учитываются

Параметр	Что делает	По умолчанию
model	Модель: libra-fast или libra-pro	обязателен
messages	Список сообщений диалога	обязателен
temperature	Разброс ответов: ниже — стабильнее, выше — свободнее	0.3
max_tokens	Предел длины ответа, от 1 до 32000	—
stream	Отдавать ответ по частям (server-sent events)	false

Какие параметры молча игнорируются

Эти поля можно прислать — запрос не упадёт с ошибкой, но и эффекта не будет. Ошибки в ответе тоже не будет, поэтому легко решить, что параметр «сработал»:

tools, tool_choice — вызова функций и инструментов нет
top_p, n, stop, seed
response_format — JSON-режима нет
presence_penalty, frequency_penalty
logprobs
user

Грабля: если вы переносите код с другого провайдера и рассчитывали на seed, stop или response_format — поведение изменится молча. Логику, которая на них опиралась, переносите на сторону вашего приложения: формат просите в system-сообщении, длину ограничивайте через max_tokens.

Картинки в messages отбрасываются

Если вы передаёте сообщение частями и среди них есть image_url, картинка молча отбрасывается. Модель её не увидит, ошибки не будет — вы получите ответ, построенный только по тексту. Vision сейчас не работает; распознавание изображений готовится.

Практическое следствие: не стройте сценарии вида «пользователь прислал скриншот — модель его разбирает». Ответ будет выглядеть правдоподобно, но он придуман по тексту вокруг.

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

bash

curl https://api.librachat.kz/v1/chat/completions \
  -H "Authorization: Bearer sk-libra-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "libra-fast",
    "messages": [
      {"role": "system", "content": "Ты — ассистент. Отвечай коротко, по-русски."},
      {"role": "user", "content": "Объясни, что такое токен, в двух предложениях."}
    ],
    "temperature": 0.3,
    "max_tokens": 300
  }'

python

from openai import OpenAI

client = OpenAI(
    api_key="sk-libra-…",
    base_url="https://api.librachat.kz/v1",
)

resp = client.chat.completions.create(
    model="libra-pro",
    messages=[
        {"role": "system", "content": "Отвечай коротко, по-русски."},
        {"role": "user", "content": "Придумай три названия для приложения заметок."},
        {"role": "assistant", "content": "Заметник, Полка, Черновик."},
        {"role": "user", "content": "Ещё три, но одним словом каждое."},
    ],
    temperature=0.3,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage)

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

json

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1754800000,
  "model": "libra-fast",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Токен — это кусочек текста, на которые модель делит ваш запрос. Стоимость и длина считаются именно в токенах, а не в словах."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 33,
    "total_tokens": 75
  }
}

Ответ приходит с Content-Type: application/json; charset=utf-8. Если вы дёргаете API из PowerShell и вместо русского текста видите крякозябры — дело не в API, а в кодировке консоли: читайте тело ответа как UTF-8 (например, через Invoke-RestMethod с явной перекодировкой или выставив [Console]::OutputEncoding в UTF-8).

Стриминг

С stream: true ответ идёт server-sent events, поток закрывается строкой data: [DONE]. Сервис сам проставляет stream_options {"include_usage": true} — передавать его не нужно.

Грабля: в ПОСЛЕДНЕМ фрагменте choices пустой, зато есть usage. В Python обязательна проверка if chunk.choices — иначе обращение к chunk.choices[0] на последнем фрагменте уронит цикл с IndexError.

python

stream = client.chat.completions.create(
    model="libra-fast",
    messages=[{"role": "user", "content": "Расскажи про токены."}],
    max_tokens=500,
    stream=True,
)

usage = None
for chunk in stream:
    if chunk.choices:                      # обязательная проверка
        delta = chunk.choices[0].delta
        if delta.content:
            print(delta.content, end="", flush=True)
    elif chunk.usage:                      # последний фрагмент
        usage = chunk.usage

print()
print(usage)

Лимиты, баланс и ошибки

120 запросов в минуту и 1 000 000 токенов в минуту на ключ; max_tokens — до 32 000.
Баланс предоплаченный, в токенах, общий на все ключи аккаунта. Перед запросом проверяется: если баланс ≤ 0 — 402. Списание происходит после ответа, по факту.
Цены за 1 млн токенов: libra-fast — вход 337,50 ₽ / кеш 54 ₽ / выход 675 ₽; libra-pro — вход 450 ₽ / кеш 72 ₽ / выход 900 ₽.

Код	Название	Когда
401	no_api_key	Заголовок Authorization не передан
401	invalid_api_key	Ключ неверный или отозван
402	insufficient_balance	Баланс аккаунта ≤ 0
429	rate_limited	Превышены запросы или токены в минуту
502	upstream_error	Ошибка при генерации ответа

Тексты ошибок русские. Ключи создаются в кабинете: «Настройки → API».

НазадЦены ДальшеПараметры запроса

Генерация текста

Эндпоинт chat/completions: роли, параметры и то, что игнорируется молча

Параметр	Значение
Базовый адрес	https://api.librachat.kz/v1
Эндпоинт	POST /v1/chat/completions
Заголовок	Authorization: Bearer sk-libra-…
Модели	libra-fast, libra-pro
Ответ	Content-Type: application/json; charset=utf-8

Поле messages и роли

messages — список сообщений диалога по порядку. У каждого сообщения есть роль и текст.

system — инструкция модели: как отвечать, в каком тоне, в каком формате. Обычно первым сообщением.
user — то, что пишет пользователь.
assistant — предыдущие ответы модели. Передавайте их, если хотите, чтобы модель помнила контекст диалога: сервис не хранит историю, весь контекст вы отправляете сами в каждом запросе.

Контекст модели — 1 млн токенов, в него входят и ваши сообщения, и ответ.

Какие параметры учитываются

Параметр	Что делает	По умолчанию
model	Модель: libra-fast или libra-pro	обязателен
messages	Список сообщений диалога	обязателен
temperature	Разброс ответов: ниже — стабильнее, выше — свободнее	0.3
max_tokens	Предел длины ответа, от 1 до 32000	—
stream	Отдавать ответ по частям (server-sent events)	false

Какие параметры молча игнорируются

tools, tool_choice — вызова функций и инструментов нет
top_p, n, stop, seed
response_format — JSON-режима нет
presence_penalty, frequency_penalty
logprobs
user

Картинки в messages отбрасываются

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

bash

curl https://api.librachat.kz/v1/chat/completions \
  -H "Authorization: Bearer sk-libra-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "libra-fast",
    "messages": [
      {"role": "system", "content": "Ты — ассистент. Отвечай коротко, по-русски."},
      {"role": "user", "content": "Объясни, что такое токен, в двух предложениях."}
    ],
    "temperature": 0.3,
    "max_tokens": 300
  }'

python

from openai import OpenAI

client = OpenAI(
    api_key="sk-libra-…",
    base_url="https://api.librachat.kz/v1",
)

resp = client.chat.completions.create(
    model="libra-pro",
    messages=[
        {"role": "system", "content": "Отвечай коротко, по-русски."},
        {"role": "user", "content": "Придумай три названия для приложения заметок."},
        {"role": "assistant", "content": "Заметник, Полка, Черновик."},
        {"role": "user", "content": "Ещё три, но одним словом каждое."},
    ],
    temperature=0.3,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage)

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

json

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1754800000,
  "model": "libra-fast",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Токен — это кусочек текста, на которые модель делит ваш запрос. Стоимость и длина считаются именно в токенах, а не в словах."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 33,
    "total_tokens": 75
  }
}

Стриминг

python

stream = client.chat.completions.create(
    model="libra-fast",
    messages=[{"role": "user", "content": "Расскажи про токены."}],
    max_tokens=500,
    stream=True,
)

usage = None
for chunk in stream:
    if chunk.choices:                      # обязательная проверка
        delta = chunk.choices[0].delta
        if delta.content:
            print(delta.content, end="", flush=True)
    elif chunk.usage:                      # последний фрагмент
        usage = chunk.usage

print()
print(usage)

Лимиты, баланс и ошибки

120 запросов в минуту и 1 000 000 токенов в минуту на ключ; max_tokens — до 32 000.
Баланс предоплаченный, в токенах, общий на все ключи аккаунта. Перед запросом проверяется: если баланс ≤ 0 — 402. Списание происходит после ответа, по факту.
Цены за 1 млн токенов: libra-fast — вход 337,50 ₽ / кеш 54 ₽ / выход 675 ₽; libra-pro — вход 450 ₽ / кеш 72 ₽ / выход 900 ₽.

Код	Название	Когда
401	no_api_key	Заголовок Authorization не передан
401	invalid_api_key	Ключ неверный или отозван
402	insufficient_balance	Баланс аккаунта ≤ 0
429	rate_limited	Превышены запросы или токены в минуту
502	upstream_error	Ошибка при генерации ответа

Тексты ошибок русские. Ключи создаются в кабинете: «Настройки → API».