Πώς να πάρεις τη μεταγραφή του YouTube με ένα API (curl, Python, JavaScript)

Για να πάρεις τη μεταγραφή του YouTube με ένα API, στείλε ένα αίτημα HTTP με το URL ή το ID του βίντεο και ένα κλειδί API, και διάβασε τη μεταγραφή από την απάντηση. Αυτός ο οδηγός δείχνει το αίτημα σε curl, Python και JavaScript με το Transcript API του sum.video και μετά καλύπτει τις μορφές, τα σφάλματα και το κόστος.

Τι επιστρέφει το API

Το τελικό σημείο επιστρέφει τους υπάρχοντες υπότιτλους ενός δημόσιου βίντεο του YouTube, είτε γραμμένους από τον δημιουργό είτε παραγμένους αυτόματα από το YouTube. Δεν μεταγράφει ήχο. Αν ένα βίντεο δεν έχει υπότιτλους, παίρνεις σφάλμα αντί για εικασία (περισσότερα παρακάτω).

Τα βασικά:

• Τελικό σημείο: POST https://sum.video/api/v1/transcript (δουλεύει και το GET)
• Έλεγχος ταυτότητας: το κλειδί σου στην κεφαλίδα X-API-Key ή Authorization: Bearer <key>
• Είσοδος: url ή video_id
• Προαιρετικό lang (προεπιλογή en)
• Προαιρετικό format: json, text ή srt

Η απάντηση σού λέει επίσης την πραγματική γλώσσα του κομματιού υποτίτλων και αν παράχθηκε αυτόματα, ώστε να ξέρεις τι ποιότητα να περιμένεις.

Βήμα 1: Δημιούργησε ένα κλειδί API

Συνδέσου και δημιούργησε ένα κλειδί στον πίνακα ελέγχου του API (/dashboard/api στο sum.video). Μπορείς να έχεις έως 5 ενεργά κλειδιά, χρήσιμο για να ξεχωρίζεις ένα δοκιμαστικό από ένα παραγωγικό. Το πρώτο σου κλειδί έρχεται με 10 δωρεάν πιστώσεις, αρκετές για 5 μεταγραφές, οπότε μπορείς να δοκιμάσεις όλα τα παρακάτω χωρίς κόστος.

Βήμα 2: Κάνε το πρώτο σου αίτημα

curl

curl -X POST https://sum.video/api/v1/transcript \
  -H "X-API-Key: $SUMVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "lang": "en", "format": "text"}'

Επειδή δουλεύει και το GET, μπορείς να δοκιμάσεις από ένα σενάριο που απλώς φτιάχνει URL. Προτίμησε την κεφαλίδα για το κλειδί, ώστε να μην καταλήξει στα αρχεία καταγραφής.

Python

import os
import requests

resp = requests.post(
    "https://sum.video/api/v1/transcript",
    headers={"X-API-Key": os.environ["SUMVIDEO_API_KEY"]},
    json={"video_id": "dQw4w9WgXcQ", "lang": "en", "format": "text"},
    timeout=30,
)

if resp.status_code == 404:
    print("No captions for this video")
else:
    resp.raise_for_status()
    print(resp.text)

JavaScript (Node 18+ ή το πρόγραμμα περιήγησης)

const resp = await fetch("https://sum.video/api/v1/transcript", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SUMVIDEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_id: "dQw4w9WgXcQ",
    lang: "en",
    format: "text",
  }),
});

if (resp.status === 404) {
  console.log("No captions for this video");
} else if (!resp.ok) {
  throw new Error(`Request failed: ${resp.status}`);
} else {
  console.log(await resp.text());
}

Κράτα το κλειδί σε διακομιστή. Ένα κλειδί σε κώδικα προγράμματος περιήγησης μπορεί να αντιγραφεί από όποιον ανοίξει τα εργαλεία προγραμματιστή.

Βήμα 3: Διάλεξε τη σωστή μορφή

Αν σκοπεύεις να συνδέεις σε μια στιγμή του βίντεο, χρησιμοποίησε json και φτιάξε τον σύνδεσμο από το offset του τμήματος. Για να τροφοδοτήσεις ένα LLM, το text είναι μικρότερο και απλούστερο. Αν αργότερα θέλεις να ψάξεις χειροκίνητα μέσα σε μια μεταγραφή, δες πώς να ψάξεις μέσα στη μεταγραφή ενός βίντεο του YouTube.

Βήμα 4: Διάλεξε γλώσσα

Το lang είναι από προεπιλογή en. Όρισέ το στη γλώσσα που θέλεις, για παράδειγμα de ή es. Η απάντηση αναφέρει τη γλώσσα του κομματιού που επιστράφηκε πραγματικά, γι' αυτό έλεγξέ τη αντί να την υποθέτεις. Ένα βίντεο έχει συχνά μόνο ένα κομμάτι υποτίτλων και το API επιστρέφει πραγματικούς υπότιτλους, άρα δεν τους μεταφράζει για σένα.

Βήμα 5: Χειρίσου τα σφάλματα

Σχεδίασε για αυτές τις περιπτώσεις από την πρώτη μέρα:

• 404 no_transcript: το βίντεο δεν έχει υπότιτλους ή είναι ζωντανή μετάδοση, ιδιωτικό ή αφαιρεμένο βίντεο. Δεν υπάρχει κάτι να ξαναδοκιμάσεις. Παράλειψέ το ή ζήτα από τον χρήστη άλλο βίντεο.
• 402 budget_exceeded: έφτασες το μηνιαίο όριο πιστώσεων που όρισες. Δες την επόμενη ενότητα.
• Όριο ρυθμού: κάθε κλειδί επιτρέπει 60 αιτήματα ανά λεπτό. Απόστασε τις μαζικές εργασίες και μείωσε τον ρυθμό όταν σε περιορίζουν.
• Αποτυχίες από τη δική μας πλευρά: ξαναδοκίμασε μετά από μια μικρή καθυστέρηση. Δεν κοστίζουν τίποτα.

Ένας απλός βρόχος που ξαναδοκιμάζει σε σφάλματα διακομιστή και παραλείπει στο 404 καλύπτει τις περισσότερες ανάγκες παραγωγής.

Πόσο κοστίζει

Κάθε μεταγραφή κοστίζει 2 πιστώσεις. Τα αιτήματα που δεν επιστρέφουν μεταγραφή ή αποτυγχάνουν από την πλευρά του sum.video δεν κοστίζουν τίποτα, άρα ένα 404 δεν αδειάζει ποτέ το υπόλοιπό σου. Μπορείς να δεις το υπόλοιπό σου με GET /api/v1/credits.

Οι πιστώσεις πωλούνται σε εφάπαξ πακέτα που δεν λήγουν ποτέ:

Οι συνδρομητές Pro παίρνουν επίσης 100 πιστώσεις μπόνους κάθε μήνα. Για βαρύτερα φορτία, όπως η εισαγωγή ενός ολόκληρου καναλιού, διάβασε το σενάριο μεταγραφές YouTube για μια εφαρμογή RAG σε μεγάλη κλίμακα, που καλύπτει την αυτόματη ανανέωση και τους προϋπολογισμούς. Δες και τις τιμές.

Περιορισμοί που πρέπει να ξέρεις πριν χτίσεις

• Λειτουργούν μόνο τα βίντεο με υπότιτλους. Αυτός είναι ο κύριος λόγος του 404 no_transcript.
• Οι υπότιτλοι που παράγονται αυτόματα μπορεί να έχουν λάθη, ειδικά σε ονόματα, προφορές και τεχνικούς όρους.
• Το API επιστρέφει μόνο τη μεταγραφή. Δεν κάνει περίληψη. Αν θέλεις περιλήψεις, χρονοσφραγίδες και συνομιλία πάνω σε μια μεταγραφή, το κάνει ο συνοψιστής του YouTube, και το εργαλείο μεταγραφής είναι η έκδοση χωρίς κώδικα για ένα βίντεο.
• Το επίσημο YouTube Data API δεν αποτελεί υποκατάστατο εδώ. Η μέθοδος λήψης υποτίτλων απαιτεί άδεια επεξεργασίας του βίντεο, άρα προορίζεται για τα δικά σου βίντεο (τεκμηρίωση Google).

Πηγές

• YouTube Data API: Captions.download
• Transcript API του sum.video