--- title: "Add subtitle" method: POST path: "/streaming/videos/{video_id}/subtitles" tags: ["Subtitles"] --- # Add subtitle `POST /streaming/videos/{video_id}/subtitles` Add new subtitle/captions to a video entity. **Add already exist subtitles** Subtitles must be in one of the following formats: - SRT – SubRip Text is described on [wikipedia.org](https://en.wikipedia.org/wiki/SubRip#SubRip_file_format). Must start from integer for sequence number. Use calidators to check the subtitles, like [srt-validator](https://taoning2014.github.io/srt-validator-website/index.html). - WebVTT – Web Video Text Tracks Format is described on [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API). Must start from "WEBVTT" header. Use validators to check the subtitles, like [W3C](https://w3c.github.io/webvtt.js/parser.html). Language is 3-letter language code according to ISO-639-2 (bibliographic code). Specify language you need, or just look at our list in the attribute "audio_language" of section ["AI Speech Recognition"](/docs/api-reference/streaming/ai/create-ai-asr-task). You can add multiple subtitles in the same language, language uniqueness is not required. Size must be up to 5Mb. The update time for added or changed subtitles is up to 30 seconds. Just like videos, subtitles are cached, so it takes time to update the data. **AI subtitles and transcribing** It is also possible to automatically create subtitles based on AI. Read more: - What is ["AI Speech Recognition"](/docs/api-reference/streaming/ai/create-ai-asr-task). - If the option is enabled via ```auto_transcribe_audio_language: auto|```, then immediately after successful transcoding, an AI task will be automatically created for transcription. - If you need to translate subtitles from original language to any other, then AI-task of subtitles translation can be applied. Use ```auto_translate_subtitles_language: default|``` parameter for that. Also you can point several languages to translate to, then a separate subtitle will be generated for each specified language. The created AI-task(s) will be automatically executed, and result will also be automatically attached to this video as subtitle(s). If AI is disabled in your account, you will receive code 422 in response. **Where and how subtitles are displayed?** Subtitles are became available in the API response and in playback manifests. All added subtitles are automatically inserted into the output manifest .m3u8. This way, subtitles become available to any player: our player, OS built-in, or other specialized ones. You don't need to do anything else. Read more information in the Knowledge Base. Example: ``` #EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",NAME="English",LANGUAGE="en",AUTOSELECT=YES,URI="subs-0.m3u8" ``` ![Auto generated subtitles example](https://demo-files.gvideo.io/apidocs/captions.gif) ## Path parameters - `video_id` integer, required ## Request body - SubtitleCreate - `name` string — Name of the subtitle. If AI is used for creating subtitles and name field is not set, then name will be taken by pattern: "{language} (AI-generated)". - `language` string, required — 3-letter language code according to ISO-639-2 (bibliographic code) - `vtt` string — Full text of subtitles/captions, with escaped "\n" ("\r") symbol of new line. If AI is used for creating subtitles, then this field must not be set. - `auto_transcribe_audio_language` 'auto' | '' — Automatic creation of subtitles by transcribing the audio track. When using this option, you do not need to attach subtitle text in ```vtt``` field. The audio track will be transcribed and the subtitle will be created automatically. Values: - auto – AI will determine language automatically. - \ – Explicit indication of the language spoken in the audio. Option is used for clarification ifAI cannot determine the language automatically. Look at list of available languages in description of AI ASR task creation. Example: ```auto_transcribe_audio_language: ger``` - `auto_translate_subtitles_language` 'default' | '' — Automatic translation of auto-transcribed subtitles to the specified language(s). Can be used both together with ```auto_transcribe_audio_language``` option only. Use it when you want to make automatic subtitles in languages other than the original language in audio. Values: - default – There are 3 default languages: eng,fre,ger - \ – Explicit language to translate to, or list of languages separated by a comma. Look at list of available languages in description of AI ASR task creation. If several languages are specified for translation, a separate subtitle will be generated for each language. Example: ```auto_translate_subtitles_language: eng,fre,ger``` Please note that subtitle translation is done separately and after transcription. Thus separate AI-tasks are created for translation. ## Response `200` Successful - Subtitle - `name` string — Name of subtitle file - `language` string — 3-letter language code according to ISO-639-2 (bibliographic code) - `vtt` string — Full text of subtitles/captions, with escaped "\n" ("\r") symbol of new line - `id` integer — ID of subtitle file ## Other responses - `404` — Not found - `422` — One or more parameters were specified incorrectly, check the request --- [API](https://skmtc.dev/g-core/apis/gcore-openapi.md) · [All operations](https://skmtc.dev/g-core/apis/gcore-openapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/g-core/gcore-openapi/revisions/09e652815095/schema)