> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/api-reference/cn/zhuan-yong-zhua-qu-qi/mei-ti-zhua-qu-qi.md).

# 媒体抓取器

Web API 专用媒体抓取器端点、参数和每个端点的交付模式参考。

<table><thead><tr><th width="110">爬虫</th><th>端点</th></tr></thead><tbody><tr><td><a href="#general">常规</a></td><td><code>/media</code></td></tr><tr><td><a href="#youtube">YouTube</a></td><td><code>/media/youtube/metadata</code>, <code>/media/youtube/subtitles</code>, <code>/media/youtube/download</code>, <code>/media/youtube/channel</code>, <code>/media/youtube/search</code>, <code>/media/youtube/search/max</code>, <code>/media/youtube/autocomplete</code>, <code>/media/youtube/video/trainability</code></td></tr></tbody></table>

{% hint style="info" %}
无法下载的视频会以媒体特定错误代码(`11201`–`11304`)。请参阅 [媒体错误代码](/api-reference/cn/cuo-wu-yu-zhuang-tai-ma.md#media-specific-errors).
{% endhint %}

{% hint style="info" %}
存储 URL 会针对以下内容进行验证 `s3`, `s3_gzip`, `s3_compatible`，以及 `tos`。无效值返回 `400` 在创建请求之前。
{% endhint %}

### 常规

#### `POST /v1/async/scrape/media`

从 URL（TikTok、BiliBili 等）下载视频，并将其上传到你的存储桶。最大视频长度 – `12` 小时。最大下载时间 – `1` 小时。

**模式：** `异步`, `批量`

<table><thead><tr><th width="142">名称</th><th width="80.5">类型</th><th width="84.5">是否必填</th><th>描述</th></tr></thead><tbody><tr><td><code>url</code></td><td>字符串</td><td>是</td><td>视频 URL。<br>TikTok: <code>tiktok.com/@{user}/video/{id}</code>, <code>tiktok.com/embed/{id}</code>, <code>vm.tiktok.com/{id}</code>, <code>vt.tiktok.com/{id}</code>。<br>BiliBili: <code>bilibili.com/video/{id}</code>, <code>bilibili.com/bangumi/play/{id}</code>.<br><code>http://</code>, <code>https://</code>, <code>www.</code> 支持前缀和查询字符串</td></tr><tr><td><code>storage</code></td><td>对象</td><td>是</td><td>将结果交付到存储桶： <code>{"type": string, "url": string}</code>. <code>type</code> 是 <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>，或 <code>tos</code>。仅限异步。 <code>url</code> 不会被验证</td></tr><tr><td><code>video_quality</code></td><td>字符串</td><td>否</td><td><code>best</code>, <code>worst</code>，或分辨率： <code>144</code>, <code>360</code>, <code>480</code>, <code>720</code>, <code>1080</code>, <code>1440</code>, <code>2160</code> (4K)， <code>4320</code> (8K)。<br>默认：TikTok – <code>720</code>，BiliBili – <code>480</code>.</td></tr><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td>完成作业的 Webhook URL。格式错误的 URL 会被拒绝，并返回 <code>400</code></td></tr></tbody></table>

### YouTube

#### **`POST /v1/scrape/media/youtube/metadata`**

返回视频的标题、频道、描述、时长、观看数、点赞数和评论数、上传日期、类别、标签、章节、缩略图以及可用的字幕语言。

**模式：** `同步`, `异步`, `批量`

<table><thead><tr><th width="131">名称</th><th width="89">类型</th><th width="83">是否必填</th><th>描述</th></tr></thead><tbody><tr><td><code>query</code></td><td>字符串</td><td>是</td><td>视频 ID，例如 <code>tIgIF5lve8U</code>。不是 URL。在批量处理中，ID 数组</td></tr><tr><td><code>output</code></td><td>字符串数组</td><td>否</td><td><code>["json"]</code> （默认）返回解析后的元数据。 <code>["json", "html"]</code> 还返回页面源代码</td></tr><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td>仅异步模式。完成作业会发送到的 Webhook URL。格式错误的 URL 会被拒绝，并返回 <code>400</code></td></tr><tr><td><code>storage</code></td><td>对象</td><td>否</td><td>将结果传送到 bucket，而不是响应： <code>{"type": string, "url": string}</code>. <code>type</code> 是 <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>，或 <code>tos</code>。仅限异步。 <code>url</code> 不会被验证</td></tr></tbody></table>

已删除、私有或受限的视频返回 `state: "done"` 并返回空的 `results`。原因在 `results[0].metadata.statuses.video_download`，例如 `11202` （不可用）或 `11206` （年龄限制）。

#### **`POST /v1/scrape/media/youtube/subtitles`**

返回视频的字幕轨道，包含文本和时间信息，并按来源和语言分组。

**模式：** `同步`, `异步`, `批量`

<table><thead><tr><th width="155">名称</th><th width="84">类型</th><th width="82">是否必填</th><th>描述</th></tr></thead><tbody><tr><td><code>query</code></td><td>字符串</td><td>是</td><td>视频 ID，例如 <code>c4P_YuNnZ7U</code>。不是 URL。在批量处理中，ID 数组</td></tr><tr><td><code>language_code</code></td><td>字符串</td><td>否</td><td>字幕语言，例如 <code>en</code>。使用小写；未知代码会被拒绝，并返回 <code>400</code>。省略可获取所有语言</td></tr><tr><td><code>subtitle_origin</code></td><td>字符串</td><td>否</td><td><code>uploader_provided</code> 或 <code>auto_generated</code>。省略可同时获取两者</td></tr><tr><td><code>json</code></td><td>对象</td><td>否</td><td>自定义提取： <code>{"prompt": string}</code> 或 <code>{"schema": object}</code>，绝不会同时返回两者。若不指定，字幕轨道会按 YouTube 提供的方式返回</td></tr><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td>仅异步模式。完成作业会发送到的 Webhook URL。格式错误的 URL 会被拒绝，并返回 <code>400</code></td></tr><tr><td><code>storage</code></td><td>对象</td><td>否</td><td>将结果传送到 bucket，而不是响应： <code>{"type": string, "url": string}</code>. <code>type</code> 是 <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>，或 <code>tos</code>。仅限异步。 <code>url</code> 不会被验证</td></tr></tbody></table>

有效的 `language_code` 若没有匹配的轨道，则返回空结果（`{}`），不是错误。

#### **`POST /v1/async/scrape/media/youtube/download`**

将视频、其音频或任一内容的剪辑下载到你的云存储。

**模式：** `同步`, `异步`

<table><thead><tr><th width="150">名称</th><th width="87">类型</th><th width="83">是否必填</th><th>描述</th></tr></thead><tbody><tr><td><code>query</code></td><td>字符串</td><td>是</td><td>视频 ID，例如 <code>9cQBNYsCqQs</code>。不是 URL。在批量处理中，ID 数组</td></tr><tr><td><code>storage</code></td><td>对象</td><td>是</td><td><code>{"type": string, "url": string}</code>. <code>type</code> 是 <code>s3</code>, <code>gcs</code>, <code>s3_compatible</code> 或 <code>tos</code>. <code>url</code> 是存储桶和文件夹，例如 <code>bucket-name/folder/</code>；API 将文件命名为</td></tr><tr><td><code>output</code></td><td>字符串数组</td><td>否</td><td>以下之一 <code>["audio_video"]</code> （默认）， <code>["audio"]</code> 或 <code>["video"]</code></td></tr><tr><td><code>video_quality</code></td><td>字符串</td><td>否</td><td><code>best</code>, <code>worst</code>, <code>144</code>, <code>360</code>, <code>480</code>, <code>720</code>, <code>1080</code>, <code>1440</code>, <code>2160</code> 或 <code>4320</code>。默认值 <code>720</code>；如果没有 720p，则返回其下方的最佳质量</td></tr><tr><td><code>audio_language</code></td><td>字符串</td><td>否</td><td><code>default</code> （默认）或 <code>original</code>，当视频有配音时，则使用其原始音轨</td></tr><tr><td><code>start_at</code></td><td>字符串</td><td>否</td><td>片段开始时间，格式为 <code>hh:mm:ss</code>，例如 <code>00:01:30</code>。省略则从开头开始</td></tr><tr><td><code>end_at</code></td><td>字符串</td><td>否</td><td>片段结束时间，格式为 <code>hh:mm:ss</code>，例如 <code>00:05:45</code>。必须晚于 <code>start_at</code></td></tr><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td>完成作业的 Webhook URL</td></tr></tbody></table>

完成作业会在 `results[0].filename`中返回文件名。年龄限制视频返回 `state: "done"` 没有文件且状态 `11206` 中 `results[0].metadata.statuses.video_download`.

#### **`POST /v1/scrape/media/youtube/channel`**

返回频道的详细信息（名称、ID、订阅者数、视频和观看数、国家、加入日期、链接）及其最新视频。

**模式：** `同步`, `异步`

<table><thead><tr><th width="135">名称</th><th width="87">类型</th><th width="84">是否必填</th><th>描述</th></tr></thead><tbody><tr><td><code>query</code></td><td>字符串</td><td>是</td><td>频道句柄，例如 <code>@Oxylabs</code> （该 <code>@</code> 项为可选）。频道 ID（<code>UC…</code>）不受支持</td></tr><tr><td><code>limit</code></td><td>整数</td><td>否</td><td>要返回的视频数量。默认 <code>20</code>; <code>0</code> 仅返回频道详情</td></tr><tr><td><code>output</code></td><td>字符串数组</td><td>否</td><td><code>["json"]</code> 返回解析后的频道数据。 <code>["html"]</code> （默认）返回页面源代码。使用 <code>json</code>: <code>["markdown"]</code> 返回的内容几乎只有页面页脚</td></tr><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td>仅异步模式。完成作业会发送到的 Webhook URL。格式错误的 URL 会被拒绝，并返回 <code>400</code></td></tr><tr><td><code>storage</code></td><td>对象</td><td>否</td><td>将结果传送到 bucket，而不是响应： <code>{"type": string, "url": string}</code>. <code>type</code> 是 <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>，或 <code>tos</code>。仅限异步。 <code>url</code> 不会被验证</td></tr></tbody></table>

#### **`POST /v1/scrape/media/youtube/search`**

返回最多 20 条 YouTube 搜索结果。

**模式：** `同步`, `异步`

<table><thead><tr><th width="168">名称</th><th width="96">类型</th><th width="87">是否必填</th><th>描述</th></tr></thead><tbody><tr><td><code>query</code></td><td>字符串</td><td>是</td><td>搜索短语</td></tr><tr><td><code>upload_date</code></td><td>字符串</td><td>否</td><td><code>last_hour</code>, <code>today</code>, <code>this_week</code>, <code>this_month</code> 或 <code>this_year</code></td></tr><tr><td><code>type</code></td><td>字符串</td><td>否</td><td><code>video</code>, <code>channel</code>, <code>playlist</code> 或 <code>movie</code></td></tr><tr><td><code>duration</code></td><td>字符串</td><td>否</td><td><code>&#x3C;4</code> （少于 4 分钟）， <code>4-20</code> （4 到 20 分钟）或 <code>>20</code> （超过 20 分钟）</td></tr><tr><td><code>sort_by</code></td><td>字符串</td><td>否</td><td><code>relevance</code> （默认）， <code>upload_date</code>, <code>view_count</code> 或 <code>rating</code></td></tr><tr><td><code>360</code></td><td>布尔值</td><td>否</td><td>仅限 360° 视频</td></tr><tr><td><code>3d</code></td><td>布尔值</td><td>否</td><td>仅限 3D 视频</td></tr><tr><td><code>4k</code></td><td>布尔值</td><td>否</td><td>仅限 4K 视频</td></tr><tr><td><code>creative_commons</code></td><td>布尔值</td><td>否</td><td>仅限 Creative Commons 许可的视频</td></tr><tr><td><code>hd</code></td><td>布尔值</td><td>否</td><td>仅限 HD 视频</td></tr><tr><td><code>hdr</code></td><td>布尔值</td><td>否</td><td>仅限 HDR 视频</td></tr><tr><td><code>live</code></td><td>布尔值</td><td>否</td><td>仅限直播</td></tr><tr><td><code>location_tag</code></td><td>布尔值</td><td>否</td><td>仅包含带有位置标签的视频。若没有匹配项，则返回空列表</td></tr><tr><td><code>purchased</code></td><td>布尔值</td><td>否</td><td>仅限已购买内容</td></tr><tr><td><code>subtitles</code></td><td>布尔值</td><td>否</td><td>仅包含字幕或隐藏字幕的视频</td></tr><tr><td><code>vr180</code></td><td>布尔值</td><td>否</td><td>仅限 VR180 视频</td></tr><tr><td><code>location</code></td><td>字符串</td><td>否</td><td>用于获取结果的国家，使用两字母 ISO 代码，例如 <code>IN</code></td></tr><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td>仅异步模式。完成作业会发送到的 Webhook URL。格式错误的 URL 会被拒绝，并返回 <code>400</code></td></tr><tr><td><code>storage</code></td><td>对象</td><td>否</td><td>将结果传送到 bucket，而不是响应： <code>{"type": string, "url": string}</code>. <code>type</code> 是 <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>，或 <code>tos</code>。仅限异步。 <code>url</code> 不会被验证</td></tr></tbody></table>

#### **`POST /v1/scrape/media/youtube/search/max`**

在相同参数下返回最多 700 条搜索结果，与 `/search`相同，但成本和延迟更高。

**模式：** `同步`, `异步`

<table><thead><tr><th width="166">名称</th><th width="96">类型</th><th width="90">是否必填</th><th>描述</th></tr></thead><tbody><tr><td><code>query</code></td><td>字符串</td><td>是</td><td>搜索短语</td></tr><tr><td><code>upload_date</code></td><td>字符串</td><td>否</td><td><code>last_hour</code>, <code>today</code>, <code>this_week</code>, <code>this_month</code> 或 <code>this_year</code></td></tr><tr><td><code>type</code></td><td>字符串</td><td>否</td><td><code>video</code>, <code>channel</code>, <code>playlist</code> 或 <code>movie</code></td></tr><tr><td><code>duration</code></td><td>字符串</td><td>否</td><td><code>&#x3C;4</code> （少于 4 分钟）， <code>4-20</code> （4 到 20 分钟）或 <code>>20</code> （超过 20 分钟）</td></tr><tr><td><code>sort_by</code></td><td>字符串</td><td>否</td><td><code>relevance</code> （默认）， <code>upload_date</code>, <code>view_count</code> 或 <code>rating</code></td></tr><tr><td><code>360</code></td><td>布尔值</td><td>否</td><td>仅限 360° 视频</td></tr><tr><td><code>3d</code></td><td>布尔值</td><td>否</td><td>仅限 3D 视频</td></tr><tr><td><code>4k</code></td><td>布尔值</td><td>否</td><td>仅限 4K 视频</td></tr><tr><td><code>creative_commons</code></td><td>布尔值</td><td>否</td><td>仅限 Creative Commons 许可的视频</td></tr><tr><td><code>hd</code></td><td>布尔值</td><td>否</td><td>仅限 HD 视频</td></tr><tr><td><code>hdr</code></td><td>布尔值</td><td>否</td><td>仅限 HDR 视频</td></tr><tr><td><code>live</code></td><td>布尔值</td><td>否</td><td>仅限直播</td></tr><tr><td><code>location_tag</code></td><td>布尔值</td><td>否</td><td>仅包含带有位置标签的视频。若没有匹配项，则返回空列表</td></tr><tr><td><code>purchased</code></td><td>布尔值</td><td>否</td><td>仅限已购买内容</td></tr><tr><td><code>subtitles</code></td><td>布尔值</td><td>否</td><td>仅包含字幕或隐藏字幕的视频</td></tr><tr><td><code>vr180</code></td><td>布尔值</td><td>否</td><td>仅限 VR180 视频</td></tr><tr><td><code>location</code></td><td>字符串</td><td>否</td><td>用于获取结果的国家，使用两字母 ISO 代码，例如 <code>IN</code></td></tr><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td>仅异步模式。完成作业会发送到的 Webhook URL。格式错误的 URL 会被拒绝，并返回 <code>400</code></td></tr><tr><td><code>storage</code></td><td>对象</td><td>否</td><td>将结果传送到 bucket，而不是响应： <code>{"type": string, "url": string}</code>. <code>type</code> 是 <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>，或 <code>tos</code>。仅限异步。 <code>url</code> 不会被验证</td></tr></tbody></table>

#### **`POST /v1/scrape/media/youtube/autocomplete`**

返回 YouTube 对部分短语的搜索建议。

**模式：** `同步`, `异步`

<table><thead><tr><th width="135">名称</th><th width="84">类型</th><th width="89">是否必填</th><th>描述</th></tr></thead><tbody><tr><td><code>query</code></td><td>字符串</td><td>是</td><td>要补全的部分短语，例如 <code>how to make</code></td></tr><tr><td><code>location_tag</code></td><td>字符串</td><td>否</td><td>建议对应的国家，使用小写两字母代码，例如 <code>de</code></td></tr><tr><td><code>language</code></td><td>字符串</td><td>否</td><td>建议语言，例如 <code>en</code></td></tr><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td>仅异步模式。完成作业会发送到的 Webhook URL。格式错误的 URL 会被拒绝，并返回 <code>400</code></td></tr><tr><td><code>storage</code></td><td>对象</td><td>否</td><td>将结果传送到 bucket，而不是响应： <code>{"type": string, "url": string}</code>. <code>type</code> 是 <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>，或 <code>tos</code>。仅限异步。 <code>url</code> 不会被验证</td></tr></tbody></table>

#### **`POST /v1/scrape/media/youtube/video/trainability`**

返回视频声明的 AI 训练权限： `permitted` 是 `["all"]`, `["None"]`，或允许在其上训练的主体列表。

**模式：** `同步`, `异步`

<table><thead><tr><th width="135">名称</th><th width="75">类型</th><th width="85">是否必填</th><th>描述</th></tr></thead><tbody><tr><td><code>query</code></td><td>字符串</td><td>是</td><td>视频 ID，例如 <code>rFNDylrjn_w</code>。不是 URL</td></tr><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td>仅异步模式。完成作业会发送到的 Webhook URL。格式错误的 URL 会被拒绝，并返回 <code>400</code></td></tr><tr><td><code>storage</code></td><td>对象</td><td>否</td><td>将结果传送到 bucket，而不是响应： <code>{"type": string, "url": string}</code>. <code>type</code> 是 <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>，或 <code>tos</code>。仅限异步。 <code>url</code> 不会被验证</td></tr></tbody></table>

该信号由权利持有人声明，不代表法律许可。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/api-reference/cn/zhuan-yong-zhua-qu-qi/mei-ti-zhua-qu-qi.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.