> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube Scraper API 端点

> 使用可复制粘贴的代码示例对所有三个Bright Data YouTube爬虫API端点进行同步请求。

本指南介绍如何向每个 Bright Data YouTube Scraper API 端点发送同步请求。完成后，您将获得频道、视频和评论的工作示例。

## 先决条件

* 一个 [Bright Data 账户](https://www.bright.cn/products/web-scraper/youtube?hs_signup=1\&utm_source=docs)，具有有效的 API 密钥
* 完成了 [快速入门](/cn/products/scrapers/youtube/quickstart)

## 请求结构

每个同步请求都遵循相同的模式：

```
POST https://api.brightdata.com/datasets/v3/scrape?dataset_id={DATASET_ID}&format=json
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

[{"url": "https://www.youtube.com/..."}]
```

端点之间唯一改变的是 `dataset_id` 和输入 URL 格式。

<Note>
  `/scrape` 端点专为实时的单 URL 请求设计。Bright Data 建议每个请求不超过 20 个 URL（这是最佳实践，而非硬性限制），端点最多等待 1 分钟。如果采集耗时更长，响应为 HTTP `202`，返回 `snapshot_id` 而不是数据，采集将继续以异步方式进行。请通过[异步请求](/cn/products/scrapers/scrapers-library/async-requests)获取结果，或使用 [Webhook 投递](/cn/products/scrapers/scrapers-library/data-delivery)接收结果。
</Note>

## 频道

**数据集 ID：** `gd_lk538t2k2p1k3oos71`

```bash theme={null}
curl -X POST \
  "https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_lk538t2k2p1k3oos71&format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://www.youtube.com/@MrBeast"}]'
```

您应该会看到 `200` 响应。处理时间取决于目标网站状况和爬虫负载。

<Accordion title="示例响应">
  ```json theme={null}
  [
    {
      "subscribers": 516000000,
      "url": "https://www.youtube.com/@mrbeast",
      "handle": "@MrBeast",
      "handle_md5": "dd748d5dfc88b91ea388429c3c685874",
      "banner_img": "https://yt3.googleusercontent.com/mHMO_eEMp0dPvh0ADwXhPXNYb_GnjSVsLI8biqF1CpxT8OPl7izhNQsDPD3JHhd5y5Mg9GrP=w2560-fcrop64=1,00005a57ffffa5a8-k-c0xffffffff-no-...",
      "profile_image": "https://yt3.googleusercontent.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE=s160-c-k-c0x00ffffff-no-rj",
      "name": "MrBeast",
      "Description": "SUBSCRIBE FOR A COOKIE!\nNew MrBeast or MrBeast Gaming video every single Saturday at noon eastern time!\nAccomplishments:\n- Raised $20,000,000 To Plant 20,000...",
      "videos_count": 1000,
      "created_date": "2012-02-19T00:00:00.000Z"
    }
  ]
  ```
</Accordion>

[完整频道响应架构](/cn/api-reference/scrapers/social-media-apis/youtube-channels-collect-by-url)

### YouTube 频道抓取器返回哪些输出字段？

YouTube 频道抓取器（`gd_lk538t2k2p1k3oos71`，`collect_by_url`）返回 21 个输出字段。字段说明保留 API 返回的英文原文。

<Accordion title="输出字段（21）">
  | 字段 | 类型 | 说明 |
  | - | - | - |
  | `url` | url | URL that link directly to the YouTube profile |
  | `handle` | text | Unique to each user (e.g., @name) |
  | `handle_md5` | text | This field stores the MD5 hash of the handle field. |
  | `banner_img` | url | URL that links to the banner photo |
  | `profile_image` | url | URL that link to the profile picture |
  | `name` | text | Profile name |
  | `subscribers` | number | How many subscribers the profile have |
  | `Description` | text | Brief descriptions or statements that users write to introduce themselves or share their interests and passions on YouTube |
  | `videos_count` | number | How many videos the profile have |
  | `created_date` | date | The date the profile was created |
  | `views` | number | How many views the profile have |
  | `Details` | object | channel Details |
  | `Links` | array | External websites that users may link to from their YouTube profiles |
  | `identifier` | text | identifier |
  | `discovery_input` | object | Discovery input value |
  | `id` | text | channel id |
  | `has_podcast` | boolean | has podcast indicator |
  | `top_videos` | array | top videos |
  | `featured_video` | url | Featured Video |
  | `featured_channels` | array | featured channels |
  | `collaborations` | array | Collaborations videos |
</Accordion>

包含输入 schema 的机器可读版本：[`/scrapers/gd_lk538t2k2p1k3oos71.json`](/scrapers/gd_lk538t2k2p1k3oos71.json)

## 视频

**数据集 ID：** `gd_lk56epmy2i5g7lzu0k`

```bash theme={null}
curl -X POST \
  "https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_lk56epmy2i5g7lzu0k&format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}]'
```

<Accordion title="示例响应">
  ```json theme={null}
  [
    {
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
      "views": 1812511291,
      "likes": 19374379,
      "date_posted": "2009-10-25T06:57:33.000Z",
      "description": "The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick...",
      "num_comments": 2457228,
      "youtuber": "@RickAstleyYT",
      "youtuber_md5": "4fc65cd6213b5c0f1d04c2aa3006f46a",
      "video_url": "https://rr2---sn-n4v7snse.googlevideo.com/videoplayback?expire=1788712345&ei=OUGdaoSULZ-RsfIP8OmfsAo&ip=208.41.164.3&id=o-ALklNMQDHiVh32KdRiuWf9qyPo-8mNxywN-..."
    }
  ]
  ```
</Accordion>

[完整视频响应架构](/cn/api-reference/scrapers/social-media-apis/youtube-videos-collect-by-url)

### YouTube 视频抓取器返回哪些输出字段？

YouTube 视频抓取器（`gd_lk56epmy2i5g7lzu0k`，`collect_by_url`）返回 49 个输出字段。字段说明保留 API 返回的英文原文。

<Accordion title="输出字段（49）">
  | 字段 | 类型 | 说明 |
  | - | - | - |
  | `url` | url | The full YouTube watch URL of the collected video |
  | `title` | text | Title of the YouTube video |
  | `youtuber` | text | The channel handle extracted from the channel's browse endpoint |
  | `youtuber_md5` | text | MD5 hash of the youtuber field |
  | `video_url` | url | Direct streaming URL of the video file, extracted from YouTube's adaptive formats or decoded from signatureCipher |
  | `video_length` | number | Duration of the video in seconds |
  | `likes` | number | Number of likes received by the video |
  | `views` | number | Number of views the video has received |
  | `date_posted` | date | Date when the video was published |
  | `description` | text | Text description accompanying the video |
  | `num_comments` | number | Number of comments on the video, as displayed by YouTube (includes both top-level comments and replies in YouTube's count) |
  | `subscribers` | number | Number of subscribers to the YouTube channel |
  | `music` | object | Information about the music used in the video. Only present when YouTube's Content ID system has identified music in the video |
  | `video_id` | text | Unique identifier for the YouTube video |
  | `channel_url` | url | URL-encoded URL of the YouTube channel, derived from the channel's canonical browse endpoint |
  | `preview_image` | image | URL of the preview image for the video |
  | `shortcode` | text | The unique short identifier of the video, identical to video\_id, used across all YouTube video types including regular videos and Shorts |
  | `verified` | boolean | Indicates whether the channel is verified |
  | `handle_name` | text | The display name of the YouTube channel as shown on the video page |
  | `avatar_img_channel` | url | The URL of the avatar image of the YouTube channel |
  | `is_sponsored` | boolean | Indicates whether the video contains a paid content overlay as declared by YouTube |
  | `related_videos` | array | List of URLs of videos shown in the sidebar alongside the current video |
  | `license` | url | URL of the video's license as declared in YouTube's video metadata |
  | `viewport_frames` | text | Resolution of the primary video stream format, derived from YouTube's streaming data |
  | `current_optimal_res` | text | Current and optimal video resolution with frame rate, from YouTube's streaming format metadata |
  | `codecs` | text | Video and audio codec strings formatted as video codec and audio codec, extracted from YouTube's adaptive streaming formats |
  | `color` | text | Color primaries of the video stream, extracted from YouTube's adaptive format color info |
  | `quality` | text | Quality identifier of the first adaptive streaming format as reported by YouTube |
  | `quality_label` | text | Human-readable video quality label as reported by YouTube |
  | `post_type` | text | Type of YouTube content inferred from the URL structure. Possible values: post for standard video, short for YouTube Short, or N/A |
  | `youtuber_id` | text | YouTube's internal channel ID, distinct from the channel handle |
  | `transcript` | text | Full plain-text transcript of the video, compiled from YouTube's caption tracks. English captions are preferred, falls back to the first available language if English is unavailable |
  | `formatted_transcript` | array | Timestamped transcript segments from YouTube's caption tracks, each containing start time, end time, and duration in milliseconds, and the caption text |
  | `hashtags` | array | List of hashtags found in the video title or description, each with the hashtag text and its YouTube search link |
  | `tags` | array | Tags of the video |
  | `next_recommended_videos` | array | Videos shown as end-screen cards during the final seconds of the video, including timing in milliseconds and display style |
  | `recommended_videos` | array | Videos recommended by YouTube in the sidebar alongside the current video |
  | `transcript_language` | array | List of caption and transcript languages available for this video on YouTube, including whether each track was auto-generated |
  | `chapters` | array | List of chapter markers defined by the creator, each with a title, start time in milliseconds, and preview image |
  | `transcription_language` | text | The language code requested by the caller for transcript retrieval, passed as an input parameter at collection time |
  | `is_age_restricted` | boolean | Whether the video is age-restricted, inferred from a non-OK playability status combined with an age-related reason from YouTube |
  | `channel_url_decoded` | text | Plain-text percent-decoded version of the channel URL |
  | `category` | text | YouTube's content category assigned to the video, from YouTube's predefined category taxonomy |
  | `audio_tracks` | array | audio Tracks |
  | `made_for_kids` | boolean | Indicates whether the video is designated as made for kids, inferred from the YouTube miniplayer playback mode |
  | `player_notification_text` | text | User-facing notification text shown inside the video player |
  | `ai_content_label` | boolean | Indicates whether the video has been labeled as AI-generated or significantly AI-altered, either by the creator or auto-detected by YouTube. |
  | `live_status` | text | Livestream status of the video, equivalent to yt-dlp's live\_status. One of "is\_live", "was\_live", or "not\_live", parsed from YouTube's info string (e.g. "Streamed live 29 minutes ago") or defaulted to "not\_live" for regular videos |
  | `comments` | array | 10 Most relevant comments of the video |
</Accordion>

包含输入 schema 的机器可读版本：[`/scrapers/gd_lk56epmy2i5g7lzu0k.json`](/scrapers/gd_lk56epmy2i5g7lzu0k.json)

## 评论

**数据集 ID：** `gd_lk9q0ew71spt1mxywf`

```bash theme={null}
curl -X POST \
  "https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_lk9q0ew71spt1mxywf&format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}]'
```

<Accordion title="示例响应">
  ```json theme={null}
  [
    {
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "likes": 311000,
      "replies": 0,
      "comment_id": "Ugzge340dBgB75hWBm54AaABAg",
      "comment_text": "can confirm: he never gave us up",
      "username": "@Yo***e",
      "username_md5": "0e4d7a0778633b4acf6631dd251f0797",
      "user_channel": "https://www.youtube.com/@YouTube",
      "date": "1 year ago",
      "video_id": "dQw4w9WgXcQ"
    }
  ]
  ```
</Accordion>

[完整评论响应架构](/cn/api-reference/scrapers/social-media-apis/youtube-comments-collect-by-url)

### YouTube 评论抓取器返回哪些输出字段？

YouTube 评论抓取器（`gd_lk9q0ew71spt1mxywf`，`collect_by_url`）返回 16 个输出字段。字段说明保留 API 返回的英文原文。

| 字段 | 类型 | 说明 |
| - | - | - |
| `comment_id` | text | Unique identifier for each comment |
| `comment_text` | text | The text content of the comment |
| `likes` | number | Number of likes received by the comment |
| `replies` | number | Number of replies to the comment |
| `username` | text | Username of the commenter |
| `username_md5` | text | This field stores the MD5 hash of the username field. |
| `user_channel` | text | URL of the commenter's YouTube channel |
| `date` | text | Date when the comment was posted |
| `url` | url | Web address of the YouTube video where the comment was posted |
| `video_id` | text | Unique identifier for the YouTube video |
| `replies_value` | array | Array of reply objects associated with this comment |
| `replies_without_names` | array | Array of reply objects with personally identifiable information (usernames) removed, containing only MD5 hashed user identifiers |
| `user_id` | text | Unique identifier for the commenter's YouTube channel |
| `mentioned_timestamps_minutes` | array | Array of timestamps mentioned in the comment, formatted in minutes (e.g., '2:35') |
| `mentioned_timestamps_seconds` | array | Array of timestamps mentioned in the comment, converted to total seconds |
| `date_iso` | date | Date in ISO format |

包含输入 schema 的机器可读版本：[`/scrapers/gd_lk9q0ew71spt1mxywf.json`](/scrapers/gd_lk9q0ew71spt1mxywf.json)

## 快速参考：数据集 ID

| 端点 | 数据集 ID | URL 模式 |
| :- | :- | :- |
| 视频 | `gd_lk56epmy2i5g7lzu0k` | `youtube.com/watch?v={video_id}` |
| 频道 | `gd_lk538t2k2p1k3oos71` | `youtube.com/@{handle}` |
| 评论 | `gd_lk9q0ew71spt1mxywf` | `youtube.com/watch?v={video_id}` |

## 输出格式

使用 `format` 查询参数控制响应格式：

| 值 | 描述 |
| :- | :- |
| `json` | JSON 数组 |
| `ndjson` | 换行分隔的 JSON，每行一条记录（默认） |
| `csv` | 逗号分隔值 |

以上是 `/scrape` 的 `format` 值。完整列表（NDJSON（默认）、JSON、JSON lines、CSV 和 Parquet）及各格式适用范围见[输出格式](/cn/products/scrapers/scrapers-library/data-delivery#支持哪些输出格式)。

## 相关内容

<CardGroup cols={2}>
  <Card title="异步批量请求" icon="layer-group" href="/products/scrapers/scrapers-library/async-requests">
    在单个批量作业中抓取数百个 URL。
  </Card>

  <Card title="API 参考" icon="code" href="/api-reference/scrapers/social-media-apis/youtube-channels-collect-by-url">
    完整的参数和响应字段参考。
  </Card>
</CardGroup>