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. Must start from integer for sequence number. Use calidators to check the subtitles, like srt-validator.
• WebVTT – Web Video Text Tracks Format is described on developer.mozilla.org. Must start from “WEBVTT” header. Use validators to check the subtitles, like W3C.

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”.

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”.
• If the option is enabled via auto_transcribe_audio_language: auto|<language_code>, 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|<language_codes,> 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" 

POST /streaming/videos/{video_id}/subtitles

Python

Python

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)

200

{
  "id": 1000,
  "name": "German (AI-generated)",
  "language": "ger",
  "vtt": "WEBVTT\n\n1\n00:00:07.154 --> 00:00:12.736\nWir haben 100 Millionen registrierte Benutzer oder aktive Benutzer, die mindestens einmal pro Woche spielen.\n\n2\n00:00:13.236 --> 00:00:20.198\nWir haben vielleicht 80 oder 100.000, die auf einem bestimmten Cluster spielen."
}

Authorizations

Authorization · string · header · required

API key for authentication. Make sure to include the word apikey, followed by a single space and then your token. Example: apikey 1234$abcdef

Path Parameters

video_id · integer · required

ID of a video

Body

application/json

language · string · required

3-letter language code according to ISO-639-2 (bibliographic code)

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)".

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 · enum<string>

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

Available options: auto, <language_code>

auto_translate_subtitles_language · enum<string>

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.

Available options: default, <language_code,>

Response

200

application/json

Successful

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