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

Начало

Текст

Изображения

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

Видео

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

Голос

Обзорскоро

Инструменты

Обзорскоро

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

Справочник

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

Потоковая передача

Как получать ответ по частям через server-sent events и не споткнуться о последний фрагмент

Как включить поток

Добавьте в тело запроса stream: true. Ответ придёт не одним JSON, а потоком server-sent events: сервер шлёт строки вида data: {…}, каждая — очередной фрагмент ответа. Поток закрывается строкой data: [DONE].

Формат фрагментов совпадает с OpenAI Chat Completions, поэтому официальные библиотеки openai для Python и Node.js работают без изменений — достаточно подставить базовый адрес и ключ LibraChat.

bash

POST https://api.librachat.kz/v1/chat/completions
Authorization: Bearer sk-libra-…
Content-Type: application/json

stream_options {include_usage: true} сервис проставляет сам. Передавать его не нужно.

Последний фрагмент: пустой choices и usage

Главная особенность потока: в самом последнем фрагменте массив choices пустой, зато есть поле usage со статистикой по токенам. Если код читает chunk.choices[0], не проверив длину массива, он упадёт на последнем фрагменте — уже после того, как весь текст получен.

Python: обязательна проверка if chunk.choices перед обращением к chunk.choices[0].
Node.js: проверяйте chunk.choices?.length перед чтением delta.
usage читайте отдельно — он приходит именно в том фрагменте, где choices пустой.
Ждите data: [DONE] как признак конца потока; после него данных не будет.

Python

python

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="libra-fast",
    messages=[{"role": "user", "content": "Объясни, что такое индекс в базе данных"}],
    temperature=0.3,
    max_tokens=1000,
    stream=True,
)

usage = None

for chunk in stream:
    # последний фрагмент: choices пустой, зато есть usage
    if chunk.usage:
        usage = chunk.usage
    if not chunk.choices:
        continue

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

print()
if usage:
    print("Токены:", usage)

Node.js

typescript

import OpenAI from "openai";

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

const stream = await client.chat.completions.create({
  model: "libra-pro",
  messages: [{ role: "user", content: "Объясни, что такое индекс в базе данных" }],
  temperature: 0.3,
  max_tokens: 1000,
  stream: true,
});

let usage = null;

for await (const chunk of stream) {
  // последний фрагмент: choices пустой, зато есть usage
  if (chunk.usage) usage = chunk.usage;
  if (!chunk.choices || chunk.choices.length === 0) continue;

  const piece = chunk.choices[0].delta?.content;
  if (piece) process.stdout.write(piece);
}

process.stdout.write("\n");
if (usage) console.log("Токены:", usage);

curl

Флаг -N выключает буферизацию, иначе curl покажет весь ответ одним куском в конце и смысл потока пропадёт.

bash

curl -N https://api.librachat.kz/v1/chat/completions \
  -H "Authorization: Bearer sk-libra-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "libra-fast",
    "messages": [{"role": "user", "content": "Привет!"}],
    "stream": true
  }'

В выводе вы увидите последовательность строк data: {…}, затем фрагмент с пустым choices и полем usage, затем data: [DONE].

В PowerShell curl — это псевдоним Invoke-WebRequest, у которого нет флага -N и другой синтаксис. Вызывайте curl.exe явно, а тело запроса с кириллицей сохраняйте в UTF-8 файл и передавайте через -d "@body.json": иначе текст уедет в другую кодировку. Ответы сервис отдаёт с Content-Type: application/json; charset=utf-8.

Что стоит учесть

Учитываются только model, 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 игнорируются молча — ошибки не будет, эффекта тоже.
Картинки, переданные в messages частями image_url, отбрасываются: обработка изображений не поддерживается.
Ключ и баланс проверяются до начала потока, поэтому 401, 402 и 429 приходят обычным JSON-ответом, а не внутри SSE.
Списание токенов происходит после ответа, по факту; баланс общий на все ключи аккаунта.
Лимиты на ключ: 120 запросов в минуту и 1 000 000 токенов в минуту.

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

Тексты ошибок приходят на русском языке.

НазадФормат ответа ДальшеГенерация изображений

Потоковая передача

Как получать ответ по частям через server-sent events и не споткнуться о последний фрагмент

Как включить поток

bash

POST https://api.librachat.kz/v1/chat/completions
Authorization: Bearer sk-libra-…
Content-Type: application/json

stream_options {include_usage: true} сервис проставляет сам. Передавать его не нужно.

Последний фрагмент: пустой choices и usage

Python: обязательна проверка if chunk.choices перед обращением к chunk.choices[0].
Node.js: проверяйте chunk.choices?.length перед чтением delta.
usage читайте отдельно — он приходит именно в том фрагменте, где choices пустой.
Ждите data: [DONE] как признак конца потока; после него данных не будет.

Python

python

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="libra-fast",
    messages=[{"role": "user", "content": "Объясни, что такое индекс в базе данных"}],
    temperature=0.3,
    max_tokens=1000,
    stream=True,
)

usage = None

for chunk in stream:
    # последний фрагмент: choices пустой, зато есть usage
    if chunk.usage:
        usage = chunk.usage
    if not chunk.choices:
        continue

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

print()
if usage:
    print("Токены:", usage)

Node.js

typescript

import OpenAI from "openai";

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

const stream = await client.chat.completions.create({
  model: "libra-pro",
  messages: [{ role: "user", content: "Объясни, что такое индекс в базе данных" }],
  temperature: 0.3,
  max_tokens: 1000,
  stream: true,
});

let usage = null;

for await (const chunk of stream) {
  // последний фрагмент: choices пустой, зато есть usage
  if (chunk.usage) usage = chunk.usage;
  if (!chunk.choices || chunk.choices.length === 0) continue;

  const piece = chunk.choices[0].delta?.content;
  if (piece) process.stdout.write(piece);
}

process.stdout.write("\n");
if (usage) console.log("Токены:", usage);

curl

Флаг -N выключает буферизацию, иначе curl покажет весь ответ одним куском в конце и смысл потока пропадёт.

bash

curl -N https://api.librachat.kz/v1/chat/completions \
  -H "Authorization: Bearer sk-libra-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "libra-fast",
    "messages": [{"role": "user", "content": "Привет!"}],
    "stream": true
  }'

В выводе вы увидите последовательность строк data: {…}, затем фрагмент с пустым choices и полем usage, затем data: [DONE].

Что стоит учесть

Учитываются только model, 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 игнорируются молча — ошибки не будет, эффекта тоже.
Картинки, переданные в messages частями image_url, отбрасываются: обработка изображений не поддерживается.
Ключ и баланс проверяются до начала потока, поэтому 401, 402 и 429 приходят обычным JSON-ответом, а не внутри SSE.
Списание токенов происходит после ответа, по факту; баланс общий на все ключи аккаунта.
Лимиты на ключ: 120 запросов в минуту и 1 000 000 токенов в минуту.

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

Тексты ошибок приходят на русском языке.