The youtube_download
source delivers the audio/video content of a YouTube video of your choice. Please note that due to the potentially large data volume this source is only available via the asynchronous and the feature.
How YouTube Downloader works
Submit via API:
One or more YouTube video IDs;
Get the API response with the confirmation that your request to download a video has been successfully accepted.
Get the videos in the specified cloud storage location as soon as they're processed by our system.
Note :
The downloader defaults to 720p video resolution. If 720p is not available, the downloader will pick the best available quality below 720p. You can override this behaviour by using the context: video_quality
parameter.
You can download videos of up to 3 hours in length.
The download time is limited to 1 hour.
Parameter
Description
Default value
Storage type of the cloud service (gcs
, s3
or s3_compatible
)
The bucket name (for AWS S3) or the URL (for other S3-compatible storage) of the cloud storage location you would like the result uploaded to.
Specifies whether to download audio
, video
, or both - audio_video
.
Sets video quality: best
, worst
, or a resolution - 480
, 720
, 1080
, 1440
, 2160(4K)
.
Submitting a single job
Endpoint
Copy POST https://data.oxylabs.io/v1/queries
Provide the job parameters in a JSON payload as shown in the example below:
cURL Python PHP C# Golang Java Node.js
Copy 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/"
}'
Copy 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())
Copy <?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);
?>
Copy 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);
}
}
}
Copy 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))
}
Copy 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();
}
}
Copy 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());
Batch job
You can submit up to 5,000 video IDs within a single batch request.
Endpoint
Copy POST https://data.oxylabs.io/v1/queries/batch
IMPORTANT: With /batch
endpoint, you can only submit lists of query
parameter values. All other parameters should have singular values.
cURL Python PHP C# Golang Java Node.js
Copy 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/"
}'
Copy 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())
Copy <?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);
?>
Copy 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);
}
}
}
Copy 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))
}
Copy 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();
}
}
Copy 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());
The API will respond with a JSON object, containing the job information for each job created. The job status will be pending
until the download is completed.
Checking job status
Endpoint
Copy GET https://data.oxylabs.io/v1/queries/{id}
Cloud storage
Content files will appear in your cloud storage location and will be named according to the following naming schema: {video_id}_{job_id}.mp4
(for video) or {video_id}_{job_id}.m4a
(for audio).
Storage parameters
Parameter
Description
Valid values
s3
(AWS S3);
s3_compatible
(other S3-compatible storage solutions).
Any AWS S3 bucket name.
Any S3-compatible storage URL.
Amazon S3 setup
To get your job results uploaded to your Amazon S3 bucket, please set up access permissions for our service. To do that, go to https://s3.console.aws.amazon.com/ > S3 > Storage > Bucket Name (if don't have one, create a new one) > Permissions > Bucket Policy
Use the bucket policy below (don't forget to change the bucket name under YOUR_BUCKET_NAME
):
Copy {
"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/*"
}
]
}
This policy allows us to write to your bucket, give access to uploaded files to you, and know the location of the bucket.
S3-compatible storage setup
If you'd like to get your results delivered to an S3-compatible storage location, you will have to include your bucket's ACCESS_KEY:SECRET
auth string in the storage_url
value in the payload:
Copy {
"source": "youtube_transcript",
"query": "jyOeeCtPu64",
"storage_type": "s3_compatible",
"storage_url": "https://ACCESS_KEY:SECRET@s3.oxylabs.io/my-videos"
}
Google Cloud Storage setup
CommentGive feedback on the editorTo get your job results uploaded to your Google Cloud Storage bucket, please set up special permissions for our service.
To do that, create a custom role with the storage.objects.create
permission, and assign it to the Oxylabs service account email oxyserps-storage@oxyserps-storage.iam.gserviceaccount.com
.