# YouTube Transcript API do filmów z napisami i bez

> YouTube Transcript API zwraca JSON, tekst, SRT lub VTT z linku. Korzysta z napisów, a gdy ich brak, z AI. 1 kredyt za minutę.

Canonical: https://transcript1.com/pl/features/youtube-transcript-api
Language: pl
Last updated: 2026-10-19

YouTube Transcript API w transcript1 przyjmuje link do filmu i zwraca JSON, tekst, SRT lub VTT. Najpierw sprawdzamy napisy. Jeśli nie da się z nich skorzystać, AI przepisuje dźwięk.

- Najpierw napisy, a jeśli ich brakuje, transkrypcja AI
- Napisy i AI w tej samej cenie: 1 kredyt za minutę
- Linki watch, youtu.be, Shorts i embed

## Wybierz, skąd ma pochodzić tekst

### Nie musisz przerabiać linków

Przyjmujemy linki watch, youtu.be, Shorts, embed i /live/, z www lub bez. Rozpoznajemy po nich konkretny film. Aktywnej transmisji na żywo nie przepiszemy.

### Pierwszeństwo mają napisy twórcy

Przy source=auto wybieramy najpierw napisy dodane przez twórcę, potem generowane automatycznie. Nie korzystamy ze ścieżek przetłumaczonych automatycznie.

### Bez napisów też dostaniesz tekst

Jeśli nie ma pasującej ścieżki napisów, przepisujemy dźwięk. Ustaw source=stt, jeśli zawsze chcesz transkrypcję audio, nawet gdy film ma napisy.

### Wiesz, skąd pochodzi transkrypcja

Sprawdź pole transcript_source. Wartość youtube_captions oznacza napisy z YouTube, a speech_to_text transkrypcję dźwięku.

### Rozliczamy długość filmu

Za każdą rozpoczętą minutę nagrania zużywasz 1 kredyt, niezależnie od źródła tekstu. Jeśli transkrypcja się nie uda albo ją anulujesz, nic nie płacisz.

## Wyślij link do filmu

Wyślij POST z linkiem i kluczem API. Możesz użyć Pythona lub dowolnego klienta HTTP. Parametr wait=60 pozwala poczekać na transkrypcję w tym samym requeście do 60 sekund. [Sprawdź pola i kody odpowiedzi](https://transcript1.com/pl/docs/api-reference#create-a-transcription).

Utwórz klucz w panelu i użyj go w swoim skrypcie lub na serwerze. Gdy API przyjmie request, od razu zapisz ID transkrypcji.

Jeśli po czasie oczekiwania transkrypcja nadal trwa, nie wysyłaj linku ponownie. Sprawdź ją przez GET /v1/transcriptions/:id. Zakończenie requestu nie przerywa przetwarzania.

Obsłuż osobno statusy queued, fetching i transcribing. Dopiero completed oznacza, że możesz czytać tekst. Przy failed odczytaj błąd. Opóźnienie połączenia czy niedostępny film nie powinny wyglądać w twojej aplikacji jak gotowa, pusta transkrypcja.

### cURL

```
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"}'
```

## Sprawdź źródło w transcript\_source

W odpowiedzi znajdziesz źródło tekstu, rodzaj napisów i billed_minutes, czyli długość filmu zaokrągloną w górę do pełnych minut. [Sprawdź wszystkie pola transkrypcji](https://transcript1.com/pl/docs/api-reference#the-transcription-object).

Zachowaj transcript_source i caption_kind, jeśli twoja aplikacja ma pokazywać, skąd pochodzi tekst. Przy napisach twórcy zachowujemy opublikowane brzmienie, ale nie dostajesz czasów pojedynczych słów.

Automatyczne napisy YouTube podają początki słów. Transkrypcja AI ma początek i koniec każdego słowa oraz confidence. Dodaj include=words przy pobieraniu JSON tylko wtedy, gdy potrzebujesz tych danych.

Segmenty mają początek i koniec w sekundach. Możesz powiązać tekst z odtwarzaczem, dopisać czas do notatki albo przekazać asystentowi właściwy fragment nagrania.

Poniższy JSON pokazuje strukturę odpowiedzi. Tekst w nim jest przykładowy, nie pochodzi z filmu użytego w requeście.

### Skrócona odpowiedź JSON

```
{
  "id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
  "status": "completed",
  "transcript_source": "youtube_captions",
  "caption_kind": "auto_generated",
  "language": "en",
  "billed_minutes": 4,
  "transcript": {
    "text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
    "segments": [
      { "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." }
    ]
  }
}
```

## Wybierz napisy albo transkrypcję audio

Domyślnie source ma wartość auto. Tryb captions (tylko napisy) zwróci no_captions bez opłaty, jeśli nie znajdziemy pasującej ścieżki. Tryb stt zawsze przepisuje dźwięk. [Sprawdź, jak łączyć ustawienia](https://transcript1.com/pl/docs/sources-and-options#source).

Wybierz captions, gdy zależy ci na napisach opublikowanych przy filmie. Ustaw stt, jeśli potrzebujesz nowej transkrypcji audio albo podziału na rozmówców.

Przy source=auto opcja diarize=true od razu kieruje nagranie do transkrypcji AI. Nie można połączyć diarize=true z source=captions. API odrzuci taki request zamiast pominąć jedną z opcji.

Napisy muszą pasować do wskazanego języka, a przy automatycznym wyborze do oryginalnego języka filmu. Nie pobieramy automatycznych tłumaczeń. Podpowiedź języka dla AI też nie tłumaczy nagrania.

### Treść requestu z source=stt

```
{
  "platform": "youtube",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "source": "stt"
}
```

## Co sprawdzić przed ponowną próbą

Zacznij od [kodu błędu](https://transcript1.com/pl/docs/errors). Ponowienie requestu nie udostępni prywatnego filmu, nie usunie ograniczenia wiekowego ani nie zakończy transmisji na żywo. Przy no_captions zdecyduj, czy możesz skorzystać z transkrypcji audio. Jeśli przetwarzanie jeszcze trwa, sprawdzaj zapisane ID.

Gdy musisz ponowić request tworzący transkrypcję, użyj [Idempotency-Key](https://transcript1.com/pl/docs/api-reference#idempotency). Ponowne użycie wcześniejszej transkrypcji to osobna opcja, która dopasowuje film i ustawienia. Sam fakt, że tekst jest w cache, nie oznacza braku opłaty za nowe zlecenie. Czytanie istniejącej, gotowej transkrypcji nie zużywa minut.

Ten sam endpoint przyjmie też linki z [TikToka](https://transcript1.com/pl/features/transkrypcja-tiktok), [Instagrama](https://transcript1.com/pl/features/transkrypcja-instagram) i innych obsługiwanych platform. Na YouTube, X, TikToku czy Bluesky tryb auto może sięgnąć najpierw po napisy, a w razie potrzeby po audio.

Sprawdzaj dozwolone kombinacje źródła i opcji według [tabeli w dokumentacji](https://transcript1.com/pl/docs/sources-and-options). Nie pokazuj użytkownikowi ustawień, których dana platforma nie obsługuje.

## Najczęstsze pytania

### Zadziała, jeśli film nie ma napisów?

Tak. Przy domyślnym source=auto przepisujemy dźwięk, jeśli nie ma pasujących napisów. Ustaw source=captions, jeżeli w takiej sytuacji wolisz dostać błąd zamiast uruchamiać AI.

### Jakie linki z YouTube mogę wysłać?

Linki watch, youtu.be, Shorts, embed i /live/. Muszą wskazywać konkretny film. Sam kanał lub playlista zwrócą 422 invalid_url. Link /live/ rozpoznaje film, ale aktywnej transmisji nie przepiszemy.

### A co z prywatnym filmem?

Pobierzemy film publiczny lub niepubliczny dostępny pod linkiem. Filmy prywatne, z ograniczeniem wiekowym i aktywne transmisje nie zadziałają. Jeśli masz własne nagranie, wrzuć plik.

### Ile kosztuje jedna transkrypcja?

Zużywasz 1 kredyt za każdą rozpoczętą minutę filmu, zarówno przy napisach, jak i AI. Na nowym koncie dostajesz jednorazowo 60 minut za darmo po potwierdzeniu e-maila. Bez karty.

### To ta sama biblioteka co youtube-transcript-api w Pythonie?

Nie. transcript1 to REST API działające na naszym serwerze. Z Pythona wywołasz je requestem HTTP ze swoim kluczem API.

## Sprawdź też

- [Czasy i napisy SRT/VTT](https://transcript1.com/pl/features/jak-stworzyc-plik-srt)
- [Pliki przez API](https://transcript1.com/pl/features/speech-to-text-api)
- [Webhooki](https://transcript1.com/pl/features/webhook-transkrypcja)
- [Nowe treści z nagrań](https://transcript1.com/pl/use-cases/zamiana-wideo-na-artykul-blogowy)