Add captions
Adding captions and subtitles to your video library.
There are two ways to add captions to a video: generating via AI or uploading a caption file.
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: languageSubtag: trDescription: TurkishAdded: 2005-10-16Suppress-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 HTTP request.
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.
Generated captions use artificial intelligence based speech-to-text technology to generate closed captions for your videos.
A video must be uploaded and in a ready state before captions can be generated. In the following example URLs, the video’s UID is referenced as <VIDEO_UID>. To receive webhooks when a video transitions to ready after upload, follow the instructions provided here.
Only English language caption generation is currently supported.
Videos may include several language captions, but each language must be unique. For example, a video may have English, French, and German captions associated with it, but it cannot have two English captions. If you have already uploaded an English language caption for a video, you must first delete it in order to create an English generated caption. Instructions on how to delete a caption can be found below.
The <LANGUAGE_TAG> must adhere to the BCP 47 format. The tag for English is en.
You may specify a region in the tag, such as en-GB, which will render a label
that shows British English for the caption.
curl -X POST \-H 'Authorization: Bearer <API_TOKEN>' \https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>/generateExample response:
{ "result": { "language": "en", "label": "English (auto-generated)", "generated": true, "status": "inprogress" }, "success": true, "errors": [], "messages": []}The result will provide a status denoting the progress of the caption generation.
There are three statuses: inprogress, ready, and error. Note that
(auto-generated) is applied to the label.
Once the generated caption is ready, it will automatically appear in the video player and video manifest.
If the caption enters an error state, you may attempt to re-generate it by first deleting it and then using the endpoint listed above. Instructions on deletion are provided below.
Note two changes if you edit a generated caption: the generated field will
change to false and the (auto-generated) portion of the label will be removed.
To create or replace a caption file:
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>{ "result": { "language": "en", "label": "English", "generated": false, "status": "ready" }, "success": true, "errors": [], "messages": []}To view captions associated with a video.
Note this results list will also include generated captions that are inprogress
and error status:
curl -H 'Authorization: Bearer <API_TOKEN>' \https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions{ "result": [ { "language": "en", "label": "English (auto-generated)", "generated": true, "status": "inprogress" }, { "language": "de", "label": "Deutsch", "generated": false, "status": "ready" } ], "success": true, "errors": [], "messages": []}To view the WebVTT caption file, you may make a GET request:
curl \-H 'Authorization: Bearer <API_TOKEN>' \https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>/vttWEBVTT
100:00:00.000 --> 00:00:01.560This is an example of
200:00:01.560 --> 00:00:03.880a WebVTT caption response.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.
{ "result": "", "success": true, "errors": [], "messages": []}- A video must be uploaded before a caption can be attached to it. In the following
example URLs, the video's ID is referenced as
media_id. - Stream only supports WebVTT ↗ formatted caption files. If you have a differently formatted caption file, use a tool to convert your file to WebVTT ↗ prior to uploading it.
- Videos may include several language captions, but each language must be unique. For example, a video may have English, French, and German captions associated with it, but it cannot have two French captions.
- Each caption file is limited to 10 MB in size. Contact support if you need to upload a larger file.
| Language Code | Language |
|---|---|
| zh | Mandarin Chinese |
| hi | Hindi |
| es | Spanish |
| en | English |
| ar | Arabic |
| pt | Portuguese |
| bn | Bengali |
| ru | Russian |
| ja | Japanese |
| de | German |
| pa | Panjabi |
| jv | Javanese |
| ko | Korean |
| vi | Vietnamese |
| fr | French |
| ur | Urdu |
| it | Italian |
| tr | Turkish |
| fa | Persian |
| pl | Polish |
| uk | Ukrainian |
| my | Burmese |
| th | Thai |