HTTP API

Три запроса — и текст в вашей системе

Отправить файл, дождаться готовности, забрать текст с разбивкой по голосам. Ничего, кроме HTTP и multipart-формы: ни SDK, ни вебхуков.

Как получить ключ

1. 1 Войдите в кабинет через бота в MAX или Telegram.
2. 2 Откройте вкладку API и нажмите «Включить доступ по API».
3. 3 Ключ и остаток минут появятся там же. Перевыпуск — старый сразу перестаёт работать.

На старте — 120 бесплатных минут. Ключ — это и есть ваш клиент: по нему считается расход и разделяются задачи. Не публикуйте его в репозиториях и чатах. Работа по API — акцепт публичной оферты; хранение задач API описано в её п. 7.6.4.

1. Отправить запись

POST /transcriptions — multipart-форма.

curl -s -X POST https://vtexte.ru/transcriptions \
  -H "X-API-Key: $KEY" \
  -F file=@call.mp3 \
  -F priority=normal

Ответ

{
  "id": "7c1f…",
  "status": "queued",
  "priority": 5,
  "priority_name": "normal",
  "status_url": "/transcriptions/7c1f…",
  "result_url": "/transcriptions/7c1f…/result"
}

Поля формы

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

2. Дождаться готовности

GET /transcriptions/{id}

curl -s https://vtexte.ru/transcriptions/$ID -H "X-API-Key: $KEY"
# {"id":"7c1f…","status":"running", …}
# готово:
# {"id":"7c1f…","status":"done","audio_seconds":302.4, …}

Статусы: queued → running → done либо failed (в failed есть поле error). Опрашивайте раз в 2–5 секунд, не чаще.

Ориентир по времени: двухминутный звонок — несколько секунд, стоминутное совещание — две-три минуты. Вебхуков пока нет, только опрос.

3. Забрать текст

GET /transcriptions/{id}/result.txt — готовый текст; GET /transcriptions/{id}/result — тот же текст файлом Markdown.

curl -s https://vtexte.ru/transcriptions/$ID/result.txt -H "X-API-Key: $KEY"

Формат — построчно, время от начала записи

[00:04-00:11] SPEAKER_00: Давайте начнём с отгрузок за прошлую неделю.
[00:11-00:26] SPEAKER_01: По складу всё закрыто, кроме двух заказов.

Задачу читает только тот ключ, которым она создана: чужой идентификатор отвечает 404, как несуществующий. Создавайте и опрашивайте задачи одним ключом.

Служебное

Лимиты

Лимит очереди — предохранитель от взбесившегося клиента, а не квота: при превышении приходит 429 с заголовком Retry-After, достаточно подождать и повторить.

Коды ошибок

Перегрузка отвечает 429, а не 500: 5xx означает нашу поломку, и о ней стоит нам сообщить.

Пример целиком, Python

import time, requests

BASE, KEY = "https://vtexte.ru", "ваш ключ"
headers = {"X-API-Key": KEY}

with open("meeting.m4a", "rb") as f:
    r = requests.post(f"{BASE}/transcriptions", headers=headers,
                      data={"priority": "express"},
                      files={"file": f}, timeout=120)
if r.status_code == 429:                      # очередь переполнена
    time.sleep(int(r.headers.get("Retry-After", 60)))
r.raise_for_status()
job_id = r.json()["id"]

while True:
    state = requests.get(f"{BASE}/transcriptions/{job_id}",
                         headers=headers, timeout=30).json()
    if state["status"] in ("done", "failed"):
        break
    time.sleep(3)

if state["status"] == "failed":
    raise RuntimeError(state.get("error"))

text = requests.get(f"{BASE}/transcriptions/{job_id}/result.txt",
                    headers=headers, timeout=60).text
print(text)