下载器

通过视频 ID 下载 YouTube 音频和视频内容，视频质量最高可配置至 8K，并直接交付至您的云存储。

该 youtube_download 该数据源提供您所选 YouTube 视频的音频/视频内容。请注意，由于数据量可能较大，此数据源仅可通过异步 Push-Pull 集成 以及 云存储 功能。

YouTube Downloader 的工作原理

1. 通过 API 提交：

   • 一个或多个 YouTube 视频 ID；
   • 云存储详情。
2. 获取 API 响应，其中确认您的视频下载请求已成功接受。
3. 视频一经我们的系统处理完毕，即会保存到指定的云存储位置。

注意:

• 下载器默认使用 720p 视频分辨率。如果 720p 不可用，下载器会选择低于 720p 的最佳可用质量。您可以通过使用 上下文：video_quality参数。
• 您最多可以下载 12 小时长的视频。
• 下载时间限制为 1 小时。

输入参数值

参数	描述	默认值
source	设置抓取器。使用 youtube_download.	–
query	YouTube 视频 ID。	–
storage_type	云服务的存储类型（gcs, s3 或 s3_compatible)	–
storage_url	您希望结果上传到的云存储位置的存储桶名称（适用于 AWS S3）或 URL（适用于其他 S3 兼容存储）。	–
callback_url	您的回调端点 URL。 更多信息	–
上下文： download_type	指定是否下载 音频, 视频，或两者都下载 - audio_video.	audio_video
上下文： video_quality	设置视频质量： best, worst，或一个分辨率： 144, 360, 480, 720, 1080, 1440, 2160(4K), 4320(8K)。	720
上下文：audio_language	指定要下载的音轨。接受 default 或 original （视频的原始音轨）。	default
上下文： start_at	部分视频下载（剪辑）开始时间戳，位于 hh:mm:ss 格式。 了解更多.	–
上下文： end_at	部分视频下载（剪辑）结束时间戳，位于 hh:mm:ss 格式。必须晚于 start_at. 了解更多.	–

– 必填参数

提交单个任务

端点

POST https://data.oxylabs.io/v1/queries

输入

请按以下示例在 JSON 负载中提供任务参数：

cURL

curl --user "user:pass1" \\
'https://data.oxylabs.io/v1/queries' \\
-H "Content-Type: application/json" \\
-d '{
    "source": "youtube_download",
    "query": "9cQBNYsCqQs",
    "storage_type": "s3",
    "storage_url": "s3://your-s3-bucket/your-folder/"
}'

Python

import requests
from pprint import pprint

payload = {
    "source": "youtube_download",
    "query": "9cQBNYsCqQs",
    "context": [
        {
            "key": "download_type",
            "value": "video"
        },
        {
            "key": "video_quality",
            "value": "1080"
        }
    ],
    "storage_type": "s3",
    "storage_url": "s3://your-s3-bucket/your-folder/"
}

response = requests.request(
    'POST',
    'https://data.oxylabs.io/v1/queries',
    auth=('user', 'pass1'),
    json=payload,
)

pprint(response.json())

PHP

<?php

$params = array(
    'source' => 'youtube_download',
    'query' => '9cQBNYsCqQs',
    "context" => [
        [
            "key" => "download_type",
            "value" => "video",
        ],
        [
            "key" => "video_quality",
            "value" => "1080",
        ]
    ],
    'storage_type' => 's3',
    'storage_url' => 's3://your-s3-bucket/your-folder/'
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://data.oxylabs.io/v1/queries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "YOUR_USERNAME" . ":" . "YOUR_PASSWORD");

$headers = array();
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
echo $result;

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);
?>

C#

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace OxyApi
{
    class Program
    {
        static async Task Main()
        {
            const string Username = "YOUR_USERNAME";
            const string Password = "YOUR_PASSWORD";
            var payload = new Dictionary<string, object>()
            {
                { "source", "youtube_download" },
                { "query", "9cQBNYsCqQs" },
                { "context", new[] {
                    new { key = "download_type", value = "video" },
                    new { key = "video_quality", value = "1080" }
                }},
                { "storage_type", "s3" },
                { "storage_url", "your-s3-bucket/your-folder/" }
            };
            
            var client = new HttpClient();
            var requestMessage = new HttpRequestMessage(HttpMethod.Post, "https://data.oxylabs.io/v1/queries/batch");
            requestMessage.Content = JsonContent.Create(payload);
            
            var authenticationString = $"{Username}:{Password}";
            var base64EncodedAuthenticationString = Convert.ToBase64String(System.Text.ASCIIEncoding.UTF8.GetBytes(authenticationString));
            requestMessage.Headers.Add("Authorization", "Basic " + base64EncodedAuthenticationString);
            
            var response = await client.SendAsync(requestMessage);
            var contents = await response.Content.ReadAsStringAsync();
            Console.WriteLine(contents);
        }
    }
}

Go 语言

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	const Username = "YOUR_USERNAME"
	const Password = "YOUR_PASSWORD"

	// Define the context structure
	type ContextItem struct {
		Key   string `json:"key"`
		Value string `json:"value"`
	}

	// Create payload with the same structure as the C# example
	payload := map[string]interface{}{
		"source": "youtube_download",
		"query":  []string{"9cQBNYsCqQs", "KGOsWPF4Wfs"},
		"context": []ContextItem{
			{Key: "download_type", Value: "video"},
			{Key: "video_quality", Value: "1080"},
		},
		"storage_type": "s3",
		"storage_url":  "your-s3-bucket/your-folder/",
	}

	jsonValue, _ := json.Marshal(payload)
	client := &http.Client{}
	request, _ := http.NewRequest("POST",
		"https://data.oxylabs.io/v1/queries/batch",
		bytes.NewBuffer(jsonValue),
	)
	request.Header.Add("Content-type", "application/json")
	request.SetBasicAuth(Username, Password)
	response, _ := client.Do(request)
	responseText, _ := ioutil.ReadAll(response.Body)
	fmt.Println(string(responseText))
}

Java

package org.example;
import okhttp3.*;
import org.json.JSONArray;
import org.json.JSONObject;
public class Main implements Runnable {
    private static final String AUTHORIZATION_HEADER = "Authorization";
    public static final String USERNAME = "YOUR_USERNAME";
    public static final String PASSWORD = "YOUR_PASSWORD";
    public void run() {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("source", "youtube_download");
        jsonObject.put("query", "9cQBNYsCqQs");
        
        // Add context structure
        JSONArray contextArray = new JSONArray();
        
        JSONObject downloadTypeContext = new JSONObject();
        downloadTypeContext.put("key", "download_type");
        downloadTypeContext.put("value", "video");
        contextArray.put(downloadTypeContext);
        
        JSONObject videoQualityContext = new JSONObject();
        videoQualityContext.put("key", "video_quality");
        videoQualityContext.put("value", "1080");
        contextArray.put(videoQualityContext);
        
        jsonObject.put("context", contextArray);
        
        jsonObject.put("storage_type", "s3");
        jsonObject.put("storage_url", "your-s3-bucket/your-folder/");
        
        Authenticator authenticator = (route, response) -> {
            String credential = Credentials.basic(USERNAME, PASSWORD);
            return response
                    .request()
                    .newBuilder()
                    .header(AUTHORIZATION_HEADER, credential)
                    .build();
        };
        var client = new OkHttpClient.Builder()
                .authenticator(authenticator)
                .build();
        var mediaType = MediaType.parse("application/json; charset=utf-8");
        var body = RequestBody.create(jsonObject.toString(), mediaType);
        var request = new Request.Builder()
                .url("https://data.oxylabs.io/v1/queries/batch")
                .post(body)
                .build();
        try (var response = client.newCall(request).execute()) {
            assert response.body() != null;
            System.out.println(response.body().string());
        } catch (Exception exception) {
            System.out.println("Error: " + exception.getMessage());
        }
        System.exit(0);
    }
    public static void main(String[] args) {
        new Thread(new Main()).start();
    }
}

Node.js

import fetch from 'node-fetch';

const username = 'YOUR_USERNAME';
const password = 'YOUR_PASSWORD';
const body = {
  source: 'youtube_download',
  query: '9cQBNYsCqQs',
  context: [
    { key: "download_type", value: "video" },
    { key: "video_quality", value: "1080"},
  ],
  storage_type: 's3',
  storage_url: 's3://your-s3-bucket/your-folder/'
};
const response = await fetch('https://data.oxylabs.io/v1/queries', {
  method: 'post',
  body: JSON.stringify(body),
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64'),
  }
});

console.log(await response.json());

批量任务

您可以在单个批量请求中提交最多 5,000 个视频 ID。

端点

POST https://data.oxylabs.io/v1/queries/batch

重要： 使用 /batch 端点，您只能提交 query参数值列表。所有其他参数应使用单个值。

输入

cURL

curl --user "user:pass1" \\
'https://data.oxylabs.io/v1/queries/batch' \\
-H 'Content-Type: application/json' \\
-d '{
    "source": "youtube_download",
    "query": ["9cQBNYsCqQs", "KGOsWPF4Wfs"],
        "context": [
        {
            "key": "download_type",
            "value": "video"
        },
        {
            "key": "video_quality",
            "value": "1080"
        }
    ],
    "storage_type": "s3",
    "storage_url": "your-s3-bucket/your-folder/"
}'

Python

import requests
import json
from pprint import pprint

payload = {
    "source": "youtube_download",
    "query": ["9cQBNYsCqQs", "KGOsWPF4Wfs"],
    "context": [
        {
            "key": "download_type",
            "value": "video"
        },
        {
            "key": "video_quality",
            "value": "1080"
        }
    ],
    "storage_type": "s3",
    "storage_url": "your-s3-bucket/your-folder/"
}

response = requests.request(
    'POST',
    'https://data.oxylabs.io/v1/queries/batch',
    auth=('user', 'pass1'),
    json=payload,
)

# Print prettified response.
pprint(response.json())

PHP

<?php

$payload = array(
    "source" => "youtube_download",
    "query" => array("9cQBNYsCqQs", "KGOsWPF4Wfs"),
    "context" => [
        [
            "key" => "download_type",
            "value" => "video",
        ],
        [
            "key" => "video_quality",
            "value" => "1080",
        ]
    ],
    "storage_type" => "s3",
    "storage_url" => "your-s3-bucket/your-folder/"
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://data.oxylabs.io/v1/queries/batch");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "user" . ":" . "pass1");

$headers = array();
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
echo $result;

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);
?>

C#

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace OxyApi
{
    class Program
    {
        static async Task Main()
        {
            const string Username = "YOUR_USERNAME";
            const string Password = "YOUR_PASSWORD";
            var payload = new Dictionary<string, object>()
            {
                { "source", "youtube_download" },
                { "query", new[] { "9cQBNYsCqQs", "KGOsWPF4Wfs" } },
                { "context", new[] {
                    new { key = "download_type", value = "video" },
                    new { key = "video_quality", value = "1080" }
                }},
                { "storage_type", "s3" },
                { "storage_url", "your-s3-bucket/your-folder/" }
            };
            
            var client = new HttpClient();
            var requestMessage = new HttpRequestMessage(HttpMethod.Post, "https://data.oxylabs.io/v1/queries/batch");
            requestMessage.Content = JsonContent.Create(payload);
            
            var authenticationString = $"{Username}:{Password}";
            var base64EncodedAuthenticationString = Convert.ToBase64String(System.Text.ASCIIEncoding.UTF8.GetBytes(authenticationString));
            requestMessage.Headers.Add("Authorization", "Basic " + base64EncodedAuthenticationString);
            
            var response = await client.SendAsync(requestMessage);
            var contents = await response.Content.ReadAsStringAsync();
            Console.WriteLine(contents);
        }
    }
}

Go 语言

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	const Username = "YOUR_USERNAME"
	const Password = "YOUR_PASSWORD"

	// Define the context structure
	type ContextItem struct {
		Key   string `json:"key"`
		Value string `json:"value"`
	}

	// Create payload with the same structure as the C# example
	payload := map[string]interface{}{
		"source": "youtube_download",
		"query":  "9cQBNYsCqQs",
		"context": []ContextItem{
			{Key: "download_type", Value: "video"},
			{Key: "video_quality", Value: "1080"},
		},
		"storage_type": "s3",
		"storage_url":  "your-s3-bucket/your-folder/",
	}

	jsonValue, _ := json.Marshal(payload)
	client := &http.Client{}
	request, _ := http.NewRequest("POST",
		"https://data.oxylabs.io/v1/queries/batch",
		bytes.NewBuffer(jsonValue),
	)
	request.Header.Add("Content-type", "application/json")
	request.SetBasicAuth(Username, Password)
	response, _ := client.Do(request)
	responseText, _ := ioutil.ReadAll(response.Body)
	fmt.Println(string(responseText))
}

Java

package org.example;
import okhttp3.*;
import org.json.JSONArray;
import org.json.JSONObject;
public class Main implements Runnable {
    private static final String AUTHORIZATION_HEADER = "Authorization";
    public static final String USERNAME = "YOUR_USERNAME";
    public static final String PASSWORD = "YOUR_PASSWORD";
    public void run() {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("source", "youtube_download");
        
        // Change query to array format like in C# example
        JSONArray queryArray = new JSONArray();
        queryArray.put("9cQBNYsCqQs");
        queryArray.put("KGOsWPF4Wfs");
        jsonObject.put("query", queryArray);
        
        // Add context structure
        JSONArray contextArray = new JSONArray();
        
        JSONObject downloadTypeContext = new JSONObject();
        downloadTypeContext.put("key", "download_type");
        downloadTypeContext.put("value", "video");
        contextArray.put(downloadTypeContext);
        
        JSONObject videoQualityContext = new JSONObject();
        videoQualityContext.put("key", "video_quality");
        videoQualityContext.put("value", "1080");
        contextArray.put(videoQualityContext);
        
        jsonObject.put("context", contextArray);
        
        jsonObject.put("storage_type", "s3");
        jsonObject.put("storage_url", "your-s3-bucket/your-folder/");
        
        Authenticator authenticator = (route, response) -> {
            String credential = Credentials.basic(USERNAME, PASSWORD);
            return response
                    .request()
                    .newBuilder()
                    .header(AUTHORIZATION_HEADER, credential)
                    .build();
        };
        var client = new OkHttpClient.Builder()
                .authenticator(authenticator)
                .build();
        var mediaType = MediaType.parse("application/json; charset=utf-8");
        var body = RequestBody.create(jsonObject.toString(), mediaType);
        var request = new Request.Builder()
                .url("https://data.oxylabs.io/v1/queries/batch")
                .post(body)
                .build();
        try (var response = client.newCall(request).execute()) {
            assert response.body() != null;
            System.out.println(response.body().string());
        } catch (Exception exception) {
            System.out.println("Error: " + exception.getMessage());
        }
        System.exit(0);
    }
    public static void main(String[] args) {
        new Thread(new Main()).start();
    }
}

Node.js

import fetch from 'node-fetch';

const username = 'YOUR_USERNAME';
const password = 'YOUR_PASSWORD';

const payload = {
    source: 'youtube_download',
    query: ['9cQBNYsCqQs', 'KGOsWPF4Wfs'],
      context: [
        { key: "download_type", value: "video" },
        { key: "video_quality", value: "1080"},
      ]
    storage_type: 's3',
    storage_url: 'your-s3-bucket/your-folder/'
};

const response = await fetch('https://data.oxylabs.io/v1/queries/batch', {
    method: 'post',
    body: JSON.stringify(payload),
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64'),
    }
});

console.log(await response.json());

API 会返回一个 JSON 对象，其中包含每个已创建任务的任务信息。任务状态将为 pending ，直到下载完成。

检查任务状态

如果您提供了有效的 回调 URL 在提交任务时，我们会在完成后通过发送一个 JSON 负载到指定的回调 URL。

但是，如果您在未使用 回调服务，您可以手动检查任务状态。请从 href 字段中的 rel:self 任务提交后收到的响应消息的部分中获取。检查任务状态的 URL 将类似于以下内容： http://data.oxylabs.io/v1/queries/12345678900987654321. 查询此 URL 将返回任务信息，包括其当前 状态.

端点

GET https://data.oxylabs.io/v1/queries/{id}

部分下载（裁剪）

要下载特定片段或剪辑而不是完整视频，请向您的 上下文 数组：

• start_at – 裁剪片段的开始时间戳，位于 hh:mm:ss 格式。
• end_at – 裁剪片段的结束时间戳，位于 hh:mm:ss 格式。

end_at 时间戳值必须晚于 start_at。仅 hh:mm:ss 支持该格式。

{
    "source": "youtube_download",
    "query": "0xFXmJgVgzc",
    "context": [
        {
            "key": "start_at",
            "value": "00:01:30"
        },
        {
            "key": "end_at",
            "value": "00:05:45"
        }
    ],
    "storage_type": "s3",
    "storage_url": "s3://your-s3-bucket/your-folder/"
}

如果同时省略这两个参数，请求将按标准完整视频下载处理。

如果 start_at 或 end_at 未通过验证，HTTP 400 错误将返回，并带有一个 消息 字段。

条件	错误信息
start_at 不在 hh:mm:ss 格式	上下文中的 start_at 值无效。支持的格式：hh:mm:ss。
end_at 不在 hh:mm:ss 格式	上下文中的 end_at 值无效。支持的格式：hh:mm:ss。
end_at 不晚于 start_at	上下文中的 end_at 值无效。必须晚于 start_at。

云存储

您可以将 YouTube 视频传送到 Google Cloud Storage, Amazon S3, Alibaba Cloud OSS, 或 其他兼容 S3 的云存储.

内容文件将出现在您的云存储位置，并将按以下命名方案之一命名：

• {video_id}_{job_id}.mp4 – 用于视频
• {video_id}_{job_id}.m4a – 用于音频

存储参数

参数	描述	有效值
storage_type	您的云存储类型。	gcs (Google Cloud Storage); s3 (AWS S3); s3_compatible (其他兼容 S3 的存储解决方案)。
storage_url	您的云存储 URL	任何 s3 或 gcs 存储桶名称； 任何 兼容 S3 存储 URL。

Google Cloud Storage 设置

要将任务结果上传到您的 Google Cloud Storage 存储桶，请 为我们的服务设置特殊权限 如我们的 Google Cloud Storage 文档.

{
    "source": "youtube_download",
    "query": "9cQBNYsCqQs",
    "storage_type": "gcs",
    "storage_url": "bucket_name/path"
}

Amazon S3 设置

要将任务结果上传到您的 Amazon S3 存储桶，请为我们的服务设置访问权限。为此，请前往 https://s3.console.aws.amazon.com/ → S3 → 存储 → 存储桶名称 （如果您没有，请创建一个新的） → 权限 → 存储桶策略。您可以在我们的 Amazon S3 云文档.

请使用下面的存储桶策略（别忘了更改下方的存储桶名称 YOUR_BUCKET_NAME):

{
    "Version": "2012-10-17",
    "Id": "Policy1577442634787",
    "Statement": [
        {
            "Sid": "Stmt1577442633719",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::324311890426:user/oxylabs.s3.uploader"
            },
            "Action": "s3:GetBucketLocation",
            "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
        },
        {
            "Sid": "Stmt1577442633719",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::324311890426:user/oxylabs.s3.uploader"
            },
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
        }
    ]
}

此策略允许我们向您的存储桶写入内容，让您访问已上传的文件，并了解存储桶的位置。

Alibaba Cloud OSS 设置

为了将结果保存到您的 Alibaba Cloud 对象存储服务 (OSS)，您必须创建 ACCESS_KEY_ID 和 ACCESS_KEY_SECRET 并使用它们来构造存储 URL。请按照我们的 Alibaba Cloud OSS 文档 .

{
    "source": "youtube_download",
    "query": "9cQBNYsCqQs",
    "storage_type": "s3_compatible",
    "storage_url": "https://ACCESS_KEY_ID:ACCESS_KEY_SECRET@BUCKET_NAME.oss-REGION.aliyuncs.com/FOLDER_NAME"
}

兼容 S3 的存储设置

如果您希望将结果传送到 其他兼容 S3 的存储 位置，您需要包含您的存储桶的 ACCESS_KEY:SECRET 认证字符串在 storage_url payload 中的值：

{
    "source": "youtube_download",
    "query": "9cQBNYsCqQs",
    "storage_type": "s3_compatible",
    "storage_url": "https://ACCESS_KEY:[e-mail]/my-videos"
}

错误代码

代码	状态	描述
11201	VIDEO_DELETED	视频已删除。
11202	VIDEO_UNAVAILABLE	视频不可用。
11203	VIDEO_PRIVATE	上传者已将视频设为私密，只有他们本人和明确邀请的用户才能查看。
11204	VIDEO_GEO_RESTRICTED	视频受地域限制。
11205	VIDEO_LIVE	视频正在直播。
11206	VIDEO_AGE_RESTRICTED	视频有年龄限制。
11207	VIDEO_MEMBER_ONLY	视频仅限频道会员观看，观众需支付月度订阅费。
11208	VIDEO_PREMIUM_ONLY	视频需要 YouTube Premium 订阅。
11209	VIDEO_LIVE_OR_TOO_LONG	视频正在直播或过长，无法下载。
11210	VIDEO_TOO_LONG	视频过长，无法下载。
11211	VIDEO_SIGN_IN_REQUIRED	需要登录。