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

Начало

Текст

Изображения

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

Видео

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

Голос

Обзорскоро

Инструменты

Обзорскоро

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

Справочник

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

Быстрый старт

От создания ключа до первого ответа с расходом токенов — за пять минут

API LibraChat повторяет формат OpenAI Chat Completions. Если у вас уже есть код под него — достаточно поменять базовый адрес и ключ.

Шаг 1. Получите ключ

Ключи создаются в кабинете: «Настройки → API». Сырое значение ключа показывается один раз при создании — сохраните его сразу. На сервере хранится только SHA-256-хеш, позже вы увидите лишь видимую часть вида sk-libra-ab12cd…

Формат ключа: префикс sk-libra- и около 43 символов.
До 10 активных ключей на аккаунт. Одиннадцатый вернёт 409 too_many_keys.
Ключ можно отозвать мгновенно, отзыв действует сразу.
Фиксируется дата последнего использования — по ней видно, какие ключи не работают.
Баланс предоплаченный, в токенах, общий на все ключи аккаунта.

Шаг 2. Базовый адрес и заголовок

Все запросы идут на базовый адрес, ключ передаётся заголовком Authorization.

bash

Базовый адрес: https://api.librachat.kz/v1
Заголовок:     Authorization: Bearer sk-libra-…

Доступны два эндпоинта: POST /v1/chat/completions и GET /v1/models. Список моделей тоже требует ключ.

Модель	Вход, ₽ / 1 млн	Кеш, ₽ / 1 млн	Выход, ₽ / 1 млн
libra-fast	337,50	54	675
libra-pro	450	72	900

Контекст — 1 млн токенов у обеих моделей. Пополнение — от 1 млн токенов, 450 ₽ за 1 млн.

Шаг 3. Первый запрос

curl (Linux / macOS):

bash

curl https://api.librachat.kz/v1/chat/completions \
  -H "Authorization: Bearer $LIBRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "libra-fast",
    "messages": [
      {"role": "user", "content": "Привет! Ответь одним предложением."}
    ],
    "temperature": 0.3,
    "max_tokens": 500
  }'

Windows PowerShell. Тело запроса кодируем в UTF-8 руками, иначе кириллица в вопросе уедет:

bash

$key  = "sk-libra-…"
$body = @{
  model    = "libra-fast"
  messages = @(@{ role = "user"; content = "Привет! Ответь одним предложением." })
  temperature = 0.3
  max_tokens  = 500
} | ConvertTo-Json -Depth 5

$bytes = [System.Text.Encoding]::UTF8.GetBytes($body)

$resp = Invoke-RestMethod `
  -Uri "https://api.librachat.kz/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $key" } `
  -ContentType "application/json; charset=utf-8" `
  -Body $bytes

$resp.choices[0].message.content
$resp.usage

Кодировка в PowerShell. Ответы отдаются с Content-Type: application/json; charset=utf-8. Windows PowerShell 5.1 не всегда учитывает этот заголовок и может показать русский текст «крокозябрами». Надёжные варианты: передавать тело как UTF-8-байты (как в примере выше), запускать код в PowerShell 7 или использовать curl.exe вместо Invoke-RestMethod. Заодно поставьте [Console]::OutputEncoding = [System.Text.Encoding]::UTF8, чтобы консоль корректно печатала ответ.

Python, официальная библиотека openai:

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-fast",
    messages=[{"role": "user", "content": "Привет! Ответь одним предложением."}],
    temperature=0.3,
    max_tokens=500,
)

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

Node.js, официальная библиотека openai:

typescript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-libra-…",
  baseURL: "https://api.librachat.kz/v1",
});

const resp = await client.chat.completions.create({
  model: "libra-fast",
  messages: [{ role: "user", content: "Привет! Ответь одним предложением." }],
  temperature: 0.3,
  max_tokens: 500,
});

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

Что приходит в ответе

json

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "libra-fast",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Рад помочь."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 7,
    "total_tokens": 25
  }
}

Поле usage — это фактический расход по запросу. Списание с баланса происходит после ответа, по факту. Перед запросом проверяется баланс: если он ≤ 0, вернётся 402 insufficient_balance.

Параметры: что учитывается, а что нет

Параметр	Поведение
model	Учитывается: libra-fast или libra-pro
messages	Учитывается
temperature	Учитывается, по умолчанию 0.3
max_tokens	Учитывается, от 1 до 32000
stream	Учитывается
tools, tool_choice, top_p, n, stop, seed, response_format, presence_penalty, frequency_penalty, logprobs, user	Молча игнорируются — ошибки не будет, эффекта тоже

Главная грабля: игнорируемые параметры не вызывают ошибку. Запрос пройдёт, а top_p, seed или response_format просто не подействуют. Сюда же — картинки: если передать в messages части с image_url, они молча отбрасываются, распознавание изображений не работает.

Стриминг

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

python

stream = client.chat.completions.create(
    model="libra-fast",
    messages=[{"role": "user", "content": "Расскажи про кофе в трёх предложениях."}],
    stream=True,
)

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

В последнем фрагменте потока choices пустой, зато есть usage — всегда проверяйте if chunk.choices перед обращением к chunk.choices[0], иначе получите IndexError на завершающем чанке.

Лимиты и ошибки

120 запросов в минуту на ключ.
1 000 000 токенов в минуту на ключ.
max_tokens — до 32 000.
При превышении приходит 429 rate_limited.
Если хранилище лимитов недоступно, ограничения пропускаются — не полагайтесь на них как на защиту своего кода от лавины запросов.

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

Тексты ошибок русские, приходят в JSON с charset=utf-8 — при логировании убедитесь, что ваш обработчик не ломает кодировку.

Чего пока нет

В API готовятся и сейчас недоступны: изображения, видео, голос, веб-поиск и другие инструменты, вызов функций, эмбеддинги, файлы и коллекции, пакетная и приоритетная обработка, JSON-режим, выбор режима рассуждений.

НазадОбзор ДальшеАутентификация

Быстрый старт

От создания ключа до первого ответа с расходом токенов — за пять минут

Шаг 1. Получите ключ

Формат ключа: префикс sk-libra- и около 43 символов.
До 10 активных ключей на аккаунт. Одиннадцатый вернёт 409 too_many_keys.
Ключ можно отозвать мгновенно, отзыв действует сразу.
Фиксируется дата последнего использования — по ней видно, какие ключи не работают.
Баланс предоплаченный, в токенах, общий на все ключи аккаунта.

Шаг 2. Базовый адрес и заголовок

Все запросы идут на базовый адрес, ключ передаётся заголовком Authorization.

bash

Базовый адрес: https://api.librachat.kz/v1
Заголовок:     Authorization: Bearer sk-libra-…

Доступны два эндпоинта: POST /v1/chat/completions и GET /v1/models. Список моделей тоже требует ключ.

Модель	Вход, ₽ / 1 млн	Кеш, ₽ / 1 млн	Выход, ₽ / 1 млн
libra-fast	337,50	54	675
libra-pro	450	72	900

Контекст — 1 млн токенов у обеих моделей. Пополнение — от 1 млн токенов, 450 ₽ за 1 млн.

Шаг 3. Первый запрос

curl (Linux / macOS):

bash

curl https://api.librachat.kz/v1/chat/completions \
  -H "Authorization: Bearer $LIBRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "libra-fast",
    "messages": [
      {"role": "user", "content": "Привет! Ответь одним предложением."}
    ],
    "temperature": 0.3,
    "max_tokens": 500
  }'

Windows PowerShell. Тело запроса кодируем в UTF-8 руками, иначе кириллица в вопросе уедет:

bash

$key  = "sk-libra-…"
$body = @{
  model    = "libra-fast"
  messages = @(@{ role = "user"; content = "Привет! Ответь одним предложением." })
  temperature = 0.3
  max_tokens  = 500
} | ConvertTo-Json -Depth 5

$bytes = [System.Text.Encoding]::UTF8.GetBytes($body)

$resp = Invoke-RestMethod `
  -Uri "https://api.librachat.kz/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $key" } `
  -ContentType "application/json; charset=utf-8" `
  -Body $bytes

$resp.choices[0].message.content
$resp.usage

Python, официальная библиотека openai:

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-fast",
    messages=[{"role": "user", "content": "Привет! Ответь одним предложением."}],
    temperature=0.3,
    max_tokens=500,
)

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

Node.js, официальная библиотека openai:

typescript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-libra-…",
  baseURL: "https://api.librachat.kz/v1",
});

const resp = await client.chat.completions.create({
  model: "libra-fast",
  messages: [{ role: "user", content: "Привет! Ответь одним предложением." }],
  temperature: 0.3,
  max_tokens: 500,
});

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

Что приходит в ответе

json

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "libra-fast",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Рад помочь."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 7,
    "total_tokens": 25
  }
}

Параметры: что учитывается, а что нет

Параметр	Поведение
model	Учитывается: libra-fast или libra-pro
messages	Учитывается
temperature	Учитывается, по умолчанию 0.3
max_tokens	Учитывается, от 1 до 32000
stream	Учитывается
tools, tool_choice, top_p, n, stop, seed, response_format, presence_penalty, frequency_penalty, logprobs, user	Молча игнорируются — ошибки не будет, эффекта тоже

Стриминг

python

stream = client.chat.completions.create(
    model="libra-fast",
    messages=[{"role": "user", "content": "Расскажи про кофе в трёх предложениях."}],
    stream=True,
)

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

Лимиты и ошибки

120 запросов в минуту на ключ.
1 000 000 токенов в минуту на ключ.
max_tokens — до 32 000.
При превышении приходит 429 rate_limited.
Если хранилище лимитов недоступно, ограничения пропускаются — не полагайтесь на них как на защиту своего кода от лавины запросов.

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