API TranscritorAi

Все эндпоинты API: что делает каждый и нужен ли вход. Те же данные доступны и в автоматических форматах ниже.

Открыть в Swagger

Базовый URL совпадает с адресом самого сайта (тот же источник, отдельного домена для API нет).

Эндпоинты с пометкой «Нужен вход» ожидают заголовок Authorization: Bearer — тот же токен, который возвращают POST /api/auth/login или POST /api/auth/registrar. API использует ту же учётную запись, что и сайт: тариф, кредиты, история и хранилище общие.

Аккаунты с двухэтапной проверкой: POST /api/auth/login отвечает requer_2fa: true и desafio (вызов); отправьте вызов и 6-значный код на POST /api/auth/login/2fa, чтобы получить токен. На сайте сеанс хранится в HttpOnly-cookie; API для скриптов по-прежнему использует Authorization: Bearer.

Contabilização: cada arquivo ou link custa 1 crédito, descontado no envio (primeiro da cota mensal do plano, depois do saldo avulso). Vídeo custa 1 crédito a cada 5 min, áudio a cada 10 min e PDF/DOCX/TXT a cada 100 páginas. Falhas e cancelamentos devolvem os créditos; "pular" um arquivo já processado e reprocessar uma falha não cobram. Consulte GET /api/usuarios/eu/capacidade antes de enviar.

API для разработчиков (v1)

Используйте ключ API, чтобы делать расшифровку из вашей собственной системы. Создайте ключ в разделе «Мой аккаунт» на вкладке «Опции». Вызовы расходуют квоту кредитов тарифа API аккаунта, а результат появляется и в «Моих файлах».

Передавайте ключ в Authorization: Bearer tr_live_.... Он действует только на /api/v1: вход на сайте там не работает, а ключ не работает на остальных маршрутах API.

Обработка асинхронная: создание сразу отвечает с id и status: queued. Проверяйте ход через GET или получите вебхук по завершении. Текст приходит в result.text.

Пример: создать расшифровку

curl -X POST https://transcritorai.com/api/v1/transcriptions \
  -H "Authorization: Bearer tr_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"source": {"type": "url", "url": "https://exemplo.com/reuniao.mp4"}, "metadata": {"id": "123"}}'

# 202 Accepted
{"id": "...", "status": "queued", "metadata": {"id": "123"}, ...}

curl https://transcritorai.com/api/v1/transcriptions/ID -H "Authorization: Bearer tr_live_SUA_CHAVE"
# {"status": "completed", "result": {"text": "..."}, ...}

Каждое уведомление вебхука содержит заголовок X-Transcritor-Signature: t=...,v1=...: HMAC-SHA256 от t.тело с вашим секретом (whsec_..., вкладка «Опции» в «Моём аккаунте»). Проверяйте подпись и отклоняйте уведомления со старым t. Только публичные адреса https. Если ваша система не отвечает 2xx, мы повторяем до 4 раз; после этого проверяйте через GET.

Проверка подписи вебхука

import hashlib, hmac, time

def aviso_valido(segredo, cabecalho, corpo_bytes):
    partes = dict(p.split("=", 1) for p in cabecalho.split(","))
    esperado = hmac.new(segredo.encode(), partes["t"].encode() + b"." + corpo_bytes, hashlib.sha256).hexdigest()
    recente = abs(time.time() - int(partes["t"])) < 300
    return recente and hmac.compare_digest(esperado, partes["v1"])

Лимит запросов в минуту зависит от тарифа и действует на каждый ключ (ответ 429 с Retry-After). Квота кредитов исчерпана: ответ 402 cota_esgotada. Одна отправка за раз на аккаунт: если получили 409 envio_em_andamento, повторите через несколько секунд.

Тарифы API

У API своя квота, отдельная от квоты сайта. Кредиты те же, что и на сайте (1 кредит за файл или за каждые 5 минут видео), и обнуляются каждый месяц. Лимит запросов в минуту действует на каждый ключ. Глоссарии в API доступны начиная с Startup.

Startup и Business оформляются картой через Mercado Pago в разделе «Тарифы» (вкладка API), помесячно или на год (годовой стоит 10 месячных платежей). Тариф начинает действовать после одобрения платежа и продлевается сам с сохранённой карты; если продление отклонено более 3 дней, аккаунт возвращается на Developer. Отменить можно в любой момент на том же экране. Startup также входит в Комбо «Полный» + API. Enterprise — по запросу: напишите в поддержку.

Маршруты

  • POST /api/v1/transcriptions · POST /api/v1/transcriptions/upload: Создаёт расшифровку по адресу (JSON) или по файлу (multipart). Принимает glossary_id, webhook_url и metadata.
  • GET /api/v1/transcriptions/{id}: Статус (queued, processing, completed, failed, canceled) и, когда готово, текст в result.text.
  • GET /api/v1/transcriptions: Постраничный список расшифровок, сделанных через API, без текста.
  • DELETE /api/v1/transcriptions/{id}: Если идёт обработка, отменяет её; затем убирает из списка. Текст остаётся в «Моих файлах».
  • GET /api/v1/usage: Тариф, лимит месяца, израсходовано, осталось, дополнительные кредиты и лимит в минуту.
  • POST|GET /api/v1/webhooks · DELETE /api/v1/webhooks/{id} · GET /api/v1/webhooks/deliveries: Регистрирует адреса уведомлений (https) и показывает историю доставок.
  • GET|POST /api/v1/glossaries · GET|POST /api/v1/glossaries/{id}/terms: Глоссарии и термины пакетом (до 500 за вызов), чтобы верно распознавать имена и термины.
  • POST|GET /api/v1/transcriptions/{id}/studio: Режим студии через API: создаёт главы YouTube (chapters), шоу-ноты (show_notes) или хуки (hooks) для расшифровки с помощью ключа ИИ самого аккаунта. Расходует 5 кредитов API за набор (остальные продукты того же выпуска в месяце ничего не стоят) и сообщает через вебхуки (studio.completed и studio.failed). GET возвращает готовый набор.