# YouTube Transcript｜半成品 WIP｜字幕转 JSON/Markdown（有风控风险） (`ahuang/youtube-transcript`) Actor

⚠️ WIP/Early access（半成品）. High volume may hit YouTube rate-limits — service may be unavailable. Failures free. BYO proxy. ⚠️ 半成品。请求量高时可能遇风控、服务可能不可用；失败不计费；请自带代理。

- **URL**: https://apify.com/ahuang/youtube-transcript.md
- **Developed by:** [HehuanHuang](https://apify.com/ahuang) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 transcript successes

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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](https://apify.com/ahuang/youtube-transcript)\
**RapidAPI:** [YouTube Transcript API](https://rapidapi.com/阿黄/api/youtube-transcript-api-Zi-Mu-Zhuan-json-markdown-Gong-Kai-Zi-Mu)

***

### 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):

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

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

```json
{
  "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](https://rapidapi.com/阿黄/api/youtube-transcript-api-Zi-Mu-Zhuan-json-markdown-Gong-Kai-Zi-Mu) — BASIC / PRO / ULTRA / MEGA. Same WIP + A+B messaging.

# Actor input Schema

## `urls` (type: `array`):

YouTube watch / youtu.be / shorts URLs or 11-char video IDs. MVP: no playlist/channel expansion. 支持 watch、youtu.be、shorts 或 11 位 videoId；不做 Playlist/Channel 展开。

## `language` (type: `string`):

ISO 639-1 preferred language (e.g. en, zh, ja). Manual captions preferred, then auto. Missing language falls back and sets fallbackNote. 首选语言；人工字幕优先，再自动字幕；不可用时回退并写 fallbackNote。

## `languages` (type: `array`):

Priority list (wins over language), e.g. zh, en. 优先级列表（覆盖 language），如 zh, en。

## `outputFormat` (type: `string`):

json = full PRD object (segments + text + markdown). text/markdown = slim rows still with ok/billed/videoId. Dataset always stores one row per URL. json=完整对象；text/markdown=精简行。

## `includeMetadata` (type: `boolean`):

title / channel / channelId / durationSeconds / availableLanguages. Default on. 默认开启。

## `maxUrls` (type: `integer`):

Hard cap per Actor run (default 50). Extra URLs are skipped with a free notice row. 单 run 上限默认 50；超出写不计费 notice。

## `maxConcurrency` (type: `integer`):

B — throttle: keep low (1–3, default 3). Higher values increase RATE_LIMITED risk on shared IPs. Actor currently processes URLs sequentially with a short delay; this field documents the intended cap. 低并发 1–3（默认 3）；过高更易 RATE_LIMITED。

## `proxyConfiguration` (type: `object`):

A — Bring your own proxy. Use Apify Proxy UI or custom http(s)://user:pass@host:port. Without a proxy, datacenter / cloud IPs often return RATE_LIMITED (ok:false, not billed). Do NOT enable RESIDENTIAL by default unless you accept Apify proxy traffic cost (C not bundled). 自带代理；不配则云 IP 常 RATE_LIMITED（失败不计费）。默认不启用住宅代理。

## Actor input object example

```json
{
  "urls": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ],
  "language": "en",
  "outputFormat": "json",
  "includeMetadata": true,
  "maxUrls": 50,
  "maxConcurrency": 3,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "urls": [
        "https://www.youtube.com/watch?v=jNQXAC9IVRw"
    ],
    "language": "en"
};

// Run the Actor and wait for it to finish
const run = await client.actor("ahuang/youtube-transcript").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "urls": ["https://www.youtube.com/watch?v=jNQXAC9IVRw"],
    "language": "en",
}

# Run the Actor and wait for it to finish
run = client.actor("ahuang/youtube-transcript").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "urls": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ],
  "language": "en"
}' |
apify call ahuang/youtube-transcript --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ahuang/youtube-transcript"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/pTxOba7rzjsj3lIEY/builds/Mk2kFLwCmyeUQuKSf/openapi.json