# Transkrypcje w Node.js z SDK > Zlecaj transkrypcje linków i plików przez @transcript1/sdk. Pobieraj tekst lub napisy, sprawdzaj postęp i obsługuj błędy na serwerze. Canonical: https://transcript1.com/pl/docs/sdk Language: pl Last updated: 2026-10-16 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 ```bash 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”](https://transcript1.com/dashboard/account/tokens). Na serwerze ustaw zmienną `TRANSCRIPT1_API_KEY` lub podaj klucz w opcji `apiKey` konstruktora: ```javascript 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. ```javascript 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: ```javascript 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](https://transcript1.com/pl/docs/sources-and-options) 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](https://transcript1.com/pl/docs/sources-and-options). Możesz też przekazać Blob, `ReadableStream` 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. ```javascript 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. ```javascript 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 ```javascript 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: | Opcja | Znaczenie | |---|---| | `speakers` | Włącza podział na rozmówców. | | `language` | Zostaw domyślne `auto` lub podaj kod języka ISO 639-1. | | `source` | Dla linków wybierz `auto` lub `stt`. Na YouTube, X, TikToku, Bluesky, Dailymotion i LinkedIn możesz też użyć `captions`, jeśli da się pobrać odpowiednie napisy. | | `fresh` | Zleca nową transkrypcję linku zamiast korzystać z wcześniejszej z ostatnich 24 godzin. | | `filename` | Nazwa pliku, obowiązkowa dla Buffer, Blob bez nazwy i strumieni. Możesz nią też zastąpić obecną nazwę pliku. | | `size` | Rozmiar w bajtach, obowiązkowy przy strumieniach i asynchronicznej iteracji. | | `idempotencyKey` | Jeśli nie podasz, SDK wygeneruje nowy UUID przy każdym wywołaniu. | | `onProgress` | Callback ze zdarzeniami informującymi o postępie. | | `signal` | Przekaż AbortSignal, żeby móc przerwać wywołanie. | 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: ```javascript await t1.transcribe('./interview.m4a', { onProgress(event) { console.log(event); }, }); ``` | Typ zdarzenia | Pola | |---|---| | `upload` | `sent` i `total`: ile bajtów wysłano i ile jest do wysłania łącznie. | | `status` | `status`: aktualny status transkrypcji. | | `waiting_slot` | `retryAfter`: ile sekund SDK odczeka przed kolejną próbą uruchomienia zadania. | | `reconnecting` | Bez dodatkowych pól. Pojawia się raz na każdą przerwę w połączeniu podczas oczekiwania. | ## Jak przerwać wywołanie Żeby móc przerwać wywołanie, przekaż `AbortSignal` z AbortController. Możesz też ustawić limit czasu przez `AbortSignal.timeout`: ```javascript 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: ```javascript 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); } } ``` | Pole | Znaczenie | |---|---| | `message` | Komunikat opisujący błąd. | | `code` | Kod błędu API, błędu transkrypcji, `canceled` lub lokalnego błędu SDK. | | `status` | Status HTTP. Nie ma go przy błędach transkrypcji i błędach lokalnych. | | `details` | Dodatkowe dane z API, np. `minutes_needed` lub `action_url`. Domyślnie pusty obiekt. | | `retryable` | Informacja, czy warto spróbować ponownie. Domyślnie false. | | `transcriptionId` | ID zadania, o ile SDK już je zna. | | `transcription` | Ostatni dostępny obiekt transkrypcji. | 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_`. 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](https://transcript1.com/pl/docs/errors) i [opis pól odpowiedzi](https://transcript1.com/pl/docs/api-reference). ## 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.