help-header

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

برای کار با پلتفرم میزبانی ویدیو ابر آروان، می‌توانید از دو روش استفاده از پنل کاربری ابر آروان یا استفاده از API ابر آروان بهره ببرید. در حالی که روش اول برای کاربران نهایی مناسب‌تر است، امکانات و دسترسی‌های API میزبانی ویدیو ابر آروان ابزاری قدرتمند را برای توسعه‌دهندگان فراهم می‌کند.

در این راهنمای فنی، به معرفی API پلتفرم ویدیو ابر آروان و شیوه‌ی کار با آن می‌پردازیم. هم‌چنین، می‌توانید اطلاعات بیش‌تر درباره‌ی این ابزار را در بخش مستندات API پلتفرم میزبانی ویدیو ابر آروان مشاهده کنید.

 

آغاز کار با API

برای آغاز کار با API ابر آروان، داشتن کلید API یا API Key الزامی است. این کار به‌سادگی و از طریق پنل کاربری ابر آروان امکان‌پذیر است. برای اطلاع از شیوه‌ی ساخت API Key، می‌توانید از راهنمای ایجاد کلید API استفاده کنید.

پس از ایجاد API Key و برای تست API ویدیو ابر آروان، می‌توانید از ابزارهای Postman یا Insomnia استفاده کنید. به این منظور و بعد از دریافت یکی از این دو ابزار، ابتدا باید فایل postman-collection را در یکی از این دو برنامه‌ی نصب شده Import و سپس API Key دریافتی از پنل کاربری ابر آروان را در قسمت Edit Collection، بخش Variables وارد کنید.

برای در دسترس قرار گرفتن سرویس میزبانی ویدیو، نخست باید Subdomain انتخابی با استفاده از درخواست Post ایجاد شود. برای این‌کار از دستور زیر استفاده کنید.

POST /domain


Parameters
Subdomain required

نکته‌ی مهم آن است که این درخواست، فقط یک بار قابل اجرا است و امکان تغییر دامنه‌ی انتخابی وجود ندارد. 

مشاهده‌ دامنه

برای مشاهده‌ی دامنه‌ی اختصاص یافته، کافی است از متد زیر استفاده کنید.

GET /domain

 

مدیریت کانال‌ها

برای آپلود فایل‌های صوتی و تصویری در سرورهای میزبانی ویدیوی ابر آروان، نخست نیاز است که دست کم یک کانال ایجاد شود. کلیه‌ی فایل‌هایی که در پلتفرم ویدیوی ابر آروان مورد استفاده قرار می‌گیرند، مانند فایل‌های ویدیو، فایل‌های صوتی، واترمارک و پروفایل، درون یک کانال‌ قرار می‌گیرند.

ساخت کانال

با استفاده از دستور زیر می‌توانید از طریق API ابر آروان یک کانال ایجاد کنید.

POST /channels

Parameters

Title (string) required

Description (string) required

Secure_link_enabled (boolean)

Secure_link_enabled (string) required if “secure_link_enabled” is true

مشاهده‌ تمام کانال‌ها

از طریق API سرویس میزبانی ویدیو ابر آروان، می‌توانید لیست کانال‌های موجود روی حساب کاربری خود را مشاهده کنید. به این منظور، می‌توانید از متد زیر استفاده کنید.

GET /channels

آپدیت کانال

برای آپدیت یک کانال مانند ساخت آن، باید قسمت  Body فرستاده شود و هم‌چنین باید در URL ،Channel ID نیز عنوان شود.

PATCH /channels/{channel_id}

مشاهده‌ یک کانال خاص

برای مشاهده‌ی اطلاعات مربوط به یک کانال خاص، می‌توان از این Route استفاده کرد.

GET /channels/{channel_id}

حذف کانال

متد زیر به شما امکان حذف کامل یک کانال را می‌دهد. 

DELETE /channels/{channel_id}

باید توجه داشت که بعد از حذف یک کانال، تمامی فایل‌های قرار گرفته روی آن، شامل تمام فایل‌های صوتی، تصویری، واترمارک‌ها و پروفایل‌های ساخته شده حذف می‌شوند.

 

آپلود فایل

اصلی‌ترین مفهوم که پیش از آغاز فایل باید از آن مطلع باشید، پروتکل TUS است. این پروتکل متن‌باز به شما امکان آپلود به‌شکل Resumable را می‌دهد. برای اطلاع دقیق‌تر درباره‌ی این پروتکل و آشنایی با شیوه‌ی کار با آن، راهنمای بارگذاری Resumable فایل‌ها با پروتکل TUS را مطالعه کنید.

پیش از شروع ارسال فایل به سرور، نخست باید بر اساس حجم فایل که از قسمت مشاهده‌ی اطلاعات فایل در دسترس است، یک فضای خالی ایجاد شود. فرض کنید یک فایل mp4 با نام video.mp4 با حجم 6.8 MB (یا 6777592 بایت) وجود دارد، ابتدا از قسمت Properties حجم فایل کپی می‌شود.

POST /channels/{channel_id}/files

Headers

tus-resumable: 1.0.0

upload_length: 6777592

upload-metadata: filename dmlkZW8ubXA0,filetype dmlkZW8vbXA0

سپس ID فضای ایجاد شده از قسمت Response Header کپی و با استفاده از PATH Request، فایل به سمت سرور ارسال می‌شود (ID فایل و کانال در URL قرار می‌گیرند).

POST /channels/{channel_id}/videos

Parameters

Title (string) required

Description (string)

Video_url (should be a valid URL. Otherwise, this will be corrupted)

File_id (should be string and it will be required whenever video_url is not available) required

Convert_mode (could be auto or manual or profile)

Profile_id (required if convert mode has set to profile)

Parallel_convert (boolean) required

Thumbnail_time (numeric) required

Convert_info (must be an array and this will be required if convert mode has set to manual)

[

    {

        “audio_bitrate”: 0,

        “video_bitrate”: 0,

        “resolution”: “string”,

    }

]

Watermark_id


Watermark_area (should be one of: center, fix_top_left, fix_top_right, fix_top_center, fix_bottom_left, fix_bottom_right, fix_bottom_center, animate_left_to_right, animate_top_to_bottom)

اگر فایل صوتی یا تصویری با URL در دسترس است، بدون در نظر گرفتن مراحل قبل، می‌توان URL فایل را به‌شکل مستقیم در video_url / audio_url وارد کرد. هم‌چنین، اگر مقادیر Bitrate و Resolution ثابت است، بهتر است از پروفایل استفاده شود تا هنگام تبدیل فایل، تنها به Profile_id  نیاز باشد.

برای قرار دادن یک تصویر روی ویدیو، نخست باید Watermark ایجاد و ID آن هنگام ارسال فایل وارد شود. برای تبدیل هم‌زمان فایل‌ها، باید مقدار parallel_convert را true ارسال کرد. در حالت معمول تمامی فایل‌ها Queue می‌شوند، در صف تبدیل قرار می‌گیرند و تک‌تک تبدیل می‌شوند. با انتخاب parallel_convert تا تعداد ۳ فایل را می‌توان به‌شکل همزمان تبدیل کرد و باید توجه داشت که بابت تبدیل همزمان هر فایل هزینه‌ای برای کاربر لحاظ خواهد شد.

وضعیت تبدیل

بعد از ارسال فایل برای تبدیل، برای در دسترس قرار گرفتن فایل باید گام‌هایی پیموده شوند. نخست، برای مشخص شدن وضعیت فایل باید از GET Request استفاده کرد. مقدار Status در Response نمایان‌گر وضعیت فعلی است.

GET/videos/{video_id}

تمامی ویدیوهای یک کانال را می‌توان با Route  زیر مشاهده کرد.

GET/channels/{channel_id}/videos

هم‌چنین، عنوان و توضیحات را می‌توان با Route زیر آپدیت کرد.

PATCH/videos/{video_id}

Parameters

Title (string) required

Description (string)

زیرنویس‌ها

برای یک ویدیو می‌توان چندین زیرنویس آپلود کرد. اضافه کردن زیرنویس باید با درخواست POST انجام شود. در حال حاضر تنها فرمت‌های SRT و VTT برای فایل زیرنویس معتبر هستند. 

POST /videos/{video_id}/subtitles

Parameters

subtitle (file) required

lang (string) required

مشاهده‌ تمام زیرنویس‌های یک ویدیو

GET/videos/{video_id}/subtitles

مشاهده‌ زیرنویس یک ویدیوی خاص

GET/subtitles/{subtitles_id}

حذف زیرنویس

DELETE/subtitles/{subtitle_id}

 

اضافه کردن واترمارک

تصاویر مختلفی می‌توانند در هر کانال به‌شکل جداگانه ذخیره شوند که در زمان تبدیل فایل ویدیویی، به‌عنوان واترمارک روی آن‌ها قرار بگیرند. برای انتخاب واترمارک، کافی است ID  تصویر موردنظر را انتخاب کرد.

POST /channels/{channel_id}/watermarks

Parameters

title (string) required

description (string)

watermark (file) required

به‌روزرسانی واترمارک

به کمک ID هر واترمارک، می‌توان آن را به‌راحتی به‌روزرسانی کرد.

POST / watermarks /{ watermark _id}

Parameters

title (string) required

description (string)

مشاهده‌ همه‌ واترمارک‌های یک کانال

GET/channels/{channel_id}/watermarks

مشاهده‌ یک واترمارک

GET/watermarks/{watermark_id}

حذف زیرنویس

DELETE/watermarks/{watermark_id}

 

مدیریت پروفایل‌ها

برای آن‌که در هربار تبدیل ویدیو یا فایل صوتی نیاز به وارد کردن تنظیمات تبدیل فایل به‌شکل دستی نباشد، می‌توان یک پروفایل ساخت تا با انتخاب آن، تبدیل فایل با توجه به تنظیمات پروفایل انجام شود. هر کانال می‌تواند چندین پروفایل داشته باشد.

POST /channels/{channel_id}/profiles

Parameters

Title (string) required

Description (string) required

 convert_mode ("auto", “manual”) required

thumbnail_time (number)

watermark_id (string)

Watermark_area (should be one of: center, fix_top_left, fix_top_right, fix_top_center, fix_bottom_left, fix_bottom_right, fix_bottom_center, animate_left_to_right, animate_top_to_bottom)

Convert_info (must be an array and this will be required if convert mode has set to manual)

[

    {

        “audio_bitrate”: 0,

        “video_bitrate”: 0,

        “resolution”: “string”,

    }

]

آپدیت پروفایل

PATCH /profiles/{profile_id}

Parameters

Title (string) required

Description (string) required

 convert_mode ("auto", “manual”) required

thumbnail_time (number)

watermark_id (string)

Watermark_area (should be one of: center, fix_top_left, fix_top_right, fix_top_center, fix_bottom_left, fix_bottom_right, fix_bottom_center, animate_left_to_right, animate_top_to_bottom)

Convert_info (must be an array and this will be required if convert mode has set to manual)

[

    {

        “audio_bitrate”: 0,

        “video_bitrate”: 0,

        “resolution”: “string”,

    }

]

مشاهده‌ تمام پروفایل‌های یک کانال

GET/channels/{channel_id}/profiles

مشاهده‌ یک پروفایل

GET/profiles/{profile_id}

حذف پروفایل

DELETE/profiles/{profile_id}