This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Справочник API
Сервер GigaAM-Multilingual ASR предоставляет интерфейс, совместимый с OpenAI Audio API. Это позволяет использовать стандартные клиенты (например, официальный пакет openai для Python) без модификаций кода, просто указав альтернативный base_url. Реализация основана на фреймворке FastAPI и описана в файле src/gigam_asr/server.py.
Ниже приведено описание доступных конечных точек, параметров запросов и формата ответов.
Общие сведения
Авторизация
Если переменная окружения API_KEYS задана (список токенов через запятую), все запросы должны содержать заголовок Authorization: Bearer <token>. Если API_KEYS пуста, авторизация отключена.
CORS
Поведение определяется переменной CORS_ORIGINS:
*(по умолчанию): разрешены все источники. Сервер корректно обрабатывает preflight-запросыOPTIONS.- Пустая строка: CORS полностью отключен.
- Список URL через запятую: разрешены только указанные источники.
Коды ошибок
401 Unauthorized: неверный или отсутствующий токен (если авторизация включена).404 Not Found: указано неизвестное имя модели в полеmodel.422 Unprocessable Entity: отсутствует обязательное полеmodelили другие ошибки валидации формата запроса.
Конечные точки
1. Транскрипция аудио
Эта конечная точка выполняет распознавание речи и возвращает текст. Она полностью совместима с методом client.audio.transcriptions.create() официального клиента OpenAI.
URL: POST /v1/audio/transcriptions
Параметры запроса (multipart/form-data)
| Параметр | Тип | Обязательность | Описание |
|---|---|---|---|
file |
File | Да | Аудиофайл. Поддерживаются форматы, которые может обработать ffmpeg (mp3, wav, m4a, ogg, flac и др.). Максимальная длительность ограничена переменной MAX_DURATION (по умолчанию 3600 секунд). |
model |
String | Да | Имя модели для использования. Допустимые значения определяются переменной MODELS. Обычно это gigaam-multilingual-large-ctc или gigaam-multilingual-ctc. |
response_format |
String | Нет | Формат ответа. Допустимые значения: json (по умолчанию), verbose_json, text, jsonl. См. раздел «Формат ответа». |
timestamp_granularities |
Array[String] | Нет | Уровень детализации меток времени. Для получения слов с временными интервалами передайте массив ["word"]. Обратите внимание, что клиенты OpenAI часто отправляют это поле как timestamp_granularities[]. |
language |
String | Нет | Язык аудио. Принимается, но игнорируется, так как модель является мультязычной и определяет язык автоматически. |
prompt |
String | Нет | Промпт. Принимается, но игнорируется. |
temperature |
Float/String | Нет | Температура. Принимается, но игнорируется (используется жадное декодирование CTC). |
Формат ответа
Структура JSON зависит от параметра response_format.
1. json (по умолчанию)
Базовый формат, содержащий полный текст.
{
"text": "Распознанный текст...",
"model": "gigaam-multilingual-large-ctc",
"latency_s": 1.25,
"_rtf": 0.03
}
text: Строка с результатом распознавания.model: Имя использованной модели.latency_s: Время обработки в секундах (с точностью до миллисекунд)._rtf: Real-Time Factor (отношение времени обработки к длительности аудио).
2. verbose_json
Расширенный формат с сегментами и словами.
{
"task": "transcribe",
"language": "ru",
"duration": 10.5,
"text": "Распознанный текст...",
"segments": [
{
"id": 0,
"start": 0.0,
"end": 5.2,
"text": "Первая часть текста.",
"tokens": ["П", "е", "р", ...],
"temperature": 0.0,
"avg_logprob": -0.5,
"compression_ratio": 1.2,
"no_speech_prob": 0.0,
"words": [
{
"word": "Первая",
"start": 0.0,
"end": 1.2,
"probability": 0.98
}
]
}
],
"words": [
{
"word": "Первая",
"start": 0.0,
"end": 1.2,
"probability": 0.98
}
],
"model": "gigaam-multilingual-large-ctc",
"latency_s": 1.25,
"_rtf": 0.03
}
segments: Массив сегментов (фрагментов речи). Если включен VAD (CHUNK_SECONDS > 0), аудио разбивается на несколько сегментов.words: Глобальный массив всех слов с метками времени (если запрошено черезtimestamp_granularities=["word"]).- Внутри каждого сегмента поле
wordsсодержит слова, относящиеся именно к этому сегменту.
3. text
Возвращает только чистый текст без JSON-обертки.
Распознанный текст...
4. jsonl
По сути, аналогичен json, но предназначен для потоковой передачи (хотя сервер возвращает единый объект). Структура та же, что и у json.
Примеры запросов
cURL (основной):
curl http://localhost:43000/v1/audio/transcriptions \
-H "Authorization: Bearer your_api_key" \
-F file=@speech.mp3 \
-F model=gigaam-multilingual-large-ctc \
-F response_format=json
Python (официальный клиент OpenAI):
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:43000/v1",
api_key="your_api_key" # или "none", если авторизация выключена
)
with open("speech.mp3", "rb") as f:
transcription = client.audio.transcriptions.create(
model="gigaam-multilingual-large-ctc",
file=f,
response_format="verbose_json",
timestamp_granularities=["word"]
)
print(transcription.text)
for word in transcription.words:
print(f"{word.start:.2f}s - {word.end:.2f}s: {word.word}")
2. Список моделей
Возвращает список доступных моделей, загруженных в текущем экземпляре сервера. Совместим с client.models.list().
URL: GET /v1/models
Параметры запроса
Нет. Требуется только заголовок авторизации (если включена).
Формат ответа
{
"object": "list",
"data": [
{
"id": "gigaam-multilingual-large-ctc",
"object": "model",
"created": 1700000000,
"owned_by": "gigam-asr"
},
{
"id": "gigaam-multilingual-ctc",
"object": "model",
"created": 1700000000,
"owned_by": "gigam-asr"
}
]
}
id: Имя модели, которое нужно использовать в полеmodelпри транскрипции.created: Unix-время создания (фиксированное значение для совместимости).owned_by: Владелец модели.
Пример запроса
curl http://localhost:43000/v1/models \
-H "Authorization: Bearer your_api_key"
3. Проверка состояния (Health Check)
Легковесная конечная точка для мониторинга доступности сервиса и загрузки моделей. Не является частью стандарта OpenAI, но полезна для оркестраторов контейнеров (Docker, Kubernetes).
URL: GET /health
Параметры запроса
Нет.
Формат ответа
{
"status": "ok",
"models_loaded": [
"gigaam-multilingual-large-ctc",
"gigaam-multilingual-ctc"
],
"device": "cuda"
}
status: Текущее состояние (okилиloading).models_loaded: Список имен моделей, успешно загруженных в память.device: Устройство инференса (cudaилиcpu).
Пример запроса
curl http://localhost:43000/health
Детали реализации
Обработка меток времени
Сервер использует функцию _chars_to_words() для группировки символьных меток времени (character-level timestamps), полученных от модели CTC, в словесные интервалы (word-level spans). Это обеспечивает высокую точность позиционирования слов в аудиопотоке.
Работа с длинными аудиофайлами
Если переменная CHUNK_SECONDS установлена в значение больше нуля (по умолчанию 300), используется Silero VAD (Voice Activity Detection) для сегментации длинных записей. Это предотвращает переполнение памяти и повышает стабильность обработки файлов длительностью до 1 часа. Подробности об архитектуре VAD описаны в разделе Архитектура.
Нормализация аудио
Входящие аудиофайлы любого формата преобразуются в моно-поток PCM 16 кГц float32 с помощью ffmpeg. Это гарантирует единообразие входных данных для нейронной сети независимо от исходного кодека или частоты дискретизации.
Связанные страницы
- Конфигурация — подробное описание переменных окружения (
MODELS,API_KEYS,CORS_ORIGINSи др.). - Производительность — данные о скорости работы (RTF) на разных устройствах.
- Установка и запуск — инструкции по скачиванию моделей и запуску сервера.