YouTube Transcript API｜字幕转 JSON / Markdown（半成品 / WIP）

⚠️ 半成品（WIP / Early access）— YouTube 风控风险

Status: unfinished MVP / Early access — 半成品. Not production-ready. Features and reliability are limited; expect rough edges.

Under high request volume, YouTube rate-limiting / blocks are likely. The service may become unavailable (cloud / shared IPs especially). Failures often return ok: false with code RATE_LIMITED and no transcript. Failures are never charged.

Mitigations shipping (A+B, no managed proxy):

• A — BYO proxy: Apify Input proxyConfiguration (Apify Proxy UI or custom http(s)://user:pass@host:port); RapidAPI/Lambda optional proxyUrl. Without a proxy, datacenter IPs often hit RATE_LIMITED.
• B — Throttle: low concurrency + backoff retries on both platforms. Still not a guarantee against hard IP blocks.
• Not included: Apify Residential by default, or any host-paid proxy pool (C/D not approved).

中文（请先读）：

• 本产品为 半成品（未完成 MVP / Early access），非生产级。
• 请求量高时可能遭遇 YouTube 风控，服务可能不可用（尤其云端默认 IP）。
• 失败（含 RATE_LIMITED）一律不计费。
• 已落地风控：A 自带代理（Apify proxyConfiguration / RapidAPI proxyUrl）+ B 低并发与退避重试。不提供我方托管住宅代理（未批 C/D）。

Extract public YouTube captions (uploader or auto-generated) as JSON, plain text, or LLM-ready Markdown. No ASR, no audio/video download, no login / age-gate / private bypass.

抽取 YouTube 公开字幕（创作者上传或自动生成），输出 JSON / 纯文本 / LLM 友好 Markdown。不做 ASR、不下载音视频、不绕过登录/年龄门/私密视频。

Store: ahuang/youtube-transcript
RapidAPI: YouTube Transcript API

---

Compliance / 合规

English: This Actor retrieves publicly available captions/transcripts already offered on YouTube videos (uploader-provided or YouTube auto-generated). It does not download or store audiovisual media, and it does not bypass login, age gates, private videos, or paywalls. You are responsible for complying with the YouTube Terms of Service and applicable laws. Not affiliated with Google or YouTube.

中文: 仅获取 YouTube 公开视频上已提供的字幕/转写文本，不下载、不存储音视频，不绕过登录、年龄限制、私密或付费墙。请自行遵守 YouTube 服务条款与适用法律。非 YouTube 官方产品。

Do not use for / 禁止用于: account takeover, mass copyright redistribution, illegal surveillance. / 账号劫持、大规模侵权再分发、非法监控。

---

Pricing / 定价（PPE）

Event	FREE	Paid tiers (BRONZE+)
transcript_success	$0.001 / success	$0.0007 / success
Failures (incl. RATE_LIMITED)	$0	$0

• Charged only when a transcript with non-empty segments is written (Actor.charge on success only).
• Business failures (ok: false) — including RATE_LIMITED, NO_TRANSCRIPT, GEO_BLOCKED, timeouts, etc. — are never charged.
• Optional platform event apify-actor-start ≈ $0.00005 per run (Apify platform).
• 仅成功写出非空字幕时计费；含 RATE_LIMITED 在内的失败一律不计费。

---

Reliability & proxies / 稳定性与代理（A+B）

半成品 / WIP: unfinished MVP — not production-ready.

Risk: High request volume often triggers YouTube rate-limits → service may be unavailable, especially on shared cloud IPs (RATE_LIMITED, no captions).

Billing: Failures are $0. Only successful non-empty transcripts are charged.

A — Bring your own proxy (recommended for production):

• Apify: set Input proxyConfiguration (Apify Proxy groups in Console, or custom proxy URL).
• RapidAPI / Lambda: optional request field proxyUrl (http(s)://user:pass@host:port). Do not log credentials.
• No proxy → higher chance of RATE_LIMITED on datacenter exits.

B — Built-in throttle: low default concurrency + backoff retries (both platforms). Helps soft limits; does not fix hard datacenter blocks alone.

Not bundled: managed residential proxy / host-paid pool (C/D not approved).

风险： 请求量高时易遇风控，服务可能不可用。失败不计费。请用 A 自带代理；已含 B 降速/退避；无托管代理。

---

MVP scope / 范围

In	Out (v1.1+)
Single video + batch	Playlist / Channel / Search
Manual + auto captions	ASR / Whisper
json / text / markdown	SRT / VTT
watch / youtu.be / shorts / 11-char id	Login / age-gate bypass

---

Input / 输入

Field	Required	Description
urls	yes	watch / youtu.be / shorts / 11-char id（batch）
language	no	ISO 639-1（e.g. en）
languages	no	priority list（wins over language）
outputFormat	no	json (default) | text | markdown
includeMetadata	no	default true
maxUrls	no	default 50, max 100 per run
maxConcurrency	no	B 1–3（default 3）；过高更易 RATE_LIMITED
proxyConfiguration	no	A Apify Proxy / custom proxy（Console Proxy UI or URL）
proxyUrl	no	A RapidAPI/Lambda only: optional http(s)://… proxy

---

Output / 输出

Success rows include: ok, videoId, url, title, channel, channelId, durationSeconds, language, requestedLanguage, isAutoGenerated, availableLanguages, segments[{start,duration,text}], text, markdown, plus fallbackNote when language fallback occurs.

Failure rows: ok: false, machine-readable code (e.g. NO_TRANSCRIPT, RATE_LIMITED, GEO_BLOCKED), not charged.

---

Example / 示例

Without proxy (often fine for light tests; may RATE_LIMITED on cloud IPs):

{
  "urls": ["https://www.youtube.com/watch?v=jNQXAC9IVRw"],
  "language": "en",
  "outputFormat": "markdown",
  "includeMetadata": true
}

With BYO proxy on Apify (recommended for heavier use):

{
  "urls": ["https://www.youtube.com/watch?v=jNQXAC9IVRw"],
  "language": "en",
  "proxyConfiguration": {
    "useApifyProxy": false,
    "proxyUrls": ["http://USER:PASS@proxy.example:8080"]
  }
}

RapidAPI / Lambda: pass optional proxyUrl the same way (never put secrets in public issues).

---

Also on RapidAPI / 同步上架 RapidAPI

Same product: Hub listing — BASIC / PRO / ULTRA / MEGA. Same WIP + A+B messaging.