# FlashData YouTube Download API

تحميل فيديو YouTube أو الصوت لتخزين السحابة الخاص بك. اختصار القرار، والشكل، ومدة الشظايا، ثم تتبع العمل غير المتناهي عن طريق الإنجاز.

مرجع كانوني: https://flashdata.dev/ar/docs/sources/youtube_download
جرى استعراضها: 2026-10-23

نقطة النهاية: POST https://data.flashdata.dev/v1/queries
المصادقة: X-API-Key: YOUR_API_KEY
Modes: [Async](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/ar/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/ar/docs/reference/bulk-processing/reference.md)

إذن المصدر المطلوب: youtube_download

يستعاض عن YOUR_API_KEY بمفتاح API الذي يملك هذا المصدر من الأذن والائتمانات المتاحة. أجري طلبات على خادمك أو وكيل مضيف.

[إقامة المصادقة](https://flashdata.dev/ar/docs/guides/headers-and-authentication/reference.md)

[تحميل شريط فيديو واحد والتحقق من التسليم](https://flashdata.dev/ar/docs/guides/download-video-recipe/reference.md)

[واجهة API لتنزيل فيديوهات YouTube — أمثلة Python](https://github.com/flashdatadev/youtube-video-download-api)

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

## أرسل طلبًا

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

## البارامترات

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

### نص الطلب

| البارامترات | النوع | مطلوب | الافتراضي | الوصف |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | نعم | — | جاهزون إلى youtube_download.  |
| <a id="parameter-video_id"></a> video_id | string | نعم | غير محدد | معرّف فيديو YouTube من 11 محرفًا، مثل FUfGcZ092b0. يقبل الحروف والأرقام والشرطات السفلية والواصلات. صغر المدة: 11. أقصى مدة: 11. Pattern: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | نعم | — | Settings for this request.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | لا | غير محدد | لـ async وbatch فقط. رابط HTTPS عام للإشعار بالاكتمال على المنفذ 443، بطول يصل إلى 2,048 حرفًا، دون بيانات اعتماد مستخدم أو جزء رابط. احذف القيمة أو استخدم null أو سلسلة فارغة لعدم إرسال إشعار. في batch، ضعه في كل استعلام خارج params.  |

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

### صوت فيديو

| البارامترات | النوع | مطلوب | الافتراضي | الوصف |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-download_type"></a> params.download_type | string | لا | "audio_video" | ويدمج audio_video الفيديو والصوت؛ ويختار الفيديو فقط؛ ويختار الصوت فقط. مسموع: "audio_video", "video", "audio". صغر المدة: 1. أقصى مدة: 11. |
| <a id="parameter-params-video_quality"></a> params.video_quality | string | لا | "<=720" | انتقاء قرارات الفيديو. ابدأوا بالحملات الصوتية فقط. مسموع: "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". صغر المدة: 1. أقصى مدة: 40. |
| <a id="parameter-params-fps"></a> params.fps | string | لا | غير محدد | قيد معدل الإطارات: >= أو <= أو == متبوعًا بقيمة من 1 إلى 240. احذفه عند تنزيل الصوت فقط. صغر المدة: 1. أقصى مدة: 6. Pattern: ^(?:>=\|<=\|==)(?:[1-9]\d?\|1\d\d\|2[0-3]\d\|240)$ |
| <a id="parameter-params-audio_language"></a> params.audio_language | string | لا | "default" | اختيار المسار الصوتي. Applies to audio_video وصوت. مسموع: "default", "original". صغر المدة: 1. أقصى مدة: 8. |
| <a id="parameter-params-audio_quality"></a> params.audio_quality | string | لا | "best" | مرّت بشكل مُطلق في الكبسولة، أو أفضل. يجب أن تُرسل خيارات عديدة كخيوط. قم بتحميل الفيديو. مسموع: "best", "320", "256", "192", "128". صغر المدة: 1. أقصى مدة: 10. |
| <a id="parameter-params-output_format"></a> params.output_format | string | لا | mp4 (video) / m4a (audio) | Video: mp4, webm or mkv. Audio: m4a, mp3 or opus. مسموع: "mp4", "webm", "mkv", "m4a", "mp3", "opus". صغر المدة: 1. أقصى مدة: 10. |
| <a id="parameter-params-yt_dlp_format"></a> params.yt_dlp_format | string | لا | غير محدد | محدّد صيغة متقدم، من 1 إلى 1,024 حرفًا بعد حذف الفراغات المحيطة. تُرفض محارف التحكم. يتجاوز video_quality وfps وaudio_language، فتُتجاهل قيمها؛ وتبقى صيغة الإخراج والاقتطاع ساريتين. صغر المدة: 1. أقصى مدة: 1024. |
| <a id="parameter-params-upload_metadata"></a> params.upload_metadata | boolean | لا | false | تحميل البيانات الوصفية JSON ملف بجانب ملف الإعلام في مخزنك  |

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

### Clipping

| البارامترات | النوع | مطلوب | الافتراضي | الوصف |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-start_at"></a> params.start_at | string | لا | غير محدد | Clip start in H:MMM:SS/H:MMM:SS format, from 00:00:00 to 12:00:00. Defaults to 00:00:00 when only end_at is supplied. صغر المدة: 1. أقصى مدة: 8. Pattern: ^\d{1,2}:[0-5]\d:[0-5]\d$ |
| <a id="parameter-params-end_at"></a> params.end_at | string | لا | غير محدد | Clip end in H:MMM:SS/H:MM:SS:SS format, up to 12:00:00. لا بد أن يكون في وقت لاحق من start_at. صغر المدة: 1. أقصى مدة: 8. Pattern: ^\d{1,2}:[0-5]\d:[0-5]\d$ |

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

### الوجهة المخزنة

| البارامترات | النوع | مطلوب | الافتراضي | الوصف |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-storage"></a> params.storage | object | نعم | — | تحديد ملفات إعلامية كاملة. ولا تقبل سوى حقول التخزين المدرجة في القائمة.  |
| <a id="parameter-params-storage-storage_type"></a> params.storage.storage_type | string | نعم | — | مورد تخزين: S3, s3_compatible, os, gcs, azure, cos, bos or tos.  |
| <a id="parameter-params-storage-storage_url"></a> params.storage.storage_url | string | نعم | — | دلو غير فارغ أو اسم حاويات، إلى جانب شخصيات 1,024. ازالة الفضاء الأبيض المحيط (ب) فيما يتعلق برقم 3، استخدام اسم دلو صالح من طراز AWS بدون ممر من طراز URL أو مسار الملف؛ وتنتمي الملفات إلى object_prefix.  |
| <a id="parameter-params-storage-object_prefix"></a> params.storage.object_prefix | string | لا | "YYYYMMDD" | Object-key prefix, 1 to 512 characters. ويقبل كل جزء مفصّل من أجزاء " ASCII " رسائل وأرقام ونقطات، وتأكيدات وهيفنز؛ وشرائح فارغة، و... مرفوضة. لا يوجد صدع رئيسي ازالة الفضاء الأبيض المُحيط وقطعة أثرية واحدة YYYMDD uses the UTC upload date, including in archive/YYYYMMDD.  |
| <a id="parameter-params-storage-access_key"></a> params.storage.access_key | string | لا | — | مفتاح وصول لـ S3 أو S3-compatible أو OSS أو COS أو BOS أو TOS؛ ويُستخدم مع secret_key.  |
| <a id="parameter-params-storage-secret_key"></a> params.storage.secret_key | string | لا | — | مفتاح سري لـ S3 أو التخزين المتوافق مع S3 أو OSS أو COS أو BOS أو TOS.  |
| <a id="parameter-params-storage-endpoint_url"></a> params.storage.endpoint_url | string | لا | — | Public HTTPS endpoint for S3-compatible storage or OSS. COS, BOS and TOS extract it from region.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | لا | — | (ب) الاحتياجات من المعدات المملوكة للوحدات، والمخزونات من السلع الأساسية، والتصنيفات؛ وكذلك الإمدادات من الـ S3 و S3-compatible downloads. (أسماء دلو (كوس تشمل (آي بي دي  |
| <a id="parameter-params-storage-service_account"></a> params.storage.service_account | object | لا | — | حساب خدمة GCS: الحقول project_id وclient_email وprivate_key بصيغة PEM.  |
| <a id="parameter-params-storage-account_name"></a> params.storage.account_name | string | لا | — | اسم حساب تخزين Azure. استخدام اسم الحاوية في storage_url.  |
| <a id="parameter-params-storage-sas_token"></a> params.storage.sas_token | string | لا | — | حاويات SAS SAS التي تحمل حرف Azure والتي تحمل صلاحيتها وتوقيعها.  |

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

## اقرأ النتيجة

وبعد إتمام العمل، وفر الـ JSON من وصلة النتائج التي تربطه بها كـ response.json. احفظ هذا read-response.py و اركضوا بيثون read-response.py. ويقرأ التقرير تفاصيل الملف دون تحميل وسائط الإعلام أو تقديم طلب آخر.

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

مثال مسجل؛ فالميادين والعدوى تعتمد على المصدر وتطلب مدخلات.
```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"
    }
  ]
}
```

## حقول الاستجابة

| الميدان | النوع | الوصف |
| --- | --- | --- |
| id | string | وظيفة تحميل ID. |
| source | string | youtube_download. |
| status | string | في انتظار قبول الوظيفة. |
| created_at | string | وقت خلق الوظائف في شكل ISO 8601. |
| usage.credits | number | 0 at submission. وتُحمَّل الحمولات بحجم البيانات المُسلَّمة بعد إتمامها. |
| links | array | (ب) أن تتبع الصلة الذاتية فيما يتعلق بحالة العمل والصلة بين النتائج لإنجاز النواتج. |
| links[].rel | string | ذاتي أو نتائج. |
| links[].href | string | URL to query with the same API key. |
| links[].method | string | GET. |

- تعمل التنزيلات كمهام في الخلفية. تحتوي استجابة الإرسال على معرّف المهمة، ولا تحتوي على ملف الوسائط. تابع حالة المهمة حتى اكتمالها، ثم استرجع النتيجة التي تصف الملفات المسلَّمة إلى تخزينك. أرسل التنزيلات إلى /v1/queries أو /v1/queries/batch؛ لا تقبل /v1/queries/realtime طلبات التنزيل.

## تنسيقات الاستجابة

وتستخدم الردود JSON حسب التقصير. اختر شكلاً آخر مع هؤلاء المرشدين الاختياريين

- Accept: application/json (التقصير) أو text/plain. ويعرض النص الشاذ نفس الحقول في مخطط قابل للقراءة ومستقطب.
- X-Respond-With: markdown. إتركوا الحقول الأصلية وتعمل شركة Markdown بأي من شكلي الاستجابة.

ينسّق Markdown سجل التنزيل؛ وتحتفظ ملفات الوسائط بصيغتها الأصلية. تدعم إيصالات الاستلام وحالة المهمة Accept فقط.

وتصف المجالات الواردة أدناه رد شركة JSON.

[أمثلة صيغ الطلب والاستجابة](https://flashdata.dev/ar/docs/guides/response-formats/reference.md#completed-results)

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

## الوجهة المخزنة

وظيفة واحدة Batch الحمولات تتطلب params.storage; وتستخدم حمولات Bulk options.storage. storage_url هي دلو أو اسم حاويات. تمدّد أوراق الاعتماد بكتابة الدخول وإبقائها على خادمك.

### s3

Provide access_key and secret_key with written access. جهزوا المنطقة إلى منطقة الدلو الخاصة بكم

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

الإمداد access_key, secret_key and a public HTTPS endpoint_url. (ب) أن تحدد المنطقة حسب ما يطلبه مقدمك؛ Cloudflare R2 تستخدم آليا.

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

أما الإمداد برقم account_name و sas_token، وهي حاوية مجهزة بإذن كتابي (البرنامج الفرعي (ث)، والرمز المرجعي (ج)، والخلاصة، والنسخة (Sv) والتوقيع (storage_url، فهي اسم الحاويات. لا ترسل 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. وتنبع نقطة النهاية من المنطقة عندما تُحذف. استخدمي اسم دلو بدون نقاط

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

### cos

إمداد access_key, secret_key and an ap-* region, such as ap-hongkong. storage_url must include the APPID suffix. لا ترسل 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

إمداد service_account مع project_id, client_email (a.gserviceaccount.com) و PEM private_key من حساب خدماتكم. يجب أن يكتب الحساب الدخول إلى الدلو. لا ترسل 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

الإمداد access_key, secret_key و منطقة الدلو العامة 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. وتنبع نقطة النهاية من المنطقة عندما تُحذف. استخدمي اسم دلو بدون نقاط

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

يستخدم منشئ الطلبات والأمثلة أعلاه معاملات هذا المصدر. استخدم أمثلة Python وcURL أدناه لخطوات الإرسال والحالة والنتائج المشتركة. جسم Batch هو كائن JSON يحتوي queries؛ ويعيد كل عنصر معرّف مهمة خاصًا به.

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

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

- [التحقق من حالة العمل](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#status)

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

- [استرجاع النتائج المنجزة](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON](https://flashdata.dev/ar/docs/reference/batch-and-bulk/reference.md#batch)
- [واجهة API لمعالجة Bulk](https://flashdata.dev/ar/docs/reference/bulk-processing/reference.md)
- [بناء تدفق عمل من طراز Bulk لهذا المصدر](https://flashdata.dev/ar/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)
- [العملاء المفتوحون](https://flashdata.dev/docs/openapi.json)

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

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

## الإخطارات المتعلقة بالإنجاز

- [استلام وثائق الإنجاز على شبكة الإنترنت والتحقق منها](https://flashdata.dev/ar/docs/guides/async-batch/reference.md#webhooks)

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

## اضطرابات

- [الأخطاء ورموز الحالة](https://flashdata.dev/ar/docs/errors/reference.md#status-codes)
- [متى يُعيدُ النظر](https://flashdata.dev/ar/docs/errors/reference.md#retries)

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

## تسليم الملفات

الحمولة لا تدعم الوقت الحقيقي.

وسائل الإعلام محملة إلى مخزنك المزود بالأجهزة JSON يصف تلك الملفات وسائل الإعلام الخاصة تستخدم التوثيق الخاص بك التخزين. JSON تنتهي مدة صلاحية النتائج 24 بعد ساعات من الانتهاء، تتبع وسائل الإعلام سياسة الاحتفاظ بمخزونك.

## APIs ذات الصلة

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