{ "x-generator": "NSwag v13.20.0.0 (NJsonSchema v10.9.0.0 (Newtonsoft.Json v13.0.0.0))", "openapi": "3.0.0", "info": { "title": "Stream API", "termsOfService": "https://bunny.net/tos", "contact": { "name": "bunny.net", "url": "https://docs.bunny.net", "email": "support@bunny.net" }, "version": "1.6.21" }, "servers": [ { "url": "https://video.bunnycdn.com" } ], "paths": { "/library/{libraryId}/collections/{collectionId}": { "get": { "tags": [ "Manage Collections" ], "summary": "Get Collection", "description": "Returns the details of a collection. Collections can group both videos and live streams, reflected separately in VideoCount and LiveStreamCount; PreviewImageUrls only reflects the videos in the collection.", "operationId": "Collection_GetCollection", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "collectionId", "in": "path", "required": true, "description": "The unique ID of the collection.", "schema": { "type": "string" }, "x-position": 2 }, { "name": "includeThumbnails", "in": "query", "description": "If set to true, populates PreviewImageUrls with thumbnails for videos in the collection.", "schema": { "type": "boolean", "default": false }, "x-position": 3 } ], "responses": { "200": { "description": "The details of the requested collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionModel" } } } }, "404": { "description": "The requested collection was not found" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] }, "post": { "tags": [ "Manage Collections" ], "summary": "Update Collection", "operationId": "Collection_UpdateCollection", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "collectionId", "in": "path", "required": true, "description": "The unique ID of the collection.", "schema": { "type": "string" }, "x-position": 2 } ], "requestBody": { "x-name": "model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionModel" } } }, "required": true, "x-position": 3 }, "responses": { "200": { "description": "The collection was successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "400": { "description": "The collection name was missing or longer than 255 characters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested collection was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] }, "delete": { "tags": [ "Manage Collections" ], "summary": "Delete Collection", "description": "Permanently deletes the collection together with every video and live stream it contains — nothing is moved out of the collection first, it is deleted along with it. Fails with 400 if the collection contains a currently running live stream; stop it before deleting the collection. This cannot be undone.", "operationId": "Collection_DeleteCollection", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "collectionId", "in": "path", "required": true, "description": "The unique ID of the collection.", "schema": { "type": "string" }, "x-position": 2 } ], "responses": { "200": { "description": "The collection was successfully deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "400": { "description": "The collection cannot currently be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested collection was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/collections": { "get": { "tags": [ "Manage Collections" ], "summary": "Get Collection List", "description": "Returns a paginated list of collections for the library. Collections can group both videos and live streams, reflected separately in VideoCount and LiveStreamCount; preview thumbnails only reflect the videos in each collection. When includeThumbnails is true, preview thumbnails are only populated for the first 60 collections of the returned page — later items in a larger page are returned without thumbnails.", "operationId": "Collection_List", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "page", "in": "query", "description": "The page number to return, 1-based; values below 1 are treated as 1.", "schema": { "type": "integer", "format": "int32", "default": 1 }, "x-position": 2 }, { "name": "itemsPerPage", "in": "query", "description": "The number of items to return per page, clamped to a range of 10-1000.", "schema": { "type": "integer", "format": "int32", "default": 100 }, "x-position": 3 }, { "name": "search", "in": "query", "description": "Filters collections by name, case-insensitive substring match.", "schema": { "type": "string", "default": "", "nullable": true }, "x-position": 4 }, { "name": "orderBy", "in": "query", "description": "The field to order results by. Possible values: date, title — any other value falls back to date.", "schema": { "type": "string", "default": "date", "nullable": true }, "x-position": 5 }, { "name": "includeThumbnails", "in": "query", "description": "If set to true, populates PreviewImageUrls for each collection (only for the first 60 collections of the page).", "schema": { "type": "boolean", "default": false }, "x-position": 6 } ], "responses": { "200": { "description": "The list of videos for the current parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginationListOfCollectionModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] }, "post": { "tags": [ "Manage Collections" ], "summary": "Create Collection", "operationId": "Collection_CreateCollection", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 } ], "requestBody": { "x-name": "model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionModel" } } }, "required": true, "x-position": 2 }, "responses": { "200": { "description": "The collection was successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionModel" } } } }, "400": { "description": "The collection name was missing or longer than 255 characters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/statistics/encoding": { "get": { "tags": [ "Encoding Statistics" ], "summary": "Get Encoding Statistics", "description": "Returns video encoding seconds for the library, split into premium and free tier. Each includes billable (normalized) and output seconds over time, plus totals by video codec, resolution, and JIT vs standard encoding. Data is available starting 2026-06-15.", "operationId": "EncodingStatistics_GetEncodingStatistics", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "dateFrom", "in": "query", "description": "Optional start of the time range (UTC). Defaults to 14 days ago. Data is available starting 2026-06-15.", "schema": { "type": "string", "format": "date-time", "nullable": true }, "x-position": 2 }, { "name": "dateTo", "in": "query", "description": "Optional end of the time range (UTC). If omitted, the current date is used.", "schema": { "type": "string", "format": "date-time", "nullable": true }, "x-position": 3 }, { "name": "hourly", "in": "query", "description": "Optional. If true, returns hourly data for ranges of up to 31 days within the last 89 days; otherwise daily (UTC). Default is daily.", "schema": { "type": "boolean", "default": false }, "x-position": 4 }, { "name": "videoCodecs", "in": "query", "style": "form", "explode": true, "description": "Optional video codecs to include: H264, VP9, HEVC, AV1. Repeat for multiple values.", "schema": { "type": "array", "nullable": true, "items": { "type": "string" } }, "x-position": 5 }, { "name": "resolutions", "in": "query", "style": "form", "explode": true, "description": "Optional highest output resolutions to include: 240, 360, 480, 540, 720, 1080, 1440, 2160. Repeat for multiple values.", "schema": { "type": "array", "nullable": true, "items": { "type": "integer", "format": "int32" } }, "x-position": 6 }, { "name": "jit", "in": "query", "description": "Optional. If true, only JIT encodes are included; if false, only standard encodes. Omit for both.", "schema": { "type": "boolean", "nullable": true }, "x-position": 7 } ], "responses": { "200": { "description": "Returns video encoding seconds for the requested video library, split by premium and free tier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoEncodingStatisticsModel" } } } }, "400": { "description": "The date range or filters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested video library was not found." }, "503": { "description": "Encoding statistics are not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}": { "get": { "tags": [ "Manage Videos" ], "summary": "Get Video", "operationId": "Video_GetVideo", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 } ], "responses": { "200": { "description": "The details of the requested video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoModel" } } } }, "404": { "description": "The requested video was not found" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] }, "post": { "tags": [ "Manage Videos" ], "summary": "Update Video", "operationId": "Video_UpdateVideo", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 } ], "requestBody": { "x-name": "model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVideoModel" } } }, "required": true, "x-position": 3 }, "responses": { "200": { "description": "The video was successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested video was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] }, "delete": { "tags": [ "Manage Videos" ], "summary": "Delete Video", "description": "Deletes the video. This cannot be undone. The video stops appearing in lookups right away, but playback may still be possible for some time afterward before access is fully revoked.", "operationId": "Video_DeleteVideo", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 } ], "responses": { "200": { "description": "The video was successfully deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested video was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] }, "put": { "tags": [ "Manage Videos" ], "summary": "Upload Video", "operationId": "Video_UploadVideo", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 }, { "name": "jitEnabled", "in": "query", "description": "Marks whether JIT encoding should be enabled for this video (works only when Premium Encoding is enabled), overrides library settings", "schema": { "type": "boolean" }, "x-position": 3 }, { "name": "enabledResolutions", "in": "query", "description": "Comma separated list of resolutions enabled for encoding, available options: 240p, 360p, 480p, 720p, 1080p, 1440p, 2160p", "schema": { "type": "string", "default": "", "nullable": true }, "x-position": 4 }, { "name": "enabledOutputCodecs", "in": "query", "description": "List of codecs that will be used to encode the file (overrides library settings). Available values: x264, vp9", "schema": { "type": "string", "default": "", "nullable": true }, "x-position": 6 }, { "name": "transcribeEnabled", "in": "query", "description": "Setting this to true will enable transcription on this video. Enabling this will incur transcription charges", "schema": { "type": "boolean", "nullable": true }, "x-position": 7 }, { "name": "transcribeLanguages", "in": "query", "description": "Comma separated list of languages that will be used as target languages, use ISO 639-1 language codes.", "schema": { "type": "string", "nullable": true }, "x-position": 8 }, { "name": "sourceLanguage", "in": "query", "description": "Language spoken in the video, use ISO 639-1 language codes.", "schema": { "type": "string", "nullable": true }, "x-position": 9 }, { "name": "generateTitle", "in": "query", "description": "Whether video title should be generated from transcription.", "schema": { "type": "boolean", "nullable": true }, "x-position": 10 }, { "name": "generateDescription", "in": "query", "description": "Whether video description should be generated from transcription.", "schema": { "type": "boolean", "nullable": true }, "x-position": 11 }, { "name": "generateChapters", "in": "query", "description": "Whether video chapters should be generated from transcription.", "schema": { "type": "boolean", "nullable": true }, "x-position": 12 }, { "name": "generateMoments", "in": "query", "description": "Whether video moments should be generated from transcription.", "schema": { "type": "boolean", "nullable": true }, "x-position": 13 } ], "requestBody": { "description": "Video file to upload", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "nullable": false } } }, "required": true }, "responses": { "200": { "description": "The video was successfully uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "400": { "description": "The requested video was already uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested video was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/heatmap": { "get": { "tags": [ "Manage Videos" ], "summary": "Get Video Heatmap", "description": "Returns the attention heatmap for a specific video, showing relative viewer interest across the timeline. May be unavailable if the feature is disabled or there isn't enough viewing data.", "operationId": "Video_GetVideoHeatmap", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 } ], "responses": { "200": { "description": "The heatmap of the requested video.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoHeatmapModel" } } } }, "404": { "description": "Video not found" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/play": { "get": { "tags": [ "Manage Videos" ], "summary": "Get Video play data", "description": "Returns playback URLs and metadata for the video. For libraries with token authentication enabled, token and expires must be a valid signed pair or the request is rejected. If the library also has CDN token authentication enabled, the returned CDN URLs are signed.", "operationId": "Video_GetVideoPlayData", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 }, { "name": "token", "in": "query", "description": "Signed access token, required when the library has token authentication enabled.", "schema": { "type": "string", "default": "", "nullable": true }, "x-position": 3 }, { "name": "expires", "in": "query", "description": "Unix timestamp (seconds) the token is valid until, required when the library has token authentication enabled.", "schema": { "type": "integer", "format": "int64", "default": 0 }, "x-position": 4 } ], "responses": { "200": { "description": "The play data of the requested video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoPlayDataModel" } } } }, "404": { "description": "The requested video was not found" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } } } }, "/library/{libraryId}/videos/{videoId}/play/heatmap": { "get": { "tags": [ "Manage Videos" ], "summary": "Get Video heatmap data", "description": "Returns raw heatmap data for the video, used to render the attention heatmap on the player timeline. Returns an empty string if the library has heatmaps disabled or no heatmap data exists yet.", "operationId": "Video_GetVideoHeatmapData", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 }, { "name": "token", "in": "query", "description": "Signed access token, required when the library has token authentication enabled.", "schema": { "type": "string", "default": "", "nullable": true }, "x-position": 3 }, { "name": "expires", "in": "query", "description": "Unix timestamp (seconds) the token is valid until, required when the library has token authentication enabled.", "schema": { "type": "integer", "format": "int64", "default": 0 }, "x-position": 4 } ], "responses": { "200": { "description": "The heatmap data of the requested video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoPlayDataModel" } } } }, "404": { "description": "The requested video was not found" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } } } }, "/library/{libraryId}/statistics": { "get": { "tags": [ "Manage Videos" ], "summary": "Get Video Statistics", "description": "Returns time-series views and watch time, plus country-level aggregates, at the library level or for a specific video. Control the time window with dateFrom/dateTo and the granularity with hourly. Statistics are available for the last 1 year. Basic safeguards prevent spam and bot inflation by de-duplicating sessions and ignoring obviously invalid events.", "operationId": "Video_GetVideoStatistics", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "dateFrom", "in": "query", "description": "Optional start of the time range (UTC). If omitted or invalid, the last 30 days are returned. Starts more than 1 year ago are moved to 1 year ago.", "schema": { "type": "string", "format": "date-time", "nullable": true }, "x-position": 2 }, { "name": "dateTo", "in": "query", "description": "Optional end of the time range (UTC). If omitted with a valid start, defaults to now; otherwise the last 30 days are returned.", "schema": { "type": "string", "format": "date-time", "nullable": true }, "x-position": 3 }, { "name": "hourly", "in": "query", "description": "Optional. If true, returns hourly data; otherwise daily (UTC). Default is daily.", "schema": { "type": "boolean", "default": false }, "x-position": 4 }, { "name": "videoGuid", "in": "query", "description": "Optional video GUID to filter results. When omitted, returns library-level aggregates.", "schema": { "type": "string", "nullable": true }, "x-position": 5 } ], "responses": { "200": { "description": "Statistics including time-series views and watch time, country breakdowns, and engagement score when available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoStatisticsModel" } } } }, "400": { "description": "The requested time range ends more than 1 year ago", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "Video not found (when filtering by videoGuid)" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/reencode": { "post": { "tags": [ "Manage Videos" ], "summary": "Reencode Video", "description": "Re-encodes the video from its stored original file. Requires the original file to still be present in storage. If the library has transcribing enabled, this also re-queues (and re-bills) transcription.", "operationId": "Video_ReencodeVideo", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 } ], "responses": { "200": { "description": "The details of the requested video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoModel" } } } }, "400": { "description": "Original file is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested video was not found" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/outputs/{outputCodecId}": { "put": { "tags": [ "Manage Videos" ], "summary": "Add output codec to video", "description": "Encodes and adds an additional output codec to an already-encoded video. Requires Premium Encoding to be enabled for the library and the codec to already be enabled for the library, and fails if the original source file is missing or the codec was already processed.", "operationId": "Video_ReencodeUsingCodec", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string", "format": "guid" }, "x-position": 2 }, { "name": "outputCodecId", "in": "path", "required": true, "description": "The output codec to encode and add, must already be enabled for the library.", "schema": { "$ref": "#/components/schemas/EncoderOutputCodec" }, "x-position": 3 } ], "responses": { "200": { "description": "The details of the requested video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoModel" } } } }, "400": { "description": "Invalid request or validation failed, check response", "content": { "application/json": { "schema": { "type": "string" } } } }, "404": { "description": "The requested video was not found" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/repackage": { "post": { "tags": [ "Manage Videos" ], "summary": "Repackage Video", "description": "Repackages the video from its existing .ts/.m4s segments without re-transcoding, primarily used to apply Enterprise DRM.", "operationId": "Video_Repackage", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 }, { "name": "keepOriginalFiles", "in": "query", "description": "Marks whether previous file versions should be kept in storage, allows for faster repackage later on. Default is true.", "schema": { "type": "boolean", "default": true }, "x-position": 3 } ], "responses": { "200": { "description": "The details of the requested video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoModel" } } } }, "400": { "description": "Enterprise DRM is disabled for the library, repackaging not available" }, "404": { "description": "The requested video was not found" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos": { "get": { "tags": [ "Manage Videos" ], "summary": "List Videos", "operationId": "Video_List", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "page", "in": "query", "description": "The page number to return, 1-based; values below 1 are treated as 1.", "schema": { "type": "integer", "format": "int32", "default": 1 }, "x-position": 2 }, { "name": "itemsPerPage", "in": "query", "description": "The number of items to return per page, clamped to a range of 10-1000.", "schema": { "type": "integer", "format": "int32", "default": 100 }, "x-position": 3 }, { "name": "search", "in": "query", "description": "Filters videos by title, case-insensitive substring match.", "schema": { "type": "string", "default": "", "nullable": true }, "x-position": 4 }, { "name": "collection", "in": "query", "description": "Filters videos by collection ID.", "schema": { "type": "string", "default": "", "nullable": true }, "x-position": 5 }, { "name": "orderBy", "in": "query", "description": "The field to order results by. Possible values: date, title — any other value falls back to date.", "schema": { "type": "string", "default": "date", "nullable": true }, "x-position": 6 } ], "responses": { "200": { "description": "The list of videos for the current parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginationListOfVideoModel" } } } }, "400": { "description": "Search is not available for this library", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" }, "503": { "description": "The search database is temporarily unavailable, retry the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] }, "post": { "tags": [ "Manage Videos" ], "summary": "Create Video", "operationId": "Video_CreateVideo", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 } ], "requestBody": { "x-name": "model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoModel" } } }, "required": true, "x-position": 2 }, "responses": { "200": { "description": "The video was successfully created and returned as the response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "400": { "description": "Request was invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/thumbnail": { "post": { "tags": [ "Manage Videos" ], "summary": "Set Thumbnail", "description": "Sets the video's thumbnail. If thumbnailUrl is omitted, the thumbnail is read from the request body as a raw image upload. If thumbnailUrl is one of thumbnail_1.jpg…thumbnail_5.jpg, an existing auto-generated thumbnail for the video is used instead. Any other value is fetched by the server as a URL, so it must point to a reachable, publicly accessible image.", "operationId": "Video_SetThumbnail", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 }, { "name": "thumbnailUrl", "in": "query", "description": "Optional. One of thumbnail_1.jpg…thumbnail_5.jpg to reuse an auto-generated thumbnail, or a URL for the server to fetch. Omit to upload a raw image in the request body instead.", "schema": { "type": "string", "nullable": true }, "x-position": 3 } ], "requestBody": { "description": "Optional thumbnail file to upload", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "nullable": true } } } }, "responses": { "200": { "description": "The thumbnail was successfully set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "400": { "description": "The request or URL was invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested video was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "422": { "description": "Unable to fetch thumbnail from origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/fetch": { "post": { "tags": [ "Manage Videos" ], "summary": "Fetch Video", "operationId": "Video_FetchNewVideo", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "collectionId", "in": "query", "description": "(Optional) The ID of the collection to put the created video in.", "schema": { "type": "string", "nullable": true }, "x-position": 3 }, { "name": "thumbnailTime", "in": "query", "description": "(Optional) Video time in ms to extract the main video thumbnail.", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 4 } ], "requestBody": { "x-name": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchVideoRequest" } } }, "required": true, "x-position": 2 }, "responses": { "200": { "description": "The video was successfully fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested video was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "400": { "description": "URL validation failed or request was invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "422": { "description": "Unable to fetch video from origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "429": { "description": "Too many fetch jobs queued. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/captions/{srclang}": { "post": { "tags": [ "Manage Videos" ], "summary": "Add Caption", "operationId": "Video_AddCaption", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 }, { "name": "srclang", "in": "path", "required": true, "description": "The srclang shortcode for the caption, e.g. \"en\".", "schema": { "type": "string" }, "x-position": 3 } ], "requestBody": { "x-name": "captionModel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptionModelAdd" } } }, "required": true, "x-position": 4 }, "responses": { "200": { "description": "The caption was successfully uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModelOfCaptionValidationModel" } } } }, "404": { "description": "The requested video was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "400": { "description": "Failed uploading the captions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModelOfCaptionValidationModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] }, "delete": { "tags": [ "Manage Videos" ], "summary": "Delete Caption", "operationId": "Video_DeleteCaption", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 }, { "name": "srclang", "in": "path", "required": true, "description": "The srclang shortcode of the caption to delete, e.g. \"en\".", "schema": { "type": "string" }, "x-position": 3 } ], "responses": { "200": { "description": "The caption was successfully deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested video was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "400": { "description": "Failed deleting the captions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/transcribe": { "post": { "tags": [ "Manage Videos" ], "summary": "Transcribe video", "description": "Queues transcription for the video, generating captions. By default this is blocked if the video was already auto-transcribed; set force to true to re-queue (and re-bill) transcription anyway.", "operationId": "Video_TranscribeVideo", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 }, { "name": "force", "in": "query", "description": "If set to true, re-queues transcription even if the video was already auto-transcribed. This re-bills transcription usage.", "schema": { "type": "boolean", "default": false }, "x-position": 4 } ], "requestBody": { "x-name": "transcribeSettings", "description": "Used to override video library transcription settings, null by default", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscribeSettings" } } }, "x-position": 5 }, "responses": { "200": { "description": "The transcription was queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested video was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "400": { "description": "Invalid request for transcription queue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/smart": { "post": { "tags": [ "Manage Videos" ], "summary": "Trigger Smart actions", "description": "Queues Smart Actions (title, description, chapters and/or moments generation) for a video that already has captions. This endpoint does not check the video library's Smart Actions setting — requests are accepted, processed and billed for transcription usage even when Smart Actions is disabled for the library. Requires at least one of GenerateTitle, GenerateDescription, GenerateChapters or GenerateMoments, and returns 429 once the library's Smart Actions usage threshold for the video is exceeded.", "operationId": "Video_SmartGenerate", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 } ], "requestBody": { "x-name": "model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartGenerateModel" } } }, "required": true, "x-position": 3 }, "responses": { "202": { "description": "The smart action was queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "404": { "description": "The requested video was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "429": { "description": "Limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "400": { "description": "Invalid request for smart feature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "503": { "description": "The smart action could not be queued; the requested features are marked as failed and the request can be retried", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/resolutions": { "get": { "tags": [ "Manage Videos" ], "summary": "Video resolutions info", "operationId": "Video_GetVideoResolutions", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 } ], "responses": { "200": { "description": "The resolutions info.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModelOfVideoResolutionsInfoModel" } } } }, "404": { "description": "The requested video was not found" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/storage": { "get": { "tags": [ "Manage Videos" ], "summary": "Get video storage size info", "operationId": "Video_GetVideoStorageSize", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 } ], "responses": { "200": { "description": "The storage size information for the video.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModelOfVideoStorageSizeModel" } } } }, "404": { "description": "The requested video was not found" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "429": { "description": "Rate limit exceeded" }, "408": { "description": "Request timeout" }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] } }, "/library/{libraryId}/videos/{videoId}/resolutions/cleanup": { "post": { "tags": [ "Manage Videos" ], "summary": "Cleanup unconfigured resolutions", "description": "Deletes stored resolution files that are no longer configured for the library, or the specific resolutions passed in resolutionsToDelete/allResolutions. This cannot be undone. If the library has 'keep original files' turned off, the original source file is also deleted as part of this cleanup even when deleteOriginal is not set.", "operationId": "Video_DeleteResolutions", "parameters": [ { "name": "libraryId", "in": "path", "required": true, "description": "The ID of the video library.", "schema": { "type": "integer", "format": "int64" }, "x-position": 1 }, { "name": "videoId", "in": "path", "required": true, "description": "The GUID of the video.", "schema": { "type": "string" }, "x-position": 2 }, { "name": "resolutionsToDelete", "in": "query", "description": "Comma-separated list of specific resolutions to delete (e.g. \"720p,480p\"), instead of relying on deleteNonConfiguredResolutions/allResolutions.", "schema": { "type": "string", "nullable": true }, "x-position": 3 }, { "name": "deleteNonConfiguredResolutions", "in": "query", "description": "If set to true, all resolutions not currently configured for the library will be deleted.", "schema": { "type": "boolean", "default": false }, "x-position": 4 }, { "name": "allResolutions", "in": "query", "description": "If set to true, all resolutions for the video will be deleted, regardless of library configuration. When targeting HLS resolutions (the default, or outputs=all), at least one resolution must remain after cleanup or the request is rejected — scope outputs to mp4 to remove every rendition.", "schema": { "type": "boolean", "default": false }, "x-position": 5 }, { "name": "deleteOriginal", "in": "query", "description": "If set to true, the original source file is deleted as well. Note: the original is also deleted when the library has 'keep original files' disabled, regardless of this flag.", "schema": { "type": "boolean", "default": false }, "x-position": 6 }, { "name": "outputs", "in": "query", "description": "Outputs to clean. Supported values: hls, mp4, all", "schema": { "type": "string", "nullable": true }, "x-position": 7 }, { "name": "deleteMp4Files", "in": "query", "description": "If set to true, MP4 fallback files for the deleted resolutions are removed too.", "schema": { "type": "boolean", "default": false }, "x-position": 8 }, { "name": "dryRun", "in": "query", "description": "If set to true, no actual file manipulation will happen, only informational data will be returned", "schema": { "type": "boolean", "default": false }, "x-position": 9 } ], "responses": { "200": { "description": "The resolutions were successfully deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModelOfResolutionsCleanupModel" } } } }, "400": { "description": "The cleanup was rejected, for example because it would leave the video with no available resolution. Data carries the plan as evaluated up to that point.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModelOfResolutionsCleanupModel" } } } }, "404": { "description": "The requested video was not found" }, "401": { "description": "The request authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "403": { "description": "The request authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusModel" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "AccessKey": [] } ] } }, "/OEmbed": { "get": { "tags": [ "OEmbed" ], "summary": "Get oEmbed data", "description": "Implements the oEmbed specification (oembed.com) for bunny.net video embed URLs, allowing third-party sites and tools to auto-generate an embeddable player for a pasted video link. url must be a bunny.net player URL for an existing video — either the legacy player (e.g. \"https://iframe.mediadelivery.net/embed/{libraryId}/{videoId}\") or the new player (e.g. \"https://player.mediadelivery.net/embed/{libraryId}/{videoId}\") — not an arbitrary link. Only the library ID and video ID segments are read, so /play/ URLs are accepted as well as /embed/ ones. For private libraries, the request must satisfy the library's referer restrictions and, separately, a valid token and expires pair if token authentication is enabled — one does not substitute for the other.", "operationId": "OEmbed_GetOEmbed", "parameters": [ { "name": "url", "in": "query", "description": "The bunny.net player URL of the video to generate oEmbed data for (legacy iframe.mediadelivery.net or new player.mediadelivery.net player). Both /embed/ and /play/ paths are accepted.", "schema": { "type": "string", "nullable": true }, "x-position": 1 }, { "name": "maxWidth", "in": "query", "description": "Maximum width in pixels for the embedded player; the player is scaled down to fit while preserving aspect ratio.", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 2 }, { "name": "maxHeight", "in": "query", "description": "Maximum height in pixels for the embedded player; the player is scaled down to fit while preserving aspect ratio.", "schema": { "type": "integer", "format": "int32", "nullable": true }, "x-position": 3 }, { "name": "token", "in": "query", "description": "Signed access token, required when the video library has token authentication enabled. An allowed referer is checked separately and does not exempt the request from this requirement.", "schema": { "type": "string", "default": "", "nullable": true }, "x-position": 4 }, { "name": "expires", "in": "query", "description": "Unix timestamp (seconds) the token is valid until, required when the video library has token authentication enabled.", "schema": { "type": "integer", "format": "int64", "default": 0 }, "x-position": 5 } ], "responses": { "200": { "description": "The oEmbed data for the video", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoOEmbedModel" } } } }, "400": { "description": "The url could not be parsed" }, "401": { "description": "The video's library is private and no valid token/referer was provided" }, "404": { "description": "The url is not a recognized bunny.net player URL, or the video library or video does not exist" } } } } }, "components": { "schemas": { "CollectionModel": { "type": "object", "additionalProperties": false, "properties": { "videoLibraryId": { "type": "integer", "description": "The video library ID that contains the collection", "format": "int64" }, "guid": { "type": "string", "description": "The unique ID of the collection", "nullable": true }, "name": { "type": "string", "description": "The name of the collection", "nullable": true }, "videoCount": { "type": "integer", "description": "The number of on-demand videos in the collection. Live streams in the collection are not included in this count.", "format": "int64" }, "liveStreamCount": { "type": "integer", "description": "The number of live streams in the collection. On-demand videos are not included in this count.", "format": "int64" }, "totalSize": { "type": "integer", "description": "The total storage size of all videos in the collection, in bytes.", "format": "int64" }, "previewVideoIds": { "type": "string", "description": "Comma-separated list of video GUIDs used as preview thumbnails for the collection.", "nullable": true }, "previewImageUrls": { "type": "array", "description": "The URLs of preview images of videos in the collection", "nullable": true, "items": { "type": "string" } } } }, "StatusModel": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "description": "Determines if the request was successful" }, "message": { "type": "string", "description": "Human-readable message describing the result, typically populated with error details when Success is false.", "nullable": true }, "statusCode": { "type": "integer", "description": "The HTTP status code corresponding to the result of the request.", "format": "int32" } } }, "PaginationListOfCollectionModel": { "type": "object", "additionalProperties": false, "properties": { "totalItems": { "type": "integer", "description": "The total number of items across all pages matching the query, not just the current page.", "format": "int64" }, "currentPage": { "type": "integer", "description": "The current page number of the result set (1-based).", "format": "int64" }, "itemsPerPage": { "type": "integer", "description": "The effective page size after clamping the requested value; the last page may contain fewer items.", "format": "int32" }, "items": { "type": "array", "description": "The items on the current page, in the order returned by the query; an empty list if no results match.", "nullable": true, "items": { "$ref": "#/components/schemas/CollectionModel" } } } }, "UpdateCollectionModel": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The name to assign to the collection. Required, up to 255 characters.", "nullable": true } } }, "VideoEncodingStatisticsModel": { "type": "object", "additionalProperties": false, "properties": { "hourly": { "type": "boolean", "description": "Indicates whether the charts use hourly or daily UTC buckets." }, "total": { "description": "Combined premium and free encoding statistics for the selected period.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/VideoEncodingBreakdownModel" } ] }, "premium": { "description": "Encoding statistics for videos encoded with the premium encoding tier.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/VideoEncodingBreakdownModel" } ] }, "free": { "description": "Encoding statistics for videos encoded with the free encoding tier.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/VideoEncodingBreakdownModel" } ] } } }, "VideoEncodingBreakdownModel": { "type": "object", "additionalProperties": false, "properties": { "normalizedTotal": { "type": "integer", "description": "Billable encoding seconds in the selected period: counted per output codec and weighted by the video's highest resolution (x0.5 below 720p, x1 up to 1080p, x3 above).", "format": "int64" }, "normalizedChart": { "type": "object", "description": "Billable (normalized) encoding seconds over time, grouped hourly or daily in UTC.", "nullable": true, "additionalProperties": { "type": "integer", "format": "int64" } }, "outputTotal": { "type": "integer", "description": "Encoded output seconds in the selected period: video length counted once per output codec, without resolution weighting.", "format": "int64" }, "outputChart": { "type": "object", "description": "Encoded output seconds over time, grouped hourly or daily in UTC.", "nullable": true, "additionalProperties": { "type": "integer", "format": "int64" } }, "byVideoCodec": { "type": "object", "description": "Encoding seconds grouped by output video codec (H264, VP9, HEVC, AV1).", "nullable": true, "additionalProperties": { "$ref": "#/components/schemas/VideoEncodingSecondsModel" } }, "byResolution": { "type": "object", "description": "Encoding seconds grouped by the video's highest output resolution. 0 means the resolution was unknown.", "nullable": true, "additionalProperties": { "$ref": "#/components/schemas/VideoEncodingSecondsModel" } }, "byJit": { "type": "object", "description": "Encoding seconds grouped by encoding type: 'jit' for just-in-time encodes, 'standard' for full encodes.", "nullable": true, "additionalProperties": { "$ref": "#/components/schemas/VideoEncodingSecondsModel" } } } }, "VideoEncodingSecondsModel": { "type": "object", "additionalProperties": false, "properties": { "normalized": { "type": "integer", "description": "Billable encoding seconds, weighted by resolution.", "format": "int64" }, "output": { "type": "integer", "description": "Encoded output seconds, without resolution weighting.", "format": "int64" } } }, "VideoModel": { "type": "object", "additionalProperties": false, "required": [ "videoLibraryId", "guid", "title", "dateUploaded", "views", "isPublic", "length", "status", "framerate", "width", "height", "outputCodecs", "thumbnailCount", "encodeProgress", "storageSize", "hasMP4Fallback", "averageWatchTime", "totalWatchTime" ], "properties": { "videoLibraryId": { "type": "integer", "description": "The ID of the video library that the video belongs to", "format": "int64" }, "guid": { "type": "string", "description": "The unique ID of the video", "minLength": 1 }, "title": { "type": "string", "description": "The title of the video", "minLength": 1 }, "description": { "type": "string", "description": "The description of the video", "nullable": true }, "dateUploaded": { "type": "string", "description": "The date when the video was uploaded", "format": "date-time", "minLength": 1 }, "views": { "type": "integer", "description": "The number of views the video received", "format": "int64" }, "isPublic": { "type": "boolean", "description": "Determines if the video is publically accessible" }, "length": { "type": "integer", "description": "The duration of the video in seconds", "format": "int32" }, "status": { "description": "The status of the video. See VideoModelStatus.", "oneOf": [ { "$ref": "#/components/schemas/VideoModelStatus" } ] }, "framerate": { "type": "number", "description": "The framerate of the video", "format": "double" }, "rotation": { "type": "integer", "description": "Rotation of the source file in degrees as read from container metadata (e.g. 90, -90, 180, 270); null when no rotation metadata is present.", "nullable": true }, "width": { "type": "integer", "description": "The width of the original video file", "format": "int32" }, "height": { "type": "integer", "description": "The height of the original video file", "format": "int32" }, "availableResolutions": { "type": "string", "description": "Comma-separated list of resolution labels (e.g. \"360p,720p,1080p\") that have finished encoding and are available for playback.", "nullable": true }, "outputCodecs": { "type": "string", "description": "Comma-separated list of output codecs generated for this video (e.g. \"x264,vp9\"). See EncoderOutputCodec for possible values.", "minLength": 1 }, "thumbnailCount": { "type": "integer", "description": "The number of thumbnails generated for this video", "format": "int32" }, "encodeProgress": { "type": "integer", "description": "Encoding progress as a percentage from 0 to 100; reaches 100 when transcoding finishes.", "format": "int32" }, "storageSize": { "type": "integer", "description": "Total storage used by this video, in bytes.", "format": "int64" }, "captions": { "type": "array", "description": "The list of captions available for the video", "nullable": true, "items": { "$ref": "#/components/schemas/CaptionModel" } }, "hasMP4Fallback": { "type": "boolean", "description": "Determines if the video has MP4 fallback files generated" }, "collectionId": { "type": "string", "description": "The ID of the collection where the video belongs", "nullable": true }, "thumbnailFileName": { "type": "string", "description": "The file name of the thumbnail inside of the storage", "nullable": true }, "thumbnailUrl": { "type": "string", "description": "The CDN URL of the thumbnail", "nullable": true }, "thumbnailBlurhash": { "type": "string", "description": "Thumbnail blurhash to show while the actual thumbnail is being loaded", "nullable": true }, "averageWatchTime": { "type": "integer", "description": "The average watch time of the video in seconds", "format": "int64" }, "totalWatchTime": { "type": "integer", "description": "The total video watch time in seconds", "format": "int64" }, "category": { "type": "string", "description": "Automatically detected content category label; \"untagged\" when no category has been determined yet.", "nullable": true }, "chapters": { "type": "array", "description": "The list of chapters available for the video", "nullable": true, "items": { "$ref": "#/components/schemas/ChapterModel" } }, "moments": { "type": "array", "description": "The list of moments available for the video", "nullable": true, "items": { "$ref": "#/components/schemas/MomentModel" } }, "metaTags": { "type": "array", "description": "The list of meta tags that have been added to the video", "nullable": true, "items": { "$ref": "#/components/schemas/MetaTagModel" } }, "transcodingMessages": { "type": "array", "description": "The list of transcoding messages that describe potential issues while the video was transcoding", "nullable": true, "items": { "$ref": "#/components/schemas/TranscodingMessageModel" } }, "jitEncodingEnabled": { "type": "boolean", "description": "Whether just-in-time encoding is enabled for this specific video, overriding the video library's default JitEncodingEnabled setting when set. Null means the library default applies.", "nullable": true }, "smartGenerateStatus": { "description": "Aggregate smart generate status derived from per-feature statuses when present: InProgress, then Queued, then Failed, then Finished; otherwise the stored legacy value. See SmartGenerateFeaturesStatus.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/SmartGenerateStatus" } ] }, "smartGenerateFeaturesStatus": { "description": "Per-feature smart generate statuses (title, description, chapters, moments). Null for a feature on legacy rows.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/SmartGenerateFeaturesStatusModel" } ] }, "hasOriginal": { "type": "boolean", "description": "Determines if video has the original file available in storage", "nullable": true }, "originalHash": { "type": "string", "description": "Original uploaded file SHA256 hash", "nullable": true }, "hasHighQualityPreview": { "type": "boolean", "description": "Whether a high-quality animated preview has been generated for this video.", "nullable": true } } }, "VideoModelStatus": { "type": "integer", "description": "", "oneOf": [ { "title": "Created", "type": "integer", "enum": [ 0 ] }, { "title": "Uploaded", "type": "integer", "enum": [ 1 ] }, { "title": "Processing", "type": "integer", "enum": [ 2 ] }, { "title": "Transcoding", "type": "integer", "enum": [ 3 ] }, { "title": "Finished", "type": "integer", "enum": [ 4 ] }, { "title": "Error", "type": "integer", "enum": [ 5 ] }, { "title": "UploadFailed", "type": "integer", "enum": [ 6 ] }, { "title": "JitSegmenting", "type": "integer", "enum": [ 7 ] }, { "title": "JitPlaylistsCreated", "type": "integer", "enum": [ 8 ] } ] }, "CaptionModel": { "type": "object", "additionalProperties": false, "properties": { "srclang": { "type": "string", "description": "The unique srclang shortcode for the caption", "nullable": true }, "label": { "type": "string", "description": "The text description label for the caption", "nullable": true }, "version": { "type": "integer", "description": "Increments each time this caption is replaced; useful as a cache-busting value for the caption file URL.", "format": "int32" } } }, "ChapterModel": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "description": "The title of the chapter, up to 255 characters.", "minLength": 1 }, "start": { "type": "integer", "description": "The start time of the chapter in seconds. Must be less than End and within the video's duration; chapters must not overlap each other.", "format": "int32" }, "end": { "type": "integer", "description": "The end time of the chapter in seconds. Must be greater than Start and within the video's duration; chapters must not overlap each other.", "format": "int32" } } }, "MomentModel": { "type": "object", "additionalProperties": false, "required": [ "label" ], "properties": { "label": { "type": "string", "description": "The text description label for the moment, up to 255 characters.", "minLength": 1 }, "timestamp": { "type": "integer", "description": "The timestamp of the moment in seconds. Must be within the video's duration.", "format": "int32" } } }, "MetaTagModel": { "type": "object", "additionalProperties": false, "properties": { "property": { "type": "string", "description": "The meta tag key. Must match ^[A-Za-z0-9._:'\"-]+$. Setting a tag with the property \"description\" also updates the video's Description field.", "nullable": true }, "value": { "type": "string", "description": "The meta tag value. HTML/markup is stripped and the value is stored as plain text.", "nullable": true } } }, "TranscodingMessageModel": { "type": "object", "additionalProperties": false, "properties": { "timeStamp": { "type": "string", "description": "Date and time when this message was added (UTC).", "format": "date-time" }, "level": { "description": "Message severity. See Severity.", "oneOf": [ { "$ref": "#/components/schemas/Severity" } ] }, "issueCode": { "description": "Issue code identifying the specific transcoding problem. See IssueCodes.", "oneOf": [ { "$ref": "#/components/schemas/IssueCodes" } ] }, "message": { "type": "string", "description": "Human-readable description of the issue.", "nullable": true }, "value": { "type": "string", "description": "Additional context value for the issue, if applicable; otherwise empty.", "nullable": true } } }, "Severity": { "type": "integer", "description": "", "oneOf": [ { "title": "Undefined", "type": "integer", "description": "Shouldn't be used", "enum": [ 0 ] }, { "title": "Information", "type": "integer", "description": "An info message to the user, shouldn't break anythying", "enum": [ 1 ] }, { "title": "Warning", "type": "integer", "description": "A warning message, for example that the transcoded video may break when playing", "enum": [ 2 ] }, { "title": "Error", "type": "integer", "description": "An error, meaning that the video will most likely not be playable", "enum": [ 3 ] } ] }, "IssueCodes": { "type": "integer", "description": "", "oneOf": [ { "title": "Undefined", "type": "integer", "description": "Shouldn't be used", "enum": [ 0 ] }, { "title": "StreamLengthsDifference", "type": "integer", "description": "Marks that there is a mismatch between lengths of audio and video streams in the transcoded file", "enum": [ 1 ] }, { "title": "TranscodingWarnings", "type": "integer", "description": "Marks that transcoding completed with warnings", "enum": [ 2 ] }, { "title": "IncompatibleResolution", "type": "integer", "description": "Marks that original video file has incompatible resolution or isn't a video stream", "enum": [ 3 ] }, { "title": "InvalidFramerate", "type": "integer", "description": "Marks that original video file has invalid framerate", "enum": [ 4 ] }, { "title": "VideoExceededMaxDuration", "type": "integer", "description": "Marks that video stream exceeded max duration", "enum": [ 5 ] }, { "title": "AudioExceededMaxDuration", "type": "integer", "description": "Marks that audio stream exceeded max duration", "enum": [ 6 ] }, { "title": "OriginalCorrupted", "type": "integer", "description": "Marks that video file is corrupted and couldn't be processed properly", "enum": [ 7 ] }, { "title": "TranscriptionFailed", "type": "integer", "description": "Marks that video transcription finished with errors and might not be complete", "enum": [ 8 ] }, { "title": "JitIncompatible", "type": "integer", "description": "Marks that video file is not compatible with JIT encoding", "enum": [ 9 ] }, { "title": "JitFailed", "type": "integer", "description": "Marks that video failed JIT encoding", "enum": [ 10 ] }, { "title": "CaptionGenerationFailed", "type": "integer", "description": "Marks that captions generation failed", "enum": [ 11 ] }, { "title": "UnsupportedFileType", "type": "integer", "description": "Marks that the uploaded or fetched file is not video or audio, for example a photo or a document", "enum": [ 12 ] } ] }, "SmartGenerateStatus": { "type": "integer", "description": "", "oneOf": [ { "title": "None", "type": "integer", "enum": [ 0 ] }, { "title": "Queued", "type": "integer", "enum": [ 1 ] }, { "title": "InProgress", "type": "integer", "enum": [ 2 ] }, { "title": "Finished", "type": "integer", "enum": [ 3 ] }, { "title": "Failed", "type": "integer", "enum": [ 4 ] } ] }, "SmartGenerateFeaturesStatusModel": { "type": "object", "additionalProperties": false, "properties": { "title": { "description": "Smart generate status for the video title, when applicable.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/SmartGenerateStatus" } ] }, "description": { "description": "Smart generate status for the video description, when applicable.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/SmartGenerateStatus" } ] }, "chapters": { "description": "Smart generate status for chapters, when applicable.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/SmartGenerateStatus" } ] }, "moments": { "description": "Smart generate status for moments, when applicable.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/SmartGenerateStatus" } ] } } }, "VideoHeatmapModel": { "type": "object", "additionalProperties": false, "properties": { "heatmap": { "type": "object", "description": "Timeline heatmap as segment-index to intensity (0–100). Keys represent consecutive segments from the start of the video; values are normalized so 100 equals the most‑watched segment. Missing segments imply 0.", "nullable": true, "additionalProperties": { "type": "integer", "format": "int32" } } } }, "VideoPlayDataModel": { "type": "object", "additionalProperties": false, "properties": { "video": { "description": "Video data.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/VideoModel" } ] }, "libraryName": { "type": "string", "description": "The name of the video library.", "nullable": true }, "pullZoneId": { "type": "integer", "description": "The pull zone ID backing the video library's CDN delivery.", "format": "int64" }, "captionsPath": { "type": "string", "description": "CDN URL of the directory containing the video's caption (.vtt) files.", "nullable": true }, "seekPath": { "type": "string", "description": "CDN URL of the directory containing the video's seek/scrub thumbnail sprites.", "nullable": true }, "thumbnailUrl": { "type": "string", "description": "CDN URL of the video's thumbnail image.", "nullable": true }, "fallbackUrl": { "type": "string", "description": "CDN URL prefix for the video's MP4 fallback renditions.", "nullable": true }, "videoPlaylistUrl": { "type": "string", "description": "CDN URL of the video's HLS master playlist.", "nullable": true }, "originalUrl": { "type": "string", "description": "CDN URL of the original uploaded source file. Only populated when the library allows early/original playback.", "nullable": true }, "previewUrl": { "type": "string", "description": "CDN URL of the video's animated preview (scrub thumbnail).", "nullable": true }, "controls": { "type": "string", "description": "Comma-separated list of player control identifiers enabled for this library.", "nullable": true }, "enableDRM": { "type": "boolean", "description": "Whether DRM protection is enabled for this video." }, "drmVersion": { "type": "integer", "description": "DRM protection tier applied to this video, as an integer cast of the Basic/Enterprise tier enum. Only relevant when EnableDRM is true.", "format": "int32" }, "playerKeyColor": { "type": "string", "description": "The player's accent/key color, as a CSS color value.", "nullable": true }, "vastTagUrl": { "type": "string", "description": "VAST ad tag URL used to serve ads in the player; empty when ads are disabled.", "nullable": true }, "viAiPublisherId": { "type": "string", "description": "Publisher ID for the vi.ai advertising integration; ads are enabled in the player when this is non-empty.", "nullable": true }, "captionsFontSize": { "type": "integer", "description": "Caption font size in pixels.", "format": "int32" }, "captionsFontColor": { "type": "string", "description": "CSS color value for the caption text.", "nullable": true }, "captionsBackground": { "type": "string", "description": "CSS color value for the caption background.", "nullable": true }, "uiLanguage": { "type": "string", "description": "Locale code for the player's UI language (e.g. \"en\").", "nullable": true }, "allowEarlyPlay": { "type": "boolean", "description": "Whether the video can be played from the original source file before encoding has finished." }, "tokenAuthEnabled": { "type": "boolean", "description": "Whether the library's CDN delivery requires signed URLs for playback assets (segments, manifests, thumbnails, etc.). This is a separate setting from whether this endpoint itself required a token to return data." }, "enableMP4Fallback": { "type": "boolean", "description": "Whether MP4 fallback renditions are available for players that cannot use HLS." }, "showHeatmap": { "type": "boolean", "description": "Whether the attention heatmap is enabled for this library's player." }, "fontFamily": { "type": "string", "description": "CSS font-family value used by the player.", "nullable": true }, "playbackSpeeds": { "type": "string", "description": "Comma-separated list of playback speed multipliers offered to the viewer (e.g. \"0.5,1,1.5,2\").", "nullable": true }, "widevineMinClientSecurityLevel": { "type": "integer", "description": "Minimum required Widevine client security level (1-3). Ignored (always null here) when WidevineSdOnlyForL3 is enabled, since that setting takes precedence.", "format": "int32", "nullable": true }, "widevineEmeRobustness": { "type": "string", "description": "EME robustness string corresponding to WidevineMinClientSecurityLevel (e.g. \"SW_SECURE_CRYPTO\", \"HW_SECURE_DECODE\"); null when no minimum level applies.", "nullable": true }, "widevineSdOnlyForL3": { "type": "boolean", "description": "When true, Widevine L3 (software-only) clients are capped to SD playback while stronger clients play at full quality; overrides WidevineMinClientSecurityLevel when both are set." }, "maxSoftwareWidevineResolution": { "type": "integer", "description": "Maximum vertical resolution allowed for software (L3) Widevine clients when WidevineSdOnlyForL3 is enabled; null otherwise.", "format": "int32", "nullable": true }, "zoneTier": { "type": "integer", "description": "Pull zone tier associated with this video library (integer enum value).", "format": "int32", "nullable": true }, "isPlayable": { "type": "boolean", "description": "Determines if the video is currently playable using either playlist or original source." }, "isPlaylistPlayable": { "type": "boolean", "description": "Determines if the HLS playlist is currently playable." }, "preferredPlaybackSource": { "description": "Preferred playback source for the current video state.", "oneOf": [ { "$ref": "#/components/schemas/VideoPlaybackSource" } ] }, "rememberPlayerPosition": { "type": "boolean", "description": "Whether the player resumes from the viewer's last watched position." }, "customCss": { "type": "string", "description": "Custom CSS injected into the player. Only populated when the caller explicitly requests it.", "nullable": true }, "exposeVideoMetadata": { "type": "boolean", "description": "Whether JSON-LD structured data (schema.org VideoObject markup) is rendered for this video, e.g. for SEO." }, "enableCompactControls": { "type": "boolean", "description": "Whether the player uses a compact control bar layout." } } }, "VideoPlaybackSource": { "type": "string", "description": "", "oneOf": [ { "title": "None", "type": "string", "enum": [ "None" ] }, { "title": "Playlist", "type": "string", "enum": [ "Playlist" ] }, { "title": "Original", "type": "string", "enum": [ "Original" ] } ] }, "VideoStatisticsModel": { "type": "object", "additionalProperties": false, "properties": { "viewsChart": { "type": "object", "description": "Shows the number of playback starts over time, with each data point representing the count of view starts in the corresponding UTC interval (hourly or daily). It is available at both the library level (aggregated across all videos) and the video level (for a single video). A playback start is counted once per viewer session per video and empty intervals are shown as zero.", "nullable": true, "additionalProperties": { "type": "integer", "format": "int64" } }, "watchTimeChart": { "type": "object", "description": "Shows the cumulative time viewers spent watching over time, with each data point representing total watch time in the corresponding UTC interval (hourly or daily). It is available at both the library level (aggregated across all videos) and the video level (for a single video). Rewatches and repeated visits add to the total and empty intervals are shown as zero.", "nullable": true, "additionalProperties": { "type": "integer", "format": "int64" } }, "countryViewCounts": { "type": "object", "description": "Shows the total number of playback starts by country for the selected time range. It is available at both the library level (aggregated across all videos) and the video level (for a single video). Each country’s value reflects unique playback starts per viewer session based on IP geolocation at playback start.", "nullable": true, "additionalProperties": { "type": "integer", "format": "int64" } }, "countryWatchTime": { "type": "object", "description": "Shows the total watch time by country for the selected time range. It is available at both the library level (aggregated across all videos) and the video level (for a single video). Values reflect cumulative viewing time (rewatches and repeated visits add to the total) based on IP geolocation at playback start.", "nullable": true, "additionalProperties": { "type": "integer", "format": "int64" } }, "engagementScore": { "type": "integer", "description": "Indicates how engaging a specific video is on a 0–100 scale based on viewing duration and viewing patterns; higher values reflect stronger viewer retention. Reported at the video level only and may be unavailable when there isn’t enough viewing data.", "format": "int32" } } }, "EncoderOutputCodec": { "type": "integer", "description": "", "oneOf": [ { "title": "x264", "type": "integer", "enum": [ 0 ] }, { "title": "vp9", "type": "integer", "enum": [ 1 ] }, { "title": "hevc", "type": "integer", "enum": [ 2 ] }, { "title": "av1", "type": "integer", "enum": [ 3 ] } ] }, "PaginationListOfVideoModel": { "type": "object", "additionalProperties": false, "properties": { "totalItems": { "type": "integer", "description": "The total number of items across all pages matching the query, not just the current page.", "format": "int64" }, "currentPage": { "type": "integer", "description": "The current page number of the result set (1-based).", "format": "int64" }, "itemsPerPage": { "type": "integer", "description": "The effective page size after clamping the requested value; the last page may contain fewer items.", "format": "int32" }, "items": { "type": "array", "description": "The items on the current page, in the order returned by the query; an empty list if no results match.", "nullable": true, "items": { "$ref": "#/components/schemas/VideoModel" } } } }, "CreateVideoModel": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "description": "The title of the video", "minLength": 1 }, "collectionId": { "type": "string", "description": "The ID of the collection where the video will be put", "nullable": true }, "thumbnailTime": { "type": "integer", "description": "Video time in ms to extract the main video thumbnail.", "format": "int32", "nullable": true } } }, "UpdateVideoModel": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "description": "The title of the video", "nullable": true }, "collectionId": { "type": "string", "description": "The ID of the collection where the video belongs. Omit/null to leave the current collection unchanged; send an empty string to remove the video from its collection.", "nullable": true }, "chapters": { "type": "array", "description": "The list of chapters available for the video, up to 200. Omit/null to leave existing chapters unchanged; providing a list, including an empty one, fully replaces all existing chapters.", "nullable": true, "items": { "$ref": "#/components/schemas/ChapterModel" } }, "moments": { "type": "array", "description": "The list of moments available for the video, up to 200. Omit/null to leave existing moments unchanged; providing a list, including an empty one, fully replaces all existing moments.", "nullable": true, "items": { "$ref": "#/components/schemas/MomentModel" } }, "metaTags": { "type": "array", "description": "The meta tags added to the video, up to 50. Omit/null to leave existing tags unchanged; providing a list, including an empty one, fully replaces all existing tags. Setting a tag with Property \"description\" also updates the video's Description field.", "nullable": true, "items": { "$ref": "#/components/schemas/MetaTagModel" } } } }, "FetchVideoRequest": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL from which the video will be fetched from.", "minLength": 1 }, "headers": { "type": "object", "description": "The headers that will be sent along with the fetch request.", "nullable": true, "additionalProperties": { "type": "string" } }, "title": { "type": "string", "description": "The title that will be set to video. If omitted, the filename from the fetch URL is used instead, falling back to \"Fetched Video\" if that can't be determined.", "nullable": true } } }, "StatusModelOfCaptionValidationModel": { "allOf": [ { "$ref": "#/components/schemas/StatusModel" }, { "type": "object", "additionalProperties": false, "properties": { "data": { "description": "The response payload. Some endpoints also populate this with error details when Success is false — see the endpoint's own response documentation.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/CaptionValidationModel" } ] } } } ] }, "CaptionValidationModel": { "type": "object", "additionalProperties": false, "properties": { "valid": { "type": "boolean", "description": "Denotes whether uploaded captions file was valid" }, "errorList": { "type": "array", "description": "When uploaded file was invalid, will contain errors found", "nullable": true, "items": { "type": "string" } }, "warningList": { "type": "array", "description": "When uploaded file was valid but non-breaking issues were found, will contain issues found", "nullable": true, "items": { "type": "string" } }, "warningMessage": { "type": "string", "description": "UI-friendly summary of warnings found in the uploaded captions file", "nullable": true } } }, "CaptionModelAdd": { "type": "object", "additionalProperties": false, "properties": { "srclang": { "type": "string", "description": "Not used — the caption's srclang is taken from the srclang route segment instead. Any value sent here is ignored.", "deprecated": true, "x-deprecatedMessage": "Not used — the caption's srclang is taken from the srclang route segment instead. Any value sent here is ignored.", "nullable": true }, "label": { "type": "string", "description": "The text description label for the caption", "nullable": true }, "captionsFile": { "type": "string", "description": "Base64 encoded captions file", "nullable": true } } }, "TranscribeSettings": { "type": "object", "additionalProperties": false, "properties": { "targetLanguages": { "type": "array", "description": "List of languages that will be used as target languages, use ISO 639-1 language codes.", "nullable": true, "items": { "type": "string" } }, "generateTitle": { "type": "boolean", "description": "Whether video title should be automatically generated.", "nullable": true }, "generateDescription": { "type": "boolean", "description": "Whether video description should be automatically generated.", "nullable": true }, "generateChapters": { "type": "boolean", "description": "Whether video chapters should be automatically generated.", "nullable": true }, "generateMoments": { "type": "boolean", "description": "Whether video moments should be automatically generated.", "nullable": true }, "sourceLanguage": { "type": "string", "description": "Video source language, use ISO 639-1 language code.", "nullable": true } } }, "SmartGenerateModel": { "type": "object", "additionalProperties": false, "properties": { "generateTitle": { "type": "boolean", "description": "Whether video title should be generated.", "nullable": true }, "generateDescription": { "type": "boolean", "description": "Whether video description should be generated.", "nullable": true }, "generateChapters": { "type": "boolean", "description": "Whether video chapters should be generated.", "nullable": true }, "generateMoments": { "type": "boolean", "description": "Whether video moments should be generated.", "nullable": true }, "sourceLanguage": { "type": "string", "description": "(Optional) Video source language, use ISO 639-1 language code.", "nullable": true } } }, "StatusModelOfVideoResolutionsInfoModel": { "allOf": [ { "$ref": "#/components/schemas/StatusModel" }, { "type": "object", "additionalProperties": false, "properties": { "data": { "description": "The response payload. Some endpoints also populate this with error details when Success is false — see the endpoint's own response documentation.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/VideoResolutionsInfoModel" } ] } } } ] }, "VideoResolutionsInfoModel": { "type": "object", "additionalProperties": false, "properties": { "videoId": { "type": "string", "description": "The GUID of the video.", "nullable": true }, "videoLibraryId": { "type": "integer", "description": "The ID of the video library.", "format": "int64" }, "availableResolutions": { "type": "array", "description": "Resolutions currently ready to stream for this video.", "nullable": true, "items": { "type": "string" } }, "configuredResolutions": { "type": "array", "description": "Resolutions the video library is configured to encode; may not all exist yet for this video.", "nullable": true, "items": { "type": "string" } }, "playlistResolutions": { "type": "array", "description": "Resolutions declared in the video's HLS master playlist.", "nullable": true, "items": { "$ref": "#/components/schemas/ResolutionReference" } }, "storageResolutions": { "type": "array", "description": "Resolutions found as folders in object storage; can diverge from PlaylistResolutions.", "nullable": true, "items": { "$ref": "#/components/schemas/ResolutionReference" } }, "mp4Resolutions": { "type": "array", "description": "Resolutions found as MP4 fallback files in object storage.", "nullable": true, "items": { "$ref": "#/components/schemas/ResolutionReference" } }, "storageObjects": { "type": "array", "description": "All storage objects found for this video.", "nullable": true, "items": { "$ref": "#/components/schemas/StorageObjectModel" } }, "oldResolutions": { "type": "array", "description": "Storage folders using the legacy \"{width}x{height}\" naming, populated only when HasBothOldAndNewResolutionFormat is true.", "nullable": true, "items": { "$ref": "#/components/schemas/StorageObjectModel" } }, "hasBothOldAndNewResolutionFormat": { "type": "boolean", "description": "True when storage contains both the legacy \"{width}x{height}\" folder naming and the current \"{height}p\" naming for the same video — can happen when a codec was added via API rather than a full re-encode." }, "hasOriginal": { "type": "boolean", "description": "Whether the original uploaded source file is present in storage." } } }, "ResolutionReference": { "type": "object", "additionalProperties": false, "properties": { "resolution": { "type": "string", "description": "The resolution this reference applies to (e.g. \"720p\").", "nullable": true }, "path": { "type": "string", "description": "The storage path where this resolution's files are found.", "nullable": true } } }, "StorageObjectModel": { "type": "object", "additionalProperties": false, "properties": { "guid": { "type": "string", "nullable": true }, "storageZoneName": { "type": "string", "nullable": true }, "path": { "type": "string", "nullable": true }, "objectName": { "type": "string", "nullable": true }, "length": { "type": "integer", "format": "int64" }, "lastChanged": { "type": "string", "format": "date-time" }, "serverId": { "type": "integer", "format": "int32" }, "isDirectory": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "dateCreated": { "type": "string", "format": "date-time" }, "storageZoneId": { "type": "integer", "format": "int64" }, "checksum": { "type": "string", "nullable": true }, "replicatedZones": { "type": "string", "nullable": true } } }, "StatusModelOfVideoStorageSizeModel": { "allOf": [ { "$ref": "#/components/schemas/StatusModel" }, { "type": "object", "additionalProperties": false, "properties": { "data": { "description": "The response payload. Some endpoints also populate this with error details when Success is false — see the endpoint's own response documentation.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/VideoStorageSizeModel" } ] } } } ] }, "VideoStorageSizeModel": { "type": "object", "additionalProperties": false, "properties": { "encoded": { "type": "object", "description": "Size in bytes of each encoded rendition, keyed by \"{resolution}-{codec}\" (e.g. \"720p-h264\"). Videos encoded before the current storage layout can also report legacy \"{width}x{height}\" resolutions, e.g. \"1920x1080-h264\".", "nullable": true, "additionalProperties": { "$ref": "#/components/schemas/CodecRenditionSizeModel" } }, "thumbnails": { "type": "integer", "description": "Size in bytes of the video's JPEG thumbnails.", "format": "int64" }, "previews": { "type": "integer", "description": "Size in bytes of the video's GIF and WEBP previews.", "format": "int64" }, "originals": { "type": "integer", "description": "Size in bytes of the original uploaded video file.", "format": "int64" }, "mp4Fallback": { "type": "integer", "description": "Size in bytes of the MP4 fallback rendition.", "format": "int64" }, "miscellaneous": { "type": "integer", "description": "Size in bytes of everything else: playlists, manifests, captions, audio extracts, etc.", "format": "int64" }, "calculatedAt": { "type": "string", "description": "Timestamp when this storage size was calculated (UTC).", "format": "date-time" } } }, "CodecRenditionSizeModel": { "type": "object", "additionalProperties": false, "properties": { "codec": { "type": "string", "description": "Output codec name as used by the storage layout (e.g. \"h264\", \"hevc\", \"vp9\", \"av1\"). Note that h264 is reported as \"x264\" in VideoModel.OutputCodecs.", "nullable": true }, "resolution": { "type": "string", "description": "Resolution of this rendition (e.g. \"720p\", \"1080p\"), or a legacy \"{width}x{height}\" value for older videos.", "nullable": true }, "size": { "type": "integer", "description": "Size of this rendition in bytes.", "format": "int64" } } }, "StatusModelOfResolutionsCleanupModel": { "allOf": [ { "$ref": "#/components/schemas/StatusModel" }, { "type": "object", "additionalProperties": false, "properties": { "data": { "description": "The response payload. Some endpoints also populate this with error details when Success is false — see the endpoint's own response documentation.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ResolutionsCleanupModel" } ] } } } ] }, "ResolutionsCleanupModel": { "type": "object", "additionalProperties": false, "properties": { "videoId": { "type": "string", "description": "The GUID of the video.", "nullable": true }, "videoLibraryId": { "type": "integer", "description": "The ID of the video library.", "format": "int64" }, "resolutionsToDelete": { "type": "array", "description": "Resolutions selected for removal as part of this cleanup, across the HLS playlist, object storage, and MP4 fallback set. Populated even when dryRun is true or an individual deletion fails — see UpdatedAvailableResolutions/ModifiedPlaylist/DeletedStorageObjects for what was actually changed.", "nullable": true, "items": { "type": "string" } }, "resolutionsToDeleteFromPlaylist": { "type": "array", "description": "Resolutions selected for removal from the HLS master playlist. Populated even when dryRun is true.", "nullable": true, "items": { "type": "string" } }, "resolutionsToDeleteFromStorage": { "type": "array", "description": "Resolutions selected for removal from object storage. Populated even when dryRun is true or an individual deletion fails.", "nullable": true, "items": { "type": "string" } }, "resolutionsToDeleteFromMp4": { "type": "array", "description": "Resolutions selected for removal from the MP4 fallback set. Populated even when dryRun is true.", "nullable": true, "items": { "type": "string" } }, "storageObjectsToDelete": { "type": "array", "description": "Storage object paths selected for deletion as part of this cleanup. These are candidates, not confirmations: the list is populated even when dryRun is true or when an individual deletion fails — see DeletedStorageObjects for whether at least one deletion actually succeeded.", "nullable": true, "items": { "type": "string" } }, "availableResolutionsAfter": { "type": "array", "description": "The video's available resolutions after this cleanup.", "nullable": true, "items": { "type": "string" } }, "updatedAvailableResolutions": { "type": "boolean", "description": "Whether the video's AvailableResolutions field was rewritten as part of this cleanup." }, "modifiedPlaylist": { "type": "boolean", "description": "Whether the HLS master playlist was rewritten to remove the deleted resolutions." }, "deletedStorageObjects": { "type": "boolean", "description": "Whether at least one of the storage objects in StorageObjectsToDelete was actually deleted (always false when dryRun is true). Individual objects can still have failed to delete — their failures are logged and do not clear this flag — so this confirms the cleanup did something, not that it removed everything listed." }, "deletedOriginal": { "type": "boolean", "description": "Whether the original uploaded source file was deleted from storage as part of this operation." } } }, "VideoOEmbedModel": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "string", "description": "The oEmbed spec version implemented by this response. Always \"1.0\".", "nullable": true }, "title": { "type": "string", "description": "The title of the video.", "nullable": true }, "type": { "type": "string", "description": "The oEmbed resource type. Always \"video\" for this endpoint.", "nullable": true }, "thumbnail_url": { "type": "string", "description": "The CDN URL of the video's thumbnail image.", "nullable": true }, "thumbnail_width": { "type": "integer", "description": "Width in pixels of the thumbnail image. Omitted for custom-uploaded thumbnails, whose dimensions are not known.", "format": "int32", "nullable": true }, "thumbnail_height": { "type": "integer", "description": "Height in pixels of the thumbnail image. Omitted for custom-uploaded thumbnails, whose dimensions are not known.", "format": "int32", "nullable": true }, "width": { "type": "integer", "description": "Width in pixels of the embedded player iframe, scaled to fit within maxWidth/maxHeight while preserving the video's aspect ratio.", "format": "int32" }, "height": { "type": "integer", "description": "Height in pixels of the embedded player iframe, scaled to fit within maxWidth/maxHeight while preserving the video's aspect ratio.", "format": "int32" }, "html": { "type": "string", "description": "The HTML