About cookies on this site Our websites require some cookies to function properly (required). In addition, other cookies may be used with your consent to analyze site usage, improve the user experience and for advertising. For more information, please review your options. By visiting our website, you agree to our processing of information as described in IBM’sprivacy statement. To provide a smooth navigation, your cookie preferences will be shared across the IBM web domains listed here.
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:
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"},
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
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"}}
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
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"}}
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
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:
WEBVTT00:09.000 --> 00:11.000We are in New York City
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
Parameters
Example of the request:
PUT videos/{video_id}/captions/en-00/vtt HTTP/1.1Host: api.video.ibm.comAuthorization: Bearer xxxxxxxxxxxxxxContent-Type: text/vttWEBVTT00:09.000 --> 00:11.000We 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:
WEBVTT00:09.000 --> 00:11.000We are in New York City
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
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)"
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 |