توثيق الـ API

أرسل رابط يوتيوب من موقعك أو تطبيقك، واحصل على رابط الفيديو المستضاف لدينا.

البدء

تُرسَل جميع الطلبات إلى العنوان التالي، وتُعاد الردود بصيغة JSON:

https://mystorevid.com/v1
  1. أنشئ مفتاحاً من صفحة مفاتيح API في حسابك، وانسخه فور ظهوره، إذ لن يُعرض كاملاً مرة أخرى.
  2. أرسل رابط يوتيوب عبر POST /videos، وستحصل على فيديو حالته queued.
  3. انتظر حتى تصبح الحالة ready، إما بالاستعلام عن GET /videos/{id} على فترات، أو باستقبال Webhook وهو الخيار الأفضل.
  4. استخدم urls.watch أو urls.embed أو urls.file في موقعك.
يجب أن تكون لديك باقة فعّالة ومساحة متاحة حتى يُقبل طلب إضافة الفيديو.

المصادقة (المفتاح)

أرسل المفتاح في ترويسة Authorization مع كل طلب:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

ويمكنك بدلاً من ذلك إرساله في ترويسة X-API-Key. المفتاح سرّي مثل كلمة المرور، فاستخدمه من خادمك فقط، ولا تضعه في كود صفحة ويب أو في تطبيق جوال يمكن فك شفرته. وإذا تسرّب المفتاح فألغِه من صفحة المفاتيح وأنشئ مفتاحاً جديداً.

حدود الاستخدام

الحدالقيمة
جميع الطلبات60 طلباً في الدقيقة لكل مفتاح
إضافة فيديو (POST)20 طلباً في الدقيقة لكل مفتاح
عدد المفاتيح10 مفاتيح فعّالة لكل حساب

عند تجاوز الحد يُعاد الرمز 429 مع ترويسة Retry-After التي تحدد عدد الثواني الواجب انتظارها.

كائن الفيديو

جميع الطلبات التي تُعيد فيديو تُعيده بالشكل التالي:

{
  "id": "vid_8f3a21kq0p",
  "title": "Big Buck Bunny",
  "status": "ready",          // queued | downloading | processing | ready | failed
  "progress": 100,              // 0–100
  "quality": "720p",           // الجودة المطلوبة
  "height": 720,                // الجودة الفعلية
  "duration_seconds": 596,
  "size_bytes": 167772160,
  "source": "youtube",
  "source_url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
  "created_via": "api",
  "urls": {                     // null حتى يجهز الفيديو
    "watch": "https://mystorevid.com/v/vid_8f3a21kq0p",
    "embed": "https://mystorevid.com/e/vid_8f3a21kq0p",
    "file":  "https://mystorevid.com/f/vid_8f3a21kq0p"
  },
  "embed_html": "<iframe src=… allowfullscreen></iframe>",
  "thumbnail": "https://i.ytimg.com/vi/aqz-KE-bpKQ/hqdefault.jpg",
  "error": null,                 // {"code","message"} عندما تكون الحالة failed
  "created_at": "2026-11-18T18:00:00+00:00",
  "updated_at": "2026-11-18T18:01:12+00:00"
}

إضافة فيديو

POST/v1/videos
الحقلالنوعالوصف
youtube_urlنص · إلزاميرابط فيديو على يوتيوب (watch أو youtu.be أو shorts أو live)
qualityنص360p أو 720p أو 1080p أو 4K، والقيمة الافتراضية 720p. إذا لم تتوفر الجودة المطلوبة نختار أقرب جودة أقل منها.
titleنصاسم تختاره للفيديو. إذا لم تُرسله نستخدم عنوان الفيديو على يوتيوب.
curl -X POST https://mystorevid.com/v1/videos \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"youtube_url":"https://youtu.be/aqz-KE-bpKQ","quality":"720p"}'

يكون الرد 202 Accepted ومعه {"data": {…الفيديو…}} بالحالة queued، ويجري التنزيل في الخلفية.

حالة فيديو

GET/v1/videos/{id}
curl https://mystorevid.com/v1/videos/vid_8f3a21kq0p -H "Authorization: Bearer sk_live_…"

إذا كنت تستعلم دورياً بدلاً من استخدام الـ Webhook، فاجعل الفاصل بين كل استعلام والذي يليه خمس ثوانٍ على الأقل.

قائمة الفيديوهات

GET/v1/videos?status=ready&page=1&per_page=20

المعامل status اختياري للتصفية، وقيمة per_page من 1 إلى 100. والرد هو {"data": [ … ], "meta": {"page", "per_page", "total", "last_page"}} مرتباً من الأحدث إلى الأقدم.

تعديل الاسم

PATCH/v1/videos/{id}
curl -X PATCH https://mystorevid.com/v1/videos/vid_8f3a21kq0p \
  -H "Authorization: Bearer sk_live_…" -H "Content-Type: application/json" \
  -d '{"title":"الدرس الأول"}'

حذف فيديو

DELETE/v1/videos/{id}

يحذف الفيديو وملفه نهائياً ويُعيد المساحة إلى حسابك. وإذا كان الفيديو لا يزال قيد التنزيل فسيُلغى التنزيل. والرد هو {"data": {"id": "…", "deleted": true}}.

بيانات الحساب

GET/v1/me

يُعيد صاحب المفتاح، والباقة وتاريخ انتهائها، والمساحة (limit_bytes وused_bytes وfree_bytes)، والجودات المتاحة. ويُنصح باستدعائه أولاً للتأكد من أن المفتاح يعمل.

الـ Webhook

أضف رابطاً يبدأ بـ https:// في صفحة مفاتيح API، وسنرسل إليه طلب POST فور اكتمال الفيديو أو فشله:

POST https://your-site.com/hooks/videos
Content-Type: application/json
X-VP-Event: video.ready                     // video.ready | video.failed | video.test
X-VP-Signature: t=1795020000,v1=5f2c…e91a

{"event": "video.ready", "created_at": "2026-11-18T18:01:12+00:00", "data": {"video": {…كائن الفيديو…}}}

التحقق من أن الطلب صادر منّا

احسب قيمة HMAC-SHA256 للنص t + "." + body (بمحتوى الطلب كما وصلك تماماً) باستخدام مفتاح التوقيع whsec_…، ثم قارنها بالقيمة v1. وارفض الطلب إذا كانت قيمة t أقدم من خمس دقائق.

// PHP
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_VP_SIGNATURE'] ?? ''), $sig);
$ok = isset($sig['t'], $sig['v1'])
   && abs(time() - (int) $sig['t']) < 300
   && hash_equals(hash_hmac('sha256', $sig['t'].'.'.$raw, 'whsec_…'), $sig['v1']);
if (! $ok) { http_response_code(400); exit; }
$event = json_decode($raw, true);

أجب برمز من فئة 2xx خلال عشر ثوانٍ. وإذا لم يصلنا رد أو أُعيد خطأ، نعيد المحاولة مرتين: بعد 30 ثانية، ثم بعد خمس دقائق. وقد يصلك الحدث نفسه أكثر من مرة، لذا اعتمد على data.video.id في معالجته.

الأخطاء

يُعاد أي خطأ بالشكل التالي:

{"error": {"code": "validation_failed", "message": "The youtube url field is required.", "fields": {"youtube_url": ["…"]}}}
HTTPcodeالمعنى
401unauthorizedالمفتاح غير موجود أو غير صحيح أو مُلغى
402no_subscriptionلا توجد باقة فعّالة في الحساب
403account_unverifiedلم يُؤكَّد البريد الإلكتروني للحساب بعد
404not_foundالفيديو غير موجود في حسابك، أو المسار غير صحيح
409storage_fullامتلأت مساحة التخزين
422validation_failed / invalid_urlبيانات ناقصة أو غير صحيحة، والتفاصيل في fields
429rate_limitedتجاوزت الحد المسموح، فانتظر عدد ثواني Retry-After
500server_errorخطأ من جهتنا، فأعد المحاولة لاحقاً

أما إذا فشل تنزيل الفيديو نفسه، فيكون الطلب قد نجح لكن تصبح حالة الفيديو failed ويحمل error.code بإحدى القيم التالية: private (فيديو خاص)، أو unavailable (محذوف)، أو members (للأعضاء فقط)، أو live (بث مباشر)، أو age (مقيّد بالعمر)، أو no_space (المساحة غير كافية)، أو blocked، أو failed.

أمثلة كاملة

PHP

$ch = curl_init('https://mystorevid.com/v1/videos');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['youtube_url' => 'https://youtu.be/aqz-KE-bpKQ', 'quality' => '720p']),
]);
$video = json_decode(curl_exec($ch), true)['data'];
echo $video['id'];   // احفظ المعرّف، وسيصلك في الـ Webhook عند اكتمال الفيديو

JavaScript (Node 18+)

const res = await fetch('https://mystorevid.com/v1/videos', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.VP_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ youtube_url: 'https://youtu.be/aqz-KE-bpKQ', quality: '1080p' }),
});
const { data, error } = await res.json();

Python

import os, requests
r = requests.post('https://mystorevid.com/v1/videos',
    headers={'Authorization': 'Bearer ' + os.environ['VP_KEY']},
    json={'youtube_url': 'https://youtu.be/aqz-KE-bpKQ', 'quality': '720p'})
video = r.json()['data']