HTTP API Voicee (0.17.0)

API Voicee - предоставляет программный доступ к услугам транскрибации, перевода, составления краткого содержания (саммари), субтитров и их перевода.

Модель voicee/transcribe возвращает транскрипт в выбранном формате и до 8 параллельных постобработок через список post_process. Мы поддерживаем только транскрибацию как по ссылке на файл, так и с загрузкой файла во время запроса.

Наше API асинхронное - это значит, что одним запросом вы ставите задачу на транскрибацию и серией других запросов (polling) вы узнаете статус задачи и получаете ее результат. Мы стараемся, чтобы результат был готов в течение нескольких минут и работаем над улучшением этой метрики. Мы уже работаем над поддержкой сервер-сервер уведомлений о статусах задач (webhooks). Если вам важно получать уведомления в браузере или вы просто больше любите уведомления по websocket - напишите нам: мы готовы повысить приоритет этой задачи.

Для того чтобы облегчить интеграцию наше API совместимо с клиентом сервиса replicate. Это означает что вы можете использовать их клиент для любой платформы для взаимодействия с нашим сервисом. Будьте внимательны: компания replicate не имеет никакого отношения к нашим сервисам и в случае неработоспособности вам стоит связываться с нашей поддержкой а не поддержкой сервиса replicate.

Authentication

API-ключ можно получить в кабинете my.voicee.ru: «Настройки» → «API» → «Получить ключ». При перевыпуске старый ключ отзывается в течение 5 минут. Ключ также выдаётся в Telegram-боте Войси: меню «API», кнопка «Получить токен». Передавайте ключ в заголовке Authorization: Bearer ключ.

bearerAuth

Security Scheme Type: HTTP

HTTP Authorization Scheme: bearer

Транскрибация файлов

Raw HTTP API

Поставить обработку в очередь
1. Если есть ссылка на аудио файл: можно отправить классический запрос с JSON в теле
```
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer tk-..." https://api.voicee.ru/v1/replicate/v1/models/voicee/transcribe/predictions -d '{"input": {"audio": "https://example.com/audio.mp3", "language": "ru", "output_format": "json"}}'
```
2. Если вы хотите загрузить файл внутри запроса
  
  Мы поддерживаем загрузку файлов в 2 форматах: multipart/form-data и application/octet-stream. Ограничение на размер файла - 300MiB.
  
  multipart/form-data
  
  Описание формата можно посмотреть на википедии: https://ru.wikipedia.org/wiki/Multipart/form-data
```
curl -X POST https://api.voicee.ru/v1/replicate/v1/models/voicee/transcribe/predictions -H "Authorization: Bearer tk-<token here>" -F "input.audio=@/path-to-file/audio.mp4"
```
  при этом /path-to-file/audio.mp4 - это путь к файлу на вашем компьютере, а собачка перед путем обязательна - она подсказывает утилите curl, что это файл.
  
  application/octet-stream
  
  Если у вас нет под рукой клиента, который уже поддерживает мультипарт запросы, возможно самым простым вариантом будет отправка файла как есть в теле запроса. При этом нашей модели понадобится подсказка в какой параметр подложить этот файл - ее следует передать в заголовке X-Voicee-Body-Field:
```
curl https://api.voicee.ru/v1/replicate/v1/models/voicee/transcribe/predictions -H "Authorization: Bearer tk-<token here>" -H "X-Voicee-Body-Field: input.audio" -H "Content-Type: application/octet-stream" --data-binary "@/path-to-file/audio.mp4"
```
В ответ вы получите айди задачки и статус:
```
{"id": "<prediction_id>", "status": "processing", ...}
```
Узнать статус обработки и получить результат

Опрашивать статус обработки можно по айди задачки:
```
curl https://api.voicee.ru/v1/replicate/v1/predictions/<prediction_id> -H "Authorization: Bearer tk-<token here>"
```
Конечными статусами являются failed и succeeded.

Формат вывода

Ответом основной нашей модели является сложный словарь с траснкриптом разделенным на сегменты. Иногда такая сложность не нужна и нужно получить просто текст Вывод можно контролировать с заголовком X-Voicee-Output-Transformers. Пример:
```
X-Voicee-Output-Transformers: text?speakers=false&timestamps=false&pauses=false
```

Работа с Replicate клиентом

Рядом с обычным API мы публикуем replicate совместимый API, чтобы вы могли использовать готовые библиотеки для работы с нашим API на множестве языков.

Полный список библиотек можно посмотреть на странице библиотек.

API ключ - используйте тот же ключ, который используете для обычного API

При создании клиента укажите baseUrl = https://api.voicee.ru/v1/replicate

В качестве модели используйте voicee/transcribe. Передайте обязательный input.audio (HTTP(S)-ссылка), при необходимости input.language; input.output_format принимает json (по умолчанию), json2, text, srt или lrc. Для дополнительных результатов передайте список input.post_process.

Пример для Python:

Установите библиотеку

pip install 'replicate<0.32.0'

Установите токен и базовый URL в переменные окружения

export REPLICATE_API_TOKEN=<ваш ключ>
export REPLICATE_BASE_URL=https://api.voicee.ru/v1/replicate

или, если у вас уже есть .env файл с переменными окружения - добавьте их в него:

REPLICATE_API_TOKEN=<ваш ключ>
REPLICATE_BASE_URL=https://api.voicee.ru/v1/replicate

или, вы можете указать эти настройки прямо в коде приложения:

from replicate import Client

client = Client(base_url='https://api.voicee.ru/v1/replicate', api_token='Ваш ключ')

# дальше используйте client.run(...) вместо replicate.run(...)

Запустите транскрибацию

import replicate

audio_file_url = "https://example.com/audio.mp3"

result = replicate.models.run(
    "voicee/transcribe",
    input={"audio": audio_file_url},
)

print(result)
# output example TBD

predictions

Запустить обработку файла

Начать новую обработку файла с учетом выбранной модели и предоставленных входных данных.

Authorizations:

bearerAuth

Request Body schema: application/json

required	object Входные данные модели в виде JSON объекта. Схема входных данных зависит от выбранной модели.
version required	string ID модели, которую вы хотите использовать для обработки. voicee/transcribe Value: "voicee/transcribe"
webhook	string HTTPS URL для получения веб-хука об изменении статуса обработки файла.
webhook_events_filter	Array of arrays По умолчанию мы отправляем запросы на ваш URL веб-хука при появлении новых логов или при завершении обработки файла.

Responses

Request samples

Payload

Content type

application/json

{"input": {"audio": "https://example.com/audio.mp3",
"language": null,
"speakers": null,
"output_format": "json",
"domain": "auto",
"efficiency": "fast",
"multilingual": true,
"prompt": "string",
"hotwords": "string",
"cut_start": "0",
"cut_duration": "-1",
"post_process": ["summary",
"action_items",
"speaker_names"
],
"custom_prompt": "string",
"target_language": "string"
},
"version": "voicee/transcribe",
"webhook": "string",
"webhook_events_filter": [ ]
}

Response samples

Content type

application/json

{"id": "string",
"model": "celery/predict.Predictor.predict",
"version": "",
"status": "succeeded",
"output": "string",
"error": "string"
}

Получить информацию об обработке файла

Получить текущее состояние обработки файла.

Authorizations:

bearerAuth

path Parameters

prediction_id

required

string

ID обработки файла для получения информации.

Responses

Response samples

Content type

application/json

{"id": "string",
"model": "celery/predict.Predictor.predict",
"version": "",
"status": "succeeded",
"output": "string",
"error": "string"
}

Постобработка, кэш и бесплатный повтор

Всё выполняет одна модель voicee/transcribe: загрузчик воркера, распознавание, транскрипт в output_format и дополнительные результаты из post_process. До 8 разных обработок запускаются параллельно. SRT/LRC выбираются через output_format. Список не принимает повторов, неизвестных и внутренних имён. Неверный post_process (не список строк, больше 8 типов, повторы или неизвестный тип) возвращает HTTP 422 с понятным detail, без создания prediction. Отсутствие обязательного target_language или непустого custom_prompt, а также custom_prompt длиннее 8192 символов возвращают HTTP 422 до обработки.

Тип	Результат
`summary`	Краткое содержание.
`gist`	Суть одним абзацем.
`detailed`	Подробный пересказ.
`meeting_minutes`	Протокол встречи.
`lecture_notes`	Конспект лекции на русском языке.
`simple`	Простое объяснение.
`key_facts`	Ключевые факты.
`action_items`	Задачи и дальнейшие действия.
`chapters`	Тематические таймкоды.
`blog_post`	Пост для блога.
`article`	Статья по записи.
`quiz`	Викторина.
`customer_insights`	Потребности и проблемы клиента.
`clean_up`	Отредактированный транскрипт.
`translation`	Перевод транскрипта на target_language.
`translated_subtitles`	Переведённые субтитры SRT.
`custom`	Результат custom_prompt, до 8192 символов.
`speaker_names`	Карта меток к именам или null.

Для перевода обязателен target_language, например en или English; см. список поддерживаемых языков. Неподдерживаемое значение target_language возвращает HTTP 422 с detail и ссылкой на список языков до создания prediction и списания. Для custom обязателен непустой custom_prompt. Проверка выполняется до скачивания. На записи без речи текстовые результаты равны "", speaker_names равен {}; LLM не вызывается. Ошибка одной обработки завершает prediction с failed, частичный успех не возвращается.

Если post_process отсутствует или равен null, output сохраняет прежнюю форму: объект для json/json2, строка для text/srt/lrc. При переданном списке ответ имеет вид {"transcript": <выбранный формат>, "results": {<тип>: <результат>}}. Пустой список возвращает results: {}. Служебные метрики, RFH и URL файлов не возвращаются.

Повтор той же ссылки использует существующий кэш загрузчика и сохранённый транскрипт. По умолчанию срок кэша и бесплатного повтора составляет 27 дней. Бесплатен только запрос, который взял готовый транскрипт из кэша и не запускал ASR, если тот же пользователь уже оплатил этот файл в окне повтора. Новые виды постобработки в таком запросе не создают нового списания. Если ASR выполняется в этом запросе, действует обычное списание, даже для того же пользователя и той же ссылки. ASR пропускается только при совпадении speakers, language, domain, efficiency, multilingual и подсказок prompt/hotwords. Иначе распознавание запускается заново. Кэш без сохранённых параметров также требует ASR; сохраняется последний вариант транскрипта. Повреждённый или истёкший meta/BMR вызывает повторную загрузку и ASR. Новая загрузка создаёт новый RFH; запрос с recovery оплачивается по обычным правилам. Публичный RFH отделён от бота и кабинета значением public-api в существующем кэше загрузчика. Если конкурентный запрос сменил параметры транскрипта до чтения, возвращается ошибка cache_changed с указанием повторить запрос. Другая ссылка на те же байты не гарантирует попадания в кэш. Удаление исходных данных или потеря download-кэша также не гарантирует повторное использование файла.

Поддержаны audio, language, speakers, output_format, post_process, custom_prompt, target_language. Параметры domain, efficiency, multilingual проверяются до загрузки и передаются в ASR. prompt передаётся как transcription_hint, hotwords как keywords. cut_start принимает только 0, пустую строку или null; cut_duration только -1, пустую строку или null. Числовые строки "0.0" и "-1.0" также допустимы. Нулевые значения обоих cut_* в формате [HH:]MM:SS, например "0:00" или "00:00:00", принимаются как значение по умолчанию. Любые другие значения возвращают HTTP 422 до загрузки; запрос не обрабатывается и не оплачивается как полная запись. Прежние параметры batch_size, correction, debug, spelling, stereo, enhance_asr, log_progress, auto_multilingual принимаются и игнорируются. Прочие неизвестные параметры также игнорируются.

Совместимость json2: сохранены source/segments/vad и форма languages/speakers. Если BMR содержит только основной язык, languages имеет один элемент с этим кодом, названием языка и null для probability/duration: эти измерения нельзя восстановить из BMR. Для text сохраняется строка с метками спикеров и времени; оформление использует форматтер воркера.

Ключ получите в кабинете my.voicee.ru: «Настройки» → «API» → «Получить ключ», или в Telegram-боте Войси: меню «API», кнопка «Получить токен». При перевыпуске старый ключ отзывается в течение 5 минут. Передавайте его через заголовок Authorization и храните вне исходного кода.

curl --request POST 'https://api.voicee.ru/v1/replicate/v1/predictions' \
  --header "Authorization: Bearer ${VOICEE_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"version":"voicee/transcribe","input":{"audio":"https://example.com/audio.mp3","output_format":"json","post_process":["summary","action_items","speaker_names"]}}'

{
  "status": "succeeded",
  "output": {
    "transcript": {"source": {"length": 600, "format": ".mp3"}, "segments": [], "vad": [], "language": "ru"},
    "results": {"summary": "Обсудили график работ.", "action_items": "Подготовить график к пятнице.", "speaker_names": {"A": null}}
  }
}

Сохраните id и опрашивайте /v1/replicate/v1/predictions/ID до терминального статуса.

required	TranscribeOutputText (string) or TranscribeOutputJson (object) or TranscribeOutputJson2 (object)
required	object Выбранный тип обработок к строке результата. speaker_names возвращает карту меток к именам или null.

{"transcript": "string",
"results": {"speaker_names": {"property1": "string",
"property2": "string"
},
"property1": "string",
"property2": "string"
}
}

Языки перевода

Для target_language используйте код или английское название языка из таблицы.

Код	Английское название
`af`	Afrikaans
`sq`	Albanian
`am`	Amharic
`ar`	Arabic
`hy`	Armenian
`as`	Assamese
`az`	Azerbaijani
`ba`	Bashkir
`eu`	Basque
`be`	Belarusian
`bn`	Bengali
`bs`	Bosnian
`br`	Breton
`bg`	Bulgarian
`yue`	Cantonese
`ca`	Catalan
`zh`	Chinese
`hr`	Croatian
`cs`	Czech
`da`	Danish
`nl`	Dutch
`en`	English
`et`	Estonian
`fo`	Faroese
`fi`	Finnish
`fr`	French
`gl`	Galician
`ka`	Georgian
`de`	German
`el`	Greek
`gu`	Gujarati
`ht`	Haitian creole
`ha`	Hausa
`haw`	Hawaiian
`he`	Hebrew
`hi`	Hindi
`hu`	Hungarian
`is`	Icelandic
`id`	Indonesian
`it`	Italian
`ja`	Japanese
`jw`	Javanese
`kn`	Kannada
`kk`	Kazakh
`km`	Khmer
`ko`	Korean
`lo`	Lao
`la`	Latin
`lv`	Latvian
`ln`	Lingala
`lt`	Lithuanian
`lb`	Luxembourgish
`mk`	Macedonian
`mg`	Malagasy
`ms`	Malay
`ml`	Malayalam
`mt`	Maltese
`mi`	Maori
`mr`	Marathi
`mn`	Mongolian
`my`	Myanmar
`ne`	Nepali
`no`	Norwegian
`nn`	Nynorsk
`oc`	Occitan
`ps`	Pashto
`fa`	Persian
`pl`	Polish
`pt`	Portuguese
`pa`	Punjabi
`ro`	Romanian
`ru`	Russian
`sa`	Sanskrit
`sr`	Serbian
`sn`	Shona
`sd`	Sindhi
`si`	Sinhala
`sk`	Slovak
`sl`	Slovenian
`so`	Somali
`es`	Spanish
`su`	Sundanese
`sw`	Swahili
`sv`	Swedish
`tl`	Tagalog
`tg`	Tajik
`ta`	Tamil
`tt`	Tatar
`te`	Telugu
`th`	Thai
`bo`	Tibetan
`tr`	Turkish
`tk`	Turkmen
`uk`	Ukrainian
`ur`	Urdu
`uz`	Uzbek
`vi`	Vietnamese
`cy`	Welsh
`yi`	Yiddish
`yo`	Yoruba

Задача transcribe: входные параметры

audio required	string <uri> HTTP(S)-ссылка на одну аудио- или видеозапись. При загрузке файла используйте input.audio.
language	string or null Default: null Язык распознавания. Повтор без ASR требует совпадения параметров распознавания.
speakers	integer or null >= 1 Default: null Ожидаемое число спикеров.
output_format	string Default: "json" Enum: "json" "json2" "text" "srt" "lrc" Вид транскрипта. SRT/LRC являются форматами, а не видами постобработки.
domain	string or null Enum: "auto" "general" "telephonic" "meeting" "surveillance" "song" "studio" "news" "experimental" null Тематика записи; проверяется до загрузки.
efficiency	string or null Enum: "fast" "balanced" "accurate" null Баланс скорости и качества; проверяется до загрузки.
multilingual	boolean or null Анализ нескольких языков; boolean или null, проверяется до загрузки.
prompt	string or null Подсказка для существующей коррекции транскрипта (transcription_hint).
hotwords	string or null Ключевые слова для распознавания через запятую (keywords).
cut_start	string or number or null Default: "0" Обрезка не поддержана. Допустимы только 0 (включая "0.0"), нулевое [HH:]MM:SS (например "0:00"), пустая строка или null. Иное значение возвращает 422 до загрузки.
cut_duration	string or number or null Default: "-1" Обрезка не поддержана. Допустимы только -1 (включая "-1.0"), нулевое [HH:]MM:SS (например "0:00"), пустая строка или null. Иное значение возвращает 422 до загрузки.
post_process	Array of strings or null (PostProcessType) <= 8 items unique Enum: "summary" "gist" "detailed" "meeting_minutes" "lecture_notes" "simple" "key_facts" "action_items" "chapters" "blog_post" "article" "quiz" "customer_insights" "clean_up" "translation" "translated_subtitles" "custom" "speaker_names" До 8 разных обработок параллельно. При отсутствии или null сохраняется прежняя форма output; пустой список добавляет results = {}.
custom_prompt	string or null [ 1 .. 8192 ] characters Обязателен для custom; строка из пробелов недопустима.
target_language	string or null Обязателен для translation и translated_subtitles. Код или английское название языка, например en или English.
property name* additional property	any

{"audio": "https://example.com/audio.mp3",
"language": null,
"speakers": null,
"output_format": "json",
"domain": "auto",
"efficiency": "fast",
"multilingual": true,
"prompt": "string",
"hotwords": "string",
"cut_start": "0",
"cut_duration": "-1",
"post_process": ["summary",
"action_items",
"speaker_names"
],
"custom_prompt": "string",
"target_language": "string"
}

Задача transcribe: выходные параметры

Any of

string (TranscribeOutputText)

Текст с метками спикеров и времени (text), либо субтитры SRT/LRC строкой.

Example

TranscribeOutputText

"string"

HTTP API Voicee (0.17.0)

Authentication

bearerAuth

Транскрибация файлов

Raw HTTP API

multipart/form-data

application/octet-stream

Формат вывода

Работа с Replicate клиентом

predictions

Запустить обработку файла

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Получить информацию об обработке файла

Authorizations:

path Parameters

Responses

Response samples

Постобработка, кэш и бесплатный повтор

Языки перевода

Задача transcribe: входные параметры

Задача transcribe: выходные параметры