Create Subtitle
Creates a task to generate subtitle-ready segments from a media URL, in the source language and any number of target languages. Send a JSON body with a publicly accessible or signed media URL.
Generating Subtitles Across Languages
Our subtitle service turns spoken media into cue-ready text. It transcribes the source language, translates into any target languages you request, and, when you ask for it, segments every language into cues sized for on-screen display. This endpoint initiates a subtitle task from a media URL and returns a unique identifier that allows you to track and retrieve your results.Understanding Subtitle Generation
Subtitle generation builds on the same speech recognition and translation technology behind our Transcription and Translation services, chained together for you in a single request:- Analyzes the media to identify speech segments in the source language
- Translates the recognized speech into each requested target language
- When
formatting_optionsis provided, segments every language’s text into cues that respect subtitle timing and length limits
Language Selection
Subtitle generation needssource_language and a non-empty target_languages array in the JSON body:
source_language: the language spoken in your media. Locale tag (e.g.en-us) or numeric ID.target_languages: one or more output languages. Pass a single-item array when you only need one language (for example["es-es"]), the same pattern as end-to-end dubbing.
target_languages if you also want same-language, subtitle-ready cues for the original speech.
Supported Media Formats
Provide a publicly accessible or signedmedia_url. For optimal results, we recommend using high-quality media with clear speech and minimal background noise. Our service accepts the following media formats:
- MP3 (
.mp3) - WAV (
.wav) - AAC (
.aac) - FLAC (
.flac) - MP4 (
.mp4) - MOV (
.mov) - MXF (
.mxf)
Transcription Mode
The optionaltranscription_mode field controls the transcription pass used for the source media:
fast(default): returns a result more quickly while maintaining quality.slow: takes longer and may produce a more accurate transcript through a more thorough pass.
fast.
Subtitle Formatting
By default, subtitle generation translates the source speech into each target language but leaves the text unsegmented, the same speech-boundary segments you’d get from Translation, not subtitle-length cues. To get cues sized for on-screen subtitles, pass the optionalformatting_options object in the JSON body. When provided, subtitle segmentation runs for every requested language:
max_segment_duration_in_seconds(default:7.0): the longest a single cue may stay on screen.min_segment_duration_in_seconds(default:1.0): the shortest a single cue may stay on screen.max_characters_in_segment(default:42): the maximum number of characters allowed in one cue.
formatting_options if you just need translated dialogue without subtitle timing rules.
Request Example
Create a subtitle task by sending a JSON body with a media URL. Here’s how to request subtitles in multiple target languages using Python with therequests library:
project_name, project_description, and folder_id.
Next Steps: Monitoring Your Subtitle Task
After submitting your subtitle request, you’ll want to monitor its progress and retrieve the results once processing completes:- Use the
/sub/{task-id}endpoint to check your task’s status - Poll the status endpoint at reasonable intervals (we recommend 5-15 second intervals for most cases)
- Once the status shows as
SUCCESS, retrieve your subtitles from/sub-result/{run_id}(every language; optionalformat_type/data_typeexport) or/sub-result/{run_id}/{language}for one language
formatting_options field for subtitle-ready cues.Authorizations
The x-api-key is a custom header required for authenticating requests to our API. Include this header in your request with the appropriate API key value to securely access our endpoints. You can find your API key(s) in the 'API' section of our studio website.
Body
Public or signed URL to the media file for subtitle generation. Supports both video and audio files.
""
The language spoken in the source media. Pass a locale tag (en-us, fr-fr, es-es). Numeric language IDs still work but are deprecated. See all source languages.
"en-us"
One or more target languages for the subtitles. Pass locale tags (es-es, fr-fr, de-de), including a single-item array when you only need one language. Numeric language IDs still work but are deprecated. See all target languages.
1Transcription mode. fast (default) is quicker; slow takes longer and may produce a more accurate transcript.
fast, slow Optional subtitle formatting rules as a JSON object. When provided, subtitle segmentation runs for every target language. Omit to skip segmentation.
Enter a distinctive name for your project that reflects its purpose or content. This name will be displayed in your CAMB.AI workspace dashboard and used to organize related assets, transcriptions, etc.. . Choose something memorable that helps you quickly identify this specific project among your other voice, audio and localization tasks.
3 - 255null
Provide details about your project's goals and specifications. Include information such as the target languages for translation or dubbing, desired voice characteristics, emotional tones to capture, or specific audio processing requirements, outlining the workflow here can serve as valuable documentation for organizational purposes.
3 - 5000null
Optional folder ID to place the run in your workspace.
null
Response
Successful Response
A JSON that contains the unique identifier for the task. This is used to query the status of the subtitle task that is running. It is returned when a create request is made to generate subtitles.