# FlashData YouTube Download API

Download YouTube video or audio to your cloud storage. Choose resolution, format and clip duration, then track the asynchronous job through completion.

Canonical reference: https://flashdata.dev/docs/sources/youtube_download
Reviewed: 2026-10-23

Endpoint: POST https://data.flashdata.dev/v1/queries
Authentication: X-API-Key: YOUR_API_KEY
Modes: [Async](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/docs/reference/bulk-processing/reference.md)

Required source permission: youtube_download

Replace YOUR_API_KEY with an API key that has this source permission and available credits. Run requests on your server or agent host.

[Set up authentication](https://flashdata.dev/docs/guides/headers-and-authentication/reference.md)

[Download one video and verify delivery](https://flashdata.dev/docs/guides/download-video-recipe/reference.md)

[YouTube Video Download API — Python examples](https://github.com/flashdatadev/youtube-video-download-api)

<a id="quickstart"></a>

## Send a request

### Python

```bash
python3 -m pip install requests
```

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_download",
    "video_id": "jNQXAC9IVRw",
    "params": {
        "download_type": "audio_video",
        "video_quality": "<=720",
        "output_format": "mp4",
        "storage": {
            "storage_type": "s3",
            "storage_url": "your-media-bucket",
            "access_key": "YOUR_ACCESS_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "region": "us-east-1",
        },
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "video_quality": "<=720",
    "output_format": "mp4",
    "storage": {
      "storage_type": "s3",
      "storage_url": "your-media-bucket",
      "access_key": "YOUR_ACCESS_KEY",
      "secret_key": "YOUR_SECRET_KEY",
      "region": "us-east-1"
    }
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## Parameters

<a id="parameters-group-0"></a>

### Request body

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Yes | — | Set to youtube_download.  |
| <a id="parameter-video_id"></a> video_id | string | Yes | Not set | The 11-character YouTube video ID, such as FUfGcZ092b0. Accepts letters, numbers, underscores and hyphens. Min length: 11. Max length: 11. Pattern: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Yes | — | Settings for this request.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | No | Not set | Async and batch only. Public HTTPS completion URL on port 443, up to 2,048 characters. No user credentials or URL fragment. Omit, use null or an empty string for no notification. In a batch, set this on each query, outside params.  |

<a id="parameters-group-1"></a>

### Video & audio

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-download_type"></a> params.download_type | string | No | "audio_video" | audio_video merges video and audio; video selects video only; audio selects audio only. Allowed: "audio_video", "video", "audio". Min length: 1. Max length: 11. |
| <a id="parameter-params-video_quality"></a> params.video_quality | string | No | "<=720" | Video resolution selection. Omit for audio-only downloads. Allowed: "best", "worst", "<=144", "==144", ">=144", "<=360", "==360", ">=360", "<=480", "==480", ">=480", "<=720", "==720", ">=720", "<=1080", "==1080", ">=1080", "<=1440", "==1440", ">=1440", "<=2160", "==2160", ">=2160", "<=4320", "==4320", ">=4320". Min length: 1. Max length: 40. |
| <a id="parameter-params-fps"></a> params.fps | string | No | Not set | Frame-rate constraint: >=, <= or == followed by a value from 1 to 240. Omit for audio-only downloads. Min length: 1. Max length: 6. Pattern: ^(?:>=\|<=\|==)(?:[1-9]\d?\|1\d\d\|2[0-3]\d\|240)$ |
| <a id="parameter-params-audio_language"></a> params.audio_language | string | No | "default" | Audio track selection. Applies to audio_video and audio. Allowed: "default", "original". Min length: 1. Max length: 8. |
| <a id="parameter-params-audio_quality"></a> params.audio_quality | string | No | "best" | Audio-only bitrate in kbps, or best. Numeric choices must be sent as strings. Omit for video downloads. Allowed: "best", "320", "256", "192", "128". Min length: 1. Max length: 10. |
| <a id="parameter-params-output_format"></a> params.output_format | string | No | mp4 (video) / m4a (audio) | Video: mp4, webm or mkv. Audio: m4a, mp3 or opus. Allowed: "mp4", "webm", "mkv", "m4a", "mp3", "opus". Min length: 1. Max length: 10. |
| <a id="parameter-params-yt_dlp_format"></a> params.yt_dlp_format | string | No | Not set | Advanced format selector, from 1 to 1,024 characters after trimming whitespace. Control characters are rejected. Overrides video_quality, fps and audio_language, whose values are then ignored; output format and clipping still apply. Min length: 1. Max length: 1024. |
| <a id="parameter-params-upload_metadata"></a> params.upload_metadata | boolean | No | false | Upload a metadata JSON file alongside the media file in your storage.  |

<a id="parameters-group-2"></a>

### Clipping

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-start_at"></a> params.start_at | string | No | Not set | Clip start in H:MM:SS or HH:MM:SS format, from 00:00:00 to 12:00:00. Defaults to 00:00:00 when only end_at is supplied. Min length: 1. Max length: 8. Pattern: ^\d{1,2}:[0-5]\d:[0-5]\d$ |
| <a id="parameter-params-end_at"></a> params.end_at | string | No | Not set | Clip end in H:MM:SS or HH:MM:SS format, up to 12:00:00. Must be later than start_at. Min length: 1. Max length: 8. Pattern: ^\d{1,2}:[0-5]\d:[0-5]\d$ |

<a id="parameters-group-3"></a>

### Storage destination

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-storage"></a> params.storage | object | Yes | — | Destination for completed media files. Only the listed storage fields are accepted.  |
| <a id="parameter-params-storage-storage_type"></a> params.storage.storage_type | string | Yes | — | Storage provider: s3, s3_compatible, oss, gcs, azure, cos, bos or tos.  |
| <a id="parameter-params-storage-storage_url"></a> params.storage.storage_url | string | Yes | — | Non-empty bucket or container name, up to 1,024 characters. Surrounding whitespace is removed. For s3, use a valid AWS bucket name without a URL or folder path; folders belong in object_prefix.  |
| <a id="parameter-params-storage-object_prefix"></a> params.storage.object_prefix | string | No | "YYYYMMDD" | Object-key prefix, 1 to 512 characters. Each slash-separated segment accepts ASCII letters, digits, dots, underscores and hyphens; empty segments, . and .. are rejected. No leading slash. Surrounding whitespace and one trailing slash are removed. YYYYMMDD uses the UTC upload date, including in archive/YYYYMMDD.  |
| <a id="parameter-params-storage-access_key"></a> params.storage.access_key | string | No | — | Access key for S3, S3-compatible, OSS, COS, BOS or TOS; paired with secret_key.  |
| <a id="parameter-params-storage-secret_key"></a> params.storage.secret_key | string | No | — | Secret key for S3, S3-compatible, OSS, COS, BOS or TOS.  |
| <a id="parameter-params-storage-endpoint_url"></a> params.storage.endpoint_url | string | No | — | Public HTTPS endpoint for S3-compatible storage or OSS. COS, BOS and TOS derive it from region.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | No | — | Required for COS, BOS and TOS; also supply for S3 and S3-compatible downloads. COS bucket names include the APPID.  |
| <a id="parameter-params-storage-service_account"></a> params.storage.service_account | object | No | — | GCS service account: project_id, client_email and PEM private_key.  |
| <a id="parameter-params-storage-account_name"></a> params.storage.account_name | string | No | — | Azure storage account name. Use the container name in storage_url.  |
| <a id="parameter-params-storage-sas_token"></a> params.storage.sas_token | string | No | — | Write-enabled Azure container SAS with expiry and signature.  |

<a id="response"></a>

## Read the result

After the job completes, save the JSON from its results link as response.json. Save this as read-response.py and run python read-response.py. It reads file details without downloading media or making another request.

### read-response.py

```python
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = {name: result.get(name) for name in (
    "file_url", "file_size", "md5", "duration", "output_format"
)}
# Use your storage credentials to access the media at file_url.
print(json.dumps(output, ensure_ascii=False, indent=2))
```

## Sample submission

Recorded example; fields and counts depend on the source and requested input.
```json
{
  "id": "job_d265c693-950e-40bf-a13e-a432044d99ba",
  "source": "youtube_download",
  "status": "pending",
  "usage": {
    "credits": 0
  },
  "created_at": "2026-09-16T07:51:13.139Z",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_d265c693-950e-40bf-a13e-a432044d99ba",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_d265c693-950e-40bf-a13e-a432044d99ba/results",
      "method": "GET"
    }
  ]
}
```

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| id | string | Download job ID. |
| source | string | youtube_download. |
| status | string | pending when the job is accepted. |
| created_at | string | Job creation time in ISO 8601 format. |
| usage.credits | number | 0 at submission. Downloads are charged by delivered data volume after completion. |
| links | array | Follow the self link for job status and the results link for completed output. |
| links[].rel | string | self or results. |
| links[].href | string | URL to query with the same API key. |
| links[].method | string | GET. |

- Downloads run as background jobs. The submission response contains a job ID; it does not contain the media file. Follow the job status until completion, then retrieve the result describing the files delivered to your storage. Submit downloads to /v1/queries or /v1/queries/batch; /v1/queries/realtime does not accept download requests.

## Response formats

Responses use JSON by default. Choose another format with these optional headers.

- Accept: application/json (default) or text/plain. Plain text presents the same fields in a readable, indented layout.
- X-Respond-With: markdown. Leave unset for original fields. Markdown works with either response format.

Markdown formats the download manifest; media files keep their original format. Receipts and job status support Accept only.

The fields below describe the default JSON response.

[Request and response format examples](https://flashdata.dev/docs/guides/response-formats/reference.md#completed-results)

<a id="storage"></a>

## Storage destination

Single-job and Batch downloads require params.storage; Bulk downloads use options.storage. storage_url is the bucket or container name. Supply credentials with write access and keep them on your server.

### s3

Supply access_key and secret_key with write access. Set region to your bucket's AWS region.

```json
{
  "storage_type": "s3",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1"
}
```

### s3_compatible

Supply access_key, secret_key and a public HTTPS endpoint_url. Set region as required by your provider; Cloudflare R2 uses auto.

```json
{
  "storage_type": "s3_compatible",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "endpoint_url": "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
  "region": "auto"
}
```

### azure

Supply account_name and sas_token, a container SAS with write permission (sp includes w), resource sr=c, expiry se, version sv and signature sig. storage_url is the container name. Do not send endpoint_url, access_key or secret_key.

```json
{
  "storage_type": "azure",
  "storage_url": "your-media-container",
  "account_name": "yourstorageaccount",
  "sas_token": "sv=2023-11-03&sr=c&sp=w&se=2099-01-01T00%3A00%3A00Z&sig=YOUR_SAS_SIGNATURE"
}
```

### bos

Supply access_key, secret_key and region: bj, su or hkg. The endpoint is derived from region when omitted. Use a bucket name without dots.

```json
{
  "storage_type": "bos",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "bj"
}
```

### cos

Supply access_key, secret_key and an ap-* region, such as ap-hongkong. storage_url must include the APPID suffix. Do not send endpoint_url; it is derived from region.

```json
{
  "storage_type": "cos",
  "storage_url": "your-media-bucket-1234567890",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "ap-hongkong"
}
```

### gcs

Supply service_account with project_id, client_email (a .gserviceaccount.com address), and the PEM private_key from your service account. The account must have write access to the bucket. Do not send access_key, secret_key, region or endpoint_url.

```json
{
  "storage_type": "gcs",
  "storage_url": "your-media-bucket",
  "service_account": {
    "project_id": "your-project-id",
    "client_email": "uploader@your-project-id.iam.gserviceaccount.com",
    "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n"
  }
}
```

### oss

Supply access_key, secret_key and the bucket region's public HTTPS endpoint_url.

```json
{
  "storage_type": "oss",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "endpoint_url": "https://oss-cn-hongkong.aliyuncs.com"
}
```

### tos

Supply access_key, secret_key and region with a cn-, ap-, eu- or us- prefix. The endpoint is derived from region when omitted. Use a bucket name without dots.

```json
{
  "storage_type": "tos",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "cn-beijing"
}
```

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## API basics

The request builder and examples above use this source's parameters. Use the Python and cURL examples below for shared submission, status and result steps. A Batch body is a JSON object containing queries; each item returns its own job ID.

- [Async request and receipt](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [Check job status](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [Retrieve completed results](https://flashdata.dev/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON requests](https://flashdata.dev/docs/reference/batch-and-bulk/reference.md#batch)
- [Bulk processing API](https://flashdata.dev/docs/reference/bulk-processing/reference.md)
- [Build a Bulk workflow for this source](https://flashdata.dev/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)
- [Customer OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## Completion notifications

- [Receive and verify completion webhooks](https://flashdata.dev/docs/guides/async-batch/reference.md#webhooks)

<a id="troubleshooting"></a>

## Troubleshooting

- [Errors and status codes](https://flashdata.dev/docs/errors/reference.md#status-codes)
- [When to retry](https://flashdata.dev/docs/errors/reference.md#retries)

<a id="delivery"></a>

## File delivery

Download does not support realtime.

Media is uploaded to your configured storage; result JSON describes those files. Private media uses your storage authentication. JSON results expire 24 hours after completion; media follows your storage retention policy.

## Related APIs

- [YouTube Video Metadata API](https://flashdata.dev/docs/sources/youtube_metadata/reference.md)
- [YouTube Transcript API](https://flashdata.dev/docs/sources/youtube_transcript/reference.md)
