Cách lấy transcript YouTube bằng API (curl, Python, JavaScript)

Để lấy transcript YouTube bằng API, bạn gửi một yêu cầu HTTP kèm URL hoặc ID video và khóa API, rồi đọc transcript trong phản hồi. Hướng dẫn này cho thấy yêu cầu bằng curl, Python và JavaScript với API transcript của sum.video, sau đó giải thích các định dạng, lỗi và chi phí.

API trả về gì

Endpoint trả về phụ đề hiện có của một video YouTube công khai, dù do người tạo viết hay do YouTube tự động tạo. Nó không chuyển giọng nói thành văn bản. Nếu video không có phụ đề, bạn nhận lỗi thay vì một phỏng đoán (xem thêm bên dưới).

Những điều cơ bản:

• Endpoint: POST https://sum.video/api/v1/transcript (GET cũng dùng được)
• Xác thực: khóa của bạn trong header X-API-Key, hoặc Authorization: Bearer <key>
• Đầu vào: url hoặc video_id
• lang tùy chọn (mặc định en)
• format tùy chọn: json, text hoặc srt

Phản hồi cho biết ngôn ngữ thật của bản phụ đề và liệu nó có được tạo tự động hay không, để bạn biết nên kỳ vọng chất lượng ra sao.

Bước 1: tạo khóa API

Đăng nhập và tạo một khóa trong bảng điều khiển API (/dashboard/api trên sum.video). Bạn có thể giữ tối đa 5 khóa đang hoạt động, tiện để tách khóa thử nghiệm với khóa thật. Khóa đầu tiên của bạn đi kèm 10 tín dụng miễn phí, đủ cho 5 transcript, nên bạn có thể thử mọi thứ bên dưới mà không tốn gì.

Bước 2: gửi yêu cầu đầu tiên

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"}'

Vì GET cũng dùng được, bạn có thể thử cả từ một script chỉ dựng URL. Nên gửi khóa trong header để nó không lọt vào log.

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+ hoặc trình duyệt)

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

Hãy giữ khóa ở phía máy chủ. Khóa nằm trong mã trình duyệt có thể bị bất kỳ ai mở công cụ nhà phát triển sao chép.

Bước 3: chọn đúng định dạng

Nếu bạn định liên kết tới một thời điểm trong video, hãy dùng json và dựng liên kết từ offset của đoạn. Để đưa cho LLM thì text ngắn và đơn giản hơn. Nếu sau này muốn tìm thủ công trong transcript, hãy xem cách tìm trong transcript của video YouTube.

Bước 4: chọn ngôn ngữ

lang mặc định là en. Đặt ngôn ngữ bạn muốn, như de hoặc es. Phản hồi cho biết ngôn ngữ của bản phụ đề thực sự được trả về, nên hãy kiểm tra thay vì giả định. Một video thường chỉ có một bản phụ đề, và API trả về phụ đề thật, nên nó không dịch giúp bạn.

Bước 5: xử lý lỗi

Hãy lên kế hoạch cho các tình huống này từ ngày đầu:

• 404 no_transcript: video không có phụ đề, hoặc là phát trực tiếp, video riêng tư hay đã gỡ. Không có gì để thử lại. Bỏ qua nó hoặc nhờ người dùng chọn video khác.
• 402 budget_exceeded: bạn đã chạm giới hạn tín dụng hằng tháng mình đặt. Xem phần tiếp theo.
• Giới hạn tốc độ: mỗi khóa cho phép 60 yêu cầu mỗi phút. Hãy dàn trải công việc theo lô và chậm lại khi bị giới hạn.
• Lỗi từ phía chúng tôi: thử lại sau ít phút. Chúng không tốn phí.

Một vòng lặp đơn giản thử lại khi máy chủ lỗi và bỏ qua khi gặp 404 đáp ứng phần lớn nhu cầu thực tế.

Chi phí bao nhiêu

Mỗi transcript tốn 2 tín dụng. Các yêu cầu không trả về transcript hoặc lỗi từ phía sum.video không tốn phí, nên 404 không bao giờ làm cạn số dư của bạn. Xem số dư bằng GET /api/v1/credits.

Tín dụng được bán theo gói mua một lần, không bao giờ hết hạn:

Người đăng ký Pro còn nhận thêm 100 tín dụng thưởng mỗi tháng. Với tác vụ nặng như nhập cả một kênh, hãy đọc tình huống transcript YouTube cho ứng dụng RAG quy mô lớn, có đề cập nạp tự động và ngân sách. Xem thêm bảng giá.

Những giới hạn cần biết trước khi xây

• Chỉ video có phụ đề mới dùng được. Đây là nguyên nhân chính của 404 no_transcript.
• Phụ đề tự động có thể có lỗi, nhất là với tên riêng, giọng vùng miền và thuật ngữ chuyên ngành.
• API chỉ trả về transcript. Nó không tạo bản tóm tắt. Nếu bạn cần tóm tắt, dấu thời gian và trò chuyện về transcript, công cụ tóm tắt YouTube làm được, còn công cụ transcript là phiên bản không cần code cho một video.
• YouTube Data API chính thức không thay thế được ở đây. Cách tải phụ đề của nó đòi quyền chỉnh sửa video, nên dành cho video của chính bạn (tài liệu của Google).

Nguồn

• YouTube Data API: Captions.download
• API transcript của sum.video