چگونه با API رونوشت یوتیوب را بگیریم (curl، Python، JavaScript)

برای گرفتن رونوشت یوتیوب با API، یک درخواست HTTP با نشانی یا شناسه ویدیو و یک کلید API بفرست و رونوشت را از پاسخ بخوان. این راهنما درخواست را با API رونوشت sum.video در curl، Python و JavaScript نشان می‌دهد و سپس قالب‌ها، خطاها و هزینه را بررسی می‌کند.

API چه چیزی برمی‌گرداند

این نقطه پایانی زیرنویس‌های موجود یک ویدیوی عمومی یوتیوب را برمی‌گرداند، چه سازنده نوشته باشد و چه یوتیوب خودکار ساخته باشد. صدا را به متن تبدیل نمی‌کند. اگر ویدیو زیرنویس نداشته باشد، به‌جای حدس یک خطا می‌گیری (توضیح بیشتر در ادامه).

مبانی:

• نقطه پایانی: 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 هم کار می‌کند، می‌توانی از اسکریپتی که فقط نشانی می‌سازد هم آزمایش کنی. بهتر است کلید را در سربرگ بدهی تا در گزارش‌ها نیفتد.

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 بخش بساز. برای دادن به یک مدل زبانی، text کوچک‌تر و ساده‌تر است. اگر بعداً خواستی دستی در رونوشت جست‌وجو کنی، چگونه در رونوشت یک ویدیوی یوتیوب جست‌وجو کنیم را ببین.

گام 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 اعتبار جایزه هم می‌گیرند. برای بارهای سنگین‌تر، مثل واردکردن یک کانال کامل، سناریوی رونوشت‌های یوتیوب برای یک برنامه RAG در مقیاس بزرگ را بخوان که شارژ خودکار و بودجه‌ها را پوشش می‌دهد. قیمت‌ها را هم ببین.

محدودیت‌هایی که پیش از ساختن باید بدانی

• فقط ویدیوهای دارای زیرنویس کار می‌کنند. این دلیل اصلی 404 no_transcript است.
• زیرنویس‌های خودکار ممکن است اشتباه داشته باشند، به‌ویژه در نام‌ها، لهجه‌ها و اصطلاحات فنی.
• API فقط رونوشت را برمی‌گرداند. خلاصه نمی‌کند. اگر خلاصه، زمان‌نگاشت و گفت‌وگو روی رونوشت می‌خواهی، خلاصه‌ساز یوتیوب این کار را می‌کند و ابزار رونوشت نسخه بدون کد برای یک ویدیو است.
• API رسمی YouTube Data اینجا جایگزین نیست. روش دانلود زیرنویس آن مجوز ویرایش ویدیو می‌خواهد، پس برای ویدیوهای خودت است (مستندات گوگل).

منابع

• YouTube Data API: Captions.download
• API رونوشت sum.video