SDK для Node.js

Пакет @transcript1/sdk берёт на себя загрузку файлов, создание задач и ожидание готового текста. Используйте его в серверном коде на TypeScript или JavaScript.

Ссылки из соцсетей поддерживаются начиная с SDK 1.1.0. В версии 1.0.1 работает только YouTube; другие ссылки SDK отклонит до обращения к API. Для обновления выполните npm i @transcript1/sdk@latest.

Версия 1.1.0 — минимальная для первых шести платформ. Для Twitch, Dailymotion, Pinterest, LinkedIn и Snapchat нужен релиз, в который уже добавлена соответствующая платформа. Старый SDK может отклонить такую ссылку, не отправляя запрос к API.

Установка

npm i @transcript1/sdk

Примеры написаны для ES-модулей: сохраните код в .mjs или добавьте "type": "module" в package.json, если используете .js. На Node 20.19+ можно также подключить пакет через require(): require('@transcript1/sdk').

API-ключ

Получите ключ на странице «API keys». Дальше либо задайте на сервере переменную TRANSCRIPT1_API_KEY, либо передайте ключ в конструктор через apiKey:

import { Transcript1 } from '@transcript1/sdk';
 
const t1 = new Transcript1(); // reads TRANSCRIPT1_API_KEY
const other = new Transcript1({ apiKey: 't1_...' });

Если ключа нет, конструктор выбросит Transcript1Error с code=missing_api_key.

Как получить транскрипт

Вызовите transcribe(input, options), чтобы создать задачу и дождаться текста. При успехе вы получите CompletedTranscription: status: 'completed' и поле transcript. Если задача завершилась с ошибкой или её отменили, промис отклоняется.

const done = await t1.transcribe('https://youtu.be/dQw4w9WgXcQ');
console.log(done.transcript.text);
 
const file = await t1.transcribe('./interview.m4a', { speakers: true });

При передаче Buffer или Uint8Array обязательно укажите имя файла. По нему SDK определяет формат записи:

import { readFile } from 'node:fs/promises';
 
const buffer = await readFile('./call.mp3');
const call = await t1.transcribe(buffer, { filename: 'call.mp3' });

Если строка начинается с http:// или https://, SDK примет её за ссылку. Любая другая строка — путь к файлу. Поддерживаются YouTube, X, TikTok, Instagram, Facebook, Bluesky, Twitch, Dailymotion, Pinterest, LinkedIn, Snapchat и загрузка своих файлов. Для дополнительных платформ нужен HTTPS. Форматы ссылок на публичные записи, поддержка субтитров и ограничения описаны в разделе «Источники и параметры».

Размер файла — до 2 000 000 000 байт. Допустимые расширения: mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm и mkv.

Нужен публичный пост. Если в нём несколько роликов, расшифруем первый. Платформу определит API по ссылке; подходящие короткие ссылки перечислены в разделе «Источники и параметры».

Можно передать и Blob, ReadableStream<Uint8Array> или асинхронный итерируемый объект, который выдаёт части Uint8Array. Для Blob укажите filename; исключение — File, у которого уже есть имя. Для потоков и асинхронных итерируемых объектов обязательны оба поля: filename и size в байтах.

Текст и файлы субтитров

Чтобы получить нужный формат, вызовите download(id, options). Метод дождётся завершения задачи и вернёт строку. Для JSON это тоже строка с ответом API, а не готовый объект.

const text = await t1.download(done.id); // text is the default
const withTimes = await t1.download(done.id, { timestamps: true });
const srt = await t1.download(done.id, { format: 'srt' });
const vtt = await t1.download(done.id, { format: 'vtt' });
const json = await t1.download(done.id, { format: 'json' });

Параметр timestamps: true доступен только для text. С другим форматом промис отклоняется с invalid_input. Ошибка или отмена задачи также приводит к отклонению промиса download.

Запуск без ожидания транскрипта

Если текст пока не нужен, создайте задачу через transcriptions.create. Метод не ждёт транскрипта, но для файла сначала полностью завершает загрузку.

const job = await t1.transcriptions.create('./long-interview.mp4');
const now = await t1.transcriptions.get(job.id);
const finished = await t1.transcriptions.get(job.id, { wait: true });

Вызов get без wait сразу вернёт текущее состояние. С wait: true он подождёт статуса completed, failed или canceled. Прежде чем обращаться к тексту, проверьте finished.status: в отличие от transcribe, промис get не отклоняется при ошибке или отмене самой задачи.

Список задач, удаление и баланс

for await (const item of t1.transcriptions.list({ status: 'completed', limit: 50 })) {
  console.log(item.id, item.created_at);
}
 
await t1.transcriptions.delete(job.id);
const account = await t1.account();
console.log(account.minutes.remaining);

Метод list сам запрашивает следующую страницу по мере обхода списка. Можно фильтровать задачи по status и platform: youtube, x, tiktok, instagram, facebook, bluesky, twitch, dailymotion, pinterest, linkedin, snapchat или upload. Размер страницы задаёт limit — от 1 до 100, по умолчанию в API 20. Поля в объектах сохраняют исходные имена API в snake_case. Значение media_id храните как есть, не пытаясь разобрать строку.

Через delete можно отменить текущую задачу или удалить завершённую вместе с текстом. Метод account покажет тариф, остаток минут и лимиты.

Параметры

В конструктор можно передать apiKey, baseUrl, fetch и maxRetries. Если baseUrl не указан, SDK возьмёт адрес из TRANSCRIPT1_API_URL, а при отсутствии переменной — https://api.transcript1.com. Для своей реализации запросов передайте fetch. Число повторов maxRetries по умолчанию равно 2; допустимы целые значения от 0 до 10.

Для transcribe и transcriptions.create доступны одинаковые параметры:

Метод transcriptions.get принимает wait, includeWords, onProgress и signal. Для пословных временных меток передайте includeWords: true. Обработчик onProgress будет сообщать об изменениях, пока метод ждёт завершения.

У download есть format, timestamps и signal; у list также можно указать signal. Для transcriptions.delete(id, options) и account(options) передайте { signal } в аргументе параметров.

Как следить за прогрессом

Добавьте обработчик onProgress в transcribe, transcriptions.create или transcriptions.get с ожиданием:

await t1.transcribe('./interview.m4a', {
  onProgress(event) {
    console.log(event);
  },
});

Как отменить вызов

Для отмены используйте AbortSignal из AbortController. Если нужен таймаут, подойдёт AbortSignal.timeout:

await t1.transcribe('https://youtu.be/dQw4w9WgXcQ', {
  signal: AbortSignal.timeout(10 * 60_000),
});

При отмене до первого запроса промис отклоняется с aborted, без ID задачи. Если отменить вызов во время загрузки, SDK попытается удалить задачу, пока она ещё в awaiting_upload. После этого промис отклоняется с aborted и ID.

Отмена ожидания не останавливает транскрибацию. Чтобы снова дождаться текста, возьмите transcriptionId из ошибки и вызовите transcriptions.get(id, { wait: true }). Если нужно остановить саму задачу, используйте transcriptions.delete(id).

Во время ожидания SDK повторяет запросы при сетевых ошибках и HTTP 429, 500, 502, 503, 504 без ограничения числа попыток. Паузы растут: 2, 4, 8, 16, затем 30 секунд. Для остальных запросов действует maxRetries. Если при создании задачи все места заняты, SDK тоже подождёт и попробует снова. Ограничить общее время вызова можно через signal.

Ошибки

Ошибки API, транскрибации и самого SDK доступны через Transcript1Error:

import { Transcript1Error } from '@transcript1/sdk';
 
try {
  await t1.transcribe('./call.mp3');
} catch (error) {
  if (error instanceof Transcript1Error) {
    console.error(error.code, error.message, error.transcriptionId);
  }
}

Собственные коды SDK: missing_api_key, invalid_input, aborted, network_error и upload_token_refused. Если сервер вернул ошибку не в JSON, код будет http_<status>.

Если задача завершилась с ошибкой, но без объекта error, SDK использует transcription_failed. Если задача завершилась успешно, а после запроса текста поле транскрипта так и не появилось, промис transcribe отклоняется с internal_error. Коды API разобраны в разделе «Ошибки», поля ответов — в справочнике API.

Где работает SDK

Нужен Node 20.19+. Bun и Deno должны работать благодаря совместимости с node:, но автоматические тесты мы запускаем только на Node. SDK предназначен для сервера. Не включайте API-ключ в браузерный код.