وثائق المطورين تُنشر بالإنجليزية. الشريط الجانبي يتبع اللغة المختارة.

مرجع الواجهة

Base URL: https://api.subdownload.com · Auth: Authorization: Bearer sk_live_xxx

نقاط النهاية

GET /v1/verify free

التحقّق من صحة مفتاح API. يُرجع معلومات الرمز والمستخدم. لا يستهلك أرصدة.

الطلب

curl -H "Authorization: Bearer sk_live_xxx" \
  https://api.subdownload.com/v1/verify

الاستجابة 200

{
  "valid": true,
  "token": { "name": "My App", "prefix": "sk_live_abc", "monthly_quota": 0, "used_quota": 120 },
  "user": { "id": 42, "email": "[email protected]", "plan": "free", "credits_remaining": 148 }
}

GET /v1/youtube/transcript 1 credit

جلب النص / الترجمات لفيديو YouTube. يقبل ID الفيديو أو أي URL صالح (watch، youtu.be، shorts).

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`video_id`	string	مطلوب	ID من 11 حرفًا أو URL YouTube كامل. الاسم البديل: `video_url`.
`lang`	string	اختياري	رموز اللغات المفضّلة مفصولة بفواصل (مثلًا `en,zh,ja`).

الطلب

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/transcript?video_id=dQw4w9WgXcQ&lang=en"

الاستجابة 200

{
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "language": "en",
    "segments": [
      { "text": "We're no strangers to love", "start": 0.0, "duration": 3.5 }
    ],
    "text": "We're no strangers to love...",
    "meta": { "title": "...", "author": "...", "thumbnail": "..." }
  },
  "credits_used": 1,
  "credits_remaining": 148
}

الأخطاء

400 video_id مفقود · 404 بدون ترجمات · 402 نفاد الأرصدة

GET /v1/youtube/search 1 credit

البحث في YouTube عن فيديوهات أو قنوات مطابقة لكلمة مفتاحية.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`q`	string	مطلوب	استعلام البحث (1-200 حرفًا).
`type`	string	اختياري	`video` (افتراضي) أو `channel`.
`limit`	integer	اختياري	1-50 نتيجة (افتراضي 20).

الطلب

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/search?q=rust+tutorial&limit=5"

GET /v1/youtube/channel/resolve free

حلّ أي إشارة إلى قناة (@handle، URL، أو UC… ID) إلى معلومات قناة قانونية.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`input`	string	مطلوب	@handle، URL القناة، URL الفيديو أو UC… ID.

GET /v1/youtube/channel/search 1 credit

البحث داخل فيديوهات قناة محدّدة.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`channel`	string	مطلوب	@handle، URL أو UC… ID (الاسم البديل: `channel_id`).
`q`	string	مطلوب	استعلام البحث.
`limit`	integer	اختياري	1-50 (افتراضي 30).

GET /v1/youtube/channel/latest free

جلب أحدث ~15 فيديو لقناة عبر RSS. سريع ومجاني.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`channel`	string	مطلوب	@handle، URL أو UC… ID (الاسم البديل: `channel_id`).

GET /v1/youtube/channel/videos 1 credit/page

سرد كل الفيديوهات التي رفعتها قناة، مقسّم ~100 لكل صفحة.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`channel`	string	الصفحة الأولى	@handle، URL أو UC… ID (الاسم البديل: `channel_id`).
`continuation`	string	الصفحات التالية	الرمز المُعاد من الاستدعاء السابق.

ملاحظة: مرّر channel أو continuation، لا كليهما.

GET /v1/youtube/playlist/videos 1 credit/page

سرد فيديوهات قائمة تشغيل YouTube مع تقسيم الصفحات.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`playlist`	string	الصفحة الأولى	URL أو ID قائمة التشغيل (`PL…`، `UU…`، `LL…`، `FL…`، `OL…`).
`continuation`	string	الصفحات التالية	الرمز من الاستجابة السابقة.

التفريغ الصوتي بالذكاء الاصطناعي (ASR)

شغّل Whisper على فيديوهات بدون ترجمات. غير متزامن: POST ينشئ مهمة، ثم استطلع GET حتى status=done. 5 نقاط، تُخصم فقط عند النجاح — إعادة تشغيل ASR على فيديو سبق دفعه مجانية.

POST /v1/youtube/asr 5 نقاط عند done

يبدأ تفريغًا صوتيًا غير متزامن باستخدام Whisper. يُرجع task_id وتلميحات ETA لضبط وتيرة الاستطلاع.

نص الطلب (JSON)

الاسم	النوع	مطلوب؟	الوصف
`video_url`	string	مطلوب	رابط YouTube (watch / youtu.be / shorts / embed).
`lang`	string	اختياري	تلميح اللغة (`en`، `ar`…). اتركه فارغًا للكشف التلقائي.

الطلب

curl -X POST -H "Authorization: Bearer sk_live_xxx"   -H "Content-Type: application/json"   -d '{"video_url":"https://youtu.be/dQw4w9WgXcQ"}'   https://api.subdownload.com/v1/youtube/asr

الاستجابة 202

{
  "task_id": "task_01HX...",
  "status": "queued",
  "from_cache": false,
  "queue_position": 2,
  "estimated_wait_seconds": 61,
  "next_poll_after_seconds": 15,
  "poll_url": "/v1/youtube/asr/task_01HX..."
}

التزم بـ next_poll_after_seconds بين كل استطلاع. عند إصابة الكاش يُعاد status=done مباشرة مع segments مضمّنة.

GET /v1/youtube/asr/{task_id} مجاني

استطلاع مهمة ASR. مجاني — بلا نقاط ولا حصة توكن. فقط المنشئ يستطيع القراءة.

الحالات: queued · downloading · transcribing · done · failed · cancelled. segments نهائية فقط عند status=done.

Library (مكتبة المستخدم)

تخزين لكل مستخدم لنصوص ASR المحفوظة وملخصات الذكاء الاصطناعي. القراءات مجانية؛ الكتابات تستهلك وحدة حصة توكن واحدة. لا تُخصم نقاط المستخدم.

GET /v1/library مجاني

يسرد العناصر التي حفظها المستخدم في Library (نصوص ASR + ملخصات).

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`favorite`	string	اختياري	`1` أو `true` لإرجاع المفضلة فقط.
`q`	string	اختياري	تطابق جزئي في العنوان/المؤلف.
`tag`	string	اختياري	تصفية بالوسم.
`limit`	integer	اختياري	1–100 (افتراضي 20).
`offset`	integer	اختياري	إزاحة الصفحات.

GET /v1/library/{id} مجاني

يجلب بيانات عنصر Library واحد. استخدم has_asr / has_summary لتقرير أي endpoint محتوى تستدعي بعدها.

GET /v1/library/{id}/transcript مجاني

يُرجع segments ASR والنص المدمج. 404 إذا لم يوجد ASR مكتمل.

GET /v1/library/{id}/summary مجاني

يُرجع نص الملخص المحفوظ. استخدم ?locale= لاختيار من اللغات المحفوظة (افتراضيًا Accept-Language ثم en). 404 عند عدم وجود ملخص لـ (video_id, locale).

POST /v1/library مجاني (وحدة حصة توكن واحدة)

kind=asr يضع علامة أن النص محفوظ (segments موجودة أصلاً في جدول ASR). kind=summary يرفع نص ملخص مُولَّد مسبقًا إلى جدول summaries ويضع has_summary=true. Upsert حسب (video_id, locale).

نص الطلب (JSON)

الاسم	النوع	مطلوب؟	الوصف
`video_id`	string	مطلوب	معرّف فيديو YouTube.
`kind`	string	مطلوب	`asr` أو `summary`.
`title / author / thumbnail / video_url / language / tag`	string	اختياري	بيانات وصفية للعرض/التصفية.
`locale`	string	في وضع summary	locale الملخص (افتراضيًا `Accept-Language` ثم `en`).
`text`	string	عند kind=summary	نص الملخص المراد حفظه.
`model`	string	اختياري	معرّف LLM (مثل `claude-opus-4`).

DELETE /v1/library/{id} مجاني

حذف ناعم لعنصر Library. POST /v1/library لاحق لنفس الفيديو يستعيد الصف بدل إنشاء تكرار.

مكتبات SDK الرسمية

استخدم مكتبات العميل الرسمية للتكامل السريع:

اللغة	المستودع
Python	api-sdk/python
JavaScript	api-sdk/javascript
Go	api-sdk/go
Java	api-sdk/java
Kotlin	api-sdk/kotlin
Rust	api-sdk/rust

→ الشيفرة الكاملة: github.com/SubDownload/api-sdk

→ للفوترة وحدود المعدل ورموز الأخطاء راجع الدعم والفوترة.

وثائق المطورين تُنشر بالإنجليزية. الشريط الجانبي يتبع اللغة المختارة.

مرجع الواجهة

Base URL: https://api.subdownload.com · Auth: Authorization: Bearer sk_live_xxx

نقاط النهاية

GET /v1/verify free

التحقّق من صحة مفتاح API. يُرجع معلومات الرمز والمستخدم. لا يستهلك أرصدة.

الطلب

curl -H "Authorization: Bearer sk_live_xxx" \
  https://api.subdownload.com/v1/verify

الاستجابة 200

{
  "valid": true,
  "token": { "name": "My App", "prefix": "sk_live_abc", "monthly_quota": 0, "used_quota": 120 },
  "user": { "id": 42, "email": "[email protected]", "plan": "free", "credits_remaining": 148 }
}

GET /v1/youtube/transcript 1 credit

جلب النص / الترجمات لفيديو YouTube. يقبل ID الفيديو أو أي URL صالح (watch، youtu.be، shorts).

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`video_id`	string	مطلوب	ID من 11 حرفًا أو URL YouTube كامل. الاسم البديل: `video_url`.
`lang`	string	اختياري	رموز اللغات المفضّلة مفصولة بفواصل (مثلًا `en,zh,ja`).

الطلب

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/transcript?video_id=dQw4w9WgXcQ&lang=en"

الاستجابة 200

{
  "data": {
    "video_id": "dQw4w9WgXcQ",
    "language": "en",
    "segments": [
      { "text": "We're no strangers to love", "start": 0.0, "duration": 3.5 }
    ],
    "text": "We're no strangers to love...",
    "meta": { "title": "...", "author": "...", "thumbnail": "..." }
  },
  "credits_used": 1,
  "credits_remaining": 148
}

الأخطاء

400 video_id مفقود · 404 بدون ترجمات · 402 نفاد الأرصدة

GET /v1/youtube/search 1 credit

البحث في YouTube عن فيديوهات أو قنوات مطابقة لكلمة مفتاحية.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`q`	string	مطلوب	استعلام البحث (1-200 حرفًا).
`type`	string	اختياري	`video` (افتراضي) أو `channel`.
`limit`	integer	اختياري	1-50 نتيجة (افتراضي 20).

الطلب

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://api.subdownload.com/v1/youtube/search?q=rust+tutorial&limit=5"

GET /v1/youtube/channel/resolve free

حلّ أي إشارة إلى قناة (@handle، URL، أو UC… ID) إلى معلومات قناة قانونية.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`input`	string	مطلوب	@handle، URL القناة، URL الفيديو أو UC… ID.

GET /v1/youtube/channel/search 1 credit

البحث داخل فيديوهات قناة محدّدة.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`channel`	string	مطلوب	@handle، URL أو UC… ID (الاسم البديل: `channel_id`).
`q`	string	مطلوب	استعلام البحث.
`limit`	integer	اختياري	1-50 (افتراضي 30).

GET /v1/youtube/channel/latest free

جلب أحدث ~15 فيديو لقناة عبر RSS. سريع ومجاني.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`channel`	string	مطلوب	@handle، URL أو UC… ID (الاسم البديل: `channel_id`).

GET /v1/youtube/channel/videos 1 credit/page

سرد كل الفيديوهات التي رفعتها قناة، مقسّم ~100 لكل صفحة.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`channel`	string	الصفحة الأولى	@handle، URL أو UC… ID (الاسم البديل: `channel_id`).
`continuation`	string	الصفحات التالية	الرمز المُعاد من الاستدعاء السابق.

ملاحظة: مرّر channel أو continuation، لا كليهما.

GET /v1/youtube/playlist/videos 1 credit/page

سرد فيديوهات قائمة تشغيل YouTube مع تقسيم الصفحات.

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`playlist`	string	الصفحة الأولى	URL أو ID قائمة التشغيل (`PL…`، `UU…`، `LL…`، `FL…`، `OL…`).
`continuation`	string	الصفحات التالية	الرمز من الاستجابة السابقة.

التفريغ الصوتي بالذكاء الاصطناعي (ASR)

POST /v1/youtube/asr 5 نقاط عند done

يبدأ تفريغًا صوتيًا غير متزامن باستخدام Whisper. يُرجع task_id وتلميحات ETA لضبط وتيرة الاستطلاع.

نص الطلب (JSON)

الاسم	النوع	مطلوب؟	الوصف
`video_url`	string	مطلوب	رابط YouTube (watch / youtu.be / shorts / embed).
`lang`	string	اختياري	تلميح اللغة (`en`، `ar`…). اتركه فارغًا للكشف التلقائي.

الطلب

curl -X POST -H "Authorization: Bearer sk_live_xxx"   -H "Content-Type: application/json"   -d '{"video_url":"https://youtu.be/dQw4w9WgXcQ"}'   https://api.subdownload.com/v1/youtube/asr

الاستجابة 202

{
  "task_id": "task_01HX...",
  "status": "queued",
  "from_cache": false,
  "queue_position": 2,
  "estimated_wait_seconds": 61,
  "next_poll_after_seconds": 15,
  "poll_url": "/v1/youtube/asr/task_01HX..."
}

التزم بـ next_poll_after_seconds بين كل استطلاع. عند إصابة الكاش يُعاد status=done مباشرة مع segments مضمّنة.

GET /v1/youtube/asr/{task_id} مجاني

استطلاع مهمة ASR. مجاني — بلا نقاط ولا حصة توكن. فقط المنشئ يستطيع القراءة.

الحالات: queued · downloading · transcribing · done · failed · cancelled. segments نهائية فقط عند status=done.

Library (مكتبة المستخدم)

GET /v1/library مجاني

يسرد العناصر التي حفظها المستخدم في Library (نصوص ASR + ملخصات).

المعامِلات

الاسم	النوع	مطلوب؟	الوصف
`favorite`	string	اختياري	`1` أو `true` لإرجاع المفضلة فقط.
`q`	string	اختياري	تطابق جزئي في العنوان/المؤلف.
`tag`	string	اختياري	تصفية بالوسم.
`limit`	integer	اختياري	1–100 (افتراضي 20).
`offset`	integer	اختياري	إزاحة الصفحات.

GET /v1/library/{id} مجاني

يجلب بيانات عنصر Library واحد. استخدم has_asr / has_summary لتقرير أي endpoint محتوى تستدعي بعدها.

GET /v1/library/{id}/transcript مجاني

يُرجع segments ASR والنص المدمج. 404 إذا لم يوجد ASR مكتمل.

GET /v1/library/{id}/summary مجاني

POST /v1/library مجاني (وحدة حصة توكن واحدة)

نص الطلب (JSON)

الاسم	النوع	مطلوب؟	الوصف
`video_id`	string	مطلوب	معرّف فيديو YouTube.
`kind`	string	مطلوب	`asr` أو `summary`.
`title / author / thumbnail / video_url / language / tag`	string	اختياري	بيانات وصفية للعرض/التصفية.
`locale`	string	في وضع summary	locale الملخص (افتراضيًا `Accept-Language` ثم `en`).
`text`	string	عند kind=summary	نص الملخص المراد حفظه.
`model`	string	اختياري	معرّف LLM (مثل `claude-opus-4`).

DELETE /v1/library/{id} مجاني

حذف ناعم لعنصر Library. POST /v1/library لاحق لنفس الفيديو يستعيد الصف بدل إنشاء تكرار.

مكتبات SDK الرسمية

استخدم مكتبات العميل الرسمية للتكامل السريع:

اللغة	المستودع
Python	api-sdk/python
JavaScript	api-sdk/javascript
Go	api-sdk/go
Java	api-sdk/java
Kotlin	api-sdk/kotlin
Rust	api-sdk/rust

→ الشيفرة الكاملة: github.com/SubDownload/api-sdk

→ للفوترة وحدود المعدل ورموز الأخطاء راجع الدعم والفوترة.