{ "openapi": "3.0.3", "info": { "title": "VideoClick Developer API", "version": "2.3.0-rc1", "description": "اتصال v2، آپلود و مدیریت ویدیو و رویداد زنده. پایان واقعی پخش نیازمند سرویس کنترل ingest پیکربندی‌شده و آزموده‌شده است." }, "servers": [ { "url": "https://videoclick.ir" } ], "security": [ { "ClientCredentials": [] } ], "components": { "securitySchemes": { "ClientCredentials": { "type": "oauth2", "description": "client_id برابر ۱۶ نویسهٔ آغاز کلید vck_ و client_secret برابر کلید کامل است. این اتصال برای سرور برنامه است.", "flows": { "clientCredentials": { "tokenUrl": "https://videoclick.ir/api/v2/oauth/token", "scopes": { "groups.read": "خواندن گروه‌های متعلق به حساب", "video.read": "خواندن وضعیت نشست و پردازش", "video.upload": "ثبت و انتقال ویدیو", "live.write": "ساخت رویداد پخش زنده با اشتراک فعال", "subtitle.write": "استعلام اعتبار و ساخت زیرنویس فارسی برای ویدیوی متعلق به حساب", "groups.write": "ساخت، ویرایش و حذف گروه متعلق به حساب", "video.write": "ویرایش و حذف ویدیوی متعلق به حساب", "video.import": "افزودن ویدیو از دامنهٔ مجاز سرور", "live.read": "فهرست و جزئیات رویدادهای زنده", "subtitle.read": "فهرست زبان‌ها و زیرنویس‌های متعلق به حساب" } } } } }, "parameters": { "UploadId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "VideoId": { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } }, "GroupId": { "name": "groupId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, "NumericVideoId": { "name": "videoId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, "LiveId": { "name": "liveId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, "SubtitleId": { "name": "subtitleId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PageSize": { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "UploadRequest": { "type": "object", "required": [ "groupId", "title", "fileName", "fileSize", "durationSeconds" ], "properties": { "groupId": { "type": "integer", "format": "int64", "minimum": 1 }, "title": { "type": "string", "maxLength": 180 }, "fileName": { "type": "string", "maxLength": 255, "description": "نام فایل با پسوند mp4 یا webm؛ بدون مسیر" }, "fileSize": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 4294967296 }, "durationSeconds": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 604800 }, "sha256": { "type": "string", "pattern": "^[A-Fa-f0-9]{64}$" }, "idempotencyKey": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]{1,100}$" } } }, "Upload": { "type": "object", "properties": { "uploadId": { "type": "string" }, "State": { "type": "string", "enum": [ "uploading", "transferring", "completed", "failed", "uncertain" ] }, "FileSize": { "type": "integer", "format": "int64" }, "NextOffset": { "type": "integer", "format": "int64" }, "chunkSize": { "type": "integer", "example": 1048576 }, "VideoId": { "type": "string", "nullable": true }, "ErrorCode": { "type": "string", "nullable": true } } }, "GroupInput": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 200 }, "parentId": { "type": "integer", "format": "int64", "nullable": true, "description": "فقط هنگام ساخت؛ ویرایش والد پشتیبانی نمی‌شود" } } }, "VideoInput": { "type": "object", "required": [ "title" ], "description": "جایگزینی کامل تنظیمات؛ بولی‌های حذف‌شده false و محدودیت‌های حذف‌شده * می‌شوند.", "properties": { "title": { "type": "string", "maxLength": 300 }, "description": { "type": "string", "maxLength": 4000 }, "downloadable": { "type": "boolean" }, "directPlayEnable": { "type": "boolean" }, "googleAnalytics": { "type": "string", "maxLength": 300 }, "theme": { "type": "string" }, "allowDomains": { "type": "string", "maxLength": 1000 }, "allowIPs": { "type": "string", "maxLength": 1000 } } }, "ImportInput": { "type": "object", "required": [ "groupId", "title", "videoUrl" ], "properties": { "groupId": { "type": "integer", "format": "int64" }, "title": { "type": "string", "maxLength": 180 }, "videoUrl": { "type": "string", "format": "uri", "description": "HTTPS، دامنهٔ مجاز و فایل MP4/WebM" } } }, "LiveUpdate": { "type": "object", "required": [ "title" ], "description": "جایگزینی کامل تنظیمات نمایش، بدون تغییر موتور ingest و وضعیت پخش", "properties": { "title": { "type": "string", "maxLength": 300 }, "description": { "type": "string", "maxLength": 4000 }, "directPlayEnable": { "type": "boolean" }, "chatEnable": { "type": "boolean" }, "chatUserCount": { "type": "boolean" }, "liveUserCount": { "type": "boolean" }, "chatOnLive": { "type": "boolean" }, "allowDomains": { "type": "string" }, "allowIPs": { "type": "string" }, "endMessage": { "type": "string", "maxLength": 500 } } }, "SubtitleUpdate": { "type": "object", "required": [ "title", "lang" ], "properties": { "title": { "type": "string", "maxLength": 200 }, "lang": { "type": "string", "maxLength": 12 }, "isDefault": { "type": "boolean" } } } }, "responses": { "Error": { "description": "خطا؛ از error.code برای تصمیم برنامه استفاده کنید", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "توکن کوتاه‌مدت غایب، منقضی یا لغوشده", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "مجوز پلن یا دامنهٔ دسترسی کافی نیست، یا HTTPS برقرار نیست", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/api/v2/oauth/token": { "post": { "summary": "دریافت توکن کوتاه‌مدت", "operationId": "issueToken", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string", "description": "۱۶ نویسهٔ ابتدای کلید کامل" }, "client_secret": { "type": "string", "format": "password", "description": "کلید vck_ کامل" }, "scope": { "type": "string", "example": "groups.read video.read video.upload" } } } } } }, "responses": { "200": { "description": "توکن معتبر برای ۹۰۰ ثانیه", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "example": 900 }, "scope": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/capabilities": { "get": { "summary": "آزمون کلید و دریافت محدودیت‌های حساب", "operationId": "getCapabilities", "responses": { "200": { "description": "دسترسی فعال", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "apiVersion": { "type": "string" }, "chunkSize": { "type": "integer" }, "maxFileBytes": { "type": "integer", "format": "int64" }, "maxOpenSessions": { "type": "integer" }, "batchEnabled": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "ClientCredentials": [] } ] } }, "/api/v2/groups": { "get": { "summary": "گروه‌های ویدیوی متعلق به صاحب کلید", "operationId": "getGroups", "responses": { "200": { "description": "فهرست گروه‌ها", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "integer", "format": "int64" }, "title": { "type": "string" }, "parentGroupId": { "type": "integer", "format": "int64", "nullable": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ClientCredentials": [ "groups.read" ] } ] }, "post": { "tags": [ "groups" ], "summary": "ساخت گروه ریشه یا زیرگروه", "operationId": "post_api_v2_groups", "security": [ { "ClientCredentials": [ "groups.write" ] } ], "responses": { "201": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInput" } } } } } }, "/api/v2/upload-sessions": { "post": { "summary": "ایجاد یک نشست آپلود", "operationId": "createUpload", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequest" } } } }, "responses": { "201": { "description": "نشست ایجاد شد", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "upload": { "$ref": "#/components/schemas/Upload" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Error" } }, "security": [ { "ClientCredentials": [ "video.upload" ] } ] }, "get": { "tags": [ "uploads" ], "summary": "۱۲ نشست آپلود اخیر حساب", "operationId": "listUploadSessions", "security": [ { "ClientCredentials": [ "video.read" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/upload-sessions/batch": { "post": { "summary": "ایجاد نشست‌های مستقل برای حداکثر هشت فایل", "description": "HTTP 200 به معنی موفقیت همهٔ اعضای results نیست؛ success هر عضو را بررسی کنید.", "operationId": "createBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "videos" ], "properties": { "videos": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "$ref": "#/components/schemas/UploadRequest" } } } } } } }, "responses": { "200": { "description": "نتایج مستقل", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "properties": { "success": { "type": "boolean" }, "upload": { "$ref": "#/components/schemas/Upload" }, "error": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ClientCredentials": [ "video.upload" ] } ] } }, "/api/v2/upload-sessions/{id}": { "get": { "summary": "وضعیت نشست و آفست ادامه", "operationId": "getUpload", "parameters": [ { "$ref": "#/components/parameters/UploadId" } ], "responses": { "200": { "description": "وضعیت نشست", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "upload": { "$ref": "#/components/schemas/Upload" } } } } } }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "ClientCredentials": [ "video.read" ] } ] }, "delete": { "tags": [ "uploads" ], "summary": "لغو نشست در حال دریافت قطعه", "operationId": "cancelUploadSession", "security": [ { "ClientCredentials": [ "video.upload" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/UploadId" } ] } }, "/api/v2/upload-sessions/{id}/chunks": { "put": { "summary": "ارسال یک قطعهٔ خام", "operationId": "putChunk", "parameters": [ { "$ref": "#/components/parameters/UploadId" }, { "name": "offset", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "description": "حداکثر 1048576 بایت" } } }, "responses": { "200": { "description": "قطعه ثبت شد", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "uploadId": { "type": "string" }, "nextOffset": { "type": "integer", "format": "int64" } } } } } }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "ClientCredentials": [ "video.upload" ] } ] }, "post": { "summary": "ارسال قطعهٔ خام با POST (معادل PUT)", "operationId": "postUploadChunk", "parameters": [ { "$ref": "#/components/parameters/UploadId" }, { "name": "offset", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "description": "حداکثر 1048576 بایت" } } }, "responses": { "200": { "description": "قطعه ثبت شد", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "uploadId": { "type": "string" }, "nextOffset": { "type": "integer", "format": "int64" } } } } } }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [ { "ClientCredentials": [ "video.upload" ] } ] } }, "/api/v2/upload-sessions/{id}/complete": { "post": { "summary": "تکمیل انتقال فایل", "description": "در خطای downstream_uncertain به‌صورت خودکار تکرار نکنید.", "operationId": "completeUpload", "parameters": [ { "$ref": "#/components/parameters/UploadId" } ], "responses": { "200": { "description": "تحویل به پردازش", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "uploadId": { "type": "string" }, "videoId": { "type": "string" }, "processingState": { "type": "string", "example": "queued" } } } } } }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error", "description": "نتیجهٔ موقتاً نامشخص؛ همان complete را با همان uploadId تکرار کنید" } }, "security": [ { "ClientCredentials": [ "video.upload" ] } ] } }, "/api/v2/videos/{videoId}": { "get": { "summary": "وضعیت پردازش ویدیو", "operationId": "getVideoProcessing", "parameters": [ { "$ref": "#/components/parameters/VideoId" } ], "responses": { "200": { "description": "وضعیت ویدیو", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "videoId": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "processing", "ready", "failed", "downloading", "unknown" ] }, "status": { "type": "integer" }, "numericVideoId": { "type": "integer", "format": "int64", "description": "شناسهٔ عددی ویدیو برای API زیرنویس" } } } } } }, "404": { "$ref": "#/components/responses/Error" } }, "security": [ { "ClientCredentials": [ "video.read" ] } ] }, "put": { "tags": [ "videos" ], "summary": "ویرایش ویدیو", "operationId": "put_api_v2_videos_videoId", "security": [ { "ClientCredentials": [ "video.write" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "502": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/NumericVideoId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoInput" } } } } }, "delete": { "tags": [ "videos" ], "summary": "حذف ویدیو", "operationId": "delete_api_v2_videos_videoId", "security": [ { "ClientCredentials": [ "video.write" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/NumericVideoId" } ] }, "patch": { "tags": [ "videos" ], "summary": "ویرایش جزئی؛ فیلدهای حذف‌شده حفظ می‌شوند", "operationId": "patchVideo", "security": [ { "ClientCredentials": [ "video.write" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/VideoId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "downloadable": { "type": "boolean" }, "directPlayEnable": { "type": "boolean" }, "googleAnalytics": { "type": "string" }, "theme": { "type": "string" }, "allowDomains": { "type": "string" }, "allowIPs": { "type": "string" } } } } } } } }, "/api/v2/live-events": { "post": { "summary": "ساخت رویداد پخش زنده با تنظیمات اختیاری", "operationId": "createLiveEvent", "security": [ { "ClientCredentials": [ "live.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveUpdate" } } } }, "responses": { "201": { "description": "رویداد ساخته شد؛ streamKey محرمانه است", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "integer", "format": "int64" }, "uid": { "type": "string" }, "confirmed": { "type": "boolean" }, "ingestUrl": { "type": "string" }, "streamKey": { "type": "string" }, "panelUrl": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/Error" } }, "description": "تنها title اجباری است؛ تنظیمات ارسال‌نشده از پیش‌فرض‌های پنل گرفته می‌شوند.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "برای جلوگیری از ساخت رویداد تکراری در تلاش دوباره، برای یک درخواست ثابت بماند. اتصال جدید باید آن را ارسال کند.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,100}$" } } ] }, "get": { "tags": [ "live-events" ], "summary": "فهرست رویدادهای زنده", "operationId": "get_api_v2_live_events", "security": [ { "ClientCredentials": [ "live.read" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ] } }, "/api/v2/videos/{videoId}/ai-subtitle/quote": { "get": { "summary": "برآورد اعتبار زیرنویس", "operationId": "getAiSubtitleQuote", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "description": "numericVideoId برگشتی از وضعیت ویدیو" } ], "security": [ { "ClientCredentials": [ "subtitle.write" ] } ], "responses": { "200": { "description": "اعتبار و هزینه", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "ready": { "type": "boolean" }, "enabled": { "type": "boolean" }, "available": { "type": "boolean" }, "cost": { "type": "integer", "format": "int64" }, "balance": { "type": "integer", "format": "int64" }, "enough": { "type": "boolean" }, "status": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/videos/{videoId}/ai-subtitle": { "post": { "summary": "ثبت کار زیرنویس فارسی", "operationId": "createAiSubtitle", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "description": "numericVideoId برگشتی از وضعیت ویدیو" } ], "security": [ { "ClientCredentials": [ "subtitle.write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expectedCost" ], "properties": { "expectedCost": { "type": "integer", "format": "int64", "minimum": 1 } } } } } }, "responses": { "202": { "description": "در صف پردازش", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "videoId": { "type": "integer", "format": "int64" }, "status": { "type": "string", "enum": [ "queued" ] }, "statusUrl": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/videos/{videoId}/ai-subtitle/status": { "get": { "summary": "پیگیری ساخت زیرنویس", "operationId": "getAiSubtitleStatus", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 }, "description": "numericVideoId برگشتی از وضعیت ویدیو" } ], "security": [ { "ClientCredentials": [ "subtitle.write" ] } ], "responses": { "200": { "description": "وضعیت ساخت", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "enum": [ "none", "queued", "processing", "complete", "failed" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "stage": { "type": "string" }, "failureMessage": { "type": "string" }, "reference": { "type": "string" }, "active": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/videos/{videoId}/subtitles": { "post": { "summary": "بارگذاری دستی فایل زیرنویس SRT/VTT", "operationId": "uploadSubtitle", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } } ], "security": [ { "ClientCredentials": [ "subtitle.write" ] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "lang": { "type": "string", "default": "fa" }, "isDefault": { "type": "boolean", "default": false } } } } } }, "responses": { "201": { "description": "فایل در سرویس رسانه ثبت شد" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "get": { "tags": [ "videos" ], "summary": "فهرست زیرنویس‌های یک ویدیو", "operationId": "get_api_v2_videos_videoId_subtitles", "security": [ { "ClientCredentials": [ "subtitle.read" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/NumericVideoId" } ] } }, "/api/v2/groups/{groupId}": { "get": { "tags": [ "groups" ], "summary": "جزئیات گروه", "operationId": "get_api_v2_groups_groupId", "security": [ { "ClientCredentials": [ "groups.read" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/GroupId" } ] }, "put": { "tags": [ "groups" ], "summary": "تغییر عنوان گروه", "operationId": "put_api_v2_groups_groupId", "security": [ { "ClientCredentials": [ "groups.write" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/GroupId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInput" } } } } }, "delete": { "tags": [ "groups" ], "summary": "حذف گروه خالی", "operationId": "delete_api_v2_groups_groupId", "security": [ { "ClientCredentials": [ "groups.write" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/GroupId" } ] } }, "/api/v2/groups/{groupId}/videos": { "get": { "tags": [ "groups" ], "summary": "فهرست ویدیوهای گروه", "operationId": "get_api_v2_groups_groupId_videos", "security": [ { "ClientCredentials": [ "video.read" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/GroupId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ] } }, "/api/v2/videos/{videoId}/details": { "get": { "tags": [ "videos" ], "summary": "جزئیات ویدیوی موجود", "operationId": "get_api_v2_videos_videoId_details", "security": [ { "ClientCredentials": [ "video.read" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/NumericVideoId" } ] } }, "/api/v2/videos/imports": { "post": { "tags": [ "videos" ], "summary": "افزودن از آدرس HTTPS مجاز", "operationId": "post_api_v2_videos_imports", "security": [ { "ClientCredentials": [ "video.import" ] } ], "responses": { "202": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "description": "نیازمند تنظیم فهرست دامنه‌های مورد اعتماد توسط مدیر سرور؛ دانلود واقعی در سرویس رسانهٔ موجود انجام می‌شود.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportInput" } } } } } }, "/api/v2/live-events/{liveId}": { "get": { "tags": [ "live-events" ], "summary": "جزئیات رویداد زنده", "operationId": "get_api_v2_live_events_liveId", "security": [ { "ClientCredentials": [ "live.read" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/LiveId" } ] }, "put": { "tags": [ "live-events" ], "summary": "ویرایش تنظیمات رویداد", "operationId": "put_api_v2_live_events_liveId", "security": [ { "ClientCredentials": [ "live.write" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/LiveId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveUpdate" } } } } }, "delete": { "tags": [ "live-events" ], "summary": "حذف رویداد بدون سابقه", "operationId": "delete_api_v2_live_events_liveId", "security": [ { "ClientCredentials": [ "live.write" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/LiveId" } ] }, "patch": { "tags": [ "live-events" ], "summary": "ویرایش جزئی تنظیمات نمایشی بدون تغییر هویت و وضعیت ingest", "operationId": "patchLive", "security": [ { "ClientCredentials": [ "live.write" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/LiveId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "directPlayEnable": { "type": "boolean" }, "chatEnable": { "type": "boolean" }, "chatUserCount": { "type": "boolean" }, "liveUserCount": { "type": "boolean" }, "chatOnLive": { "type": "boolean" }, "allowDomains": { "type": "string" }, "allowIPs": { "type": "string" }, "endMessage": { "type": "string" } } } } } } } }, "/api/v2/subtitle-languages": { "get": { "tags": [ "subtitle-languages" ], "summary": "فهرست زبان‌های زیرنویس", "operationId": "get_api_v2_subtitle_languages", "security": [ { "ClientCredentials": [ "subtitle.read" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v2/subtitles/{subtitleId}": { "put": { "tags": [ "subtitles" ], "summary": "ویرایش اطلاعات زیرنویس", "operationId": "put_api_v2_subtitles_subtitleId", "security": [ { "ClientCredentials": [ "subtitle.write" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/SubtitleId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubtitleUpdate" } } } } }, "delete": { "tags": [ "subtitles" ], "summary": "حذف زیرنویس", "operationId": "delete_api_v2_subtitles_subtitleId", "security": [ { "ClientCredentials": [ "subtitle.write" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "خطا", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "$ref": "#/components/parameters/SubtitleId" } ] } }, "/api/v2/live-events/{liveId}/credentials": { "get": { "tags": [ "live-events" ], "summary": "بازیابی اطلاعات اتصال نرم‌افزار پخش", "operationId": "getLiveCredentials", "security": [ { "ClientCredentials": [ "live.write" ] } ], "parameters": [ { "$ref": "#/components/parameters/LiveId" } ], "responses": { "200": { "description": "اطلاعات محرمانهٔ اتصال؛ فقط در سرور نگهداری شود" }, "404": { "description": "رویداد متعلق به حساب نیست" }, "409": { "description": "کلید رویداد در پنل باید بازیابی شود" } } } }, "/api/v2/videos": { "get": { "tags": [ "videos" ], "summary": "فهرست سراسری و جستجوی ویدیوهای حساب", "operationId": "listVideos", "security": [ { "ClientCredentials": [ "video.read" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "groupId", "in": "query", "required": false, "schema": { "type": "integer" } } ] } }, "/api/v2/videos/{videoId}/playback": { "get": { "tags": [ "videos" ], "summary": "اطلاعات Embed و لینک پخش ویدیوی آماده", "operationId": "getVideoPlayback", "security": [ { "ClientCredentials": [ "video.read" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/VideoId" } ] } }, "/api/v2/live-events/{liveId}/status": { "get": { "tags": [ "live-events" ], "summary": "وضعیت واقعی از callback RTMP و زمان آخرین سیگنال", "operationId": "getLiveStatus", "security": [ { "ClientCredentials": [ "live.read" ] } ], "responses": { "200": { "description": "onAir، signalState، lastSignalAt، publishBlocked؛ stale پیش‌فرض ۳۵ ثانیه", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/LiveId" } ] } }, "/api/v2/live-events/{liveId}/playback": { "get": { "tags": [ "live-events" ], "summary": "اطلاعات Embed و پخش رویداد", "operationId": "getLivePlayback", "security": [ { "ClientCredentials": [ "live.read" ] } ], "responses": { "200": { "description": "موفق", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/LiveId" } ] } }, "/api/v2/live-events/{liveId}/finish": { "post": { "tags": [ "live-events" ], "summary": "انسداد انتشار، قطع ناشر در Nginx محلی و بستن جلسه", "operationId": "finishLive", "security": [ { "ClientCredentials": [ "live.write" ] } ], "responses": { "200": { "description": "ناشر قطع و جلسه بسته شد", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "خطا با error.code و error.message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "انسداد ثبت شد، اما قطع ناشر تأیید نشد؛ finish را تکرار کنید", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/LiveId" } ] } } } }