TwitterDownTwitterDown

توثيق TwitterDown API

TwitterDownon 17 days ago

وثائق تطوير واجهة برمجة تطبيقات 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