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.
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 -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.
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.
{
"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.
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.
{
"platform": "youtube",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"source": "stt"
}Co sprawdzić przed ponowną próbą
Zacznij od kodu błędu. 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. 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, Instagrama 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. Nie pokazuj użytkownikowi ustawień, których dana platforma nie obsługuje.