> ## Documentation Index > Fetch the complete documentation index at: https://gcore.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Add subtitle > 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) ## OpenAPI ````yaml /api-reference/services_documented/streaming_api.yaml post /streaming/videos/{video_id}/subtitles openapi: 3.1.0 info: title: Gcore OpenAPI – Streaming API description: >- This OpenAPI is an aggregated OpenAPI specification that unifies all Gcore products into a single file. It covers Cloud, CDN, DNS, WAAP, DDoS Protection, Object Storage, Streaming, and FastEdge services. version: '2026-05-15T06:37:28.230198+00:00' servers: - url: https://api.gcore.com security: - APIKey: [] tags: - name: AI x-displayName: AI - name: Broadcasts x-displayName: Broadcasts - name: Directories x-displayName: Directories - name: Overlays x-displayName: Overlays - name: Players x-displayName: Players - name: Playlists x-displayName: Playlists - name: QualitySets x-displayName: QualitySets - name: Restreams x-displayName: Restreams - name: Streaming Statistics x-displayName: Statistics - name: Streams x-displayName: Streams - name: Subtitles x-displayName: Subtitles - name: Videos x-displayName: Videos paths: /streaming/videos/{video_id}/subtitles: post: tags: - Subtitles summary: Add subtitle description: >- 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) operationId: post_api_videos_video_id_subtitles parameters: - name: video_id in: path description: ID of a video required: true schema: type: integer requestBody: content: application/json: schema: $ref: '#/components/schemas/subtitleCreate' required: true responses: '200': description: Successful content: application/json: schema: $ref: '#/components/schemas/subtitle' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/notfound' '422': description: One or more parameters were specified incorrectly, check the request content: application/json: schema: $ref: '#/components/schemas/subtitleerror422' x-codeSamples: - lang: Python source: |- import os from gcore import Gcore client = Gcore( api_key=os.environ.get("GCORE_API_KEY"), # This is the default and can be omitted ) subtitle = client.streaming.videos.subtitles.create( video_id=0, body={}, ) print(subtitle) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/G-Core/gcore-go\"\n\t\"github.com/G-Core/gcore-go/option\"\n\t\"github.com/G-Core/gcore-go/streaming\"\n)\n\nfunc main() {\n\tclient := gcore.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tsubtitle, err := client.Streaming.Videos.Subtitles.New(\n\t\tcontext.TODO(),\n\t\t0,\n\t\tstreaming.VideoSubtitleNewParams{\n\t\t\tBody: streaming.VideoSubtitleNewParamsBody{\n\t\t\t\tSubtitleBaseParam: streaming.SubtitleBaseParam{},\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", subtitle)\n}\n" components: schemas: subtitleCreate: allOf: - $ref: '#/components/schemas/subtitleBase' - required: - language - properties: auto_transcribe_audio_language: type: string description: >- 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``` enum: - auto - default: null auto_translate_subtitles_language: type: string description: >- 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. enum: - default - default: null name: description: >- 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)". vtt: description: >- 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. example: name: German (AI-generated) language: ger vtt: >- WEBVTT 1 00:00:07.154 --> 00:00:12.736 Wir haben 100 Millionen registrierte Benutzer oder aktive Benutzer, die mindestens einmal pro Woche spielen. 2 00:00:13.236 --> 00:00:20.198 Wir haben vielleicht 80 oder 100.000, die auf einem bestimmten Cluster spielen. subtitle: allOf: - $ref: '#/components/schemas/subtitleBase' - properties: id: type: integer description: ID of subtitle file example: id: 1000 name: German (AI-generated) language: ger vtt: >- WEBVTT 1 00:00:07.154 --> 00:00:12.736 Wir haben 100 Millionen registrierte Benutzer oder aktive Benutzer, die mindestens einmal pro Woche spielen. 2 00:00:13.236 --> 00:00:20.198 Wir haben vielleicht 80 oder 100.000, die auf einem bestimmten Cluster spielen. notfound: allOf: - $ref: '#/components/schemas/badrequest' - example: status: 404 error: >- Not Found. Entity you are looking for was not found, please check the initial parameters subtitleerror422: allOf: - $ref: '#/components/schemas/badrequest' - example: status: 422 error: Unprocessable Entity. Language code is not recognized. subtitleBase: type: object properties: name: type: string description: Name of subtitle file language: type: string description: 3-letter language code according to ISO-639-2 (bibliographic code) vtt: type: string description: >- Full text of subtitles/captions, with escaped "\n" ("\r") symbol of new line example: null badrequest: type: object properties: status: type: integer description: Error number error: type: string description: Error message example: status: 400 error: >- Bad Request response status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (for example, malformed request syntax, invalid request message framing, or deceptive request routing). securitySchemes: APIKey: description: >- API key for authentication. Make sure to include the word `apikey`, followed by a single space and then your token. Example: `apikey 1234$abcdef` type: apiKey in: header name: Authorization ````