Skip to main content
POST
Create Subtitle

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:
  1. Analyzes the media to identify speech segments in the source language
  2. Translates the recognized speech into each requested target language
  3. When formatting_options is provided, segments every language’s text into cues that respect subtitle timing and length limits
This lets you go from a raw recording to subtitles in several languages without orchestrating transcription, translation, and segmentation as separate calls.

Language Selection

Subtitle generation needs source_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.
Include the source language itself in target_languages if you also want same-language, subtitle-ready cues for the original speech.
For a complete list of supported languages and their locale tags, see source languages and target languages.

Supported Media Formats

Provide a publicly accessible or signed media_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)
Please note that MXF format support is exclusively available to customers on our Enterprise plan, offering professional broadcast-quality media handling for organizations with advanced needs.

Transcription Mode

The optional transcription_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.
Omit the field to use 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 optional formatting_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.
Omit 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 the requests library:
Optional body fields include 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:
  1. Use the /sub/{task-id} endpoint to check your task’s status
  2. Poll the status endpoint at reasonable intervals (we recommend 5-15 second intervals for most cases)
  3. Once the status shows as SUCCESS, retrieve your subtitles from /sub-result/{run_id} (every language; optional format_type/data_type export) or /sub-result/{run_id}/{language} for one language
Need a plain transcript in a single language instead of translated, multi-language subtitles? Use Create Transcription. It shares the same formatting_options field for subtitle-ready cues.

Authorizations

x-api-key
string
header
required

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

application/json
media_url
string
required

Public or signed URL to the media file for subtitle generation. Supports both video and audio files.

Example:

""

source_language
string
required

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.

Example:

"en-us"

target_languages
string[]
required

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.

Minimum array length: 1
Example:
transcription_mode
enum<string>
default:fast

Transcription mode. fast (default) is quicker; slow takes longer and may produce a more accurate transcript.

Available options:
fast,
slow
formatting_options
SubtitleFormattingOptions · object | null

Optional subtitle formatting rules as a JSON object. When provided, subtitle segmentation runs for every target language. Omit to skip segmentation.

Example:
project_name
string | null

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.

Required string length: 3 - 255
Example:

null

project_description
string | null

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.

Required string length: 3 - 5000
Example:

null

folder_id
integer | null

Optional folder ID to place the run in your workspace.

Example:

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.

task_id
string
Last modified on July 27, 2026