# FlashData YouTube Download API

Tải về YouTube Video hoặc âm thanh đến kho lưu trữ đám mây. Chọn độ phân giải, định dạng và đoạn clip trong suốt, rồi theo dõi công việc tiện ích qua việc hoàn thành.

Tài liệu tham khảo chính điển: https://flashdata.dev/vi/docs/sources/youtube_download
Xem lại: 2026-10-23

Điểm kết thúc: POST https://data.flashdata.dev/v1/queries
Xác thực: X-API-Key: YOUR_API_KEY
Chế độ: [Async](https://flashdata.dev/vi/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/vi/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/vi/docs/reference/bulk-processing/reference.md)

Cần thiết quyền truy cập nguồn: youtube_download

Thay thế YOUR_API_KEY với một API Chìa khóa mà có quyền sử dụng nguồn này và tín dụng sẵn có. Chạy yêu cầu trên máy chủ hay máy phục vụ.

[Đang thiết lập xác thực](https://flashdata.dev/vi/docs/guides/headers-and-authentication/reference.md)

[Tải một video và xác nhận giao hàng](https://flashdata.dev/vi/docs/guides/download-video-recipe/reference.md)

[API tải video YouTube — ví dụ Python](https://github.com/flashdatadev/youtube-video-download-api)

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

## Gửi một yêu cầu

### 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>

## Tham số

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

### Nội dung yêu cầu

| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Vâng | — | Thiết lập youtube_download.  |
| <a id="parameter-video_id"></a> video_id | string | Vâng | Chưa đặt | Hạt 11- Hồ sơ. YouTube video IDNhư FUfGcZ092b0. Chấp nhận chữ cái, số, điểm nhấn và dấu gạch nối. Chiều dài tối thiểu: 11. Chiều dài tối đa: 11. Mẫu: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Vâng | — | Settings cho yêu cầu này.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | Không | Chưa đặt | Async và chỉ một mẻ. Chung HTTPS hoàn tất URL trên cổng 443Đến 2,048 các nhân vật. Không có phân khúc người dùng hay URL. Omit, dùng null hoặc chuỗi rỗng không cho thông báo nào. Trong một mẻ, đặt nó trên mỗi câu hỏi, bên ngoài các tham số.  |

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

### Ảnh động và âm thanh

| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-download_type"></a> params.download_type | string | Không | "audio_video" | audio_video Kết hợp video và âm thanh; video chỉ chọn video; âm thanh chỉ chọn âm thanh. Cho phép: "audio_video", "video", "audio". Chiều dài tối thiểu: 1. Chiều dài tối đa: 11. |
| <a id="parameter-params-video_quality"></a> params.video_quality | string | Không | "<=720" | Lựa chọn độ phân giải video. Chỉ dùng để tải về âm thanh. Cho phép: "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". Chiều dài tối thiểu: 1. Chiều dài tối đa: 40. |
| <a id="parameter-params-fps"></a> params.fps | string | Không | Chưa đặt | & Hạn chế độ cao khung: >=, <= hay == theo sau bởi một giá trị từ 1 phải 240. Chỉ dùng để tải về âm thanh. Chiều dài tối thiểu: 1. Chiều dài tối đa: 6. Mẫu: ^(?:>=\|<=\|==)(?:[1-9]\d?\|1\d\d\|2[0-3]\d\|240)$ |
| <a id="parameter-params-audio_language"></a> params.audio_language | string | Không | "default" | Chọn âm thanh. Ứng dụng cho audio_video và âm thanh. Cho phép: "default", "original". Chiều dài tối thiểu: 1. Chiều dài tối đa: 8. |
| <a id="parameter-params-audio_quality"></a> params.audio_quality | string | Không | "best" | Chỉ bị cắn bởi tiếng kbps, hoặc tốt nhất. Các phần tử phải được lựa chọn theo chuỗi. Omit cho việc tải video. Cho phép: "best", "320", "256", "192", "128". Chiều dài tối thiểu: 1. Chiều dài tối đa: 10. |
| <a id="parameter-params-output_format"></a> params.output_format | string | Không | mp4 (video) / m4a (audio) | Video:mp4, webm hoặc mkv. Âm thanh: m4a,mp3 hoặc opus. Cho phép: "mp4", "webm", "mkv", "m4a", "mp3", "opus". Chiều dài tối thiểu: 1. Chiều dài tối đa: 10. |
| <a id="parameter-params-yt_dlp_format"></a> params.yt_dlp_format | string | Không | Chưa đặt | Trình chọn định dạng cấp cao, từ 1 phải 1,024 ký tự sau khi cắt bỏ không gian trắng. Các nhân vật điều khiển bị từ chối. Ghi đè video_quality, fps và audio_language, mà giá trị được bỏ qua; định dạng xuất và cắt xén vẫn được áp dụng. Chiều dài tối thiểu: 1. Chiều dài tối đa: 1024. |
| <a id="parameter-params-upload_metadata"></a> params.upload_metadata | boolean | Không | false | Tải siêu dữ liệu lên JSON Hồ sơ bên cạnh hồ sơ truyền thông trong kho của anh.  |

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

### Gỡ bỏ

| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-start_at"></a> params.start_at | string | Không | Chưa đặt | Bắt đầu với H:MM:SS hoặc HH:MM:SS định dạng, từ 00:00:00 phải 12:00:00. Mặc định 00:00:00 chỉ khi end_at được cung cấp. Chiều dài tối thiểu: 1. Chiều dài tối đa: 8. Mẫu: ^\d{1,2}:[0-5]\d:[0-5]\d$ |
| <a id="parameter-params-end_at"></a> params.end_at | string | Không | Chưa đặt | Clip kết thúc trong H:MM:SS hoặc HH:MM định dạngSS, đến 12:00:00. Chắc trễ hơn rồi. start_at. Chiều dài tối thiểu: 1. Chiều dài tối đa: 8. Mẫu: ^\d{1,2}:[0-5]\d:[0-5]\d$ |

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

### Đích kho lưu trữ

| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-storage"></a> params.storage | object | Vâng | — | Đích cho tập tin phương tiện đã hoàn tất. Chỉ có những khu kho lưu trữ được chấp nhận.  |
| <a id="parameter-params-storage-storage_type"></a> params.storage.storage_type | string | Vâng | — | Nhà cung cấp kho: S3, s3_compatible, oss, gcs, azure, cos, bos hoặc tos.  |
| <a id="parameter-params-storage-storage_url"></a> params.storage.storage_url | string | Vâng | — | Không rỗng xô hoặc tên hộp, đến 1,024 các nhân vật. Bao quanh không gian trắng đã bị phá hủy. Đối với s3, sử dụng một tên xô AWS hợp lệ mà không có một URL hoặc đường dẫn thư mục; thư mục thuộc về object_prefix.  |
| <a id="parameter-params-storage-object_prefix"></a> params.storage.object_prefix | string | Không | "YYYYMMDD" | Tiền tố quan trọng đối tượng, 1 phải 512 các nhân vật. Mỗi đoạn cắt ngang chấp nhận chữ cái, chữ số, chấm, dấu gạch nối và dấu gạch nối; đoạn trống, và... bị từ chối. Không được chém đầu. Bao quanh không gian trắng và một dấu vết được gỡ bỏ. YYYMMD sử dụng ngày tải lên UTC, bao gồm trong archive/YYYYMMDD.  |
| <a id="parameter-params-storage-access_key"></a> params.storage.access_key | string | Không | — | Phím truy cập cho S3, S3- Tương đương, OSS, COS, BOS hoặc TOS; kết hợp với secret_key.  |
| <a id="parameter-params-storage-secret_key"></a> params.storage.secret_key | string | Không | — | Chìa khóa bí mật cho S3, S3- Hợp lý, OSS, COS, BOS hay TOS.  |
| <a id="parameter-params-storage-endpoint_url"></a> params.storage.endpoint_url | string | Không | — | Chung HTTPS điểm kết thúc cho S3- Kho lưu trữ hoặc OSS tương ứng. COS, BOS và TOS lấy nó từ khu vực.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | Không | — | Cần thiết cho COS, BOS và TOS; cũng cung cấp cho S3 và S3- Tải về tương ứng. Tên xô COS bao gồm APPID.  |
| <a id="parameter-params-storage-service_account"></a> params.storage.service_account | object | Không | — | GCS Tài khoản dịch vụ: project_id, client_email PEM private_key.  |
| <a id="parameter-params-storage-account_name"></a> params.storage.account_name | string | Không | — | Azure tên tài khoản lưu trữ. Dùng tên hộp chứa trong storage_url.  |
| <a id="parameter-params-storage-sas_token"></a> params.storage.sas_token | string | Không | — | Ghi Azure Công-te-nơ có dấu và dấu hiệu.  |

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

## Đọc kết quả

Sau khi xong việc, hãy cứu lấy JSON từ kết quả của nó kết nối như response.json. Lưu cái này vào read-response.py và chạy python read-response.py. Nó đọc chi tiết tập tin mà không cần tải về phương tiện truyền thông hay yêu cầu khác.

### 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))
```

## & Gởi mẫu

Ví dụ được thu; trường và số phụ thuộc vào nguồn và yêu cầu nhập.
```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"
    }
  ]
}
```

## Trường đáp ứng

| Tìm kiếm | Kiểu | Mô tả |
| --- | --- | --- |
| id | string | Tải về ID. |
| source | string | youtube_download. |
| status | string | Chờ đợi khi công việc được chấp nhận. |
| created_at | string | Thời gian tạo việc làm theo định dạng ISO 8601. |
| usage.credits | number | 0 đang phục tùng. Tải về được tính bằng số lượng dữ liệu sau khi hoàn tất. |
| links | array | Theo liên kết tự liên kết đến trạng thái công việc và liên kết kết kết quả cho kết xuất hoàn tất. |
| links[].rel | string | bản thân hoặc kết quả. |
| links[].href | string | URL để truy vấn cùng một kiểu API Chìa khóa. |
| links[].method | string | GET. |

- Tải về Đáp ứng phục tùng chứa một công việc ID; nó không chứa tập tin phương tiện. Theo tình trạng công việc cho đến khi hoàn tất, sau đó lấy kết quả mô tả các tập tin được gửi đến kho của bạn. Gửi bản tải về /v1/queries hay /v1/queries/batch; /v1/queries/realtime không chấp nhận yêu cầu tải về.

## Định dạng phản hồi

Đáp ứng được dùng JSON theo mặc định. Chọn một định dạng khác với những đầu trang tùy chọn này.

- Accept: application/json (mặc định) hay text/plain. Văn bản thường trình bày cùng một lĩnh vực trong một bố trí có thể đọc được, được in lề.
- X-Respond-With: markdown. Hãy để lại chỗ trống cho những cánh đồng nguyên thủy. Markdown hoạt động với định dạng trả lời.

Markdown Định dạng danh sách việc tải về; các tập tin phương tiện giữ định dạng gốc. Hỗ trợ truy vấn và quản lý trạng thái công việc Accept Chỉ có điều.

Các trường bên dưới mô tả giá trị mặc định JSON Trả lời đi.

[Ví dụ định dạng đáp ứng yêu cầu](https://flashdata.dev/vi/docs/guides/response-formats/reference.md#completed-results)

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

## Đích kho lưu trữ

Công việc đơn lẻ và Batch Cần thiết tải về params.storage; Bulk tải về options.storage. storage_url là xô hay là tên container. Cung cấp thông tin về truy cập ghi và giữ chúng trên máy chủ của bạn.

### s3

Cung cấp access_key và secret_key với quyền ghi. Đặt khu vực vào khu vực AWS.

```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

Cung cấp access_key, secret_key và công chúng HTTPS endpoint_url. Đặt vùng như được yêu cầu bởi nhà cung cấp của bạn; Cloudflare R2 sử dụng xe hơi.

```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

Cung cấp account_name và sas_token, một container SaS với quyền ghi (sp bao gồm w), tài nguyên sr=c, expiry se, phiên bản sv và sig chữ ký. storage_url là tên container. Đừng gửi endpoint_url, access_key hay 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

Cung cấp access_key, secret_key và khu vực: bj, su hoặc hkg. Điểm cuối được lấy từ vùng bị bỏ qua. Dùng tên xô không dấu vết.

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

### cos

Cung cấp access_key, secret_key và một khu vực ap-*, chẳng hạn như ap-Hongkong. storage_url Phải bao gồm hậu tố APPID. Đừng gửi endpoint_url; nó bắt nguồn từ vùng.

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

### gcs

Cung cấp service_account có project_id, client_email (a.gserviceaccount.com địa chỉ) và PEM private_key từ tài khoản của anh. Chắc là tài khoản có ghi vào xô. Không gửi access_key, secret_keyvùng hoặc 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

Cung cấp access_key, secret_key và khu vực xô xô công cộng 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

Cung cấp access_key, secret_key và khu vực với một tiền tố cn-, ap-, eu-hoặc chúng ta. Điểm cuối được lấy từ vùng bị bỏ qua. Dùng tên xô không dấu vết.

```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>

## Kiến thức cơ bản về API

Các yêu cầu xây dựng và ví dụ trên sử dụng các tham số của nguồn này. Sử dụng Python và cURL Những ví dụ bên dưới để được chia sẻ sự phục tùng, địa vị và kết quả là bước. A Batch Cơ thể là một JSON Đối tượng chứa các đồ thị; mỗi món đồ trả lại công việc của chính mình ID.

- [Async yêu cầu và biên lai](https://flashdata.dev/vi/docs/reference/realtime-and-async/reference.md#async)

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

- [Kiểm tra tình trạng công việc](https://flashdata.dev/vi/docs/reference/realtime-and-async/reference.md#status)

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

- [Lấy kết quả hoàn tất](https://flashdata.dev/vi/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON yêu cầu](https://flashdata.dev/vi/docs/reference/batch-and-bulk/reference.md#batch)
- [API xử lý Bulk](https://flashdata.dev/vi/docs/reference/bulk-processing/reference.md)
- [Xây dựng a Bulk dòng làm việc cho nguồn này](https://flashdata.dev/vi/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)
- [Trình khách OpenAPI](https://flashdata.dev/docs/openapi.json)

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

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

## Thông báo đầy đủ

- [Nhận và kiểm tra hoàn tất kết nối web](https://flashdata.dev/vi/docs/guides/async-batch/reference.md#webhooks)

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

## Khắc phục sự cố

- [Lỗi và mã trạng thái](https://flashdata.dev/vi/docs/errors/reference.md#status-codes)
- [Khi nào cần thử lại](https://flashdata.dev/vi/docs/errors/reference.md#retries)

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

## Gửi tập tin

Tải về không hỗ trợ thời gian thực.

Vật chứa đã được tải lên kho đã cấu hình; kết quả JSON Mô tả những tập tin đó. Truyền thông tư nhân sử dụng xác thực lưu trữ của bạn. JSON Kết quả hết hạn 24 Hàng giờ sau khi hoàn thành, phương tiện truyền thông làm theo chính sách lưu trữ của bạn.

## API liên quan

- [YouTube Siêu dữ liệu ảnh động API](https://flashdata.dev/vi/docs/sources/youtube_metadata/reference.md)
- [YouTube Transcript API](https://flashdata.dev/vi/docs/sources/youtube_transcript/reference.md)
