Skip navigation
Kinescope help center

Video enrichment

Posters, subtitles, annotations, and additional materials.

Posters

Posters list

GET {{baseHost}}/v1/videos/:video_id/posters

Returns a list of posters. Results are paginated and can be filtered via query parameters.

Responses
{  "meta": {    "pagination": {      "page": 1,      "per_page": 10,      "total": 1    },    "order": {      "created_at": "desc"    }  },  "data": [    {      "id": "<UUID>",      "type": "image",      "from_time": 0,      "status": "done",      "active": true,      "to_time": 0,      "original": "https://kinescopecdn.net/<UUID>/posters/<UUID>/<UUID>.jpg",      "md": "https://kinescopecdn.net/<UUID>/posters/<UUID>/md/<UUID>.jpg",      "sm": "https://kinescopecdn.net/<UUID>/posters/<UUID>/sm/<UUID>.jpg",      "xs": "https://kinescopecdn.net/<UUID>/posters/<UUID>/xs/<UUID>.jpg"    }  ]}

Create poster by time

POST {{baseHost}}/v1/videos/:video_id/posters

Generates a poster image from a frame of the video at the specified timestamp. The poster is attached to the video and can be made active.

Request body (json)
{  "from_time": 2.3333}

Get poster

GET {{baseHost}}/v1/videos/:video_id/posters/:poster_id

Retrieves the details of a single poster by its unique ID.

Responses
{  "data": {    "id": "<UUID>",    "type": "image",    "from_time": 0,    "status": "done",    "active": true,    "to_time": 0,    "original": "https://kinescopecdn.net/<UUID>/posters/<UUID>/<UUID>.jpg",    "md": "https://kinescopecdn.net/<UUID>/posters/<UUID>/md/<UUID>.jpg",    "sm": "https://kinescopecdn.net/<UUID>/posters/<UUID>/sm/<UUID>.jpg",    "xs": "https://kinescopecdn.net/<UUID>/posters/<UUID>/xs/<UUID>.jpg"  }}
{  "error": {    "code": 400404,    "message": "not found"  }}

Set active poster

POST {{baseHost}}/v1/videos/:video_id/posters/:poster_id/active

Marks the specified poster as the active one — it will be shown in the video player and in lists.

Delete poster

DELETE {{baseHost}}/v1/videos/:video_id/posters/:poster_id

Permanently deletes the poster. This action cannot be undone.

Subtitles

List subtitles

GET {{baseHost}}/v1/videos/:video_id/subtitles

Returns a list of subtitles. Results are paginated and can be filtered via query parameters.

Body (formdata)
ParameterTypeDescription
languagetextExample: ru
descriptiontextExample: subtitle file description
filefile—
Responses
{  "data": null}

Add subtitle file

POST {{baseHost}}/v1/videos/:video_id/subtitles

Uploads a subtitle file (VTT or SRT) and attaches it to the video under the specified language.

Body (formdata)
ParameterTypeDescription
languagetextExample: ru
descriptiontextExample: subtitle file description
filefile—
Responses
{  "data": {    "id": "<UUID>",    "video_id": "<UUID>",    "description": "subtitle file description",    "language": "ru",    "file": "",    "file_name": "<UUID>.vtt",    "hls_file": "",    "url": "https://kinescopecdn.net/<UUID>/subtitles/<UUID>/<UUID>?expires=<EXPIRES>&sign=<SIGNATURE>"  }}

Generate subtitles automatically

POST {{baseHost}}/v1/videos/:video_id/subtitles/auto

Queues speech recognition for the video and creates one subtitle track per requested language. Pass the languages as ISO 639-1 codes in languages; an unknown code is rejected with 400, and either all tracks are created or none are.

The response returns immediately, before recognition starts, so every track comes back with status: "pending", an empty data object and an empty url. Poll GET /v1/videos/:video_id/subtitles/:subtitle_id until status becomes done — the recognised cues and the .vtt URL appear at that point.

Body (json)
ParameterTypeDescription
languagesarray of stringLanguages to recognise, as ISO 639-1 codes. One subtitle track is created per element. Example: ["ru", "en"]
Request body (json)
{  "languages": [    "ru",    "en"  ]}
Responses
{  "data": [    {      "id": "<UUID>",      "video_id": "<UUID>",      "description": "",      "language": "ru",      "status": "pending",      "position": 1,      "data": {},      "active": true,      "url": "",      "updated_at": "2024-03-04T11:54:32.451502Z",      "file": "",      "file_name": "<UUID>.vtt",      "hls_file": ""    }  ]}

Reorder

PATCH {{baseHost}}/v1/videos/:video_id/subtitles/reorder

Changes the order of subtitle tracks. Pass the full list of subtitle IDs in the desired order.

Request body (json)
[  "<UUID>",  "<UUID>",  "<UUID>",  "<UUID>"]
Responses
{  "data": {    "id": "<UUID>",    "video_id": "<UUID>",    "description": "subtitle file description",    "language": "ru",    "file": "",    "file_name": "<UUID>.vtt",    "hls_file": "",    "url": "https://kinescopecdn.net/<UUID>/subtitles/<UUID>/<UUID>?expires=<EXPIRES>&sign=<SIGNATURE>"  }}

Get subtitle

GET {{baseHost}}/v1/videos/:video_id/subtitles/:subtitle_id

Retrieves the details of a single subtitle by its unique ID.

Body (formdata)
ParameterTypeDescription
languagetextExample: ru
descriptiontextExample: subtitle file description
filefile—
Responses
{  "data": {    "id": "<UUID>",    "video_id": "<UUID>",    "description": "subtitle file description",    "language": "ru",    "file": "",    "file_name": "<UUID>.vtt",    "hls_file": "",    "url": "https://kinescopecdn.net/<UUID>/subtitles/<UUID>/<UUID>?expires=<EXPIRES>&sign=<SIGNATURE>"  }}

Update subtitle info

PATCH {{baseHost}}/v1/videos/:video_id/subtitles/:subtitle_id

Updates the metadata of a subtitle track (language, description, ordering).

Request body (json)
{  "language": "ru",  "description": "desc111"}
Responses
{  "data": {    "id": "<UUID>",    "video_id": "<UUID>",    "description": "desc",    "language": "ru",    "file": "",    "file_name": null,    "hls_file": "",    "url": "https://kinescopecdn.net/<UUID>/subtitles/<UUID>/<UUID>?expires=<EXPIRES>&sign=<SIGNATURE>"  }}

Copy

POST {{baseHost}}/v1/videos/:video_id/subtitles/:subtitle_id/copy

Duplicates a subtitle track. Useful for creating a variant based on an existing translation.

Responses
{  "data": {    "id": "<UUID>",    "video_id": "<UUID>",    "description": "desc",    "language": "ru",    "file": "",    "file_name": null,    "hls_file": "",    "url": "https://kinescopecdn.net/<UUID>/subtitles/<UUID>/<UUID>?expires=<EXPIRES>&sign=<SIGNATURE>"  }}

Delete subtitle

DELETE {{baseHost}}/v1/videos/:video_id/subtitles/:subtitle_id

Permanently deletes the subtitle. This action cannot be undone.

Responses
{  "data": {    "success": true  }}

Annotations

Get annotation

GET {{baseHost}}/v1/videos/:video_id/annotations/:annotation_id

Retrieves the details of a single annotation by its unique ID.

Responses
{  "data": {    "id": "<UUID>",    "media_id": "<UUID>",    "video_id": null,    "annotation_type": "text",    "title": "ann1",    "link": "",    "start_time": 0,    "end_time": 6740,    "annotation_poster_id": "<UUID>",    "created_at": "2024-02-27T10:04:30.259938Z",    "updated_at": null  }}

List annotations

GET {{baseHost}}/v1/videos/:video_id/annotations

Returns a list of annotations. Results are paginated and can be filtered via query parameters.

Responses
{  "data": []}

Add annotation

POST {{baseHost}}/v1/videos/:video_id/annotations

Creates a new annotation. Returns the newly created object on success.

Request body (json)
{  "video_id": "<UUID>",  "annotation_poster_id": "<UUID>",  "type": "video/text",  "title": "new annotation",  "link": "https://example.com",  "start_time": 0,  "end_time": 10000}
Responses
{  "data": {    "id": "<UUID>",    "media_id": "<UUID>",    "video_id": "<UUID>",    "annotation_type": "video",    "title": "annotation 1",    "link": "",    "start_time": 20000,    "end_time": 21000,    "annotation_poster_id": null,    "created_at": "2024-03-04T11:54:32.451502Z",    "updated_at": null  }}

Update annotation

PUT {{baseHost}}/v1/videos/:video_id/annotations/:annotation_id

Updates the specified annotation. Only fields provided in the request body are changed; others are left unchanged.

Request body (json)
{  "video_id": "<UUID>",  "annotation_poster_id": "<UUID>",  "title": "new annotation",  "link": "https://example.com",  "start_time": 0,  "end_time": 10000}
Responses
{  "data": {    "id": "<UUID>",    "media_id": "<UUID>",    "video_id": "<UUID>",    "annotation_type": "video",    "title": "annotation 1",    "link": "",    "start_time": 20000,    "end_time": 21000,    "annotation_poster_id": null,    "created_at": "2024-03-04T11:54:32.451502Z",    "updated_at": null  }}

Delete annotation

DELETE {{baseHost}}/v1/videos/:video_id/annotations/:annotation_id

Permanently deletes the annotation. This action cannot be undone.

Responses
{  "data": {    "success": true  }}

Additional materials

Upload additional material

POST {{uploadHost}}/additional-material

Uploads a file to be attached to a video as additional material (e.g. a PDF handout or source files).

Headers
ParameterDescription
X-Video-ID4iUMUmb63dLAvnbsMRkSUX
X-File-Namematerial.png
X-TitleMaterial title
GET {{baseHost}}/v1/additional-materials/:material_id/link

Returns a short-lived signed URL for downloading the material.

Responses
{  "data": {    "link": "https://..."  }}

Update additional material

PUT {{baseHost}}/v1/additional-materials/:material_id

Updates the specified additional material. Only fields provided in the request body are changed; others are left unchanged.

Request body (json)
{  "title": "New title"}
Responses
{  "data": {    "id": "8VYZT2rW5vbvRBcWruuNFo",    "video_id": "fq48rAScQ5zAYKJ2gYHZ3w",    "storage_id": "mucjva43n3sLsw5YRwsZYS",    "title": "New title",    "filename": "img.png",    "filetype": "image/png",    "size": 163427,    "position": 1,    "created_at": "2020-08-30T15:14:03.792708Z",    "updated_at": "2020-08-31T10:22:43.67869Z",    "deleted_at": null  }}

Reorder additional materials

PATCH {{baseHost}}/v1/additional-materials/reorder

Changes the display order of the additional materials attached to a video.

Request body (json)
[  "8VYZT2rW5vbvRBcWruuNFo",  "b32Wjbh6a3pYNaKvfxhXFU"]
Responses
{  "data": {    "success": true  }}

Delete additional material

DELETE {{baseHost}}/v1/additional-materials/:material_id

Permanently deletes the additional material. This action cannot be undone.

Responses
{  "data": {    "success": true  }}

Posters

Upload poster

POST {{uploadHost}}/v2/poster

Uploads a custom poster image for a live event.

Headers
ParameterDescription
X-Video-ID4iUMUmb63dLAvnbsMRkSUX
X-Poster-URLurl to poster