Cartesia

App · 20 actions

Cartesia non-streaming speech, voices, datasets, agents and calls.

Actions

ActionWhat it does
Create agentCreate agent.
Create datasetCreate dataset.
Delete agentDelete agent.
Delete datasetDelete dataset.
Delete dataset fileDelete dataset file.
Delete voiceDelete voice.
Generate speechGenerate speech.
Get agentGet agent.
Get api statusGet api status.
Get datasetGet dataset.
Get voiceGet voice.
List agentsList agents.
List callsList calls.
List dataset filesList dataset files.
List datasetsList datasets.
List modelsList models.
List voicesList voices.
Localize voiceLocalize voice.
Update datasetUpdate dataset.
Update voiceUpdate voice.

Create agent

Create agent.

Inputs

Configconfigobject
Config.
Descriptiondescriptiontext
Description of the agent.
Namenametext
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

NamenametextRequired
Name for the new dataset
DescriptiondescriptiontextRequired
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

Agentagent_idtextRequired
The ID of the agent.

Outputs

dataobject
Api result.
Example output
{
  "data": {}
}

Delete dataset

Delete dataset.

Inputs

DatasetidtextRequired
ID of the dataset to delete

Outputs

dataobject
Api result.
Example output
{
  "data": {}
}

Delete dataset file

Delete dataset file.

Inputs

DatasetidtextRequired
ID of the dataset containing the file
FilefileIDtextRequired
ID of the file to remove

Outputs

dataobject
Api result.
Example output
{
  "data": {}
}

Delete voice

Delete voice.

Inputs

VoiceidtextRequired
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 idmodel_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.
TranscripttranscripttextRequired
Transcript.
Languagelanguagetext
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).
Accentaccenttext
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).
Normalizationnormalizationtext
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 idpronunciation_dict_idtext
The ID of a pronunciation dictionary to use for the generation. Pronunciation dictionaries are supported by `sonic-3` models and newer.
Generation configgeneration_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.
Voicevoice_idtextRequired
Voice id.
ContainercontainertextRequired
Container.One of: wav, mp3, raw.
Sample ratesample_ratenumberRequired
Sample rate.One of: 8000, 16000, 22050, 24000, 44100, 48000.
Encodingencodingtext
Encoding.One of: pcm_f32le (Pcm f32le), pcm_s16le (Pcm s16le), pcm_mulaw (Pcm mulaw), pcm_alaw (Pcm alaw).
Bit ratebit_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

Agentagent_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

DatasetidtextRequired
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

VoiceidtextRequired
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 afterstarting_aftertext
A cursor for pagination. Pass the ID of the last item from the previous page to fetch the next page.
Ending beforeending_beforetext
A cursor for pagination. Pass the ID of the first item from the previous page to fetch the previous page.
Limitlimitnumber
The maximum number of items to return, ranging between 1 and 100.From 1 to 100.
Qqtext
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

Agentagent_idtext
The ID of the agent. Required unless `batch_id` is supplied.
Batch idbatch_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 gtestart_time_gtedate and time
Only return calls that started at or after this RFC 3339 timestamp, inclusive.
Start time ltestart_time_ltedate and time
Only return calls that started at or before this RFC 3339 timestamp, inclusive.
Expandexpandtext
The fields to expand in the response. Currently, the only supported value is `transcript`.
Starting afterstarting_aftertext
(Pagination option)The ID of the call to start after.
Ending beforeending_beforetext
(Pagination option) The ID of the call to end before.
Limitlimitnumber
(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

DatasetidtextRequired
ID of the dataset to list files from
Limitlimitnumber
The number of files to return per page, ranging between 1 and 100.
Starting afterstarting_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 beforeending_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

Limitlimitnumber
The number of Datasets to return per page, ranging between 1 and 100.
Starting afterstarting_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 beforeending_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

Capabilitycapabilitytext
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

Limitlimitnumber
The number of Voices to return per page, ranging between 1 and 100.
Starting afterstarting_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 beforeending_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.
Qqtext
Query string to search for voices by name, description, or Voice ID.
Is owneris_ownertrue/false
Whether to only return voices owned your organization.
Gendergendertext
The gender presentation of the voices to return.One of: masculine, feminine, gender_neutral (Gender neutral).
Languagelanguagetext
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 archivedinclude_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

Voicevoice_idtextRequired
ID of the existing voice you want to localize.
NamenametextRequired
Name for the newly localized voice.
Descriptiondescriptiontext
Description for the newly localized voice.
Taglinetaglinetext
Short tagline for the newly localized voice.At most 32.
AccentaccenttextRequired
The accent to localize into. Get ids from [GET /accents](/api-reference/accents/list) with `is_localizable=true`.One of: modern-standard-arabic.
Accessaccessobject
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

DatasetidtextRequired
ID of the dataset to update
NamenametextRequired
New name for the dataset
DescriptiondescriptiontextRequired
New description for the dataset

Outputs

dataobject
Api result.
Example output
{
  "data": {}
}

Update voice

Update voice.

Inputs

VoiceidtextRequired
The ID of the voice. Find one in the [Voice Library](https://play.cartesia.ai/voices) or via [List Voices](/api-reference/voices/list).
Namenametext
The name of the voice.
Taglinetaglinetext
A few words describing the voice. At most 32 characters.From 0 to 32.
Descriptiondescriptiontext
A description for the voice, typically longer than the tagline if both are provided.
Gendergendertext
Gender.One of: masculine, feminine, gender_neutral (Gender neutral).
Accentaccenttext
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.
Accessaccessobject
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"
  }
}

On this page