Adding captions
Captions allow hearing impaired users to read the words being said in your video. It also improves watch times, and can improve your SEO.
To add captions to your video, you'll need a VTT file for a video already uploaded to api.video.
Find all details to display your captions in our docs
Authenticate your session
You will need your API key to obtain the access_token. You can find your API key in your dashboard.
First, call the authentication endpoint and get your access token.
Example - Curl Request
curl -X POST \
https://sandbox.api.video/auth/api-key \
-H 'Content-Type: application/json' \
-d '{"apiKey": "your_api_key"}'
Example - Http Request
POST /auth/api-key HTTP/1.1
Host: sandbox.api.video
Content-Type: application/json
{
"apiKey": "your_api_key"
}
Example - Json Response
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImFiYjcxNmNiY2ZiNmY4MDc2OWEzZmQ1MjlhMjZiZWRkY2EwMzhlYzA3NDk5M2ZiMTA0YjhiZGMwOTI5MzgxN2M3NmNkNzI4ZDIzOGMzZmNlIn0.eyJhdWQiOiJsaWJjYXN0IiwianRpIjoiYWJiNzE2Y2JjZmI2ZjgwNzY5YTNmZDUyOWEyNmJlZGRjYTAzOGVjMDc0OTkzZmIxMDRiOGJkYzA5MjkzODE3Yzc2Y2Q3MjhkMjM4YzNmY2UiLCJpYXQiOjE1MjY1NDgzMDEsIm5iZiI6MTUyNjU0ODMwMSwiZXhwIjoxNTI2NTUxOTAxLCJzdWIiOiJ1c01vbml0b3IiLCJzY29wZXMiOlsibW9uaXRvci5saWJjYXN0LmNvbSJdLCJjb250ZXh0Ijp7InVzZXIiOiJ1c01vbml0b3IiLCJwcm9qZWN0IjoicHJNb25pdG9yIiwibWVtYmVyIjoibWVNb25pdG9yIn19.jWHC18iEur69FzD5dm78wAwNzh2cPKTRvKuspyQNQKPvhEbYa2v4XhqVNh0TTw8JeNxBtcePBTMHl4S9nWsw7pW4KD8zbqzUjCZNYlaYDpu8vu_tmWVO2JccglJIjuQEaiTbkUsfLdgtsb_9DJ3frk1-WgAKuzu0HewhcGb80xivdJPqNYA6I1Ig8GOief9LTUNNJoqqZn1A1-UiGRTXDag7_yODuxzpMFaAzbaisfK0gYti-PnjyHGWhpGwRplMKPPJk6rSAp1d9TWWXVgg-bNqUzz4_sr33ICJTx7_qZzfamMqk5PDZbHOwpIj8L2DBfo3isvt6QliWmgFEOuvog",
"refresh_token": "def502001d5c8aeb3f921c833f0c90fbbb9ef2be1f25e476d7acf999010c435c043bf382f462bd48e82c9253ee0bcad1dd07c07b827552ef540b1429e032acdb78325d17401d54a4baf421e41eaed4b545938f3539428ea52297cb8760269b95284da8c89c55d72c9584ced47510976a9f3106a034173dd3e39c3bf4f7119c4722fda4f70c15241a392be79ba5a1ff9e4f3edfa204c22ad9f9776258fb511137e6e0f40a917866158bc13c7536243146bb35b5f6edf59f6d2d346721fcbc22810364fdb4236949db605e4eb1de1578af97866e850fe535b1febb21ab52dfc0dfe91719d5c81c477ba4c979c993e404d6ed3e51d549a239cc486c17e5e3f414ad66fa71e1a16eba2124eaaba97fc9c8729109b8294c8a440e0cd78f8c9b0006c15a8e32e19eb364f9d644a3510735301ff525aa856728791b240523f8a85d2a57754c221e49de80b690a5908f3d599b43aec5164bab7dd4dce10b5f336140d32315ba64ee4cf3b68e9babea65f493db6cfb28f53c5e2dcaf440f4509c39bfda2076c6e9b8efcb"
}
Add the caption to your video
curl https://ws.api.video/videos/{videoId}/captions/{lang}
-H ‘Authorization: Bearer {access_token}’
-F file=@/path/to/caption.vtt
replace {videoId} with the videoId of the video to receive captions; {lang} with the language of the video (ex: en-US for US english); and {access_token} with your access token.
JSON response
{ “uri”:”/videos/vi5UNyaStzuuj0xTAGp7qtjf/captions/en”,
”src”:”https://cdn.api.video/vod/vi5UNyaStzuuj0xTAGp7qtjf/captions/en.vtt",
"srclang":"en",
"default":false
}
Make captions default
The JSON response above shows that by default, captions are off. To add them, send a PATCH update command:
curl -X PATCH https://ws.api.video/videos/{videoId}}/captions/{lang}}
-H ‘Authorization: Bearer {access_token}’
-d ‘{“default”: true}’
Conclusion
Captions make it easier to watch a video. Not just for hearing impaired users, but for autoplaying videos that begin muted. You users can just read what is happening without sound, and then, if they are interested can un-mute the video. You can also add internationalization by translating the captions to additional languages.
Let us know how you are using captions in our developer community. Happy building!