HTTP API Voicee (0.18.0)

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

Планируемый простой API без Replicate-совместимости.

1. Поставить обработку в очередь

   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", ...}
   

2. Узнать статус обработки и получить результат

   Опрашивать статус обработки можно по айди задачки:

   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
   

Рядом с обычным 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:

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

pip install 'replicate<0.32.0'

2. Установите токен и базовый 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(...)

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

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

Создание, опрос и отмена обработок в Replicate-совместимой форме.

Эндпоинты памяти голосов позволяют назвать спикеров расшифровки и запомнить их голоса: присвоенное имя подставляется в выбранную обработку и автоматически появляется в будущих обработках того же голоса. Совпадение ищется по голосу, а не по метке спикера, поэтому один и тот же человек сохраняет имя в разных записях, даже если метка в них другая. Два разных человека, названных одинаково, остаются разными профилями.

Память привязана к ключу API: ключ определяется по заголовку Authorization, передавать его или ID ключа в теле запроса не нужно. У каждого ключа своя память: другой ключ того же аккаунта и повторно выпущенный ключ видят отдельную пустую память, а обработки одного ключа недоступны другому ключу на чтение и переименование. При перевыпуске ключа память начинается заново. После отзыва старого ключа его обработки с ID gpa: больше недоступны через API: сохраните нужные результаты до перевыпуска. Обработки, созданные до привязки к ключу, доступны владельцу как прежде, но память голосов не пополняют.

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

Эти эндпоинты не входят в клиенты replicate - используйте прямые HTTP-запросы.

1. Создать обработку и дождаться результата

   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/interview.mp3","output_format":"json","post_process":["speaker_names"]}}'
   

   Опрашивайте GET /v1/replicate/v1/predictions/<prediction_id> до терминального статуса succeeded:

   {
     "id": "<prediction_id>",
     "status": "succeeded",
     "output": {
       "transcript": {
         "segments": [
           {"start": 0.0, "end": 4.2, "speaker": "A", "text": "Добрый день."},
           {"start": 4.4, "end": 9.1, "speaker": "B", "text": "Здравствуйте!"}
         ]
       },
       "results": {"speaker_names": {"A": null, "B": null}}
     }
   }
   

   Метки спикеров (A, B) локальны для этой обработки. Соберите разные значения segments[].speaker, чтобы узнать их.

2. Присвоить имя спикеру

   curl --request PATCH 'https://api.voicee.ru/v1/replicate/v1/predictions/<prediction_id>/speakers/A' \
     --header "Authorization: Bearer ${VOICEE_API_KEY}" \
     --header 'Content-Type: application/json' \
     --data '{"name":"Алексей"}'
   

   {
     "speaker_id": "A",
     "name": "Алексей",
     "profile_id": "<profile_id>",
     "remembered": true,
     "names": {"A": "Алексей"}
   }
   

   remembered: true означает, что образец голоса сохранён и имя будет автоматически подставляться в будущих обработках. Если образец голоса в этой записи недоступен, имя в неё всё равно подставится, но ответ вернёт remembered: false и reason с пояснением; профиль при этом не создаётся.

   Имя появляется в результате этой обработки и будущих обработок того же голоса: в json — в карте names рядом с segments, в json2 — в поле name внутри speakers по метке, в text/srt имя заменяет метку спикера. Формат lrc содержит только текст и временные метки, без имён спикеров.

3. Новая запись того же голоса получит имя сама

   Создайте обычную обработку новой записи с post_process: ["speaker_names"]. Если голос уже назван, метки получат имена без ручного переименования:

   {"results": {"speaker_names": {"A": "Алексей", "B": null}}}
   

4. Другой ключ видит отдельную память

   Та же ссылка под другим ключом вернёт неназванные метки, а список голосов этого ключа будет пуст:

   {"results": {"speaker_names": {"A": null}}}
   

5. Список сохранённых голосов и удаление

   curl 'https://api.voicee.ru/v1/replicate/v1/speakers' \
     --header "Authorization: Bearer ${VOICEE_API_KEY}"
   

   [
     {"id": "<profile_id>", "name": "Алексей", "samples": 2, "created_at": "2026-10-23T10:00:00Z", "updated_at": "2026-10-23T10:05:00Z"}
   ]
   

   Удалите профиль, чтобы будущие обработки перестали узнавать голос. Готовые результаты это не меняет:

   curl --request DELETE 'https://api.voicee.ru/v1/replicate/v1/speakers/<profile_id>' \
     --header "Authorization: Bearer ${VOICEE_API_KEY}"
   

Пример на Python:

import os, time
import requests

BASE = "https://api.voicee.ru/v1/replicate"
HEADERS = {"Authorization": f"Bearer {os.environ['VOICEE_API_KEY']}"}

# создать обработку и дождаться результата
resp = requests.post(f"{BASE}/v1/predictions", headers=HEADERS, json={
    "version": "voicee/transcribe",
    "input": {"audio": "https://example.com/interview.mp3",
              "output_format": "json", "post_process": ["speaker_names"]},
})
prediction_id = resp.json()["id"]
while True:
    data = requests.get(f"{BASE}/v1/predictions/{prediction_id}", headers=HEADERS).json()
    if data["status"] in ("succeeded", "failed", "canceled", "aborted"):
        break
    time.sleep(5)
if data["status"] != "succeeded":
    raise RuntimeError(f"Обработка завершилась: {data['status']}")

# метки спикеров этой записи
labels = sorted({s["speaker"] for s in data["output"]["transcript"]["segments"]})

# назвать спикера
requests.patch(f"{BASE}/v1/predictions/{prediction_id}/speakers/{labels[0]}",
               headers=HEADERS, json={"name": "Алексей"})

# список сохранённых голосов и удаление профиля
profiles = requests.get(f"{BASE}/v1/speakers", headers=HEADERS).json()
requests.delete(f"{BASE}/v1/speakers/{profiles[0]['id']}", headers=HEADERS)

Ошибки возвращаются с понятным detail: 401 - ключ не передан или недействителен; 404 - обработка, спикер или профиль не найдены; 409 - обработка ещё не завершилась успешно; 422 - некорректное имя (пустое или длиннее 120 печатных символов); 503 - сервис временно недоступен.

Каждая модель вызывается в одной Replicate-совместимой форме: POST /v1/replicate/v1/models/voicee/<модель>/predictions (или POST /v1/replicate/v1/predictions с version: "voicee/<модель>"), затем GET /v1/replicate/v1/predictions/<id> до терминального статуса. Поддержаны webhook, Idempotency-Key, Prefer: wait и отмена через /cancel. Официальный replicate SDK работает без изменений.

Файл передаётся тремя способами: JSON со ссылкой, multipart (input.<поле>) или поток байт с X-Voicee-Body-Field: input.<поле>, до 300 MiB. Имя поля задаёт модель (audio или video), url — его синоним.

Исходный prediction (source_prediction) — завершённый prediction этого же ключа вместо файла: модель берёт его файл и транскрипт без повторной загрузки и распознавания. Чужой — 404; незавершённый, упавший или истёкший — 422; вместе с файлом — 422.

Результат-файл — ссылка, которая действует сутки и подписывается заново при каждом GET; файл хранится 30 дней.

Цена такая же, как на сайте. Списание проходит до начала работы. Если средств недостаточно, истекла подписка или превышен лимит, prediction завершается со статусом failed и причиной в error (not_enough_tokens, limit_exceeded, subscription_expired, …) без запуска работы. При сбое деньги возвращаются; повтор с тем же Idempotency-Key не списывает и не запускает работу второй раз.

Одна запись — один транскрипт, а из него бесплатно строятся остальные результаты: саммари, перевод, слайды, видео с субтитрами, караоке, монтаж, минусовка. Транскрибация оплачивается один раз, по длительности; постобработки бесплатны, как на сайте. Заказать их можно сразу вместе с транскрибацией (post_process) или позже по готовой записи (source_prediction) без повторной загрузки и распознавания.

Всё выполняет одна модель 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 до обработки.

Текстовые постобработки — результат строка:

Медиа-постобработки — результат строится из записи и транскрипта:

Ссылки действуют сутки и подписываются заново при каждом GET; файлы хранятся 30 дней.

Параметры медиа-постобработок — post_process_options по имени типа, тип должен быть в post_process (иначе 422):

• subtitles_video: color (#RRGGBB), position (bottom, top, center, lower_third), oneword, karaoke; subtitles — свой srt/ass до 1 MiB (видео до 2 часов), тогда из стиля допустим только color;
• karaoke: color, position, frame (landscape, portrait);
• montage: segments — от 1 до 50 {"start", "end"} в секундах (обязательно; end − start ≥ 1, в пределах файла), burn_subtitles, color, position, oneword, karaoke.

Язык субтитров subtitles_video и montage — общий target_language; другой язык, чем у записи, — перевод.

{"version": "voicee/transcribe", "input": {"audio": "https://example.com/video.mp4", "post_process": ["summary", "slides", "montage"], "post_process_options": {"montage": {"segments": [{"start": 0, "end": 30}]}}}}

Ограничения. slides и subtitles_video требуют видеодорожку: файл без видео — prediction failed до списания, source_prediction без видео — 422 сразу. Не больше 8 постобработок в запросе. Ошибка любой постобработки, текстовой или медиа, завершает prediction с failed и полным возвратом.

target_language — язык результата любой текстовой постобработки, включая custom; транскрипт остаётся на исходном языке. Для перевода он обязателен, например 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 до терминального статуса.

Дозаказ по готовой записи. Постобработку, текстовую или медиа, можно заказать по уже готовой транскрибации: передайте вместо audio поле source_prediction с её id. Файл не загружается, распознавание не выполняется и не оплачивается повторно; в результат попадают имена спикеров, переименованных через PATCH.

{"version": "voicee/transcribe", "input": {"source_prediction": "gpa:…", "post_process": ["summary"], "target_language": "en"}}

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

Модель voicee/dub. Переозвучка видео на target_language, по желанию с субтитрами перевода. quality: premium — внешний провайдер.

Цена: платно всегда, в том числе по source_prediction: по длительности исходника, тариф basic или premium.

curl --request POST 'https://api.voicee.ru/v1/replicate/v1/models/voicee/dub/predictions' \
  --header "Authorization: Bearer ${VOICEE_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"input": {"video": "https://example.com/video.mp4", "target_language": "en"}}'

Ссылка на MP4. Ссылка действует сутки и подписывается заново при каждом GET; файл хранится 30 дней.

Модель voicee/synthesize. Озвучка текста из text или текста транскрипта готовой записи (source_prediction).

Цена: платно всегда: по числу символов текста.

curl --request POST 'https://api.voicee.ru/v1/replicate/v1/models/voicee/synthesize/predictions' \
  --header "Authorization: Bearer ${VOICEE_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"input": {"text": "Привет! Это синтез речи Voicee."}}'

Ссылка на M4A или OPUS (audio_format). Ссылка действует сутки и подписывается заново при каждом GET; файл хранится 30 дней.

Модель voicee/sing. Песня из текста или темы с выбранным стилем и ограничением длительности.

Цена: по заказанной длительности (авто — 300 с); итог пересчитывается по фактической длительности песни.

curl --request POST 'https://api.voicee.ru/v1/replicate/v1/models/voicee/sing/predictions' \
  --header "Authorization: Bearer ${VOICEE_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"input": {"prompt": "короткая песня про утренний кофе", "duration_limit": 60}}'

Ссылка на M4A. Ссылка действует сутки и подписывается заново при каждом GET; файл хранится 30 дней.

Модель voicee/image. Изображение из промпта и/или текста готовой записи, со своими фото (input_images).

Цена: за изображение по тарифу (обычное, HD, векторное, с фото) плюс доплата за каждое входное фото.

curl --request POST 'https://api.voicee.ru/v1/replicate/v1/models/voicee/image/predictions' \
  --header "Authorization: Bearer ${VOICEE_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"input": {"prompt": "рыжий кот на подоконнике, акварель"}}'

Ссылка на PNG (SVG для векторных стилей). Ссылка действует сутки и подписывается заново при каждом GET; файл хранится 30 дней.

Модель voicee/video. Видеоклип из промпта и/или текста готовой записи; первый кадр — ссылка, файл или результат voicee/image.

Цена: по секундам клипа, тариф HD или стандартный.

curl --request POST 'https://api.voicee.ru/v1/replicate/v1/models/voicee/video/predictions' \
  --header "Authorization: Bearer ${VOICEE_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"input": {"prompt": "рыжий кот прыгает на подоконник, солнечное утро", "duration_seconds": 5}}'

Ссылка на MP4. Ссылка действует сутки и подписывается заново при каждом GET; файл хранится 30 дней.