Skip to main contentIBM Video Streaming Developers

Manage video captions

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

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:

KEYTYPEDESCRIPTION
is_defaultbooleanIf value is true, the video player automatically displays this caption. A video can only have one default caption.
is_visiblebooleanIf value is true, this caption is available in the video player.
languagestringThe language of the caption
statusstringPossible values: processing, active
video_idstringUnique ID of the video

Example of a success response:

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

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundVideo was not found
429 Too Many Requeststoo_many_requestsRate limit exceeded (Read more)
503 Service UnavailableThere 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

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.

KEYTYPEDESCRIPTION
is_defaultbooleanIf value is true, the video player automatically displays this caption. A video can only have one default caption.
is_visiblebooleanIf value is true, this caption is available in the video player.
languagestringThe language of the caption
statusstringPossible values: processing, active
video_idstringUnique ID of the video

Example of a success response:

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

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 UnauthorizedunauthorizedThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundVideo was not found
429 Too Many Requeststoo_many_requestsRate limit exceeded (Read more)
503 Service UnavailableThere 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

Parameters

The parameters for the PUT request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
is_visiblebooleanREQUIREDSet this value to true to make this caption available in the video player.
is_defaultbooleanREQUIREDSet 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.

KEYTYPEDESCRIPTION
is_defaultbooleanIf value is true, the video player automatically displays this caption. A video can only have one default caption.
is_visiblebooleanIf value is true, this caption is available in the video player.
languagestringThe language of the caption
statusstringPossible values: processing, active
video_idstringUnique ID of the video

Example of a success response:

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

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 UnauthorizedunauthorizedThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundVideo was not found
429 Too Many Requeststoo_many_requestsRate limit exceeded (Read more)
503 Service UnavailableThere 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

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

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 UnauthorizedunauthorizedThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundVideo was not found
429 Too Many Requeststoo_many_requestsRate limit exceeded (Read more)
503 Service UnavailableThere 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

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

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

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
404 Bad Requestnot_valid_vttThe caption has errors
401 UnauthorizedunauthorizedThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundVideo was not found
429 Too Many Requeststoo_many_requestsRate limit exceeded (Read more)
503 Service UnavailableThere 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

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:

KEYTYPEDESCRIPTION
codestringUnique code of the language
namestringName of the language

Example of a success response:

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

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 UnauthorizedunauthorizedThe provided access token is missing, revoked, expired or malformed
429 Too Many Requeststoo_many_requestsRate limit exceeded (Read more)
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request