API v1 مستقرة

واجهة API لوصف الفيديو التوثيق

أنشئ عناوين وأوصافًا ووسومًا مدعومة بالذكاء الاصطناعي لأي فيديو. معالجة غير متزامنة مع تسليم عبر webhook وبيئة sandbox مجانية للاختبار. تفضّل واجهة استخدام؟ استخدم بوابة Descrideo لرفع الفيديوهات وإدارة المهام.

دليل البدء السريع جرّب Sandbox مجانًا

تفضّل واجهة استخدام؟ استخدم مولد الفيديو الخاص بنا لرفع الفيديوهات والحصول على النتائج بدون كتابة شيفرة.

بدء سريع

ابدأ باستخدام Descrideo API في 3 خطوات بسيطة. أنشئ أول وصف فيديو خلال أقل من 5 دقائق.

1

احصل على مفتاح API

أنشئ حسابًا واحصل على مفتاح API من لوحة التحكم. كل مفتاح يبدأ بالمقدمة nxt_.

إنشاء حساب →
2

أنشئ مهمة وصف

أرسل رابط فيديو وحدد نقطة نهاية الـ webhook لاستلام النتائج.

الطلب POST 
curl -X POST https://api.descrideo.com/v1/video-descriptions \
  -H "X-API-Key: nxt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "direct_url",
      "url": "https://example.com/video.mp4"
    },
    "frames": 20,
    "generation_mode": "vision",
    "webhook": {
      "url": "https://your-app.com/webhooks/video"
    },
    "client_context": {
      "lang": "en",
      "output_fields": ["title", "description", "tags"]
    }
  }'
3

استقبل webhook بالنتائج

عند اكتمال المعالجة، سنرسل النتائج إلى رابط الـ webhook الخاص بك عبر طلب POST موقّع بـ HMAC.

حمولة الـ Webhook 
{
  "job_id": "01HXYZ123ABC",
  "status": "succeeded",
  "result": {
    "title": "Mountain Hiking Adventure in Swiss Alps",
    "description": "A breathtaking journey through...",
    "tags": ["hiking", "mountains", "switzerland", "nature"]
  },
  "billing": {
    "token_cost": 1.23,
    "base_cost": 1.0,
    "frames_cost": 0.0,
    "transcription_cost": 0.23
  },
  "meta": {
    "generation_mode": "vision_audio",
    "transcription": {
      "enabled": true,
      "status": "completed",
      "seconds": 45.5
    }
  },
  "timing_ms": {
    "probe": 500,
    "audio": 3200,
    "frames": 2100,
    "ai": 8100,
    "webhook": 120
  }
}

المصادقة

تتطلب جميع طلبات API المصادقة عبر Bearer token في ترويسة Authorization. 

Authorization: Bearer nxt_your_api_key_here

الأمان: لا تكشف مفتاح API أبدًا داخل شيفرة العميل. نفّذ استدعاءات API دائمًا من الخادم الخلفي لديك.

اختبار Sandbox

اختبر تكامل الـ webhook مجانًا باستخدام بيئة sandbox لدينا. تحاكي مهام sandbox سير العمل الكامل دون معالجة فيديو حقيقية.

مزايا Sandbox

  • حصة يومية مجانية دون الحاجة إلى توكنات
  • عمليات تسليم webhook حقيقية مع تواقيع HMAC
  • لا حاجة إلى رابط فيديو
  • إعادة تشغيل webhook لأغراض التصحيح
طلب Sandbox POST 
POST /v1/sandbox/video-descriptions

{
  "frames": 10,
  "webhook": {
    "url": "https://your-app.com/webhooks/video"
  },
  "client_context": {
    "lang": "en",
    "output_fields": ["title", "description", "tags"],
    "custom_instructions": "Focus on technical details"
  }
}

Demo API (بوابة مرور)

تتيح لك Demo API التكامل مع سير عمل غير متزامن حقيقي مع تسليم عبر webhook قبل الإطلاق الفعلي. استخدمها للتحقق من الوصول المباشر لرابط الفيديو ومستقبل الـ webhook لديك.

القيود: مهمة واحدة يوميًا لكل مفتاح Demo API، وframes=10 فقط، وlang=en فقط (أي لغة أخرى تعيد 422). التعليمات المخصصة مسموح بها.

نقاط النهاية

  • POST /api/demo/v1/video-descriptions — إنشاء مهمة تجريبية (روابط مباشرة فقط)
  • GET /api/demo/v1/video-descriptions/{job_id} — جلب الحالة/النتيجة
  • POST /api/demo/v1/video-descriptions/{job_id}/replay-webhook — إعادة تشغيل الـ webhook المرسل إلى المستقبل لديك
  • GET /api/demo/v1/webhook-secret — الحصول على سر الـ webhook للتحقق من التوقيع

إنشاء مهمة تجريبية (مثال)

الطلب POST 
curl -X POST https://your-portal.com/api/demo/v1/video-descriptions \
  -H "X-API-Key: demo_your_demo_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "direct_url",
      "url": "https://example.com/video.mp4"
    },
    "frames": 10,
    "webhook": {
      "url": "https://your-app.com/webhooks/demo"
    },
    "client_context": {
      "lang": "en",
      "output_fields": ["title", "description", "tags"],
      "custom_instructions": "Make the description more detailed"
    }
  }'

تواقيع Webhook

تعيد Demo API توجيه webhooks إلى رابطك باستخدام نفس ترويسات التوقيع كما في الواجهة الرئيسية: X-Nxt-Timestamp وX-Nxt-Signature. استخدم GET /api/demo/v1/webhook-secret للحصول على السر المستخدم للتحقق.

إنشاء مهمة وصف

POST /v1/video-descriptions

جسم الطلب

المعلمة النوع مطلوب الوصف
source object نعم إعدادات مصدر الفيديو
type string * direct_url أو source_provider
url string * رابط مباشر لملف الفيديو (عندما type=direct_url)
provider object * إعدادات نقطة نهاية Source Provider (عندما type=source_provider)
webhook.url string نعم الرابط الذي يستقبل النتائج
client_context.output_fields array لا الحقول التي سيتم إنشاؤها: title وdescription وtags
client_context.lang string لا لغة المخرجات (ISO 639-1)، الافتراضي: en
frames integer نعم عدد الإطارات المستخرجة: 10 أو 20 أو 30. مطلوبة في وضعي vision وvision_audio ولا تستخدم في وضع audio.
generation_mode string لا vision (الافتراضي) أو vision_audio أو audio. يحدد وضع التحليل.
transcription object لا إعدادات التفريغ الصوتي. تختلف الحقول المطلوبة بحسب generation_mode.
enabled boolean * تفعيل التفريغ الصوتي. يُفعّل تلقائيًا في وضعي vision_audio/audio.
segments integer * عدد مقاطع الصوت المأخوذة كعينات: 10 أو 20 أو 30
segment_sec number * مدة كل مقطع بالثواني (5–60)
client_context.custom_instructions string لا تعليمات ذكاء اصطناعي مخصصة لأسلوب المخرجات

الاستجابة

تعيد 202 Accepted مع معرّف المهمة.

{
  "job_id": "01HXYZ123ABC",
  "status": "queued"
}

جلب حالة المهمة

GET /v1/video-descriptions/{job_id}

افحص حالة المهمة دوريًا. مفيد لمتابعة التقدم إذا لم تكن webhooks مناسبة.

حالات المهمة

queued

المهمة بانتظار المعالجة

resolving_source

جارٍ حل الوصول إلى الفيديو

probing

جارٍ تحليل بيانات الفيديو الوصفية

extracting_audio

جارٍ استخراج مقاطع الصوت

transcribing_audio

جارٍ تحويل الصوت إلى نص

extracting_frames

جارٍ استخراج إطارات الفيديو

ai_request

الذكاء الاصطناعي ينشئ الأوصاف

succeeded

اكتملت المعالجة

failed

فشلت المعالجة

أمان الـ Webhook

تُوقّع جميع webhooks باستخدام HMAC-SHA256. تحقّق من التواقيع لضمان الموثوقية.

ترويسات التوقيع

X-Nxt-Timestamp: 1707400000
X-Nxt-Signature: sha256=abc123def456...

مثال تحقق (Python)

import hmac
import hashlib

def verify_webhook(raw_body: bytes, timestamp: str, signature_header: str, secret: str) -> bool:
    # Signature header format: "sha256="
    expected_sig = signature_header.removeprefix("sha256=")
    message = raw_body + timestamp.encode()
    computed = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed, expected_sig)

نصيحة: احصل على سر الـ webhook من GET /v1/webhook-secret

نمط Source Provider

بالنسبة للفيديوهات الخاصة، استخدم نمط Source Provider. تعمل نقطة النهاية الخاصة بك كوسيط وصول يعيد روابط موقعة مسبقًا عندما تحتاج واجهتنا إلى جلب الفيديو.

سير العمل

  1. 1 ترسل المهمة مع إعدادات source.provider
  2. 2 تستدعي واجهتنا نقطة النهاية لديك بطلب موقّع
  3. 3 تتحقق أنت من التوقيع وتعيد رابطًا موقّعًا مسبقًا
  4. 4 تجلب واجهتنا الفيديو من الرابط الموقّع مسبقًا

الأمان: تبقى فيديوهاتك خاصة. نحن نصل إليها فقط عبر روابط موقعة مؤقتة تتحكم أنت بها.

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

تعيد الواجهة رموز HTTP قياسية مع رسائل خطأ مفصلة.

الحالة المعنى
400 طلب غير صالح - معلمات غير صحيحة
401 غير مصرح - مفتاح API غير صالح
402 الدفع مطلوب - توكنات غير كافية
404 غير موجود - المورد غير موجود
429 تجاوز حد المعدل - طلبات كثيرة جدًا
500 خطأ داخلي - مشكلة في الخادم

الفوترة والتوكنات

التكلفة الأساسية لكل مهمة ناجحة هي 1 توكن. يُحسب التفريغ الصوتي كإضافة لكل 10 ثوانٍ من الصوت المأخوذ كعينة. وتُبلغ التكلفة النهائية داخل حقل billing.token_cost في الـ webhook.

الوضع مسبق الدفع

اشترِ باقات توكنات مقدمًا. تُحجز التوكنات عند إنشاء المهمة وتُقتطع عند النجاح.

الوضع لاحق الدفع

ادفع في نهاية دورة الفوترة. يمكن تحديد حدود شهرية اختيارية للتحكم في الإنفاق.

عرض خطط الأسعار