Cloudflare Docs
Stream
Visit Stream on GitHub
Set theme to dark (⇧+D)

Add captions

Adding captions and subtitles to your video library.

​​ Add or modify a caption

To create or modify a caption on a video a Cloudflare API Token is required.

The <LANGUAGE_TAG> must adhere to the BCP 47 format. For convenience, the most common language codes are provided at the bottom of this document. If the language you are adding isn’t included in the table, you can find the value through the The IANA registry, which maintains a list of language codes. To find the value to send, search for the language. Below is an example value from IANA when we look for the value to send for a Turkish subtitle:

%%
Type: language
Subtag: tr
Description: Turkish
Added: 2005-10-16
Suppress-Script: Latn
%%

The Subtag code indicates a value of tr. This is the value you should send as the language at the end of the PUT request shown above.

A label is generated from the provided language. The label will be visible for user selection in the player. For example, if sent tr, the label Türkçe will be created; if sent de, the label Deutsch will be created.

curl -X PUT \
-H 'Authorization: Bearer <API_TOKEN>' \
-F file=@/Users/mickie/Desktop/example_caption.vtt \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>

​​ Example Response to Add or Modify a Caption

{
"result": {
"language": "en",
"label": "English"
},
"success": true,
"errors": [],
"messages": []
}

​​ List the captions associated with a video

To view captions associated with a video:

curl -H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions

​​ Example response to get the captions associated with a video

{
"result": [
{
"language": "en",
"label": "English"
},
{
"language": "de",
"label": "Deutsch"
}
],
"success": true,
"errors": [],
"messages": []
}

​​ Directly access captions

To directly access the captions for your video, use the following URI and add in your video’s UID and language tag:

https://customer-{CODE}.cloudflarestream.com/<VIDEO_UID>/caption/<LANGUAGE_TAG>

​​ Delete the captions

To remove a caption associated with your video:

curl -X DELETE \
-H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>

If there is an entry in errors response field, the caption has not been deleted.

​​ Example response to delete the caption

{
"result": "",
"success": true,
"errors": [],
"messages": []
}

​​ Limitations

​​ Most common language codes

Language CodeLanguage
zhMandarin Chinese
hiHindi
esSpanish
enEnglish
arArabic
ptPortuguese
bnBengali
ruRussian
jaJapanese
deGerman
paPanjabi
jvJavanese
koKorean
viVietnamese
frFrench
urUrdu
itItalian
trTurkish
faPersian
plPolish
ukUkrainian
myBurmese
thThai