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

# YouTube API

> 搜索 YouTube，并以 JSON 读取视频、评论、频道、频道上传内容和字幕，包括播放量、点赞数、发布时间、章节和字幕文本。

通过异步任务 API 以 JSON 读取公开的 YouTube 数据。发送 `taskType` `SOCIAL` 并设置 `platform` `youtube`，用 `action` 选择要读取的内容。每次完成的请求消耗 **0.5 积分**。

## 请求

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "SOCIAL", "payload": { "platform": "youtube", "action": "search", "query": "wireless earbuds review", "limit": 10 } }'
```

提交任务后，轮询 `GET /v1/async/task/{id}` 或通过 webhook 接收。参见[异步任务](https://docs.querying.ai/zh/concepts/async-tasks.md)。

## 操作

| `action` | 读取内容 | 必填 |
| - | - | - |
| `search`（默认） | YouTube 搜索结果 | `query` |
| `recent` | 某个查询的最新上传，按时间从新到旧 | `query` |
| `video` | 一个视频的观看页 | `videoId` |
| `comments` | 视频的评论及其回复 | `videoId` |
| `channel` | 频道详情和链接 | `channel` |
| `channel_videos` | 频道的视频、Shorts 或直播 | `channel` |
| `transcript` | 视频字幕 | `videoId` |

`videoId` 接受视频 ID 或 YouTube 视频 URL（观看页、`youtu.be`、Shorts 或嵌入）。`channel` 接受频道 ID（`UC...`）、`@handle` 或频道 URL。

## 参数

`search` 和 `recent`：

* `query`：必填。搜索查询。
* `limit`：可选整数，范围 1-50，默认 10。
* `type`：`video`（默认）、`all`、`shorts`、`channel`、`playlist` 或 `movie`。
* `order`：`relevance`（默认）、`viewCount`、`date` 或 `rating`。`date` 与 `recent` 一样按上传时间从新到旧排列。`rating` 将 YouTube 播放量最高的结果按点赞数排序。`channel` 和 `playlist` 搜索接受 `relevance` 或 `viewCount`。
* `publishedAfter`：ISO 8601 时间，例如 `2026-11-01T00:00:00Z`。返回此时间之后发布的视频。
* `videoDuration`：`short`（3 分钟以内）、`medium`（3-20 分钟）或 `long`（超过 20 分钟）。
* `features`：`live`、`4k`、`hd`、`subtitles`、`creative_commons`、`360`、`vr180`、`3d`、`hdr`、`location` 和 `purchased` 中的任意值，以数组或逗号分隔的字符串发送。
* `exactSpelling`：设为 `true` 时按原样搜索查询，不经 YouTube 拼写纠正。
* `pageToken`：上一页的 `nextPageToken`。不带 `publishedAfter`、按 `relevance` 或 `viewCount` 排序的视频搜索会返回该值，每一页都会跳过之前各页已返回的视频。
* `regionCode` 和 `languageCode`：搜索所用的 YouTube 地区（`US`、`KR`、`JP`）和界面语言（`en`、`ko`、`ja`）。

`comments`：

* `limit`：可选整数，范围 1-500，默认 100。回复计入数量。
* `order`：`relevance`（默认，YouTube 的热门评论）或 `time`（从新到旧）。
* `includeReplies`：可选，默认 `true`。

`channel_videos`：

* `tab`：`videos`（默认）、`shorts` 或 `streams`。
* `sort`：`latest`（默认）、`popular` 或 `oldest`。
* `limit`：可选整数，范围 1-50，默认 20。

`transcript`：

* `languages`：按优先顺序排列的字幕语言，例如 `["en", "ko"]`。未设置时依次读取视频的默认字幕、英文字幕和第一条字幕轨。
* `isGenerated`：`true` 只读取自动生成的字幕，`false` 只读取上传者的字幕。
* `trackName`：要读取的字幕轨名称。
* `translateTo`：语言代码。YouTube 会把字幕翻译成该语言。
* `maxSegments`：可选整数，范围 1-5,000，默认 2,000。

## 响应示例

```json theme={"theme":"css-variables"}
{
  "platform": "youtube",
  "action": "search",
  "query": "wireless earbuds review",
  "order": "relevance",
  "totalResults": 4523475,
  "returnedCount": 1,
  "videos": [
    {
      "position": 1,
      "videoId": "YdJh6QdOGME",
      "url": "https://www.youtube.com/watch?v=YdJh6QdOGME",
      "title": "Earbuds Awards 2026 - Best Bluetooth Earbuds by Category!",
      "channelId": "UCZZ4ivUawsXRktLKej8d6Xw",
      "channelTitle": "Mike O'Brien",
      "channelHandle": "@MikeOBrienMedia",
      "channelIsVerified": true,
      "publishedAt": "2026-11-17T15:39:37Z",
      "publishedTimeText": "21 hours ago",
      "duration": "PT16M35S",
      "durationSeconds": 995,
      "viewCount": 62618,
      "likeCount": 957,
      "category": "Science & Technology",
      "badges": ["New"],
      "thumbnails": { "high": "https://i.ytimg.com/vi/YdJh6QdOGME/hqdefault.jpg" }
    }
  ],
  "nextPageToken": "eyJyIjpbIllkSmg2UWRPR01FIl19"
}
```

## 结果字段

* 每个响应都会原样返回 `platform` 和 `action`。列表带有 `returnedCount`。
* `search` 和 `recent` 返回 `videos`。每个视频包含 `position`、`videoId`、`url`、`title`、`description`，频道的 `channelId`、`channelTitle`、`channelHandle`、`channelUrl`、`channelThumbnail` 和 `channelIsVerified`，以及 `publishedAt`、`publishedTimeText`、`duration`（ISO 8601）、`durationSeconds`、`viewCount`、`likeCount`、`category`、`thumbnails`、`richThumbnail`（动态预览）、`badges` 和 `isFamilySafe`。电影还会加上 `movie`，包含海报、类型、年份、演员和导演。
* 搜索还会返回结果页显示的 `channels`、`playlists`、`shorts` 和 `shelves`，以及 `totalResults`（YouTube 的估计值）；YouTube 纠正查询时会返回 `didYouMean` 或 `showingResultsFor`。
* `video` 增加 `tags`、`commentCount`、`subscriberCount`、`hasCaptions`、`chapters`、`mostReplayed`、`music`、`descriptionLinks` 和 `relatedVideos`。上传者的章节排在前面，自动章节带有 `autoGenerated: true`。
* `comments` 返回 `comments`，每条评论包含 `commentId`、`parentId`（顶层评论为 `null`）、`text`、`authorDisplayName`、`authorChannelId`、`authorProfileImageUrl`、`authorIsVerified`、`authorIsChannelOwner`、`isPinned`、`isHearted`、`likeCount`、`replyCount`、`publishedAt` 和 `updatedAt`。`totalCount` 是 YouTube 显示的数量，`topLevelCount` 和 `replyCount` 是 `returnedCount` 的拆分。
* `channel` 返回 `channelId`、`title`、`handle`、`description`、`country`、`publishedAt`、`subscriberCount`、`videoCount`、`viewCount`、`isVerified`、`keywords`、`links`、`thumbnails`、`bannerUrl`、`rssUrl` 和 `uploadsPlaylistId`。
* `channel_videos` 按 `sort` 的顺序返回 `videos`，并附带频道的 `channelId` 和 `channelTitle`。
* `transcript` 返回字幕 `text`、带时间的 `segments`（`start` 和 `duration`，单位为秒）、读取的 `language` 和 `availableLanguages`。`truncated: true` 表示字幕在 `maxSegments` 处被截断。
* 隐藏点赞数的视频带有 `likesHidden: true`，关闭评论的视频带有 `commentsDisabled: true`。会员专属视频带有 `membersOnly: true`，且没有 `viewCount`。
* 不存在的视频、频道或字幕轨，或需要登录观看的内容（例如年龄限制视频），会使任务以 `PAGE_UNAVAILABLE` 结束。不能组合使用的参数会使任务以 `BAD_PAYLOAD` 结束。只对完成的请求计费。

## 相关

* [Instagram](https://docs.querying.ai/zh/engines/instagram.md)
* [Threads](https://docs.querying.ai/zh/engines/threads.md)
* [引擎概览](https://docs.querying.ai/zh/engines/overview.md)
* [积分与限制](https://docs.querying.ai/zh/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.