Skip navigation
Kinescope help center

Video enrichment

Posters, subtitles, annotations, and additional materials.

Posters

Create poster by time

POST https://api.kinescope.io/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
}

Set active poster

POST https://api.kinescope.io/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.

Posters list

GET https://api.kinescope.io/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"
    }
  ]
}

Get poster

GET https://api.kinescope.io/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"
  }
}

Delete poster

DELETE https://api.kinescope.io/v1/videos/:video_id/posters/:poster_id

Permanently deletes the poster. This action cannot be undone.

Subtitles

Add subtitle file

POST https://api.kinescope.io/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 https://api.kinescope.io/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": ""
    }
  ]
}

Copy

POST https://api.kinescope.io/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>"
  }
}

List subtitles

GET https://api.kinescope.io/v1/videos/:video_id/subtitles

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

Responses
{
  "data": null
}

Get subtitle

GET https://api.kinescope.io/v1/videos/:video_id/subtitles/:subtitle_id

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

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>"
  }
}

Reorder

PATCH https://api.kinescope.io/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>"
  }
}

Update subtitle info

PATCH https://api.kinescope.io/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>"
  }
}

Delete subtitle

DELETE https://api.kinescope.io/v1/videos/:video_id/subtitles/:subtitle_id

Permanently deletes the subtitle. This action cannot be undone.

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

Annotations

Add annotation

POST https://api.kinescope.io/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",
  "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
  }
}

Get annotation

GET https://api.kinescope.io/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 https://api.kinescope.io/v1/videos/:video_id/annotations

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

Responses
{
  "data": []
}

Update annotation

PUT https://api.kinescope.io/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 https://api.kinescope.io/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 https://uploader.kinescope.io/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 https://api.kinescope.io/v1/additional-materials/:material_id/link

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

Responses
{
  "data": {
    "link": "https://kinescopecdn.net/<UUID>/materials/<UUID>?expires=<EXPIRES>&sign=<SIGNATURE>"
  }
}

Update additional material

PUT https://api.kinescope.io/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 https://api.kinescope.io/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 https://api.kinescope.io/v1/additional-materials/:material_id

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

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

Posters

Upload poster

POST https://uploader.kinescope.io/v2/poster

Uploads a custom poster image for a live event.

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