توثيق TwitterDown API

وثائق تطوير واجهة برمجة تطبيقات TwitterDown#

نظرة عامة#

توفر واجهة برمجة تطبيقات TwitterDown v1 وصولاً برمجيًا لاستخراج معلومات الفيديو من روابط Twitter/X. تسمح هذه الواجهة للمطورين بدمج قدرات تحليل فيديوهات تويتر في تطبيقاتهم.

عنوان URL الأساسي#

https://twitterdown.com/api/v1

المصادقة#

تتطلب جميع طلبات الـ API المصادقة باستخدام مفتاح API. يجب عليك تضمين مفتاح الـ API الخاص بك في رأس Authorization لكل طلب.

تنسيق مفتاح الـ API#

Authorization: Bearer مفتاح_الـ_API_الخاص_بك

الحصول على مفتاح الـ API#

1. أنشئ حساباً على TwitterDown.
2. اشترِ اشتراكاً مميزاً.
3. انتقل إلى قسم مفتاح الـ API في لوحة التحكم الخاصة بك.
4. أنشئ مفتاح API جديداً.

ملاحظة: الوصول إلى الـ API متاح فقط للمستخدمين المميزين.

تحديد المعدل (Rate Limiting)#

• الطلبات لكل دقيقة: 60
• الطلبات لكل ساعة: 1,000
• الطلبات لكل يوم: 10,000

تتضمن جميع الاستجابات رؤوس تحديد المعدل:

• X-RateLimit-Limit: حد الطلبات للنافذة الزمنية الحالية.
• X-RateLimit-Remaining: عدد الطلبات المتبقية في النافذة الحالية.
• X-RateLimit-Reset: الطابع الزمني يونكس عندما يتم إعادة تعيين حد المعدل.

نقاط النهاية (Endpoints)#

1. تحليل عنوان URL لفيديو تويتر#

يستخرج معلومات الفيديو من عنوان URL لـ Twitter/X.

عنوان نقطة النهاية: POST /twitter

الطلب

رؤوس الطلب:

Content-Type: application/json
Authorization: Bearer مفتاح_الـ_API_الخاص_بك

جسم الطلب (Request Body):

{
  "url": "https://x.com/username/status/1234567890123456789"
}

المعاملات (Parameters):

اسم المعامل	النوع	مطلوب	الوصف
url	string	نعم	عنوان URL صالح لتغريدة Twitter/X تحتوي على فيديو

الاستجابة

استجابة ناجحة (200 OK):

{
  "code": 0,
  "message": "ok",
  "data": {
    "thumbnail": "https://pbs.twimg.com/amplify_video_thumb/1234567890123456789/img/ExampleThumbnail.jpg",
    "videos": [
      {
        "resolution": "720p",
        "quality": "HD",
        "url": "https://video.twimg.com/amplify_video/1234567890123456789/vid/avc1/1280x720/ExampleVideoHD.mp4?tag=21"
      },
      {
        "resolution": "360p",
        "quality": "SD",
        "url": "https://video.twimg.com/amplify_video/1234567890123456789/vid/avc1/640x360/ExampleVideoSD.mp4?tag=21"
      },
      {
        "resolution": "270p",
        "quality": "SD",
        "url": "https://video.twimg.com/amplify_video/1234567890123456789/vid/avc1/480x270/ExampleVideoLow.mp4?tag=21"
      }
    ],
    "text": "هذا مثال لمحتوى تغريدة تحتوي على فيديو",
    "username": "username",
    "statusId": "1234567890123456789",
    "processed_at": "2024-01-01T12:00:00.000Z"
  }
}

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

اسم الحقل	النوع	الوصف
code	integer	رمز الاستجابة (0 = نجاح، -1 = خطأ)
message	string	رسالة الاستجابة
data	object	بيانات الاستجابة
thumbnail	string	عنوان URL للصورة المصغرة للتغريدة (يمكن أن يكون فارغاً)
videos	array	مصفوفة بتنسيقات الفيديو المتاحة
text	string	المحتوى النصي للتغريدة
username	string	اسم مستخدم تويتر
statusId	string	معرف حالة التغريدة
processed_at	string	طابع زمني ISO 8601 لوقت المعالجة

حقول كائن الفيديو:

اسم الحقل	النوع	الوصف
resolution	string	دقة الفيديو (مثل: "720p", "360p")
quality	string	جودة الفيديو (مثل: "HD", "SD")
url	string	رابط التحميل المباشر للفيديو

2. وثائق الـ API#

يحصل على وثائق الـ API ومعلومات الاستخدام.

عنوان نقطة النهاية: GET /twitter

الاستجابة

يعيد وثائق الـ API كاملة بتنسيق JSON، بما في ذلك معلومات نقاط النهاية، متطلبات المصادقة، والأمثلة.

معالجة الأخطاء#

تنسيق استجابة الخطأ#

{
  "code": -1,
  "message": "وصف الخطأ"
}

رموز حالة HTTP#

رمز الحالة	الوصف
200	نجاح
400	طلب سيء - معاملات غير صالحة
401	غير مصرح به - مفتاح API مفقود أو غير صالح
403	محظور - يتطلب اشتراكاً مميزاً
422	كيان غير قابل للمعالجة - تعذر تحليل URL
429	طلبات كثيرة جداً - تجاوز حد المعدل
500	خطأ داخلي في الخادم

رسائل الأخطاء الشائعة#

رسالة الخطأ	السبب
Missing API key	لم يتم توفير رأس Authorization
Invalid API key	مفتاح الـ API غير موجود أو منتهي الصلاحية
API access is only available for premium users	المستخدم غير المميز يحاول الوصول إلى الـ API
URL parameter is required	معلمة URL مطلوبة في جسم الطلب
Invalid Twitter/X URL format	تنسيق URL غير صحيح أو غير مدعوم
No video found	التغريدة لا تحتوي على محتوى فيديو

أمثلة#

مثال cURL#

curl --location --request POST 'https://twitterdown.com/api/v1/twitter' \
  --header 'Authorization: Bearer sk-1234567890abcdef123456789012345678' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "url": "https://x.com/username/status/1234567890123456789"
  }'

مثال JavaScript#

const response = await fetch('https://twitterdown.com/api/v1/twitter', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk-1234567890abcdef123456789012345678'
  },
  body: JSON.stringify({
    url: 'https://x.com/username/status/1234567890123456789'
  })
});

const data = await response.json();

if (data.code === 0) {
  console.log('تم العثور على الفيديو:', data.data.videos);
} else {
  console.error('خطأ:', data.message);
}

مثال Python#

import requests

url = "https://twitterdown.com/api/v1/twitter"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-1234567890abcdef123456789012345678"
}
payload = {
    "url": "https://x.com/username/status/1234567890123456789"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if data["code"] == 0:
    print("تم العثور على الفيديو:", data["data"]["videos"])
else:
    print("خطأ:", data["message"])

مثال PHP#

<?php
$url = 'https://twitterdown.com/api/v1/twitter';
$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer sk-1234567890abcdef123456789012345678'
];
$payload = json_encode([
    'url' => 'https://x.com/username/status/1234567890123456789'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data['code'] === 0) {
    echo "تم العثور على الفيديو: " . print_r($data['data']['videos'], true);
} else {
    echo "خطأ: " . $data['message'];
}
?>

أفضل الممارسات#

دعم تنسيق URL#

تدعم واجهة برمجة التطبيقات تنسيقات URL التالية:

• https://twitter.com/username/status/1234567890
• https://x.com/username/status/1234567890
• https://mobile.twitter.com/username/status/1234567890

معالجة الأخطاء#

تحقق دائماً من حقل code في الاستجابة:

• code: 0 يشير إلى النجاح
• code: -1 يشير إلى خطأ

نفّذ معالجة الأخطاء المناسبة في تطبيقك للتعامل مع أخطاء الـ API بطريقة أنيقة.

تحديد المعدل#

راقب رؤوس تحديد المعدل في الاستجابات وطبّق استراتيجية التراجع عند الاقتراب من الحدود.

الأمان#

• حافظ على سرية مفتاح الـ API الخاص بك؛ لا تكشف عنه أبداً في كود الواجهة الأمامية.
• قم بتخزين مفاتيح الـ API باستخدام متغيرات البيئة.
• قم بتدوير مفاتيح الـ API بانتظام.
• احذف مفاتيح الـ API غير المستخدمة.

الدعم#

للدعم والأسئلة المتعلقة بالـ API:

• البريد الإلكتروني: support@twitterdown.com
• الوثائق: https://twitterdown.com/docs
• صفحة الحالة: https://status.twitterdown.com

سجل التغييرات (Changelog)#

الإصدار 1.0.0 (27 مايو 2025)#

• الإصدار الأولي لواجهة برمجة التطبيقات
• تحليل فيديوهات Twitter/X
• مصادقة المستخدمين المميزين
• تنفيذ تحديد المعدل

آخر تحديث: 27 مايو 2025