# FlashData YouTube Transcript API

استرجع نصوص YouTube مع الطوابع الزمنية والنص الكامل. تُختار الترجمات التلقائية افتراضيًا.

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

نقطة النهاية: POST https://data.flashdata.dev/v1/queries/realtime
المصادقة: X-API-Key: YOUR_API_KEY
Modes: [Realtime](https://flashdata.dev/ar/docs/reference/realtime-and-async/reference.md#realtime) · [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_transcript

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

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

[اختر لغة النص وتتبعه](https://flashdata.dev/ar/docs/guides/youtube-data-guide/reference.md#captions)

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

## أرسل طلبًا

### Python

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

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_transcript",
    "video_id": "dQw4w9WgXcQ",
    "params": {
        "language": "en",
        "auto": True,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    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/realtime" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_transcript",
  "video_id": "dQw4w9WgXcQ",
  "params": {
    "language": "en",
    "auto": true
  }
}
FLASHDATA_JSON
```

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

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

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

### نص الطلب

| البارامترات | النوع | مطلوب | الافتراضي | الوصف |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | نعم | — | جاهزون إلى youtube_transcript.  |
| <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-language"></a> params.language | string \| array | لا | en-orig → en | Omit for English (en-orig, then en). بالسياراتtrueكل شفرة تُحاولُ مسارها الأوّل، ثمّ الرمز المطلوب. رموز أوتوماتيكياتfalse إبقي على وجه الدقة. تطلب شركة آريز لغات متميزة من طراز 1–10. ابدأي بالأفضل و ارجعي الى الداخل و ارجعي مسارا واحدا بالسياراتtrueكل شفرة تُحاولُ مسارَها الأوّل، ثمّ الرمز المطلوب؛ رموزَ واضحةَ - حَجْمَة وسيارةِfalse إبقي على وجه الدقة. وتحاول التصويرات من الرموز المميزة للزدجاج الزكسي الزكسيكي (1–10) كل اللغات المطلوبة وتتبعات العودة والأخطاء في كل لغة حسب الطلب. وتحدد شركة languageCode المسار المختار؛ وتدرج requestedLanguageCode عندما تختلف عن الرمز المطلوب. |
| <a id="parameter-params-auto"></a> params.auto | boolean | لا | true | وتختار شركة true أغطية من طراز YouTube-generated؛ وتختار شركة false أغطية مجهزة بالشحنات. ويختار هذا المصدر، وليس الكشف عن اللغة، أو وصفاً جديداً.  |

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

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

وفّر ردّ شركة JSON الناجح على أنها response.json. احفظ هذا read-response.py و اركضوا بيثون read-response.py. إنها تستخدم فقط Pythonمكتبة عادية ولا تقدم طلباً جديداً

### 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 = {
    "tracks": result.get("tracks", [result]),
    "errors": result.get("errors", []),
}
print(json.dumps(output, ensure_ascii=False, indent=2))
```

## مثال للاستجابة

مثال مسجل؛ فالميادين والعدوى تعتمد على المصدر وتطلب مدخلات.
```json
{
  "source": "youtube_transcript",
  "status": "done",
  "results": [
    {
      "videoId": "dQw4w9WgXcQ",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": true,
      "segments": [
        {
          "start": 0.32,
          "end": 14.58,
          "text": "[Music]"
        },
        {
          "start": 18.8,
          "end": 25.96,
          "text": "We're no strangers to"
        },
        {
          "start": 21.8,
          "end": 29.119,
          "text": "love. You know the rules and so do"
        },
        {
          "start": 25.96,
          "end": 30.279,
          "text": "I. I feel commitments from what I'm"
        },
        {
          "start": 29.119,
          "end": 34.36,
          "text": "thinking"
        },
        {
          "start": 30.279,
          "end": 39.559,
          "text": "of. You wouldn't get this from any other"
        },
        {
          "start": 34.36,
          "end": 43.12,
          "text": "guy. I just want to tell you how I'm"
        },
        {
          "start": 39.559,
          "end": 45.84,
          "text": "feeling. Got to make you understand."
        },
        {
          "start": 43.12,
          "end": 49.2,
          "text": "Never going to give you up. I'm going to"
        },
        {
          "start": 45.84,
          "end": 53.32000000000001,
          "text": "let you down. I'm going to run around"
        },
        {
          "start": 49.2,
          "end": 56.399,
          "text": "and desert you. I'm going to make"
        },
        {
          "start": 53.32,
          "end": 59.879,
          "text": "you say goodbye."
        },
        {
          "start": 56.399,
          "end": 64.04,
          "text": "Tell a lie and hurt"
        },
        {
          "start": 59.879,
          "end": 67.2,
          "text": "you. We've known each other for so"
        },
        {
          "start": 64.04,
          "end": 70.56,
          "text": "long. Your heart's been aching, but"
        },
        {
          "start": 67.2,
          "end": 72.60000000000001,
          "text": "you're too shy to say we don't know"
        },
        {
          "start": 70.56,
          "end": 77.799,
          "text": "what's been going"
        },
        {
          "start": 72.6,
          "end": 81.479,
          "text": "on. We know the game and we're going to"
        },
        {
          "start": 77.799,
          "end": 84.56,
          "text": "play. If you ask me how I'm"
        },
        {
          "start": 81.479,
          "end": 88.32,
          "text": "feeling, don't tell me your truth. to"
        },
        {
          "start": 84.56,
          "end": 88.32000000000001,
          "text": "see. I will give"
        },
        {
          "start": 89.88,
          "end": 94.72,
          "text": "you"
        },
        {
          "start": 91.72,
          "end": 94.72,
          "text": "around"
        },
        {
          "start": 95,
          "end": 99.04,
          "text": "you. I will say"
        },
        {
          "start": 99.56,
          "end": 106.759,
          "text": "goodbye and hurt you. I will give"
        },
        {
          "start": 103.99,
          "end": 108.6,
          "text": "[Music]"
        },
        {
          "start": 106.759,
          "end": 115.92,
          "text": "you"
        },
        {
          "start": 108.6,
          "end": 115.92,
          "text": "around you. I will leave you. I will say"
        },
        {
          "start": 116.439,
          "end": 121.079,
          "text": "goodbye and hurt you."
        },
        {
          "start": 128.319,
          "end": 132.56,
          "text": "Never going to give. Never going to"
        },
        {
          "start": 129.759,
          "end": 134,
          "text": "give."
        },
        {
          "start": 132.56,
          "end": 136.8,
          "text": "Never going to give. Never going to"
        },
        {
          "start": 134,
          "end": 141.04,
          "text": "give."
        },
        {
          "start": 136.8,
          "end": 143.68,
          "text": "We've known each other for so long."
        },
        {
          "start": 141.04,
          "end": 147.51999999999998,
          "text": "Your heart's been aching, but you're too"
        },
        {
          "start": 143.68,
          "end": 148.52,
          "text": "shy to say it. We both know what's been"
        },
        {
          "start": 147.52,
          "end": 152.239,
          "text": "going"
        },
        {
          "start": 148.52,
          "end": 157.8,
          "text": "on. We know the game and we're going to"
        },
        {
          "start": 152.239,
          "end": 161.36,
          "text": "play it. I just want to tell you how I'm"
        },
        {
          "start": 157.8,
          "end": 163.92000000000002,
          "text": "feeling. Got to make you understand."
        },
        {
          "start": 161.36,
          "end": 166.8,
          "text": "Never going to give you up. Never going"
        },
        {
          "start": 163.92,
          "end": 171.28,
          "text": "to let you down. Never going to run"
        },
        {
          "start": 166.8,
          "end": 171.28,
          "text": "around and desert you. Heat."
        },
        {
          "start": 172.33,
          "end": 182.76,
          "text": "[Music]"
        },
        {
          "start": 178.76,
          "end": 182.76,
          "text": "Heat. Heat. Heat."
        },
        {
          "start": 183.39,
          "end": 195.2,
          "text": "[Music]"
        },
        {
          "start": 191.04,
          "end": 197.76,
          "text": "Never going to tell a lie and hurt you."
        },
        {
          "start": 195.2,
          "end": 200.64,
          "text": "Never going to give you up. Never going"
        },
        {
          "start": 197.76,
          "end": 204.239,
          "text": "to let you down. Never going to run"
        },
        {
          "start": 200.64,
          "end": 206.83999999999995,
          "text": "around and desert you. Never going to"
        },
        {
          "start": 204.239,
          "end": 211.879,
          "text": "make you cry. Never going to say"
        },
        {
          "start": 206.84,
          "end": 211.879,
          "text": "goodbye. Never going to say goodbye."
        }
      ],
      "fullText": "[Music] We're no strangers to love. You know the rules and so do I. I feel commitments from what I'm thinking of. You wouldn't get this from any other guy. I just want to tell you how I'm feeling. Got to make you understand. Never going to give you up. I'm going to let you down. I'm going to run around and desert you. I'm going to make you say goodbye. Tell a lie and hurt you. We've known each other for so long. Your heart's been aching, but you're too shy to say we don't know what's been going on. We know the game and we're going to play. If you ask me how I'm feeling, don't tell me your truth. to see. I will give you around you. I will say goodbye and hurt you. I will give [Music] you around you. I will leave you. I will say goodbye and hurt you. Never going to give. Never going to give. Never going to give. Never going to give. We've known each other for so long. Your heart's been aching, but you're too shy to say it. We both know what's been going on. We know the game and we're going to play it. I just want to tell you how I'm feeling. Got to make you understand. Never going to give you up. Never going to let you down. Never going to run around and desert you. Heat. [Music] Heat. Heat. Heat. [Music] Never going to tell a lie and hurt you. Never going to give you up. Never going to let you down. Never going to run around and desert you. Never going to make you cry. Never going to say goodbye. Never going to say goodbye."
    }
  ],
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-09-16T07:45:44.040Z"
}
```

## لغات متعددة

إرسال صفيفة لغوية لتلقي المسارات والأخطاء في كل لغة. ويظهر هذا المثال أن الإنكليزية متاحة والإسبانية غير متاحة.

```json
{
  "source": "youtube_transcript",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "language": [
      "en",
      "es"
    ],
    "auto": true
  }
}
```

`results[0]`:

```json
{
  "videoId": "jNQXAC9IVRw",
  "isAutoGenerated": true,
  "tracks": [
    {
      "videoId": "jNQXAC9IVRw",
      "languageCode": "en-orig",
      "requestedLanguageCode": "en",
      "languageName": null,
      "isAutoGenerated": true,
      "segments": [
        {
          "start": 0,
          "end": 1.5,
          "text": "Hello world."
        }
      ],
      "fullText": "Hello world."
    }
  ],
  "errors": [
    {
      "languageCode": "es",
      "code": "language_unavailable",
      "message": "Auto-generated subtitles not available for language: es"
    }
  ]
}
```

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

| الميدان | النوع | الوصف |
| --- | --- | --- |
| source | string | المصدر المطلوب من شركة API. |
| status | string | تم عندما يتكلل الطلب بالنجاح. |
| created_at | string | وقت إنشاء الاستجابة في شكل ISO 8601. |
| usage.credits | number | إئتمانات مُقيدة على الطلب، بناءً على خطتك. |
| results[0].videoId | string | الفيديو المطلوب ID. |
| results[0].languageCode | string | رمز المسار الفعلي المختار، مثل النسيج. |
| results[0].languageName | string · nullable | اسم العرض اللغوي عندما يكون متاحا |
| results[0].requestedLanguageCode | string · optional | الرمز المطلوب عندما يختلف عن languageCode، مثل en عند اختيار en-orig. |
| results[0].isAutoGenerated | boolean | وسواء تم توليد الأسر المختارة تلقائياً. |
| results[0].segments | array | أجزاء من القدرات حسب الترتيب الزمني. |
| results[0].segments[].start | number | تبدأ القطعة في ثواني. |
| results[0].segments[].end | number | نهاية الفصل في ثواني. |
| results[0].segments[].text | string | رسالة استطلاعية |
| results[0].fullText | string | وانضمت جميع نصوص الأجزاء إلى محضر. |
| results[0].tracks | array · optional | لصفائف اللغات فقط. (ب) المسارات المتاحة حسب الطلب؛ ولكل من هذه المسارات الحقول ذات المسار الواحد الواردة أعلاه. |
| results[0].errors | array · optional | لصفائف اللغات فقط. اللغات المعطلة حسب الطلب. فارغة عندما ينجح كل المسار |
| results[0].errors[].languageCode | string | اللغة المطلوبة التي فشلت. |
| results[0].errors[].code | string | تظهر language_unavailable عندما لا يوجد المسار المحدد، وretrieval_failed عندما يتعذر تنزيله أو تحليله. |
| results[0].errors[].message | string | Description of the language failure. |

- تقرأ API الترجمات الموجودة على YouTube. ولا تنشئ نصوصًا جديدة ولا تنتقل تلقائيًا بين الترجمات التلقائية والترجمات التي يوفّرها رافع الفيديو.
- تحافظ اللغة المحددة كسلسلة نصية على استجابة المسار الواحد. أما المصفوفة، حتى ["en"]، فتعيد tracks وerrors بدلًا من languageCode وsegments وfullText في المستوى الأعلى. يحتوي كل مسار على تلك الحقول. ينطبق auto على جميع اللغات.
- عند طلب مصفوفة لغات، راجع errors لمعرفة المسارات التي تعذّر جلبها. إذا لم يُجلب أي مسار، يفشل الطلب وتُردّ الأرصدة المحجوزة. يفشل الطلب أيضًا عند تعذّر استخراج الفيديو أو انتهاء المهلة.
- متاحة في الوقت الحقيقي، الأسينك، البصل والسوائب. Bulk الصادرات JSONL مع سجل واحد لكل شريط فيديو، بما في ذلك آثاره وأخطائه. Accept and X-Respond-With apply as usual.

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

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

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

يتوفر Markdown للاستعلامات الفورية والنتائج المكتملة.

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

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

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

## APIs ذات الصلة

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