Файлы и коллекцииготовится

Раздел решает две задачи. Первая — положить файл на сторону LibraChat один раз и дальше ссылаться на него по идентификатору, не пересылая содержимое в каждом запросе. Вторая — собрать из файлов коллекцию и искать по ней из чата: модель сама найдёт нужные куски ваших документов и ответит по ним.

Файл и коллекция — разные сущности. Файл лежит как есть, за него берётся плата за хранение и за скачивание. Коллекция — это проиндексированные файлы, подготовленные к поиску; индекс занимает больше места, поэтому ставка за хранение коллекции выше.

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

Загрузка планируется через multipart/form-data, как в конвенции OpenAI: поле file с содержимым и поле purpose с назначением файла.

curl https://api.librachat.kz/v1/files \
  -H "Authorization: Bearer sk-libra-…" \
  -F purpose=assistants \
  -F file=@contract.pdf

Ожидаемый ответ:

{
  "id": "file-9f3a7c21",
  "object": "file",
  "bytes": 184320,
  "created_at": 1786000000,
  "filename": "contract.pdf",
  "purpose": "assistants",
  "status": "processed"
}

Значения purpose планируются такие: assistants — файл для работы модели (вложение в запрос, источник для коллекции), batch — входной файл пакетной обработки, user_data — просто хранение.

Хранение считается по фактическому объёму в сутки. Удалили файл — начисление прекращается со следующего расчётного интервала.

Коллекция собирается из уже загруженных файлов. Вы создаёте коллекцию, добавляете в неё file_id, ждёте индексации и дальше используете её в чате.

curl https://api.librachat.kz/v1/collections \
  -H "Authorization: Bearer sk-libra-…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Договоры 2026",
    "file_ids": ["file-9f3a7c21", "file-1b48de07"]
  }'

{
  "id": "col-4d2e88",
  "object": "collection",
  "name": "Договоры 2026",
  "created_at": 1786000100,
  "status": "indexing",
  "file_counts": { "total": 2, "indexed": 0, "failed": 0 },
  "usage_bytes": 0
}

Пока status равен indexing, поиск по коллекции возвращать результаты не обязан. Готовая коллекция переходит в completed, поле usage_bytes показывает объём индекса — именно он тарифицируется по ставке коллекций.

Поиск подключается как инструмент в обычный запрос к /v1/chat/completions. Модель сама решает, нужно ли лезть в документы.

{
  "model": "libra-pro",
  "messages": [
    { "role": "user", "content": "Какой срок оплаты в договоре с ООО Ромашка?" }
  ],
  "tools": [
    {
      "type": "collection_search",
      "collection_search": {
        "collection_ids": ["col-4d2e88"],
        "max_results": 8
      }
    }
  ]
}

Отдельный файл можно приложить к запросу без коллекции — как вложение. Это тарифицируется по ставке «вложенные файлы» за вызов, а не по ставке поиска.

{
  "model": "libra-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Сделай выжимку" },
        { "type": "file", "file": { "file_id": "file-9f3a7c21" } }
      ]
    }
  ]
}

Важно: текст, который поиск подложит в контекст, оплачивается как обычные входные токены модели. Плата за вызов инструмента идёт сверх этого. Контекст остаётся 1 млн токенов, max_tokens — до 32 000.

Ожидаемые ошибки — те же коды, что и в остальном API: 401 no_api_key, 401 invalid_api_key, 402 insufficient_balance, 429 rate_limited, 502 upstream_error. Дополнительно планируются 404 file_not_found и 404 collection_not_found, а также 409 collection_not_ready, если коллекция ещё индексируется.

Токены, которые модель прочитала из найденных фрагментов, считаются по обычным ставкам: libra-fast — 337,50 ₽ вход / 54 ₽ кеш / 675 ₽ выход за 1 млн; libra-pro — 450 ₽ / 72 ₽ / 900 ₽ за 1 млн. Пакетная обработка даёт −20% к ставкам, приоритетная — ×2. Пополнение баланса от 1 млн токенов, 450 ₽ за 1 млн.