Generate a list of all available closed captions for a video on an account.

GET https://api.video.ibm.com/videos/{video_id}/captions.json
Copy to clipboard

Parameters

This request has no parameters.

Success response

Upon success a response with HTTP status “200 OK” is returned with an array under a captions key. The elements of the array contain the following key-value pairs for each caption:

KEY	TYPE	DESCRIPTION
`is_default`	boolean	If value is true, the video player automatically displays this caption. A video can only have one default caption.
`is_visible`	boolean	If value is true, this caption is available in the video player.
`language`	string	The language of the caption
`status`	string	Possible values: `processing`, `active`
`video_id`	string	Unique ID of the video

Example of a success response:

{
  "captions": [
    {
      "is_default": true,
      "is_visible": false,
      "language": "en-00",
      "status": "active",
      "video_id": "10001"
    },
Copy to clipboard

Error responses

Possible error responses:

HTTP RESPONSE CODE	ERROR VALUE	ERROR CONDITIONS
401 Unauthorized		The provided access token is missing, revoked, expired or malformed
403 Forbidden	`lack_of_ownership`	The API user is not allowed to manage the given channel
404 Not Found	`not_found`	Video was not found
429 Too Many Requests	`too_many_requests`	Rate limit exceeded (Read more)
503 Service Unavailable		There is a temporary error on the server which makes it impossible to serve the request

Get caption details

Returns the details of a specific set of captions on a video.

GET https://api.video.ibm.com/videos/{video_id}/captions/{language}.json
Copy to clipboard

Parameters

This request has no parameters.

Success response

Upon success a response with HTTP status “200 OK” is returned with the following key-value pairs under a caption key.

KEY	TYPE	DESCRIPTION
`is_default`	boolean	If value is `true`, the video player automatically displays this caption. A video can only have one default caption.
`is_visible`	boolean	If value is `true`, this caption is available in the video player.
`language`	string	The language of the caption
`status`	string	Possible values: `processing`, `active`
`video_id`	string	Unique ID of the video

Example of a success response:

{
  "caption": {
    "is_default": true,
    "is_visible": false,
    "language": "en-00",
    "status": "active",
    "video_id": "10001"
  }
}
Copy to clipboard

Error responses

Possible error responses:

HTTP RESPONSE CODE	ERROR VALUE	ERROR CONDITIONS
401 Unauthorized	`unauthorized`	The provided access token is missing, revoked, expired or malformed
403 Forbidden	`lack_of_ownership`	The API user is not allowed to manage the given channel
404 Not Found	`not_found`	Video was not found
429 Too Many Requests	`too_many_requests`	Rate limit exceeded (Read more)
503 Service Unavailable		There is a temporary error on the server which makes it impossible to serve the request

Modify caption settings

Change if a video’s closed captions are available and if it’s displayed automatically.

PUT https://api.video.ibm.com/videos/{video_id}/captions/{language}.json
Copy to clipboard

Parameters

The parameters for the PUT request:

PARAMETER	TYPE	IMPORTANCE	DESCRIPTION
`is_visible`	boolean	REQUIRED	Set this value to `true` to make this caption available in the video player.
`is_default`	boolean	REQUIRED	Set this value to `true` to make the video player automatically displays this caption. A video can only have one default caption.

Success response

Upon success a response with HTTP status “200 OK” is returned with the following key-value pairs under a caption key.

KEY	TYPE	DESCRIPTION
`is_default`	boolean	If value is `true`, the video player automatically displays this caption. A video can only have one default caption.
`is_visible`	boolean	If value is `true`, this caption is available in the video player.
`language`	string	The language of the caption
`status`	string	Possible values: `processing`, `active`
`video_id`	string	Unique ID of the video

Example of a success response:

{
  "caption": {
    "is_default": true,
    "is_visible": false,
    "language": "en-00",
    "status": "active",
    "video_id": "10001"
  }
}
Copy to clipboard

Error responses

Possible error responses:

HTTP RESPONSE CODE	ERROR VALUE	ERROR CONDITIONS
401 Unauthorized	`unauthorized`	The provided access token is missing, revoked, expired or malformed
403 Forbidden	`lack_of_ownership`	The API user is not allowed to manage the given channel
404 Not Found	`not_found`	Video was not found
429 Too Many Requests	`too_many_requests`	Rate limit exceeded (Read more)
503 Service Unavailable		There is a temporary error on the server which makes it impossible to serve the request

Download VTT file

Returns the contents of a particular set of caption in the WebVTT format.

GET https://api.video.ibm.com/videos/{video_id}/captions/{language}/vtt
Copy to clipboard

Parameters

This request has no parameters.

Success response

Upon success a response with HTTP status “200 OK” is returned with the content of the caption in WebVTT format. Example of a success response:

WEBVTT

00:09.000 --> 00:11.000
We are in New York City
Copy to clipboard

Error responses

Possible error responses:

HTTP RESPONSE CODE	ERROR VALUE	ERROR CONDITIONS
401 Unauthorized	`unauthorized`	The provided access token is missing, revoked, expired or malformed
403 Forbidden	`lack_of_ownership`	The API user is not allowed to manage the given channel
404 Not Found	`not_found`	Video was not found
429 Too Many Requests	`too_many_requests`	Rate limit exceeded (Read more)
503 Service Unavailable		There is a temporary error on the server which makes it impossible to serve the request

Upload a caption

Upload a new set of closed captions for a video in the WebVTT format.

PUT https://api.video.ibm.com/videos/{video_id}/captions/{language}/vtt
Copy to clipboard

Parameters

Example of the request:

PUT videos/{video_id}/captions/en-00/vtt HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer xxxxxxxxxxxxxx
Content-Type: text/vtt

WEBVTT

00:09.000 --> 00:11.000
We are in New York City
Copy to clipboard

The token in the request above is only an example.

Success response

Upon success a response with HTTP status “200 OK” is returned with the content of the captions in the WebVTT format. Example of a success response:

WEBVTT

00:09.000 --> 00:11.000
We are in New York City
Copy to clipboard

Error responses

Possible error responses:

HTTP RESPONSE CODE	ERROR VALUE	ERROR CONDITIONS
404 Bad Request	`not_valid_vtt`	The caption has errors
401 Unauthorized	`unauthorized`	The provided access token is missing, revoked, expired or malformed
403 Forbidden	`lack_of_ownership`	The API user is not allowed to manage the given channel
404 Not Found	`not_found`	Video was not found
429 Too Many Requests	`too_many_requests`	Rate limit exceeded (Read more)
503 Service Unavailable		There is a temporary error on the server which makes it impossible to serve the request

List possible languages

Returns all possible languages for closed captions with their codes.

GET https://api.video.ibm.com/caption-languages.json
Copy to clipboard

Parameters

This request has no parameters.

Success response

Upon success a response with HTTP status “200 OK” is returned with an array under a languages key. The elements of the array contain the following key-value pairs for each language:

KEY	TYPE	DESCRIPTION
`code`	string	Unique code of the language
`name`	string	Name of the language

Example of a success response:

{
  "languages": [
    {
      "code": "en-00",
      "name": "English"
    },
    {
      "code": "en-US",
      "name": "English (US)"
Copy to clipboard

Error responses

Possible error responses:

HTTP RESPONSE CODE	ERROR VALUE	ERROR CONDITIONS
401 Unauthorized	`unauthorized`	The provided access token is missing, revoked, expired or malformed
429 Too Many Requests	`too_many_requests`	Rate limit exceeded (Read more)
503 Service Unavailable		There is a temporary error on the server which makes it impossible to serve the request

Edit this page on GitHub

Video management: Manage video chapters

Video management: Manage audio tracks

Manage video captions

Parameters

Success response

Error responses

Get caption details

Parameters

Success response

Error responses

Modify caption settings

Parameters

Success response

Error responses

Download VTT file

Parameters

Success response

Error responses

Upload a caption

Parameters

Success response

Error responses

List possible languages

Parameters

Success response

Error responses