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

# 视频下载器

> 将视频下载到您的存储空间

Decodo 视频下载器（`target: youtube_video`）可用于下载并保存指定的 YouTube 视频到 S3 兼容存储中。

<Tip>
  要获取访问权限，请[联系我们的销售团队](https://decodo.cn/scraping#contact-sales)
</Tip>

## youtube\_video

<Note>
  * `youtube_video` 目标仅支持[异步](https://help.decodo.com/docs/cn/web-scraping-api-asynchronous-requests#/)和[批量](https://help.decodo.com/docs/cn/web-scraping-api-asynchronous-requests#/)集成。
  * 批量 `youtube_video` 请求限制为每次请求 100 个视频。
  * 支持下载 12 小时或更短的视频。
  * 下载时间限制为 10 小时。
</Note>

将 **YouTube 视频**下载到 Amazon S3 兼容的存储位置。

| 参数           | 类型     | 必需 | 描述                                                                                | 默认值           | 示例                                     |
| ------------ | ------ | -- | --------------------------------------------------------------------------------- | ------------- | -------------------------------------- |
| `target`     | string | ✅  | 选择 YouTube 下载所需。                                                                  |               | `youtube_video`                        |
| `query`      | string | ✅  | YouTube 视频 ID。                                                                    |               | `dFu9aKJoqGg`                          |
| `upload_url` | string | ✅  | S3 兼容存储位置的 URL。                                                                   |               | `https://<key>:<secreat>@<bucket-url>` |
| `media`      | string |    | 选择无声音的 `video`、`audio` 或包含两者的 `audio_video`。                                      | `audio_video` |                                        |
| `quality`    | string |    | 视频或音频的质量。有效选项：`best`、`worst`、`144`、`360`、`480`、`720`、`1080`、`1440`、`2160`、`4320`。 | `720`         |                                        |
| `start_time` | string |    | 设置 `hh:mm:ss` 格式的时间戳，作为部分视频下载的起始时间。                                               |               | `06:16:43`                             |
| `end_time`   | string |    | 设置 `hh:mm:ss` 格式的时间戳，作为部分视频下载的结束时间。                                               |               | `10:00:00`                             |

<CodeGroup>
  ```shellscript cURL theme={null}
  # 将 'TOKEN VALUE' 更新为您的授权令牌
  curl --request 'POST' \
          --url 'https://scraper-api.decodo.com/v2/task' \
          --header 'Accept: application/json' \
          --header 'Authorization: Basic TOKEN VALUE' \
          --header 'Content-Type: application/json' \
          --data '
      {
        "target": "youtube_video",
        "query": "PFRn5zKJTD8",
        "upload_url": "https://storage_username:[email protected]/video-folder"
      }
  '
  ```
</CodeGroup>

## 传送到 S3

您可以通过 `upload_url` 参数提供一些参数，将视频直接下载到您的 S3 存储桶中。在以下步骤中，我们将把示例视频上传到新存储桶。

<Note>
  如果可以的话，我们建议为视频下载创建一个新存储桶。也就是说，以下步骤也适用于现有存储桶。
</Note>

要开始下载视频：

1. 使用默认设置和权限创建新的 S3 存储桶。
2. [创建新的 IAM 用户](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html)。
3. 在 IAM 用户上为您的存储桶附加 `PutObject` 权限：
   1. 添加内联策略：
      <Frame>
        <img src="https://mintcdn.com/decodo/eRLuBYAbadfvmqDE/images/docs/2adf3a13f937409e2880eef980c9c6d431283b05d19b5a2737e1acd327cf6885-aws_01.png?fit=max&auto=format&n=eRLuBYAbadfvmqDE&q=85&s=3445290941a84af30ee6069f18a4e712" alt="" width="1384" height="291" data-path="images/docs/2adf3a13f937409e2880eef980c9c6d431283b05d19b5a2737e1acd327cf6885-aws_01.png" />
      </Frame>
   2. 在服务下，选择 S3。
   3. 在操作下：
      1. 需要将以下权限添加到存储桶：
         * `GetBucketLocation`
      2. 需要将以下权限添加到存储桶的文件夹：
         * `PutObject`
         * `PutObjectAcl`
   4. 在资源下，选择特定，点击添加 ARN，添加您的存储桶名称和视频文件夹名称：
      <Frame>
        <img src="https://mintcdn.com/decodo/eRLuBYAbadfvmqDE/images/docs/1ac1fadb9c67eba6dc99ea3d409b79f6ce62437eafe016035196e0cff6b23275-aws_02.png?fit=max&auto=format&n=eRLuBYAbadfvmqDE&q=85&s=b21a99953aeea4bf29d96b988d302004" alt="" width="939" height="428" data-path="images/docs/1ac1fadb9c67eba6dc99ea3d409b79f6ce62437eafe016035196e0cff6b23275-aws_02.png" />
      </Frame>
   5. 您的最终策略声明应如下所示：
      ```text theme={null}
      {
      	"Version": "2012-10-17",
      	"Statement": [
      		{
      			"Sid": "Statement01",
      			"Effect": "Allow",
      			"Action": "s3:GetBucketLocation"
      			"Resource": "arn:aws:s3:::your-bucket"
      		},
      		{
      			"Sid": "Statement02",
      			"Effect": "Allow",
      			"Action": [
      				"s3:PutObject",
      				"s3:PutObjectAcl"
      			],
      			"Resource": "arn:aws:s3:::your-bucket/*"
      		}
      	]
      }
      ```
4. 为该用户[生成访问密钥和密钥](https://docs.aws.amazon.com/keyspaces/latest/devguide/create.keypair.html)。
   1. 当询问用例时，选择其他。
   <Warning>
     发送到 Scraper API 的访问密钥不能包含任何可能与 `upload_url` 参数冲突的非 URI 转义字符，例如 `/` 或 `@`。如果 AWS 生成的密钥包含此类字符，请重新生成您的密钥。
   </Warning>
5. 使用以下示例参数调用 Scraper API：

```text theme={null}
{
    "target": "youtube_video",
    "query": "PFRn5zKJTD8",
    "upload_url": "https://access_key:[email protected]/video-folder"
}
```

注意事项：

* `access_key` 和 `access_secret` 从第 4 步生成。
* `us-west-2` 用作示例区域，您的 AWS 区域可能不同。
* 必须提供 `/video-folder`。

## S3 兼容提供商

以下是一些 S3 兼容提供商，它们也可以与此目标开箱即用：

* [MinIO](https://min.io)
* [Wasabi](https://wasabi.com)
* [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces)
* [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html)
* [Scaleway Object Storage](https://www.scaleway.com/en/object-storage/)
* [Linode Object Storage](https://www.linode.com/products/object-storage/)
* [IBM Cloud Object Storage](https://www.ibm.com/cloud/object-storage)
* [Oracle Cloud Object Storage](https://www.oracle.com/cloud/storage/object-storage.html)
* [Hetzner Cloud Storage](https://www.hetzner.com/storage)

<Warning>
  Scraper API 目前不支持：

  * 显示下载进度（已完成/剩余百分比）
  * 指示上传到 `upload_url` 失败的情况（无效凭据、找不到存储桶等）

  即使上传到 `upload_url` 失败，请求仍会收费 - 我们建议先使用小视频进行测试。
</Warning>

## 示例请求

<CodeGroup>
  ```shellscript cURL theme={null}
  # 将 'TOKEN VALUE' 更新为您的授权令牌
  curl --request 'POST' \
          --url 'https://scraper-api.decodo.com/v2/task' \
          --header 'Accept: application/json' \
          --header 'Authorization: Basic Authentication Token' \
          --header 'Content-Type: application/json' \
          --data '
      {
        "target": "youtube_video",
        "query": "PFRn5zKJTD8",
        "upload_url": "https://storage_username:[email protected]/video-folder"
      }
  '
  ```
</CodeGroup>

成功排队的作业将返回类似以下的响应：

```text theme={null}
{
    "target": "youtube_video",
    "query": "PFRn5zKJTD8",
    "page_from": 1,
    "limit": 10,
    "geo": null,
    "device_type": "desktop",
    "headless": null,
    "parse": false,
    "locale": null,
    "domain": "com",
    "output_schema": null,
    "created_at": "2025-07-01 11:09:53",
    "id": "7345770621134969857",
    "status": "pending",
    "content_encoding": "utf-8",
    "updated_at": "2025-07-01 11:09:53",
    "force_headers": false,
    "force_cookies": false,
    "headers_cookies_policy": false,
    "media": "audio_video",
    "quality": "720"
}
```

## 访问地理限制视频

Scraper API 会尝试自动选择下载地理限制视频的最佳位置。但是，YouTube 视频不会公开有关给定视频限制到哪个地理位置的信息，因此，Scraper API 可能会在固定次数的尝试后失败。可能需要手动重试抓取请求。

## 监控进度

可以通过 `https://scraper-api.decodo.com/v3/task/{task_id}/results` 端点检查排队视频下载的状态（您可以在创建任务后的响应正文中找到 `id`）：

* HTTP 状态码 204 表示下载仍在处理中。
* HTTP 状态码 200 表示下载已完成，并已尝试上传到您的存储目录。如果视频未成功上传，响应中的 `status_code` 将提供具体原因；即使请求失败，仍会按尝试获取视频所使用的流量计费：

| **状态码** | **描述**               |
| :------ | :------------------- |
| 11201   | 视频已被删除               |
| 11202   | 视频不可用                |
| 11203   | 视频为私密视频              |
| 11204   | 视频受地理位置限制            |
| 11205   | 视频正在直播中              |
| 11206   | 视频有年龄限制              |
| 11207   | 视频仅限频道会员观看           |
| 11208   | 视频需要 YouTube Premium |
| 11209   | 视频为直播或时长过长           |
| 11210   | 视频时长过长               |
| 11211   | 需要登录                 |

<Info>
  流量按完成下载所移动的总数据计费：包括视频文件本身，以及获取视频所需的少量不可避免的传输数据。这部分额外数据因视频而异，具体取决于源平台的传输方式，因此总流量通常会略高于存储中最终文件的大小。
</Info>

***

<Columns cols={2}>
  <Card title="支持" href="https://direct.lc.chat/12092754" cta="让我们聊聊！">
    需要帮助或只是想打个招呼？我们的支持团队全天候为您服务。 \
    您也可以随时通过电子邮件 [support@decodo.com](mailto:support@decodo.com) 联系我们。
  </Card>

  <Card title="反馈" href="mailto:feedback@decodo.com" cta="分享反馈">
    找不到您要找的内容？请求一篇文章！ \
    有反馈意见？分享您对我们如何改进的想法。
  </Card>
</Columns>