openapi: 3.0.3
info:
title: Camb.AI API
description: >-
The Camb.AI API provides generative voice AI - text-to-speech, dubbing,
translation, voice discovery and cloning, and transcription - powered by the
MARS (speech / voice) and BOLI (translation) research models. The REST API is
served from https://client.camb.ai/apis and authenticated with an x-api-key
header. Most operations are asynchronous: a POST starts a task and returns a
task_id, the task is polled with a GET until its status is SUCCESS, and the
result (audio, transcript, or translation) is then retrieved. Real-time
streaming for TTS, transcription, and speech-to-speech translation is offered
over separate public WebSocket channels (see the companion AsyncAPI document).
Endpoint paths are grounded in the public documentation at https://docs.camb.ai;
request and response schemas below are modeled from the documented parameters
and may be simplified.
version: '1.0'
contact:
name: Camb.AI
url: https://www.camb.ai
servers:
- url: https://client.camb.ai/apis
description: Camb.AI production API
security:
- apiKeyAuth: []
tags:
- name: Text-to-Speech
description: Convert text to speech with the MARS voice models.
- name: Dubbing
description: End-to-end video and audio dubbing across languages.
- name: Translation
description: Neural text translation via the BOLI model.
- name: Voices
description: Discover, clone, design, and manage voices.
- name: Transcription
description: Speech-to-text transcription with timestamps.
- name: Languages
description: Supported source and target languages.
paths:
/tts-stream:
post:
operationId: createTtsStream
tags:
- Text-to-Speech
summary: Stream text-to-speech
description: >-
Synthesize speech from text and return a binary audio stream in real time.
The response is an audio byte stream (for example audio/wav or audio/mpeg)
and includes an X-Credits-Required header indicating credit usage.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TtsStreamRequest'
responses:
'200':
description: A binary audio stream.
content:
audio/wav:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
/tts:
post:
operationId: createTts
deprecated: true
tags:
- Text-to-Speech
summary: Create a text-to-speech task (deprecated)
description: >-
Deprecated. For new integrations use POST /tts-stream. Starts an
asynchronous text-to-speech task and returns a task_id to poll.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TtsRequest'
responses:
'200':
description: Task accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreated'
'401':
$ref: '#/components/responses/Unauthorized'
/tts/{task_id}:
get:
operationId: getTtsStatus
tags:
- Text-to-Speech
summary: Poll a text-to-speech task
description: Returns the status of a TTS task and, when complete, the run_id used to fetch the audio.
parameters:
- $ref: '#/components/parameters/TaskId'
responses:
'200':
description: Current task status.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStatus'
'401':
$ref: '#/components/responses/Unauthorized'
/tts-result/{run_id}:
get:
operationId: getTtsResult
tags:
- Text-to-Speech
summary: Download text-to-speech audio
description: Retrieves the generated audio file for a completed TTS run.
parameters:
- name: run_id
in: path
required: true
description: The run identifier returned by GET /tts/{task_id}.
schema:
type: integer
responses:
'200':
description: The generated audio file.
content:
audio/wav:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
/dub:
post:
operationId: createDub
tags:
- Dubbing
summary: Create an end-to-end dubbing task
description: >-
Starts an end-to-end dubbing task for a media file, translating and
re-voicing it into one or more target languages while preserving delivery.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DubRequest'
responses:
'200':
description: Dubbing task accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreated'
'401':
$ref: '#/components/responses/Unauthorized'
/dub/{task_id}:
get:
operationId: getDubStatus
tags:
- Dubbing
summary: Poll a dubbing task
description: Returns the status and, when complete, the results of a dubbing task.
parameters:
- $ref: '#/components/parameters/TaskId'
responses:
'200':
description: Current dubbing task status and results.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStatus'
'401':
$ref: '#/components/responses/Unauthorized'
/translate:
post:
operationId: createTranslation
tags:
- Translation
summary: Create a translation task
description: >-
Translates an array of texts from a source language into a target
language using the BOLI model, with optional formality, gender, and
specialized-vocabulary controls.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationRequest'
responses:
'200':
description: Translation task accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreated'
'401':
$ref: '#/components/responses/Unauthorized'
/translate/{task_id}:
get:
operationId: getTranslationStatus
tags:
- Translation
summary: Poll a translation task
description: Returns the status and, when complete, the translated texts.
parameters:
- $ref: '#/components/parameters/TaskId'
responses:
'200':
description: Current translation task status and result.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStatus'
'401':
$ref: '#/components/responses/Unauthorized'
/transcribe:
post:
operationId: createTranscription
tags:
- Transcription
summary: Create a transcription task
description: >-
Transcribes speech to text from an uploaded media file or a media URL,
with speaker identification and word-level timestamps.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/TranscriptionRequest'
responses:
'200':
description: Transcription task accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreated'
'401':
$ref: '#/components/responses/Unauthorized'
/transcribe/{task_id}:
get:
operationId: getTranscriptionStatus
tags:
- Transcription
summary: Poll a transcription task
description: Returns the status and, when complete, the transcript.
parameters:
- $ref: '#/components/parameters/TaskId'
responses:
'200':
description: Current transcription task status and result.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStatus'
'401':
$ref: '#/components/responses/Unauthorized'
/list-voices:
get:
operationId: listVoices
tags:
- Voices
summary: List voices
description: >-
Returns all available voices - public voices, shared voices, and
custom-created voices - with metadata such as id, voice_name, gender,
age, language, and description.
responses:
'200':
description: A list of voices.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Voice'
'401':
$ref: '#/components/responses/Unauthorized'
/create-custom-voice:
post:
operationId: createCustomVoice
tags:
- Voices
summary: Create a custom (cloned) voice
description: Clones a custom voice from a reference audio sample.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CustomVoiceRequest'
responses:
'200':
description: The created custom voice.
content:
application/json:
schema:
$ref: '#/components/schemas/Voice'
'401':
$ref: '#/components/responses/Unauthorized'
/text-to-voice:
post:
operationId: createTextToVoice
tags:
- Voices
summary: Design a voice from a text description
description: Starts a task that generates candidate voices from a natural-language description.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TextToVoiceRequest'
responses:
'200':
description: Voice-design task accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreated'
'401':
$ref: '#/components/responses/Unauthorized'
/text-to-voice/{task_id}:
get:
operationId: getTextToVoiceStatus
tags:
- Voices
summary: Poll a voice-design task
description: Returns the status and, when complete, the generated voice options.
parameters:
- $ref: '#/components/parameters/TaskId'
responses:
'200':
description: Current voice-design task status and result.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStatus'
'401':
$ref: '#/components/responses/Unauthorized'
/delete-voice/{voice_id}:
delete:
operationId: deleteVoice
tags:
- Voices
summary: Delete a custom voice
description: Permanently removes a custom voice.
parameters:
- name: voice_id
in: path
required: true
description: The identifier of the custom voice to delete.
schema:
type: integer
responses:
'200':
description: Voice deleted.
'401':
$ref: '#/components/responses/Unauthorized'
/source-languages:
get:
operationId: getSourceLanguages
tags:
- Languages
summary: List source languages
description: Lists all supported source languages with identifiers and locale tags.
responses:
'200':
description: A list of source languages.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Language'
'401':
$ref: '#/components/responses/Unauthorized'
/target-languages:
get:
operationId: getTargetLanguages
tags:
- Languages
summary: List target languages
description: Lists all supported target languages with identifiers and locale tags.
responses:
'200':
description: A list of target languages.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Language'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
parameters:
TaskId:
name: task_id
in: path
required: true
description: The task identifier returned when the task was created.
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
TtsStreamRequest:
type: object
required:
- text
- language
- voice_id
properties:
text:
type: string
minLength: 3
maxLength: 3000
description: The text to synthesize into speech.
language:
type: string
description: BCP-47 locale code, for example en-us or fr-fr.
voice_id:
type: integer
description: A voice profile ID from GET /list-voices.
speech_model:
type: string
description: Model variant, for example mars-8.1-flash-beta or mars-instruct.
user_instructions:
type: string
description: Guidance for overall delivery (mars-instruct only).
enhance_named_entities_pronunciation:
type: boolean
output_configuration:
type: object
description: Output format, sample rate, and enhancement settings.
voice_settings:
type: object
description: Speaking rate, accent preservation, and reference quality.
inference_options:
type: object
description: Stability, temperature, and speaker similarity.
TtsRequest:
type: object
required:
- text
- voice_id
- language
properties:
text:
type: string
description: The text to be converted to speech.
voice_id:
type: integer
description: Voice identifier.
language:
type: string
description: Locale tag such as en-us.
gender:
type: integer
description: Speaker gender hint (0, 1, 2, or 9).
age:
type: integer
description: Speaker age characteristic.
DubRequest:
type: object
required:
- video_url
- source_language
- target_languages
properties:
video_url:
type: string
description: URL of the media file to dub.
source_language:
type: string
description: Source language locale tag, for example en-us.
target_languages:
type: array
description: Target language locale tags, for example ["es-es", "fr-fr"].
items:
type: string
TranslationRequest:
type: object
required:
- texts
- source_language
- target_language
properties:
texts:
type: array
description: An array of strings to be translated.
items:
type: string
source_language:
type: string
description: Source language locale tag.
target_language:
type: string
description: Target language locale tag.
formality:
type: string
description: Optional formality control.
gender:
type: string
description: Optional gender control.
TranscriptionRequest:
type: object
required:
- language
properties:
language:
type: string
description: Locale tag of the audio, for example en-us.
media_file:
type: string
format: binary
description: Binary audio or video file (MP3, WAV, AAC, FLAC, MP4, MOV, MXF).
media_url:
type: string
description: Media URL to transcribe (alternative to media_file).
project_name:
type: string
project_description:
type: string
CustomVoiceRequest:
type: object
required:
- voice_name
- file
properties:
voice_name:
type: string
description: Name for the new custom voice.
file:
type: string
format: binary
description: Reference audio sample to clone from.
gender:
type: integer
age:
type: integer
TextToVoiceRequest:
type: object
required:
- voice_description
properties:
voice_description:
type: string
description: Natural-language description of the desired voice.
text:
type: string
description: Optional preview text to render with the generated voices.
TaskCreated:
type: object
properties:
task_id:
type: string
description: Identifier used to poll the task.
TaskStatus:
type: object
properties:
status:
type: string
description: Task status, for example PENDING, PROCESSING, SUCCESS, or FAILED.
enum:
- PENDING
- PROCESSING
- SUCCESS
- FAILED
run_id:
type: integer
description: Present when the task has completed; used to fetch the result.
Voice:
type: object
properties:
id:
type: integer
voice_name:
type: string
gender:
type: integer
age:
type: integer
language:
type: string
description:
type: string
is_published:
type: boolean
Language:
type: object
properties:
id:
type: integer
language:
type: string
short_name:
type: string
Error:
type: object
properties:
message:
type: string
code:
type: string