Transkrypcje w Node.js z SDK

Zainstaluj @transcript1/sdk, żeby zlecać transkrypcje i wysyłać pliki z kodu TypeScript lub JavaScript na serwerze. SDK może też poczekać, aż tekst będzie gotowy.

Do linków z social mediów potrzebujesz SDK 1.1.0 lub nowszego. Wersja 1.0.1 przyjmuje tylko linki z YouTube, a pozostałe odrzuca przed wysłaniem do API. Zaktualizuj pakiet przez npm i @transcript1/sdk@latest.

Wersja 1.1.0 obsługuje pierwsze sześć platform. Twitch, Dailymotion, Pinterest, LinkedIn i Snapchat wymagają wydania SDK, które już je obsługuje. Starsza wersja może odrzucić taki link, zanim wyśle go do API.

Instalacja

npm i @transcript1/sdk

Przykłady korzystają z modułów ES. Zapisz je w plikach .mjs. Jeśli używasz .js, dodaj "type": "module" w package.json. Na Node 20.19+ możesz też użyć require(), na przykład require('@transcript1/sdk').

Klucz API

Utwórz klucz w panelu na stronie „API keys”. Na serwerze ustaw zmienną TRANSCRIPT1_API_KEY lub podaj klucz w opcji apiKey konstruktora:

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

Jeśli nie podasz klucza, konstruktor rzuci Transcript1Error z kodem missing_api_key.

Jak zlecić transkrypcję

Wywołaj transcribe(input, options), żeby zlecić transkrypcję i poczekać na tekst. Dostaniesz CompletedTranscription z status: 'completed' i polem transcript. Jeśli transkrypcja się nie uda albo ją anulujesz, zwracany promise zostaje odrzucony.

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

Gdy przekazujesz Buffer lub Uint8Array, dodaj nazwę pliku. SDK rozpoznaje po niej typ nagrania:

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

SDK traktuje string zaczynający się od http:// lub https:// jako link. Każdy inny string to ścieżka do pliku. Możesz podać link z YouTube, X, TikToka, Instagrama, Facebooka, Bluesky, Twitcha, Dailymotion, Pinteresta, LinkedIn lub Snapchata albo wysłać własny plik. W opisie źródeł i opcji sprawdzisz, jakie publiczne nagrania i napisy obsługujemy oraz jakie są ograniczenia. Dodatkowe platformy wymagają HTTPS. Plik może mieć do 2 000 000 000 bajtów i rozszerzenie mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm lub mkv.

Post z social mediów musi być publiczny. Jeśli zawiera kilka filmów, przepiszemy tylko pierwszy. API samo rozpoznaje platformę z adresu. Sprawdź, które krótkie linki działają i jakie mają limity.

Możesz też przekazać Blob, ReadableStream<Uint8Array> lub obiekt do asynchronicznej iteracji, który zwraca fragmenty Uint8Array. Dla Blob podaj filename, chyba że przekazujesz obiekt File z nazwą. Przy strumieniach i asynchronicznej iteracji musisz podać zarówno filename, jak i size w bajtach.

Jak pobrać tekst lub napisy

Użyj download(id, options), żeby poczekać na gotową transkrypcję i pobrać ją jako string. Przy formacie JSON też dostajesz tekst odpowiedzi API, nie sparsowany obiekt.

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' });

Opcja timestamps: true działa tylko z text. Przy innym formacie promise zostaje odrzucony z kodem invalid_input. Jeśli transkrypcja się nie uda albo ją anulujesz, promise zwracany przez download też zostaje odrzucony.

Zleć teraz, odbierz później

Metoda transcriptions.create pozwala zlecić transkrypcję bez czekania na gotowy tekst. Jeśli podasz plik, poczeka na zakończenie uploadu i dopiero wtedy zwróci obiekt zadania.

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 });

Bez wait metoda get od razu zwraca bieżący stan. Ustaw wait: true, żeby poczekać na status completed, failed lub canceled. Zanim odczytasz tekst, sprawdź finished.status. Nawet jeśli transkrypcja się nie uda lub ją anulujesz, promise zwracany przez get nie zostaje odrzucony. To różnica względem transcribe.

Historia transkrypcji i dane konta

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);

Podczas iteracji list samo pobiera kolejne strony. Możesz filtrować po status lub platform (youtube, x, tiktok, instagram, facebook, bluesky, twitch, dailymotion, pinterest, linkedin, snapchat albo upload). Opcja limit określa rozmiar strony: od 1 do 100, domyślnie 20 w API. Nazwy pól pozostają w snake_case, tak jak w API. Nie interpretuj zawartości media_id; traktuj ją jako identyfikator tekstowy.

Wywołaj delete, żeby anulować trwającą transkrypcję lub usunąć zakończone zadanie razem z tekstem. Przez account sprawdzisz plan, minuty i limity konta.

Opcje

W konstruktorze możesz podać apiKey, baseUrl, fetch i maxRetries. Bez baseUrl SDK sprawdza zmienną TRANSCRIPT1_API_URL, a jeśli jej nie ma, korzysta z https://api.transcript1.com. Opcja fetch pozwala podstawić własną implementację. Dla maxRetries podaj liczbę całkowitą od 0 do 10; domyślna wartość to 2.

Przy wywołaniu transcribe lub transcriptions.create możesz użyć tych samych opcji:

W transcriptions.get możesz podać wait, includeWords, onProgress i signal. Ustaw includeWords: true, żeby pobrać czasy poszczególnych słów. Callback onProgress informuje o zmianach, gdy czekasz na zakończenie.

Metoda download obsługuje format, timestamps i signal. W list też możesz użyć signal. Dla transcriptions.delete(id, options) i account(options) przekaż { signal } w argumencie opcji.

Jak śledzić postęp

Dodaj callback onProgress do transcribe, transcriptions.create lub do transcriptions.get, jeśli czekasz w nim na zakończenie:

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

Jak przerwać wywołanie

Żeby móc przerwać wywołanie, przekaż AbortSignal z AbortController. Możesz też ustawić limit czasu przez AbortSignal.timeout:

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

Jeśli przerwiesz wywołanie przed pierwszym requestem, promise zostaje odrzucony z kodem aborted, bez ID zadania. Podczas uploadu SDK najpierw próbuje usunąć zadanie, o ile nadal ma ono status awaiting_upload. Następnie promise zostaje odrzucony z kodem aborted i ID zadania.

Samo przerwanie oczekiwania nie zatrzymuje transkrypcji. Weź transcriptionId z błędu i wywołaj transcriptions.get(id, { wait: true }), żeby znów na nią poczekać. Jeśli chcesz anulować transkrypcję, użyj transcriptions.delete(id).

Gdy czekasz na transkrypcję, SDK ponawia połączenie po błędach sieci oraz HTTP 429, 500, 502, 503 i 504 bez limitu prób. Przerwy trwają kolejno 2, 4, 8, 16 i potem 30 sekund. Pozostałe requesty podlegają maxRetries. Przy tworzeniu zadania SDK czeka i próbuje ponownie, jeśli wszystkie miejsca na aktywne transkrypcje są zajęte. Użyj signal, żeby ograniczyć całkowity czas wywołania.

Błędy

Przechwyć Transcript1Error, żeby rozróżnić błędy API, transkrypcji i samego SDK:

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 używa lokalnych kodów missing_api_key, invalid_input, aborted, network_error i upload_token_refused. Gdy odpowiedź z błędem nie jest JSON-em, dostaniesz kod http_<status>.

Jeśli zadanie się nie uda, ale nie zawiera obiektu błędu, SDK zwróci transcription_failed. Jeśli po pobraniu zakończonego zadania brakuje w nim transkrypcji, promise zwracany przez transcribe zostaje odrzucony z kodem internal_error. Sprawdź kody błędów API i opis pól odpowiedzi.

Gdzie uruchomisz SDK

SDK wymaga Node 20.19+. Powinno też działać w Bun i Deno dzięki obsłudze node:, ale automatycznie testujemy tylko Node. Uruchamiaj SDK wyłącznie na serwerze. Nigdy nie wysyłaj klucza API do przeglądarki.