# YouTube Transcript & AI Summary Extractor (`kind_cordial/youtube-transcript-ai-extractor`) Actor

Extract YouTube transcripts (timestamped, multi-language, SRT/VTT/CSV/TXT export), expand channels/playlists, and generate AI summaries with topic-based chapters. Proxy-aware with auto anti-block retries.

- **URL**: https://apify.com/kind\_cordial/youtube-transcript-ai-extractor.md
- **Developed by:** [Rupesh](https://apify.com/kind_cordial) (community)
- **Categories:** AI, Automation, Videos
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## YouTube Transcript & AI Summary Extractor

Turn any YouTube video, Short, channel, or playlist into structured, timestamped
transcript text and AI-generated summaries — one clean dataset row per video.

### What it does

- Resolves watch URLs, Shorts URLs, and bare video IDs.
- **Timestamped transcripts** — every segment carries a `startTime` (`HH:MM:SS`) and text.
- **Multi-language** — request a preferred language; falls back to auto-generated captions and reports `language` + `isAutoGenerated`.
- **Export formats** — choose `json` (default), `srt`, `vtt`, `csv`, or `txt`. SRT/VTT/CSV/TXT are generated in spec-correct format and attached to the row.
- **Channel / playlist input** — pass a channel page (`@handle`, `/channel/...`), or a playlist (`?list=`) URL; it auto-expands to the video list (capped by `maxVideos`).
- **Proxy-aware + anti-block** — detects YouTube IP-bans / 429-style blocks, rotates the proxy, and retries with exponential backoff (`maxRetries`).
- **AI summary** — optional bullet summary with selectable `summaryLength` (short/medium/long) and an independent `summaryLanguage`.
- **Chapter segmentation (stretch)** — optional AI topic-based chapters with title + start/end times.
- One dataset row per processed video.

```mermaid
flowchart LR
  A["startUrls"] --> B{"Classify URL"}
  B -->|video| C["Fetch transcript"]
  B -->|channel/playlist| D["Expand to videos"]
  D --> E["Cap by maxVideos"]
  E --> C
  C --> F{"Preferred\nlanguage found?"}
  F -->|yes| G["Use preferred caption"]
  F -->|no| H["Try fallback langs"]
  H --> I{"Any caption\navailable?"}
  I -->|yes| J["Use available caption"]
  I -->|no| K["Emit row with warnings"]
  G --> L{"includeSummary?"}
  J --> L
  L -->|yes| M["Generate AI summary"]
  L -->|no| N["Emit dataset row"]
  M --> O{"enableChapters?"}
  O -->|yes| P["Segment chapters"]
  O -->|no| N
  P --> N
  K --> N
  N --> Q["Done"]
```

### Inputs

| Field | Type | Default | Notes |
|---|---|---|---|
| `startUrls` *(required)* | array\[string] | — | Video, Short, video-ID, channel, or playlist URLs. Channels/playlists expand automatically. |
| `mode` | enum | `auto` | `auto` tries direct then browser title; `direct`; `browser`. |
| `maxVideos` | integer | `1` | Max videos to process across all URLs + expansions (1–200). |
| `preferredLanguage` | string | `en` | Preferred transcript language code. Auto-generated captions used as fallback. |
| `languages` *(legacy)* | array\[string] | `["en","en-US","en-GB","a.en"]` | Kept for backward compatibility; used only when `preferredLanguage` is omitted. |
| `languagesExtended` | array\[string] | = preferred | Extra fallback codes. |
| `includeRawTranscript` | boolean | `true` | Include timestamped segments + full text. |
| `includeSummary` | boolean | `false` | Generate an AI summary. Requires `OPENAI_API_KEY` + `OPENAI_BASE_URL`. |
| `summaryModel` | string | `gpt-4o-mini` | Model for summary + chapters. |
| `summaryLength` | enum | `medium` | `short` (3-5), `medium` (5-8), `long` (8-12) bullets. |
| `summaryLanguage` | string | `""` | Language for the summary, independent of transcript language. |
| `enableChapters` | boolean | `false` | AI topic-based chapter segmentation (needs `includeSummary`). |
| `outputFormat` | enum | `json` | `json`, `srt`, `vtt`, `csv`, `txt`. |
| `maxRetries` | integer | `3` | Exponential-backoff retries on YouTube blocks/IP-bans (proxy rotates each retry). |
| `maxTranscriptLength` | integer | `15000` | Truncate transcript after this many characters. |
| `proxyConfiguration` | object | `{ "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }` | **Defaults to Apify RESIDENTIAL proxies.** YouTube blocks datacenter IPs (the Apify run node and the `BUYPROXIES` group are both blocked), so residential proxies are required for reliable channel/playlist/bulk runs. Override with your own `proxyUrl` or a different group if you have proxy access. |

> **Backward compatibility:** with no new inputs set, behavior matches the previous
> version (single video, `en` transcript, `json` output, optional summary).
> The old `languages` input is still honored when `preferredLanguage` is omitted.

### Example 1 — single video, timestamped transcript (default)

```json
{
  "startUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
  "mode": "auto",
  "maxVideos": 1,
  "preferredLanguage": "en",
  "includeRawTranscript": true,
  "includeSummary": false,
  "outputFormat": "json"
}
```

### Example 2 — SRT export + AI summary (Spanish)

```json
{
  "startUrls": ["https://www.youtube.com/watch?v=abc123"],
  "outputFormat": "srt",
  "includeSummary": true,
  "summaryLength": "short",
  "summaryLanguage": "es",
  "maxTranscriptLength": 8000
}
```

### Example 3 — whole channel, auto-language fallback, chapters

```json
{
  "startUrls": ["https://www.youtube.com/@someChannel"],
  "maxVideos": 20,
  "preferredLanguage": "en",
  "includeSummary": true,
  "enableChapters": true,
  "summaryLength": "long"
}
```

### Example 4 — playlist with proxy + anti-block retries

```json
{
  "startUrls": ["https://www.youtube.com/playlist?list=PLxxxxxxxxxxxx"],
  "maxVideos": 50,
  "proxyConfiguration": { "useApifyProxy": true, "groups": ["BUYPROXIES94952"] },
  "maxRetries": 5,
  "outputFormat": "vtt"
}
```

### Output schema (per video row)

| Field | Type | Description |
|---|---|---|
| `videoUrl` | string | Source URL. |
| `videoId` | string | 11-char YouTube video ID. |
| `title` | string | Video title (when available). |
| `language` | string | Resolved transcript language code. |
| `isAutoGenerated` | boolean | `true` when auto-generated captions were used. |
| `transcriptSegments` | array | `[{ startTime: "HH:MM:SS", startSeconds, text }]`. |
| `fullText` | string | Full concatenated transcript (when `includeRawTranscript`). |
| `summary` | object | `{ model, summary, error? }` when `includeSummary`. |
| `exportFormat` | string | The chosen export format. |
| `srt` / `vtt` / `csv` / `txt` | string | Present only for the matching `outputFormat`. |
| `chapters` | array | `[{ title, startTime, endTime }]` when `enableChapters`. |
| `warnings` | array\[string] | Non-fatal issues (e.g. `transcript-empty-or-quota-limited`). |

#### Example output row (`outputFormat: json`)

```json
{
  "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "videoId": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up",
  "language": "en",
  "isAutoGenerated": false,
  "transcriptSegments": [
    { "startTime": "00:00:01", "startSeconds": 1.36, "text": "[♪♪♪]" },
    { "startTime": "00:00:18", "startSeconds": 18.64, "text": "♪ We're no strangers to love ♪" }
  ],
  "fullText": "[♪♪♪] ♪ We're no strangers to love ♪ ...",
  "summary": { "model": "gpt-4o-mini", "summary": "- Iconic 80s song\n- ..." },
  "exportFormat": "json",
  "chapters": [
    { "title": "Intro", "startTime": "00:00:00", "endTime": "00:01:00" }
  ],
  "warnings": []
}
```

### AI summary / chapters — setup

Set these environment variables on the Actor (Apify Console → Actor → Environment):
`OPENAI_API_KEY` and `OPENAI_BASE_URL` (any OpenAI-compatible endpoint,
e.g. OpenRouter). When unset, `includeSummary` / `enableChapters` produce
an empty `summary` with an `error` field rather than failing the run.

### Run costs

Pay-per-event pricing:

- per dataset row written
- per run

Actual cost depends on run + row counts. Check the Apify Console after a run.

### Notes / limitations

- **Proxy / IP bans:** YouTube blocks datacenter IPs (including the Apify run node and the `BUYPROXIES` group). The actor therefore **defaults to Apify RESIDENTIAL proxies**, which reliably bypass the block. Without a working residential proxy, channel/playlist/bulk runs will fail with "YouTube is blocking requests from your IP." If you have your own residential proxy, set `proxyConfiguration.proxyUrl`.
- Channel/playlist expansion is best-effort and capped by `maxVideos`.
- Not all videos have captions; unavailable transcripts surface a `warnings` entry.
- `isAutoGenerated` reflects whether the served transcript was auto-generated.

# Actor input Schema

## `startUrls` (type: `array`):

YouTube watch URLs, Shorts URLs, video IDs, OR channel/playlist URLs (channel pages, @handles, or ?list= playlist links). Channels/playlists are expanded to their videos automatically (capped by maxVideos).

## `mode` (type: `string`):

Direct mode only. Browser/auto modes were removed in 0.3.

## `maxVideos` (type: `integer`):

Maximum number of videos to process in one run (across all URLs and expanded channels/playlists).

## `preferredLanguage` (type: `string`):

Preferred transcript language code (e.g. 'en', 'es', 'hi'). Auto-generated captions are used as fallback when this language is unavailable. Defaults to 'en' when omitted.

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

DEPRECATED in favor of preferredLanguage, kept for backward compatibility. Used only when preferredLanguage is omitted. Ordered list of language codes.

## `languagesExtended` (type: `array`):

Additional fallback language codes used when preferred language is unavailable. Defaults to the preferred language when omitted.

## `includeRawTranscript` (type: `boolean`):

Return timestamped segments and full text in output. Default true.

## `includeSummary` (type: `boolean`):

Generate an optional AI summary when a transcript is available. Requires an OpenAI-compatible API key (OPENAI\_API\_KEY + OPENAI\_BASE\_URL).

## `summaryModel` (type: `string`):

Model name used for optional summarization and chapter segmentation.

## `summaryLength` (type: `string`):

AI summary length. short = 3-5 bullets, medium = 5-8, long = 8-12.

## `summaryLanguage` (type: `string`):

Language for the AI summary, independent of the transcript language (e.g. 'es', 'fr'). Leave empty for the model default (usually matches transcript).

## `enableChapters` (type: `boolean`):

Use AI to group the transcript into topic-based chapters with title + start/end times. Requires includeSummary + an OpenAI-compatible key.

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

Output format. json = full structured dataset row (default). srt/vtt/csv/txt = also attach a formatted transcript string to the row (srt, vtt, csv, or txt text file body).

## `maxRetries` (type: `integer`):

Number of exponential-backoff retries when YouTube returns a block/IP-ban (429-style) error. Each retry rotates the proxy when one is configured.

## `maxTranscriptLength` (type: `integer`):

Truncate transcript text/segments after this many characters.

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

Proxy for transcript fetching and channel/playlist expansion. Defaults to Apify RESIDENTIAL proxies (YouTube blocks datacenter IPs, so residential is required for reliable bulk/channel runs). Set useApifyProxy:true + apifyProxyGroups:\["RESIDENTIAL"], or supply your own proxyUrl. Leave empty to use the residential default.

## Actor input object example

```json
{
  "mode": "direct",
  "maxVideos": 1,
  "preferredLanguage": "en",
  "languages": [
    "en",
    "en-US",
    "en-GB",
    "a.en"
  ],
  "includeRawTranscript": true,
  "includeSummary": false,
  "summaryModel": "gpt-4o-mini",
  "summaryLength": "medium",
  "enableChapters": false,
  "outputFormat": "json",
  "maxRetries": 3,
  "maxTranscriptLength": 15000,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("kind_cordial/youtube-transcript-ai-extractor").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 = {}

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

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

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

```

## CLI example

```bash
echo '{}' |
apify call kind_cordial/youtube-transcript-ai-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=kind_cordial/youtube-transcript-ai-extractor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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