ویدیوکلیک مرکز توسعه‌دهندگان • راهنمای اتصال
API نسخهٔ ۲ · subtitle.write

زیرنویس فارسی با هوش مصنوعی

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

۱. بررسی ویدیو و اعتبار

توکن را با محدودهٔ subtitle.write بگیرید و فقط بعد از آماده‌شدن ویدیو درخواست دهید. شناسهٔ این مسیر، شناسهٔ عددی ویدیوی پنل است؛ پس از تکمیل آپلود، GET /api/v2/videos/{videoId} را با UID برگشتی بخوانید و numericVideoId پاسخ را اینجا بگذارید.

GET https://videoclick.ir/api/v2/videos/72882/ai-subtitle/quote
Authorization: Bearer vct_YOUR_ACCESS_TOKEN

پاسخ شامل ready، enabled، available، balance، cost و enough است. cost را در مرحلهٔ بعد عیناً بفرستید.

۲. ثبت ساخت زیرنویس

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

{"expectedCost":300}

پاسخ 202 Accepted با status: queued به‌معنی ثبت در صف است. هزینه فقط یک بار در رزرو کار کسر می‌شود؛ برای همان ویدیو درخواست هم‌زمان تکراری پذیرفته نمی‌شود. مقدار ۳۰۰ فقط مثال است؛ همیشه از quote.cost استفاده کنید.

۳. پیگیری تا نتیجه

GET https://videoclick.ir/api/v2/videos/72882/ai-subtitle/status
Authorization: Bearer vct_YOUR_ACCESS_TOKEN

مقادیر status شامل none، queued، processing، complete و failed است. مقدار progress درصد مرحله‌های انجام‌شده است. در complete، فیلد active را هم کنترل کنید. در خطا، reference را به پشتیبانی بدهید.

نکات امنیتی و پلن

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

بارگذاری فایل زیرنویس موجود

اگر از قبل فایل SRT یا VTT دارید، همان API قدیمی فایل را از مسیر زیر با subtitle.write می‌پذیرد؛ این عملیات اعتبار هوش مصنوعی مصرف نمی‌کند. ویدیو باید آماده و متعلق به حساب شما باشد.

curl -X POST 'https://videoclick.ir/api/v2/videos/72882/subtitles' \
  -H 'Authorization: Bearer vct_YOUR_ACCESS_TOKEN' \
  -F 'file=@caption-fa.vtt' -F 'lang=fa' -F 'isDefault=true'

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

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

با subtitle.read زبان‌های ثبت‌شده را بگیرید. برای هر ویدیوی متعلق به حساب، شناسه و تنظیم پیش‌فرض زیرنویس‌ها قابل دریافت است. شناسهٔ عددی ویدیو را استفاده کنید.

GET https://videoclick.ir/api/v2/subtitle-languages
Authorization: Bearer vct_YOUR_ACCESS_TOKEN

GET https://videoclick.ir/api/v2/videos/72882/subtitles
Authorization: Bearer vct_YOUR_ACCESS_TOKEN

ویرایش و حذف زیرنویس

با subtitle.write عنوان، زبان و پیش‌فرض بودن فایل را ویرایش کنید. محتوای فایل از این مسیر تغییر نمی‌کند؛ برای فایل تازه از بارگذاری دستی استفاده کنید. ویرایش و حذف از همان سرویس رسانهٔ فعلی انجام می‌شوند.

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

{"title":"فارسی","lang":"fa","isDefault":true}

DELETE https://videoclick.ir/api/v2/subtitles/1126
Authorization: Bearer vct_YOUR_ACCESS_TOKEN

اگر شناسهٔ زیرنویس متعلق به حساب دیگری باشد پاسخ 404 است. برای تغییر پیش‌فرض، ویرایش را روی شناسهٔ زیرنویس موجود انجام دهید.

مرکز توسعه‌دهندگان ویدیوکلیکمرجع اتصال و مدیریت رسانه · API نسخهٔ ۲