# FlashData YouTube Download API

Unduh YouTube video atau audio ke penyimpanan awan Anda. Pilih resolusi, format, dan durasi klip, kemudian lacak tugas asinkron melalui pelengkapan.

Referensi kanonikal: https://flashdata.dev/id/docs/sources/youtube_download
Diulas: 2026-10-23

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

Izin sumber yang diperlukan: youtube_download

Ganti kunci YOUR_API_KEY dengan kunci API yang memiliki hak sumber ini dan kredit yang tersedia. Jalankan permintaan pada server atau agen host.

[Atur otentikasi](https://flashdata.dev/id/docs/guides/headers-and-authentication/reference.md)

[Unduh satu video dan verifikasi pengiriman](https://flashdata.dev/id/docs/guides/download-video-recipe/reference.md)

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

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

## Kirim permintaan

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

## Parameter

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

### Isi permintaan

| Parameter | Jenis | Wajib | Default | Deskripsi |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Ya | — | Set ke youtube_download.  |
| <a id="parameter-video_id"></a> video_id | string | Ya | Tak ditata | Karakter 11-YouTube video ID, seperti FUFFGCZ092b0. Menerima surat, nomor, garis bawah dan tanda hubung. Panjang Min: 11. Panjang Max: 11. Pola: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Ya | — | Settings untuk permintaan ini.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | Tidak | Tak ditata | Async dan batch saja. Publik HTTPS pelengkapan URL di port 443, sampai 2,048 karakter. Tak ada kredensial pengguna atau fragmen URL. Omit, gunakan null atau string kosong untuk tanpa pemberitahuan. Dalam batch, set ini pada setiap query, di luar param.  |

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

### Video & audio

| Parameter | Jenis | Wajib | Default | Deskripsi |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-download_type"></a> params.download_type | string | Tidak | "audio_video" | audio_video menggabungkan video dan audio; hanya memilih video; pemilih audio saja. Diizinkan: "audio_video", "video", "audio". Panjang Min: 1. Panjang Max: 11. |
| <a id="parameter-params-video_quality"></a> params.video_quality | string | Tidak | "<=720" | Seleksi resolusi video. Keluarkan untuk audio- hanya unduhan. Diijinkan: "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". Panjang Min: 1. Panjang Max: 40. |
| <a id="parameter-params-fps"></a> params.fps | string | Tidak | Tak ditata | Batas rate Frame-: > =, < = atau = = diikuti dengan nilai dari 1 ke 240. Keluarkan untuk audio- hanya unduhan. Panjang Min: 1. Panjang Max: 6. Pola: ^(?:>=\|<=\|==)(?:[1-9]\d?\|1\d\d\|2[0-3]\d\|240)$ |
| <a id="parameter-params-audio_language"></a> params.audio_language | string | Tidak | "default" | Pilihan trek audio. Aplikasi ke audio_video dan audio. Diizinkan: "default", "original". Panjang Min: 1. Panjang Max: 8. |
| <a id="parameter-params-audio_quality"></a> params.audio_quality | string | Tidak | "best" | Audio- hanya bitrate dalam kbps, atau yang terbaik. Pilihan numerik harus dikirim sebagai string. Keluarkan untuk mengunduh video. Diizinkan: "best", "320", "256", "192", "128". Panjang Min: 1. Panjang Max: 10. |
| <a id="parameter-params-output_format"></a> params.output_format | string | Tidak | mp4 (video) / m4a (audio) | Video: mp4, webm atau mkv. Audio: m4a, mp3 atau opus. Diizinkan: "mp4", "webm", "mkv", "m4a", "mp3", "opus". Panjang Min: 1. Panjang Max: 10. |
| <a id="parameter-params-yt_dlp_format"></a> params.yt_dlp_format | string | Tidak | Tak ditata | Penunjuk format lanjutan, dari 1 ke 1,024 karakter setelah pemecahan whitespace. Karakter kontrol ditolak. Timpa video_quality, fps dan audio_language, nilai-nilainya kemudian diabaikan; format keluaran dan kliping masih berlaku. Panjang Min: 1. Panjang Max: 1024. |
| <a id="parameter-params-upload_metadata"></a> params.upload_metadata | boolean | Tidak | false | Unggah berkas metadata JSON bersama berkas media di penyimpanan Anda.  |

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

### Mengklik

| Parameter | Jenis | Wajib | Default | Deskripsi |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-start_at"></a> params.start_at | string | Tidak | Tak ditata | Awal klik dalam H: MM: SS atau HH: MM: Format SS, dari 00:00:00 ke 12:00:00. Baku untuk 00:00:00 ketika hanya end_at yang disediakan. Panjang Min: 1. Panjang Max: 8. Pola: ^\d{1,2}:[0-5]\d:[0-5]\d$ |
| <a id="parameter-params-end_at"></a> params.end_at | string | Tidak | Tak ditata | Format klip di H: MM: SS atau HH: MM: SS, hingga 12:00:00. Pasti lebih lambat dari start_at. Panjang Min: 1. Panjang Max: 8. Pola: ^\d{1,2}:[0-5]\d:[0-5]\d$ |

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

### Tujuan penyimpanan

| Parameter | Jenis | Wajib | Default | Deskripsi |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-storage"></a> params.storage | object | Ya | — | Tujuan untuk berkas media yang selesai. Hanya area penyimpanan yang terdaftar yang diterima.  |
| <a id="parameter-params-storage-storage_type"></a> params.storage.storage_type | string | Ya | — | Penyedia penyimpanan: s3, s3_compatible, oss, gcs, azure, cos, bos atau tos.  |
| <a id="parameter-params-storage-storage_url"></a> params.storage.storage_url | string | Ya | — | Ember kosong atau nama kontainer, hingga karakter 1,024. Sekitar whitespace dihapus. Untuk s3, gunakan nama bucket AWS yang valid tanpa URL atau path folder; folder milik dalam object_prefix.  |
| <a id="parameter-params-storage-object_prefix"></a> params.storage.object_prefix | string | Tidak | "YYYYMMDD" | Object- prefiks kunci, 1 untuk karakter 512. Setiap segmen terpisah-slash menerima huruf ASCII, digit, titik, garis bawah dan hyphens; segmen kosong,. dan.. ditolak. Tidak ada garis miring. Mengelilingi ruang putih dan satu garis miring yang tertinggal dihapus. YYYYMMDD menggunakan tanggal upload UTC, termasuk dalam archive/YYYYMMDD.  |
| <a id="parameter-params-storage-access_key"></a> params.storage.access_key | string | Tidak | — | Kunci akses untuk S3, kompatibel S3Q-, OSS, COS, BOS atau TOS; dipasangkan dengan secret_key.  |
| <a id="parameter-params-storage-secret_key"></a> params.storage.secret_key | string | Tidak | — | Kunci rahasia untuk S3, S3Q- kompatibel, OSS, COS, BOS atau TOS.  |
| <a id="parameter-params-storage-endpoint_url"></a> params.storage.endpoint_url | string | Tidak | — | Publik HTTPS titik akhir untuk S3- yang kompatibel dengan penyimpanan atau OSS. COS, BOS dan TOS mendapatkannya dari wilayah.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | Tidak | — | Diperlukan untuk COS, BOS dan TOS; juga persediaan untuk unduhan S3 dan S3Q- yang kompatibel. COS nama ember termasuk APPID.  |
| <a id="parameter-params-storage-service_account"></a> params.storage.service_account | object | Tidak | — | GCS akun layanan: project_id, client_email dan PEM private_key.  |
| <a id="parameter-params-storage-account_name"></a> params.storage.account_name | string | Tidak | — | Azure nama rekening penyimpanan. Gunakan nama kontainer dalam storage_url.  |
| <a id="parameter-params-storage-sas_token"></a> params.storage.sas_token | string | Tidak | — | Write- diaktifkan Azure kontainer SAS dengan kadaluwarsa dan tanda tangan.  |

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

## Baca hasilnya

Setelah pekerjaan selesai, simpan JSON dari hasil link sebagai response.json. Simpan ini sebagai read-response.py dan jalankan python read-response.py. Ini membaca rincian berkas tanpa mengunduh media atau membuat permintaan lain.

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

## Sampel pengiriman

Contoh direkam; ruas dan jumlah bergantung pada sumber dan masukan yang diminta.
```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"
    }
  ]
}
```

## Ruas respon

| Ruas | Jenis | Deskripsi |
| --- | --- | --- |
| id | string | Download job ID. |
| source | string | youtube_download. |
| status | string | menunggu ketika pekerjaan diterima. |
| created_at | string | Waktu pembuatan Job dalam format ISO 8601. |
| usage.credits | number | 0 di pengiriman. Unduhan diisi oleh volume data yang dikirim setelah pelengkapan. |
| links | array | Ikuti link mandiri untuk status kerja dan taut hasil untuk keluaran yang selesai. |
| links[].rel | string | diri atau hasil. |
| links[].href | string | URL untuk query dengan sama API kunci. |
| links[].method | string | GET. |

- Unduhan dijalankan sebagai pekerjaan latar belakang. Respon pengajuan berisi suatu tugas ID; ini tidak berisi berkas media. Ikuti status pekerjaan sampai penyelesaian, kemudian mengambil hasil menjelaskan file yang dikirim ke penyimpanan Anda. Kirim pengunduhan ke /v1/queries atau /v1/queries/batch; /v1/queries/realtime tidak menerima permintaan unduh.

## Format respons

Respon menggunakan JSON secara baku. Pilih format lain dengan header opsional ini.

- Accept: application/json (baku) atau text/plain. Teks biasa menyajikan ruas yang sama dalam tata letak yang dapat dibaca, tidak terbaca.
- X-Respond-With: markdown. Tinggalkan unset untuk bidang asli. Markdown bekerja dengan baik format respon.

Markdown format download manifest; berkas media menyimpan format asli mereka. Penerima dan status kerja hanya mendukung Accept saja.

Bidang di bawah ini menjelaskan respon baku JSON.

[Permohonan dan contoh format respon](https://flashdata.dev/id/docs/guides/response-formats/reference.md#completed-results)

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

## Tujuan penyimpanan

Tugas tunggal dan Batch unduhan memerlukan params.storage; Bulk unduhan menggunakan options.storage. storage_url adalah ember atau nama wadah. Suppply kredensial dengan menulis akses dan menjaga mereka di server Anda.

### s3

Supply access_key dan secret_key dengan menulis akses. Atur wilayah ke wilayah AWS ember Anda.

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

Suplai access_key, secret_key dan publik HTTPS endpoint_url. Atur wilayah seperti yang diperlukan oleh penyedia Anda; Cloudflare R2 menggunakan 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

Persediaan account_name dan sas_token, sebuah SAS kontainer dengan izin menulis (sp termasuk w), sumber daya sr = c, expiry se, version sv dan signature sig. storage_url adalah nama kontainer. Jangan kirim endpoint_url, access_key atau 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

Persediaan access_key, secret_key dan daerah: bj, su atau hkg. Titik akhir berasal dari daerah ketika diabaikan. Gunakan nama ember tanpa titik.

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

### cos

Persediaan access_key, secret_key dan daerah ap- *, seperti ap- hongkong. storage_url harus menyertakan akhiran APPID. Jangan kirim endpoint_url; ini diturunkan dari daerah.

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

### gcs

Suplai service_account dengan project_id, client_email (alamat layanan Anda. gserviceaccount.com), dan PEM private_key dari akun layanan Anda. Rekening harus memiliki akses menulis ke ember. Jangan kirim access_key, secret_key, wilayah atau 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

Suplai access_key, secret_key dan area ember publik 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

Persediaan access_key, secret_key dan wilayah dengan cn-, ap-, ea- atau kita- prefix. Titik akhir berasal dari daerah ketika diabaikan. Gunakan nama ember tanpa titik.

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

## Dasar-dasar API

Permintaan pembangun dan contoh di atas menggunakan parameter sumber ini. Gunakan contoh Python dan cURL di bawah ini untuk penyerahan bersama, status, dan langkah-langkah hasil. Tubuh Batch adalah objek JSON berisi kueri; setiap item mengembalikan pekerjaannya sendiri ID.

- [Async permintaan dan tanda terima](https://flashdata.dev/id/docs/reference/realtime-and-async/reference.md#async)

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

- [Periksa status pekerjaan](https://flashdata.dev/id/docs/reference/realtime-and-async/reference.md#status)

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

- [Mengambil hasil selesai](https://flashdata.dev/id/docs/reference/realtime-and-async/reference.md#results)
- [permintaan Batch JSON](https://flashdata.dev/id/docs/reference/batch-and-bulk/reference.md#batch)
- [API pemrosesan Bulk](https://flashdata.dev/id/docs/reference/bulk-processing/reference.md)
- [Bangun Bulk alur kerja bagi sumber ini](https://flashdata.dev/id/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)
- [Pelanggan OpenAPI](https://flashdata.dev/docs/openapi.json)

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

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

## Pemberitahuan penyelesaian

- [Menerima dan memverifikasi pelengkapan webhooks](https://flashdata.dev/id/docs/guides/async-batch/reference.md#webhooks)

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

## Permasalahan menarik

- [Kesalahan dan kode status](https://flashdata.dev/id/docs/errors/reference.md#status-codes)
- [Kapan untuk mencoba lagi](https://flashdata.dev/id/docs/errors/reference.md#retries)

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

## Pengiriman berkas

Unduh tidak mendukung real time.

Media diunggah ke penyimpanan yang telah dikonfigurasi; hasil JSON menggambarkan berkas-berkas tersebut. Media swasta menggunakan otentikasi penyimpanan Anda. Hasil JSON berakhir dengan 24 jam setelah penyelesaian; media mengikuti kebijakan penyimpanan Anda.

## Terkait APIs

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