СтатьяСредний8 минОбновлено 2026-10-09

API-ключ и SDK

Как получить API-ключ, базовый адрес /api/v1, авторизация Bearer, основные методы для баз знаний, документов, ассистентов и сессий, пример на Python SDK.

Всё, что доступно в интерфейсе Semantix, доступно и через HTTP API. Ключ привязан к организации, поэтому запросы видят только её базы знаний, ассистентов и агентов.

Получение ключа

Нажмите аватар в правом верхнем углу и откройте настройки.
Перейдите на страницу «API».
Создайте ключ и сохраните его в защищённом хранилище: повторно он не показывается целиком.

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

Внимание

API-ключ даёт доступ к данным организации. Не помещайте его в клиентский код, репозитории и журналы.

Базовый адрес и авторизация

Базовый адрес: https://<ваш-адрес>/api/v1. Каждый запрос содержит заголовок:

http

Authorization: Bearer <api-key>
Content-Type: application/json

Ответ приходит в виде {"code": 0, "data": ...}. Ненулевой code означает ошибку, текст в поле message. Коды 401 и 403 говорят о неверном ключе или отсутствии прав.

Основные методы

Группа	Метод	Назначение
Базы знаний	`POST /datasets`, `GET /datasets`, `PUT /datasets/{id}`, `DELETE /datasets`	Создание, список, изменение, удаление
Документы	`POST /datasets/{id}/documents` (multipart), `GET /datasets/{id}/documents`, `POST /datasets/{id}/chunks`	Загрузка, список, запуск обработки
Фрагменты	`GET /datasets/{id}/documents/{doc_id}/chunks`, `POST /retrieval`	Просмотр фрагментов, поиск по базам
Ассистенты	`POST /chats`, `GET /chats`, `PUT /chats/{id}`, `DELETE /chats`	Управление ассистентами
Сессии	`POST /chats/{id}/sessions`, `GET /chats/{id}/sessions`, `DELETE /chats/{id}/sessions`	Беседы ассистента
Ответы	`POST /chats/{id}/completions`	Вопрос ассистенту, потоковый или обычный ответ
Агенты	`POST /agents/{id}/sessions`, `POST /agents/{id}/completions`	Запуск агента с холста
OpenAI-совместимый	`POST /chats_openai/{id}/chat/completions`, `POST /agents_openai/{id}/chat/completions`	Формат `messages`, подходит для готовых клиентов

Полный перечень параметров приведён в справочнике HTTP API в составе документации платформы.

Потоковый ответ

Запрос с "stream": true возвращает text/event-stream. Каждое событие имеет вид data: {"code": 0, "data": {"answer": "...", "reference": {...}, "session_id": "..."}}, где answer накапливается, а reference содержит фрагменты и документы, на которые опирается ответ. Последнее событие содержит "data": true.

bash

curl -N https://<ваш-адрес>/api/v1/chats/<chat_id>/completions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"question": "Какой срок согласования заявки?", "stream": true}'

Если не передать session_id, первое обращение создаёт сессию и возвращает её идентификатор в ответе. Передавайте его в следующих запросах, чтобы сохранить историю беседы.

Для ассистентов на новом ядре чата ответ дополнительно содержит объект smx_runtime со статусом хода, идентификаторами сессии и запуска и сведениями о подтверждении. Если ассистент готовит действие во внешней системе, он останавливается и ждёт решения: решение отправляется в тот же endpoint с session_id, confirmation_id, decision (approve или reject) и новым operation_id. Параметр operation_id делает повтор запроса безопасным: один и тот же идентификатор не приводит к повторному выполнению.

Python SDK

Пакет называется ragflow-sdk и устанавливается через pip install ragflow-sdk. Пример полного цикла: база знаний, документ, ассистент, вопрос.

python

from ragflow_sdk import RAGFlow

rag = RAGFlow(api_key="<api-key>", base_url="https://<ваш-адрес>")

dataset = rag.create_dataset(name="Регламенты")
with open("reglament.pdf", "rb") as f:
    dataset.upload_documents([{"display_name": "reglament.pdf", "blob": f.read()}])
docs = dataset.list_documents()
dataset.async_parse_documents([d.id for d in docs])

chat = rag.create_chat(name="Помощник по регламентам", dataset_ids=[dataset.id])
session = chat.create_session()
for chunk in session.ask("Какой срок согласования заявки?", stream=True):
    print(chunk.content)

base_url указывается без суффикса /api/v1: SDK добавляет его сам. Обработка документов идёт в фоне, поэтому перед первым вопросом дождитесь состояния «УСПЕШНО» у документов (метод list_documents возвращает статус обработки).

Совет

Для поиска без генерации используйте rag.retrieve(...) или POST /retrieval: вы получите фрагменты с оценками сходства и сможете собрать ответ своим кодом.

Что дальше

Встраивание чата на сайт: публичный виджет без API-ключа на клиенте.
MCP-серверы: инструменты для агентов и внешних клиентов.
Агенты на холсте: агент как endpoint с входными параметрами.

Спросить Сему

Было полезно?

Дальше

Встраивание чата на сайт