البداية السريعة

يأخذك هذا الدليل من الصفر إلى فيديو يُشغَّل على صفحتك أنت. تجري كلّ خطوة في الوضع التجريبي، فتستطيع المتابعة بأمان دون المساس بأيّ محتوى حقيقيّ. ينبغي أن يستغرق ذلك نحو عشر دقائق.

المتطلّبات المسبقة

• حساب على فيديوهاتي. سجّل من لوحة التحكّم وأكّد بريدك الإلكتروني. تمرّ الحسابات الجديدة بمراجعة قصيرة قبل اعتمادها.
• واحد ممّا يلي لتنفيذ الطلبات:
  • Node.js الإصدار 18 أو أحدث، إن أردت استخدام حِزمة التطوير الرسمية، أو
  • curl، إن فضّلت استدعاء الواجهة البرمجية مباشرةً من الطرفيّة.

١. أنشئ مشروعًا

المشروع مساحة عمل تضمّ مجموعة من مقاطع الفيديو ومفاتيح الواجهة البرمجية الخاصّة بها. تستخدم معظم الفرق مشروعًا واحدًا لكلّ موقع أو تطبيق.

من لوحة التحكّم، أنشئ مشروعك الأوّل — مثلًا، Course videos. ستوجّه مفاتيحك وعمليّات رفعك إلى هذا المشروع من الآن فصاعدًا.

احصل على مفتاح واجهة برمجية

مفتاح الواجهة البرمجية هو السرّ الذي تستخدمه شيفرتك لتُثبت أحقّيّتها في التصرّف ضمن مشروعك. أنشئ واحدًا قبل تنفيذ أيّ طلب.

داخل مشروعك، افتح مفاتيح الواجهة البرمجية وأنشئ مفتاحًا في الوضع التجريبي. يُعرَض المفتاح كاملًا مرّة واحدة فقط، فانسخه فورًا واحفظه كسرّ.

• يظهر المفتاح التجريبي بالصيغة vh_test_... ويعمل على بيانات تجريبية — الواجهة ذاتها، مفصولة عن محتواك المباشر.
• يظهر المفتاح المباشر بالصيغة vh_live_... ويتصرّف في محتواك الحقيقيّ. لا تستخدم المفاتيح المباشرة إلّا لاحقًا، حين تكون جاهزًا.

صدّر مفتاحك التجريبي كي تستطيع الأمثلة أدناه قراءته:

export VIDEOHATI_API_KEY="vh_test_your_key_here"

٢. نفّذ أوّل طلب لك

أسرع طريقة للتأكّد من عمل مفتاحك هي سرد مقاطع الفيديو في مشروعك. يُرجِع المشروع الجديد تمامًا قائمة فارغة — وتلك النتيجة الفارغة هي النجاح الذي تبحث عنه.

تقع كلّ نقطة وصول تحت العنوان https://api.videohati.com/v1 وتُوثَّق بمفتاحك المُرسَل كرمز حامل (bearer).

curl https://api.videohati.com/v1/videos \
  -H "Authorization: Bearer $VIDEOHATI_API_KEY"

{
  "data": [],
  "nextCursor": null
}

npm install @videohati/node

import { Videohati } from "@videohati/node";

const client = new Videohati({ apiKey: process.env.VIDEOHATI_API_KEY });

const { data } = await client.videos.list();
console.log(`This project has ${data.length} video(s).`);

٣. ارفع أوّل فيديو لك

رفع الفيديو استدعاءٌ واحد. يُنشئ videos.upload() الفيديو، ويُرسل الملفّ على أجزاء صغيرة إلى نقطة الرفع، ويُكمل الرفع نيابةً عنك. ويتيح لك النداء الراجع onProgress متابعة التقدّم.

const video = await client.videos.upload("./lecture-01.mp4", {
  onProgress: ({ partsCompleted, totalParts }) => {
    console.log(`Uploaded part ${partsCompleted}/${totalParts}`);
  },
});

console.log(video.videoId); // 01JZ9WV3N8GQ5T2M7K4C6XBARH

بعد الرفع، تعالج فيديوهاتي الملفّ إلى عدّة مستويات جودة. انتظر حتى يصبح جاهزًا (ready) قبل أن تحاول تشغيله:

const ready = await client.videos.waitForState(video.videoId, {
  targetStates: ["ready", "failed"],
});

if (ready.state === "failed") {
  throw new Error("This video could not be processed.");
}

console.log("Video is ready to play.");

٤. شغّله

لعرض فيديو، يُنشئ خادمك أوّلًا جلسة تشغيل — إذنًا قصير الأمد لمشاهد واحد كي يشاهد فيديو واحدًا. أنشئها على الخادم وسلّم الصفحة رمز الجلسة فقط (لا مفتاح الواجهة البرمجية أبدًا).

const session = await client.playback.createSession({
  videoId: ready.id,
  viewerDisplayText: "[email protected]", // اختياري: يُعرَض فوق الفيديو
});

console.log(session.sessionToken); // مرّره إلى المشغّل

ثمّ ضمّن المشغّل في صفحتك. يقرأ المشغّل الخالي من الأُطُر ما يحتاجه من سمات data-:

<script src="https://cdn.videohati.com/player.js" async></script>
<div
  data-videohati-video-id="01JZ9WV3N8GQ5T2M7K4C6XBARH"
  data-videohati-project-id="01JZ9WV3N8GQ5T2M7K4C6XBARP"
  data-videohati-session-token="01JZ9WV3N8GQ5T2M7K4C6XBARK.1781485200.bXktbWFj"
></div>

تلك هي الحلقة كاملةً: ارفع، وانتظر الجاهزيّة، وأنشئ جلسة، وضمّن المشغّل. أوّل فيديو لك يُشغَّل الآن.

إلى أين بعد ذلك