بارگذاری ویدیو از برنامهٔ شما

۱. ایجاد نشست

بدنهٔ JSON شامل groupId، title، fileName، fileSize به بایت و durationSeconds است. sha256 و idempotencyKey اختیاری‌اند. شناسهٔ تکرار را برای همان فایل ثابت نگه دارید.

POST https://videoclick.ir/api/v2/upload-sessions
Authorization: Bearer vct_YOUR_ACCESS_TOKEN
Content-Type: application/json

{"groupId":123,"title":"ویدیوی آموزشی","fileName":"lesson.mp4",
 "fileSize":5242880,"durationSeconds":180,
 "idempotencyKey":"lesson-001"}

پاسخ ۲۰۱: {"success":true,"upload":{"uploadId":"32-character-hex","State":"uploading","FileSize":5242880,"NextOffset":0,"chunkSize":1048576,"VideoId":null,"ErrorCode":null}}. نام بعضی فیلدهای شیء upload در کنترلر فعلی با حرف بزرگ آغاز می‌شوند؛ مقدار uploadId و chunkSize با حرف کوچک است.

۲. ارسال قابل ادامه

از NextOffset آغاز کنید. بدنهٔ درخواست خودِ بایت‌های فایل است؛ multipart نفرستید. هر پاسخ nextOffset می‌دهد. پس از قطع ارتباط، با GET وضعیت نشست، جای قطعهٔ بعدی را بخوانید و همان فایل را ادامه دهید.

PUT https://videoclick.ir/api/v2/upload-sessions/{uploadId}/chunks?offset=0
Authorization: Bearer vct_YOUR_ACCESS_TOKEN
Content-Type: application/octet-stream

[up to 1048576 raw file bytes]

در صورت دریافت ۴۰۹، GET /api/v2/upload-sessions/{uploadId} را بزنید. ارسال دوبارهٔ قطعهٔ یکسان پشتیبانی می‌شود؛ قطعهٔ تکراریِ متفاوت خطا می‌دهد. سقف نرخ ارسال برای هر حساب ۲۴۰ درخواست قطعه در دقیقه است.

۳. تکمیل انتقال

وقتی NextOffset با FileSize برابر شد، درخواست تکمیل را بفرستید؛ اگر پاسخ گم شد، همان نشست و همان فرمان را تکرار کنید. سرویس نوع فایل و در صورت ارائه، SHA-256 را بررسی و سپس آن را به فرایند پردازش فعلی تحویل می‌دهد.

POST https://videoclick.ir/api/v2/upload-sessions/{uploadId}/complete
Authorization: Bearer vct_YOUR_ACCESS_TOKEN

پاسخ موفق شامل videoId و processingState: "queued" است. این پاسخ پایان انتقال فایل است، نه آماده‌شدن ویدیو برای پخش. اگر downstream_uncertain دریافت کردید، وضعیت نشست را بخوانید و برای نشست تازهٔ v2 همان complete را تکرار کنید. نشست‌های ساخته‌شده پیش از نصب نسخهٔ جدید به بررسی دستی نیاز دارند.

آپلود گروهی

با یک درخواست، مشخصات حداکثر ۸ ویدیو ثبت می‌شود. هر نتیجه مستقل است؛ پاسخ HTTP ۲۰۰ می‌تواند برای برخی آیتم‌ها success:false داشته باشد. قطعه‌ها و تکمیل هر نشست را جداگانه انجام دهید.

POST https://videoclick.ir/api/v2/upload-sessions/batch
Authorization: Bearer vct_YOUR_ACCESS_TOKEN
Content-Type: application/json

{"videos":[
 {"groupId":123,"title":"قسمت اول","fileName":"part1.mp4","fileSize":5242880,"durationSeconds":180},
 {"groupId":123,"title":"قسمت دوم","fileName":"part2.mp4","fileSize":7340032,"durationSeconds":210}
]}

مجوز گروهی را با GET /capabilities و فیلد batchEnabled بررسی کنید. حداکثر ۸ نشست باز هم‌زمان برای هر حساب مجاز است.

پیگیری نشست و پردازش

وضعیت ویدیو یکی از queued، processing، ready، failed، downloading یا unknown است. فقط پس از ready لینک تماشا را نمایش دهید. نسخهٔ فعلی برای آماده‌شدن ویدیو وب‌هوک ندارد؛ وضعیت را با فاصلهٔ معقول بررسی کنید.

کدهای خطا و بازیابی

پاسخ خطا به شکل {"success":false,"error":{"code":"...","message":"..."}} برمی‌گردد. کلید API را در گزارش خطا ذخیره نکنید.

نمونهٔ اجرای گروهی

هر دو فایل Python پایین را در یک پوشه بگذارید و فهرست حداکثر ۸ فایل را در videos.json کنار آن‌ها ذخیره کنید. برای هر فایل، نتیجهٔ ثبت نشست جدا بررسی می‌شود و از شناسهٔ ثابت جلوگیری از تکرار استفاده می‌شود.

[
  {"file":"part1.mp4","groupId":123,"title":"قسمت اول","durationSeconds":180},
  {"file":"part2.mp4","groupId":123,"title":"قسمت دوم","durationSeconds":210}
]

python3 videoclick_bulk_upload_v2.py videos.json

فهرست، جزئیات، ویرایش و حذف

شناسهٔ عددی numericVideoId را از پاسخ وضعیت پردازش بخوانید. شناسهٔ متنی وضعیت آپلود با شناسهٔ عددی مدیریت متفاوت است.

PUT جایگزینی کامل تنظیمات است؛ بولی حذف‌شده به false و دامنهٔ حذف‌شده به * برمی‌گردد. نخست جزئیات را بخوانید و همهٔ تنظیمات مطلوب را بفرستید.

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

{"title":"جلسهٔ اول - نسخهٔ نهایی","description":"معرفی دوره",
 "downloadable":false,"directPlayEnable":false,
 "googleAnalytics":"","theme":"#5A61E6",
 "allowDomains":"*","allowIPs":"*"}

افزودن از آدرس

با محدودهٔ video.import فایل MP4/WebM را از آدرس مستقیم HTTPS ثبت کنید. مدیر سرور باید میزبان منبع را در DeveloperApiV2ImportAllowedHosts مجاز کرده باشد. پاسخ ۲۰۲ به معنی پذیرش است؛ آماده‌شدن را جداگانه بررسی کنید.

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

{"groupId":123,"title":"ویدیوی معرفی",
 "videoUrl":"https://cdn.example.com/files/intro.mp4"}

اگر میزبان مجاز نشده باشد 403 import_host_denied برمی‌گردد. فقط منابع قابل اعتماد و فایل‌های با حجم کنترل‌شده را مجاز کنید.

از آپلود تا مدیریت بدون ورود به پنل

پس از تکمیل نشست، videoId متنی را از پاسخ بگیرید و GET /api/v2/videos/{videoId} را تا ready دنبال کنید. سپس numericVideoId را برای ویرایش بگیرید. فهرست سراسری با جستجو و اطلاعات نمایش مسیرهای جداگانه دارند.

GET /api/v2/upload-sessions
GET /api/v2/videos?page=1&pageSize=25&q=جلسه
GET /api/v2/videos/72882/playback
PATCH /api/v2/videos/72882
Authorization: Bearer vct_YOUR_ACCESS_TOKEN
Content-Type: application/json

{"title":"جلسهٔ اول، نسخهٔ ویرایش‌شده"}

PATCH فیلدهای ارسال‌نشده را حفظ می‌کند. نشست آپلود را فقط تا وقتی در وضعیت uploading است با DELETE /api/v2/upload-sessions/{uploadId} لغو کنید. در وضعیت uncertain، همان فرمان complete نتیجهٔ شناسهٔ پایدار را بازیابی می‌کند یا ارسال را بدون ایجاد ویدیوی دوم تکرار می‌کند؛ این قابلیت به نصب نسخهٔ جدید Delivery وابسته است.