Cartesia
App · 20 actions
Cartesia non-streaming speech, voices, datasets, agents and calls.
Actions
| Action | What it does |
|---|---|
| Create agent | Create agent. |
| Create dataset | Create dataset. |
| Delete agent | Delete agent. |
| Delete dataset | Delete dataset. |
| Delete dataset file | Delete dataset file. |
| Delete voice | Delete voice. |
| Generate speech | Generate speech. |
| Get agent | Get agent. |
| Get api status | Get api status. |
| Get dataset | Get dataset. |
| Get voice | Get voice. |
| List agents | List agents. |
| List calls | List calls. |
| List dataset files | List dataset files. |
| List datasets | List datasets. |
| List models | List models. |
| List voices | List voices. |
| Localize voice | Localize voice. |
| Update dataset | Update dataset. |
| Update voice | Update voice. |
Create agent
Create agent.
Inputs
- Config
configobject - Config.
- Description
descriptiontext - Description of the agent.
- Name
nametext - Name shown for the agent. It does not need to be unique.
Outputs
dataobject- Api result.
Example output
{
"data": {
"config": {
"audio": {
"input": {
"keyterms": [],
"noise_suppression": "off"
},
"output": {
"background_sound": {
"file_id": "example",
"volume": 1.0
},
"emotion": "example",
"pronunciation_dictionary_id": "example",
"speed": 1.0,
"voice_id": "example",
"volume": 1.0
}
},
"dynamic_variable_placeholders": {},
"initial_message": "example",
"initial_message_interruptions": "allow",
"instructions": "example",
"language": {
"additional": [],
"presets": {},
"primary": "en"
},
"model": {
"fallback_strategy": {
"type": "auto"
},
"id": "example",
"max_output_tokens": 1,
"temperature": 1.0
},
"prompt_optimization": false,
"speculative_generation": false,
"system_tools": {
"end_call": {
"description": "example",
"pre_tool_speech": "auto"
},
"send_dtmf": {
"description": "example",
"pre_tool_speech": "auto"
},
"skip_turn": {
"description": "example",
"pre_tool_speech": "auto",
"wait_timeout_secs": 1
},
"transfer_to_number": {
"description": "example",
"pre_tool_speech": "auto",
"transfers": []
},
"voicemail_detection": {
"description": "example",
"message": "example",
"pre_tool_speech": "auto"
}
},
"timezone": "example",
"tools": [],
"turn": {
"inactivity_check_in_secs": 1,
"inactivity_end_call_secs": 1
}
},
"created_at": "example",
"description": "example",
"id": "example",
"name": "example",
"updated_at": "example",
"version": {
"created_at": "example",
"created_by": "example",
"description": "example",
"id": "example"
}
}
}Create dataset
Create dataset.
Inputs
- Name
nametextRequired - Name for the new dataset
- Description
descriptiontextRequired - Optional description for the dataset
Outputs
dataobject- A collection of files used for fine-tuning models
Example output
{
"data": {
"created_at": "example",
"description": "example",
"id": "example",
"name": "example"
}
}Delete agent
Delete agent.
Inputs
- Agent
agent_idtextRequired - The ID of the agent.
Outputs
dataobject- Api result.
Example output
{
"data": {}
}Delete dataset
Delete dataset.
Inputs
- Dataset
idtextRequired - ID of the dataset to delete
Outputs
dataobject- Api result.
Example output
{
"data": {}
}Delete dataset file
Delete dataset file.
Inputs
- Dataset
idtextRequired - ID of the dataset containing the file
- File
fileIDtextRequired - ID of the file to remove
Outputs
dataobject- Api result.
Example output
{
"data": {}
}Delete voice
Delete voice.
Inputs
- Voice
idtextRequired - The ID of the voice. Find one in the [Voice Library](https://play.cartesia.ai/voices) or via [List Voices](/api-reference/voices/list).
Outputs
dataobject- Api result.
Example output
{
"data": {}
}Generate speech
Generate speech.
Inputs
- Model id
model_idtextRequired - The ID of the model to use for the generation. See [Models](/build-with-cartesia/tts-models/latest) all options.One of:
sonic-3.6,sonic-3.5,sonic-3,sonic-latest. - Transcript
transcripttextRequired - Transcript.
- Language
languagetext - The transcript's language or locale (for example `en` or `en-GB`). `language` and `locale` accept the same values. Set one or the other, never both; setting both returns a 400 error. See [supported codes](/build-with-cartesia/capability-guides/advanced-capabilities#which-locales-are-supported).
- Accent
accenttext - Usually unnecessary: Cartesia picks the closest accent the voice supports for the requested `language` or `locale`. Set it only to make a [multilingual voice](/build-with-cartesia/capability-guides/multilingual-voices) sound accented (e.g. speak English with a French accent). Must come from the voice's [Get Voice `accents` field](/api-reference/voices/get#response-accents). Learn more [here](/build-with-cartesia/capability-guides/multilingual-voices#using-a-multilingual-voice).
- Normalization
normalizationtext - Text normalization. `auto` (default) runs the locale-aware normalizer, `off` skips it, or pass a language or locale code (for example `en` or `en-IN`) to pin the normalizer independently of the generation language. See [Text Normalization](/build-with-cartesia/capability-guides/text-normalization).
- Pronunciation dict id
pronunciation_dict_idtext - The ID of a pronunciation dictionary to use for the generation. Pronunciation dictionaries are supported by `sonic-3` models and newer.
- Generation config
generation_configobject - Configure the various attributes of the generated speech. Available on `sonic-3` and newer models; not available on earlier models. See [Volume, Speed, and Emotion](/build-with-cartesia/capability-guides/volume-speed-emotion) for a guide on this option.
- Voice
voice_idtextRequired - Voice id.
- Container
containertextRequired - Container.One of:
wav,mp3,raw. - Sample rate
sample_ratenumberRequired - Sample rate.One of:
8000,16000,22050,24000,44100,48000. - Encoding
encodingtext - Encoding.One of:
pcm_f32le(Pcm f32le),pcm_s16le(Pcm s16le),pcm_mulaw(Pcm mulaw),pcm_alaw(Pcm alaw). - Bit rate
bit_ratenumber - Bit rate.One of:
32000,64000,96000,128000,192000.
Outputs
dataobject- Api result.
Example output
{
"data": {
"content_base64": "example",
"content_type": "example"
}
}Get agent
Get agent.
Inputs
- Agent
agent_idtextRequired - The ID of the agent.
Outputs
dataobject- Api result.
Example output
{
"data": {
"config": {
"audio": {
"input": {
"keyterms": [],
"noise_suppression": "off"
},
"output": {
"background_sound": {
"file_id": "example",
"volume": 1.0
},
"emotion": "example",
"pronunciation_dictionary_id": "example",
"speed": 1.0,
"voice_id": "example",
"volume": 1.0
}
},
"dynamic_variable_placeholders": {},
"initial_message": "example",
"initial_message_interruptions": "allow",
"instructions": "example",
"language": {
"additional": [],
"presets": {},
"primary": "en"
},
"model": {
"fallback_strategy": {
"type": "auto"
},
"id": "example",
"max_output_tokens": 1,
"temperature": 1.0
},
"prompt_optimization": false,
"speculative_generation": false,
"system_tools": {
"end_call": {
"description": "example",
"pre_tool_speech": "auto"
},
"send_dtmf": {
"description": "example",
"pre_tool_speech": "auto"
},
"skip_turn": {
"description": "example",
"pre_tool_speech": "auto",
"wait_timeout_secs": 1
},
"transfer_to_number": {
"description": "example",
"pre_tool_speech": "auto",
"transfers": []
},
"voicemail_detection": {
"description": "example",
"message": "example",
"pre_tool_speech": "auto"
}
},
"timezone": "example",
"tools": [],
"turn": {
"inactivity_check_in_secs": 1,
"inactivity_end_call_secs": 1
}
},
"created_at": "example",
"description": "example",
"id": "example",
"name": "example",
"updated_at": "example",
"version": {
"created_at": "example",
"created_by": "example",
"description": "example",
"id": "example"
}
}
}Get api status
Get api status.
Inputs
None.
Outputs
dataobject- Api result.
Example output
{
"data": {
"ok": false,
"version": "example"
}
}Get dataset
Get dataset.
Inputs
- Dataset
idtextRequired - ID of the dataset to retrieve
Outputs
dataobject- A collection of files used for fine-tuning models
Example output
{
"data": {
"created_at": "example",
"description": "example",
"id": "example",
"name": "example"
}
}Get voice
Get voice.
Inputs
- Voice
idtextRequired - The ID of the voice. Find one in the [Voice Library](https://play.cartesia.ai/voices) or via [List Voices](/api-reference/voices/list).
- Expand[]
expandlist - Additional fields to include in the response.One or more of:
preview_file_url(Preview file url).
Outputs
dataobject- Api result.
Example output
{
"data": {
"accents": [],
"access": "private",
"country": "example",
"created_at": "example",
"description": "example",
"gender": "masculine",
"id": "example",
"is_owner": false,
"is_pro": false,
"language": "example",
"name": "example",
"preview_file_url": "example",
"status": "active",
"tagline": "example",
"visibility": "owner"
}
}List agents
List agents.
Inputs
- Starting after
starting_aftertext - A cursor for pagination. Pass the ID of the last item from the previous page to fetch the next page.
- Ending before
ending_beforetext - A cursor for pagination. Pass the ID of the first item from the previous page to fetch the previous page.
- Limit
limitnumber - The maximum number of items to return, ranging between 1 and 100.From 1 to 100.
- Q
qtext - Search agents by name or description.
Outputs
dataobject- Api result.
Example output
{
"data": {
"data": [],
"has_more": false,
"next_page": "example"
}
}List calls
List calls.
Inputs
- Agent
agent_idtext - The ID of the agent. Required unless `batch_id` is supplied.
- Batch id
batch_idtext - The ID of the outbound call batch. Required unless `agent_id` is supplied. Returns one entry per call attempt, so a retried recipient appears more than once. Recipients that failed before dialing have no call record here and remain on [Get Call Batch](/api-reference/agents/call-batches/get-call-batch).
- Start time gte
start_time_gtedate and time - Only return calls that started at or after this RFC 3339 timestamp, inclusive.
- Start time lte
start_time_ltedate and time - Only return calls that started at or before this RFC 3339 timestamp, inclusive.
- Expand
expandtext - The fields to expand in the response. Currently, the only supported value is `transcript`.
- Starting after
starting_aftertext - (Pagination option)The ID of the call to start after.
- Ending before
ending_beforetext - (Pagination option) The ID of the call to end before.
- Limit
limitnumber - (Pagination option) The number of calls to return per page, ranging between 1 and 100.
Outputs
dataobject- Api result.
Example output
{
"data": {
"data": [],
"has_more": false,
"next_page": "example"
}
}List dataset files
List dataset files.
Inputs
- Dataset
idtextRequired - ID of the dataset to list files from
- Limit
limitnumber - The number of files to return per page, ranging between 1 and 100.
- Starting after
starting_aftertext - A cursor to use in pagination. `starting_after` is a file ID that defines your place in the list. For example, if you make a dataset files request and receive 20 objects, ending with `file_abc123`, your subsequent call can include `starting_after=file_abc123` to fetch the next page of the list.
- Ending before
ending_beforetext - A cursor to use in pagination. `ending_before` is a file ID that defines your place in the list. For example, if you make a dataset files request and receive 20 objects, starting with `file_abc123`, your subsequent call can include `ending_before=file_abc123` to fetch the previous page of the list.
Outputs
dataobject- Paginated list of files in a dataset
Example output
{
"data": {
"data": [],
"has_more": false,
"next_page": "example"
}
}List datasets
List datasets.
Inputs
- Limit
limitnumber - The number of Datasets to return per page, ranging between 1 and 100.
- Starting after
starting_aftertext - A cursor to use in pagination. `starting_after` is a Dataset ID that defines your place in the list. For example, if you make a /datasets request and receive 20 objects, ending with `dataset_abc123`, your subsequent call can include `starting_after=dataset_abc123` to fetch the next page of the list.
- Ending before
ending_beforetext - A cursor to use in pagination. `ending_before` is a Dataset ID that defines your place in the list. For example, if you make a /datasets request and receive 20 objects, starting with `dataset_abc123`, your subsequent call can include `ending_before=dataset_abc123` to fetch the previous page of the list.
Outputs
dataobject- Paginated list of datasets
Example output
{
"data": {
"data": [],
"has_more": false,
"next_page": "example"
}
}List models
List models.
Inputs
- Capability
capabilitytext - Filter to `tts` or `stt`. Omit to return both.One of:
tts,stt.
Outputs
dataobject- Api result.
Example output
{
"data": {
"data": []
}
}List voices
List voices.
Inputs
- Limit
limitnumber - The number of Voices to return per page, ranging between 1 and 100.
- Starting after
starting_aftertext - A cursor to use in pagination. `starting_after` is a Voice ID that defines your place in the list. For example, if you make a /voices request and receive 100 objects, ending with `voice_abc123`, your subsequent call can include `starting_after=voice_abc123` to fetch the next page of the list.
- Ending before
ending_beforetext - A cursor to use in pagination. `ending_before` is a Voice ID that defines your place in the list. For example, if you make a /voices request and receive 100 objects, starting with `voice_abc123`, your subsequent call can include `ending_before=voice_abc123` to fetch the previous page of the list.
- Q
qtext - Query string to search for voices by name, description, or Voice ID.
- Is owner
is_ownertrue/false - Whether to only return voices owned your organization.
- Gender
gendertext - The gender presentation of the voices to return.One of:
masculine,feminine,gender_neutral(Gender neutral). - Language
languagetext - Filter voices by a language or language-locale pair such as `en` or `en-GB`. A language-locale pair returns accents for that specific locale; a language alone returns all accents for that language. Both `-` and `_` separators are accepted.
- Include archived
include_archivedtrue/false - Defaults to `false`. Set to `true` to include archived voices in the response.
- Expand[]
expandlist - Additional fields to include in the response.One or more of:
preview_file_url(Preview file url).
Outputs
dataobject- Api result.
Example output
{
"data": {
"data": [],
"has_more": false,
"next_page": "example"
}
}Localize voice
Localize voice.
Inputs
- Voice
voice_idtextRequired - ID of the existing voice you want to localize.
- Name
nametextRequired - Name for the newly localized voice.
- Description
descriptiontext - Description for the newly localized voice.
- Tagline
taglinetext - Short tagline for the newly localized voice.At most 32.
- Accent
accenttextRequired - The accent to localize into. Get ids from [GET /accents](/api-reference/accents/list) with `is_localizable=true`.One of:
modern-standard-arabic. - Access
accessobject - Controls who can access this resource. Prefer `"public"` | `"private"`. Deprecated nested `{ "type": "public" | "private" }` is still accepted.One of:
private,public.
Outputs
dataobject- Api result.
Example output
{
"data": {
"access": "private",
"created_at": "example",
"description": "example",
"id": "example",
"language": "example",
"name": "example",
"tagline": "example",
"user_id": "example",
"visibility": "owner"
}
}Update dataset
Update dataset.
Inputs
- Dataset
idtextRequired - ID of the dataset to update
- Name
nametextRequired - New name for the dataset
- Description
descriptiontextRequired - New description for the dataset
Outputs
dataobject- Api result.
Example output
{
"data": {}
}Update voice
Update voice.
Inputs
- Voice
idtextRequired - The ID of the voice. Find one in the [Voice Library](https://play.cartesia.ai/voices) or via [List Voices](/api-reference/voices/list).
- Name
nametext - The name of the voice.
- Tagline
taglinetext - A few words describing the voice. At most 32 characters.From 0 to 32.
- Description
descriptiontext - A description for the voice, typically longer than the tagline if both are provided.
- Gender
gendertext - Gender.One of:
masculine,feminine,gender_neutral(Gender neutral). - Accent
accenttext - Metadata for labeling the accent of this voice, and a prerequisite for [Add Voice Accents](/api-reference/voices/add-accents). See [GET /accents](/api-reference/accents/list) for values valid for each language.One of:
emirati-arabic,khaleeji,middle-eastern-arabic,modern-standard-arabic. - Access
accessobject - Controls who can access this resource. Prefer `"public"` | `"private"`. Deprecated nested `{ "type": "public" | "private" }` is still accepted.One of:
private,public.
Outputs
dataobject- Api result.
Example output
{
"data": {
"accents": [],
"access": "private",
"country": "example",
"created_at": "example",
"description": "example",
"gender": "masculine",
"id": "example",
"is_owner": false,
"is_pro": false,
"language": "example",
"name": "example",
"preview_file_url": "example",
"status": "active",
"tagline": "example",
"visibility": "owner"
}
}