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

Эта документация описывает все доступные эндпоинты API для приложения, включая методы, параметры, ответы и примеры использования. API разделено на три группы маршрутов: /api/auth, /api/settings и /api/dashboard. Большинство эндпоинтов, кроме /api/auth/login, требуют авторизации через Bearer-токен, который можно получить через эндпоинт логина.

Общая информация

Базовый URL: http://192.168.200.111:8000
Авторизация: Большинство эндпоинтов требуют заголовок Authorization: Bearer <token> или query-параметр token=<token>. Токен получается через /api/auth/login.
Формат ответов: JSON.
Коды ошибок:
- 401 Unauthorized: Требуется авторизация или токен недействителен.
- 500 Internal Server Error: Ошибка на сервере.

Получение токена авторизации

Для доступа к защищённым эндпоинтам необходимо получить Bearer-токен через эндпоинт /api/auth/login.

Эндпоинт: POST /api/auth/login
Описание: Аутентифицирует пользователя и возвращает сессионный токен.

Тело запроса (JSON):

{
  "username": "string",
  "password": "string"
}

Ответ:

Успех (200):

{
  "access_token": "string",
  "token_type": "bearer"
}

Ошибка (401):

{
  "detail": "Неверные учетные данные"
}

Пример:

curl -X POST http://192.168.200.111:8000/api/auth/login \
 -H "Content-Type: application/json" \
 -d '{"username": "admin", "password": "admin"}'

Результат (пример):

{
  "access_token": "123e4567-e89b-12d3-a456-426614174000",
  "token_type": "bearer"
}

Сохраните access_token для использования в других запросах.

Эндпоинты /api/auth

Получение информации о текущем пользователе
- Эндпоинт: GET /api/auth/me
- Описание: Возвращает информацию о текущем пользователе на основе предоставленного токена. Если токен отсутствует или недействителен, возвращает неаутентифицированный статус.
- Параметры запроса:
  - authorization (опционально, строка): Заголовок Authorization: Bearer .
  - token_param (опционально, строка): Query-параметр token=.
- Ответ:
  - Успех (200):
```
{
  "username": "string",
  "is_authenticated": true
}
```
  - Неаутентифицирован (200):
```
{
  "username": "",
  "is_authenticated": false
}
```
  - Ошибка (500): {"detail": "Описание ошибки"}
- Пример:
```
curl -X GET http://192.168.200.111:8000/api/auth/me \
 -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
 -H "accept: application/json"
```
Выход из системы
- Эндпоинт: POST /api/auth/logout
- Описание: Завершает сессию пользователя, удаляя токен.
- Параметры запроса:
  - authorization (опционально, строка): Заголовок Authorization: Bearer .
  - token_param (опционально, строка): Query-параметр token=.
- Ответ:
  - Успех (200):
```
{
  "status": "success",
  "message": "Выход выполнен успешно"
}
```
  - Нет сессии (200):
```
{
  "status": "success",
  "message": "Нет активной сессии"
}
```
  - Ошибка (500): {"detail": "Описание ошибки"}
- Пример:
```
curl -X POST http://192.168.200.111:8000/api/auth/logout \
 -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
 -H "accept: application/json"
```

Эндпоинты /api/settings

Получение всех настроек
- Эндпоинт: GET /api/settings
- Описание: Возвращает все настройки приложения (VAD, system, STT, commands, auth).
- Ответ:
  - Успех (200): Объект с полями vad, system, stt, commands, auth (см. модели в коде).
  - Ошибка (401): {"detail": "Не авторизован"}
  - Ошибка (500): {"detail": "Описание ошибки"}
- Пример:
```
curl -X GET http://192.168.200.111:8000/api/settings \
 -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
 -H "accept: application/json"
```
Обновление настроек VAD
- Эндпоинт: PUT /api/settings/vad
- Описание: Обновляет настройки VAD.
- Тело запроса (JSON): Объект VADSettings (см. модель в коде).
- Ответ:
  - Успех (200): Обновлённый объект VADSettings.
  - Ошибка (401): {"detail": "Не авторизован"}
  - Ошибка (500): {"detail": "Описание ошибки"}
- Пример:
```
curl -X PUT http://192.168.200.111:8000/api/settings/vad \
 -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
 -H "Content-Type: application/json" \
 -d '{"mode": 1, "sample_rate": 16000, ...}'
```

(Аналогично для /system, /stt, /commands, /auth — обновление соответствующих настроек.)

Перезапуск VAD и STT
- Эндпоинт: POST /api/settings/restart
- Описание: Перезапускает VAD и STT с новыми настройками.
- Ответ:
  - Успех (200):
```
{
  "status": "success",
  "message": "VAD и STT перезапущены"
}
```
  - Ошибка (401): {"detail": "Не авторизован"}
  - Ошибка (500): {"detail": "Описание ошибки"}
- Пример:
```
curl -X POST http://192.168.200.111:8000/api/settings/restart \
 -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
 -H "accept: application/json"
```

Эндпоинты /api/dashboard

Получение данных о речи и энергии
- Эндпоинт: GET /api/dashboard/speech-data
- Описание: Возвращает текущие данные о речи и энергии, включая расширенные метрики VAD и STT.
- Ответ:
  - Успех (200):
```
{
  "state": "string",
  "speech_prob": 0.0,
  "energy": 0.0,
  "energy_threshold": 0.0,
  "speech_detected": false,
  "continuous_frames": 0,
  "gain": 1.0,
  "noise_floor": 0.0,
  "stt_model_path": "string",
  "stt_commands_count": 0
}
```
  - Ошибка (401): {"detail": "Не авторизован"}
  - Ошибка (500): {"detail": "Описание ошибки"}
- Пример:
```
curl -X GET http://192.168.200.111:8000/api/dashboard/speech-data \
 -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
 -H "accept: application/json"
```
Получение последних распознанных фраз
- Эндпоинт: GET /api/dashboard/recent-phrases
- Описание: Возвращает список последних распознанных фраз (до указанного лимита).
- Параметры запроса:
  - limit (опционально, целое число, по умолчанию 10): Максимальное количество фраз.
- Ответ:
  - Успех (200):
```
[
  {
    "text": "Пример фразы",
    "timestamp": "2025-10-13T11:13:00",
    "is_command": true
  },
  ...
]
```
  - Ошибка (401): {"detail": "Не авторизован"}
  - Ошибка (500): {"detail": "Описание ошибки"}
- Пример:
```
curl -X GET http://192.168.200.111:8000/api/dashboard/recent-phrases?limit=5 \
 -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
 -H "accept: application/json"
```
Получение статистики системы
- Эндпоинт: GET /api/dashboard/stats
- Описание: Возвращает расширенную статистику работы системы (время работы, количество распознанных фраз, системная нагрузка и т.д.).
- Ответ:
  - Успех (200):
```
{
  "uptime": "0:00:00",
  "recognized_phrases_count": 0,
  "commands_executed_count": 0,
  "system_load": {
    "cpu_percent": 0.0,
    "memory_percent": 0.0,
    "temperature": 0.0
  },
  "total_speech_frames": 0,
  "avg_speech_prob": 0.0,
  "vad_initialized": true,
  "stt_initialized": true
}
```
  - Ошибка (401): {"detail": "Не авторизован"}
  - Ошибка (500): {"detail": "Описание ошибки"}
- Пример:
```
curl -X GET http://192.168.200.111:8000/api/dashboard/stats \
 -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
 -H "accept: application/json"
```
Получение данных о нагрузке системы
- Эндпоинт: GET /api/dashboard/sys-monitor
- Описание: Возвращает данные о нагрузке системы (CPU, память, температура).
- Ответ:
  - Успех (200):
```
{
  "cpu_percent": 0.0,
  "memory_percent": 0.0,
  "temperature": 0.0
}
```
  - Ошибка (401): {"detail": "Не авторизован"}
  - Ошибка (500): {"detail": "Описание ошибки"}
- Пример:
```
curl -X GET http://192.168.200.111:8000/api/dashboard/sys-monitor \
 -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
 -H "accept: application/json"
```

Замечания

Авторизация: Все эндпоинты, кроме /api/auth/login, требуют токен, полученный через /api/auth/login. Токен можно передать:
- В заголовке: Authorization: Bearer <token>
- В query-параметре: ?token=<token>
Безопасность: Пароли в настройках хранятся в открытом виде. Рекомендуется использовать хэширование (например, bcrypt) для auth.password.
Хранение сессий: Токены хранятся в памяти (ACTIVE_SESSIONS). Для продакшена используйте Redis или другую базу данных.
Ограничения: Токены не имеют срока действия. Рекомендуется добавить expiration (например, хранить timestamp в ACTIVE_SESSIONS).
Обновления: Документация актуализирована на 13 октября 2025 года. Добавлены новые поля в /speech-data, новый эндпоинт /sys-monitor и расширенная структура для /stats.

12 KiB Raw Blame History Unescape Escape