ساخت رویداد پخش زنده

۱. دریافت توکن

هنگام تبادل کلید برنامه محدودهٔ live.write را درخواست کنید. کلید vck_ را مستقیم به endpoint رویداد نفرستید.

۲. ایجاد رویداد

POST https://videoclick.ir/api/v2/live-events
Authorization: Bearer vct_YOUR_ACCESS_TOKEN
Content-Type: application/json; charset=utf-8

{"title":"پخش زندهٔ رویداد امروز"}

پاسخ موفق 201 Created شامل id، uid، ingestUrl، streamKey، confirmed و panelUrl است. این API از تنظیمات سرور اختصاصی مشتری و پیش‌فرض‌های پنل استفاده می‌کند؛ پخش موجود را تغییر نمی‌دهد.

۳. اتصال نرم‌افزار پخش

ingestUrl و streamKey را در بخش Server و Stream Key نرم‌افزار خود قرار دهید. کلید پخش را در مرورگر، کد Embed یا مخزن عمومی منتشر نکنید. رویداد ابتدا با confirmed: false ساخته می‌شود؛ وضعیت و لینک تماشا را در panelUrl بررسی کنید.

تنظیمات اختیاری هنگام ساخت

علاوه بر title می‌توانید description، directPlayEnable، chatEnable، chatUserCount، liveUserCount، chatOnLive، allowDomains، allowIPs و endMessage بفرستید. فیلدهای ارسال‌نشده پیش‌فرض پنل را می‌گیرند؛ ایجاد رویداد آغاز واقعی پخش نیست.

فهرست و جزئیات رویدادها

GET https://videoclick.ir/api/v2/live-events?page=1&pageSize=25
Authorization: Bearer vct_YOUR_ACCESS_TOKEN

GET https://videoclick.ir/api/v2/live-events/452
Authorization: Bearer vct_YOUR_ACCESS_TOKEN

با live.read فقط رویدادهای متعلق به حساب و وضعیت آن‌ها را بخوانید. پاسخ این مسیرها streamKey را بازنمی‌گرداند. برای بازیابی محرمانهٔ اطلاعات اتصال، GET /api/v2/live-events/{liveId}/credentials را با live.write از سرور برنامه بزنید؛ کلید را در لاگ یا مرورگر نگذارید.

ویرایش تنظیمات و حذف

با live.write، درخواست PUT تمام تنظیمات نمایشی را جایگزین می‌کند، ولی شناسهٔ پخش، کلید ingest، ظرفیت و وضعیت جلسهٔ فعال را عوض نمی‌کند. حذف فقط برای رویداد غیرفعال و بدون سابقهٔ برگزاری ممکن است؛ در غیر این صورت 409 live_in_use می‌گیرید.

PUT https://videoclick.ir/api/v2/live-events/452
Authorization: Bearer vct_YOUR_ACCESS_TOKEN
Content-Type: application/json; charset=utf-8

{"title":"پخش جمعه","description":"پوشش زنده",
 "directPlayEnable":false,"chatEnable":true,
 "chatUserCount":true,"liveUserCount":true,"chatOnLive":false,
 "allowDomains":"*","allowIPs":"*","endMessage":"پخش تمام شد"}

DELETE https://videoclick.ir/api/v2/live-events/452

گردش کامل اتصال و وضعیت

برای ساخت رویداد، هدر Idempotency-Key یکتا و ثابت برای همان درخواست بفرستید. اگر پاسخ قطع شد، همان درخواست را با همان مقدار تکرار کنید. وضعیت واقعی از گزارش callback سرور ingest و زمان آخرین سیگنال می‌آید؛ ساخت رویداد به‌تنهایی onAir نیست.

POST /api/v2/live-events
Idempotency-Key: event-2026-10-19-001
Authorization: Bearer vct_YOUR_ACCESS_TOKEN
Content-Type: application/json

{"title":"رویداد نمونه"}

GET /api/v2/live-events/452/status
GET /api/v2/live-events/452/playback
GET /api/v2/live-events/452/credentials

وضعیت on_air به معنی جلسهٔ باز و گزارش RTMP تازه، stale به معنی سیگنال کهنه، offline به معنی نبود پخش، و unobserved برای رویداد قدیمی فاقد سیگنال اختصاصی است. بازهٔ پیش‌فرض ۳۵ ثانیه است. لینک Embed جدا از کلید محرمانه دریافت می‌شود.

ویرایش جزئی و پایان رویداد

PATCH فقط فیلدهای ارسالی را تغییر می‌دهد. POST .../finish ابتدا انتشار دوباره را در بانک مسدود می‌کند، سپس ناشر را از کنترل محلی Nginx قطع و جلسه را می‌بندد. پاسخ 503 ingest_stop_uncertain یعنی قطع تأیید نشده است؛ پس از رفع خطا فرمان را تکرار کنید. رویداد پایان‌یافته دیگر قابل انتشار نیست و برای پخش بعدی باید رویداد تازه بسازید.

PATCH /api/v2/live-events/452
Authorization: Bearer vct_YOUR_ACCESS_TOKEN
Content-Type: application/json

{"title":"عنوان تازه"}

POST /api/v2/live-events/452/finish
Authorization: Bearer vct_YOUR_ACCESS_TOKEN