> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camb.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
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](get-source-languages) and [target languages](get-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.
```bash [expandable] theme={null}
curl -X POST "https://client.camb.ai/apis/sub" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_language": "en-us",
"media_url": "https://example.com/interview.mp4",
"target_languages": ["es-es", "fr-fr"],
"transcription_mode": "fast",
"formatting_options": {
"max_segment_duration_in_seconds": 7,
"min_segment_duration_in_seconds": 1,
"max_characters_in_segment": 42
}
}'
```
## 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:
```python [expandable] theme={null}
import json
import requests
def create_subtitle_task(
api_key,
media_url,
source_language="en-us",
target_languages=None,
formatting_options=None,
):
"""
Initiates a subtitle task from a media URL.
Args:
api_key (str): API authentication key
media_url (str): Public or signed URL of the media resource
source_language (str): Locale tag like "en-us"; numeric IDs still work but are deprecated
target_languages (list[str]): Locale tags for one or more target languages
formatting_options (dict, optional): Subtitle segmentation rules, e.g.
{"max_segment_duration_in_seconds": 7, "min_segment_duration_in_seconds": 1, "max_characters_in_segment": 42}
Returns:
dict: Response containing task_id for status tracking
"""
url = "https://client.camb.ai/apis/sub"
headers = {
"x-api-key": api_key,
"Content-Type": "application/json",
}
payload = {
"source_language": source_language,
"media_url": media_url,
"target_languages": target_languages or [],
"transcription_mode": "fast",
}
if formatting_options:
payload["formatting_options"] = formatting_options
response = requests.post(url, headers=headers, data=json.dumps(payload))
if response.ok:
return response.json()
print(f"Error {response.status_code}: {response.text}")
return None
# Request subtitles in Spanish and French, with subtitle-ready cues
result = create_subtitle_task(
api_key="your_api_key",
source_language="en-us",
target_languages=["es-es", "fr-fr"],
media_url="https://storage.example.com/interview.mp3",
formatting_options={
"max_segment_duration_in_seconds": 7,
"min_segment_duration_in_seconds": 1,
"max_characters_in_segment": 42,
},
)
```
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}`](poll-subtitle-result) 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}`](get-subtitle-run-result) (every language; optional `format_type`/`data_type` export) or [`/sub-result/{run_id}/{language}`](get-subtitle-result-for-language) for one language
Need a plain transcript in a single language instead of translated, multi-language subtitles? Use [Create Transcription](create-transcription). It shares the same `formatting_options` field for subtitle-ready cues.
## OpenAPI
````yaml post /sub
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://client.camb.ai/apis
security: []
paths:
/sub:
post:
tags:
- Apis
summary: Create Subtitle
operationId: create_subtitle_sub_post
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSubtitleRequestPayload'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TaskID'
description: >-
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.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
CreateSubtitleRequestPayload:
allOf:
- type: object
required:
- media_url
- source_language
- target_languages
properties:
media_url:
type: string
title: Media URL
description: >-
Public or signed URL to the media file for subtitle generation.
Supports both video and audio files.
example: ''
source_language:
$ref: '#/components/schemas/LanguageInput'
description: >-
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](/api-reference/endpoint/get-source-languages).
example: en-us
target_languages:
type: array
minItems: 1
title: Target Languages
description: >-
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](/api-reference/endpoint/get-target-languages).
example:
- es-es
items:
$ref: '#/components/schemas/LanguageInput'
transcription_mode:
type: string
enum:
- fast
- slow
title: Transcription Mode
description: >-
Transcription mode. `fast` (default) is quicker; `slow` takes
longer and may produce a more accurate transcript.
default: fast
formatting_options:
allOf:
- $ref: '#/components/schemas/SubtitleFormattingOptions'
nullable: true
description: >-
Optional subtitle formatting rules as a JSON object. When
provided, subtitle segmentation runs for every target language.
Omit to skip segmentation.
- $ref: '#/components/schemas/CreateTaskWithNameAndDescription'
- type: object
properties:
folder_id:
type: integer
title: Folder Id
nullable: true
exclusiveMinimum: 0
description: Optional folder ID to place the run in your workspace.
example: null
title: CreateSubtitleRequestPayload
TaskID:
properties:
task_id:
type: string
title: Task ID
type: object
title: Task ID
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
LanguageInput:
type: string
title: Language
SubtitleFormattingOptions:
type: object
title: SubtitleFormattingOptions
description: >-
Optional subtitle formatting rules. When provided, translate+subtitle
segmentation runs for each target language.
properties:
max_segment_duration_in_seconds:
type: number
title: Max Segment Duration In Seconds
description: The longest a single cue may stay on screen.
default: 7
exclusiveMinimum: 0
example: 7
min_segment_duration_in_seconds:
type: number
title: Min Segment Duration In Seconds
description: The shortest a single cue may stay on screen.
default: 1
exclusiveMinimum: 0
example: 1
max_characters_in_segment:
type: integer
title: Max Characters In Segment
description: The maximum number of characters allowed in one cue.
default: 42
exclusiveMinimum: 0
example: 42
additionalProperties: false
example:
max_segment_duration_in_seconds: 7
min_segment_duration_in_seconds: 1
max_characters_in_segment: 42
CreateTaskWithNameAndDescription:
properties:
project_name:
type: string
title: Project Name
description: >-
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.
minLength: 3
maxLength: 255
nullable: true
example: null
project_description:
type: string
title: Project Description
description: >-
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.
minLength: 3
maxLength: 5000
nullable: true
example: null
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: x-api-key
description: >-
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.
````