# Cartesia

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

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/cartesia

## Actions

### Create agent

Create agent.

**Inputs**

- Config (`config`, object): Config.
- Description (`description`, text): Description of the agent.
- Name (`name`, text): Name shown for the agent. It does not need to be unique.

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "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 (`name`, text, required): Name for the new dataset
- Description (`description`, text, required): Optional description for the dataset

**Outputs**

- `data` (object): A collection of files used for fine-tuning models

**Example output**

```json
{
  "data": {
    "created_at": "example",
    "description": "example",
    "id": "example",
    "name": "example"
  }
}
```

### Delete agent

Delete agent.

**Inputs**

- Agent (`agent_id`, text, required): The ID of the agent.

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "data": {}
}
```

### Delete dataset

Delete dataset.

**Inputs**

- Dataset (`id`, text, required): ID of the dataset to delete

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "data": {}
}
```

### Delete dataset file

Delete dataset file.

**Inputs**

- Dataset (`id`, text, required): ID of the dataset containing the file
- File (`fileID`, text, required): ID of the file to remove

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "data": {}
}
```

### Delete voice

Delete voice.

**Inputs**

- Voice (`id`, text, required): 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**

- `data` (object): Api result.

**Example output**

```json
{
  "data": {}
}
```

### Generate speech

Generate speech.

**Inputs**

- Model id (`model_id`, text, required): 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 (`transcript`, text, required): Transcript.
- Language (`language`, text): 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 (`accent`, text): 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 (`normalization`, text): 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_id`, text): The ID of a pronunciation dictionary to use for the generation. Pronunciation dictionaries are supported by `sonic-3` models and newer.
- Generation config (`generation_config`, object): 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_id`, text, required): Voice id.
- Container (`container`, text, required): Container. One of: `wav`, `mp3`, `raw`.
- Sample rate (`sample_rate`, number, required): Sample rate. One of: `8000`, `16000`, `22050`, `24000`, `44100`, `48000`.
- Encoding (`encoding`, text): Encoding. One of: `pcm_f32le` (Pcm f32le), `pcm_s16le` (Pcm s16le), `pcm_mulaw` (Pcm mulaw), `pcm_alaw` (Pcm alaw).
- Bit rate (`bit_rate`, number): Bit rate. One of: `32000`, `64000`, `96000`, `128000`, `192000`.

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "data": {
    "content_base64": "example",
    "content_type": "example"
  }
}
```

### Get agent

Get agent.

**Inputs**

- Agent (`agent_id`, text, required): The ID of the agent.

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "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**

- `data` (object): Api result.

**Example output**

```json
{
  "data": {
    "ok": false,
    "version": "example"
  }
}
```

### Get dataset

Get dataset.

**Inputs**

- Dataset (`id`, text, required): ID of the dataset to retrieve

**Outputs**

- `data` (object): A collection of files used for fine-tuning models

**Example output**

```json
{
  "data": {
    "created_at": "example",
    "description": "example",
    "id": "example",
    "name": "example"
  }
}
```

### Get voice

Get voice.

**Inputs**

- Voice (`id`, text, required): 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[] (`expand`, list): Additional fields to include in the response. One or more of: `preview_file_url` (Preview file url).

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "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_after`, text): A cursor for pagination. Pass the ID of the last item from the previous page to fetch the next page.
- Ending before (`ending_before`, text): A cursor for pagination. Pass the ID of the first item from the previous page to fetch the previous page.
- Limit (`limit`, number): The maximum number of items to return, ranging between 1 and 100. From 1 to 100.
- Q (`q`, text): Search agents by name or description.

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "data": {
    "data": [],
    "has_more": false,
    "next_page": "example"
  }
}
```

### List calls

List calls.

**Inputs**

- Agent (`agent_id`, text): The ID of the agent. Required unless `batch_id` is supplied.
- Batch id (`batch_id`, text): 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_gte`, date and time): Only return calls that started at or after this RFC 3339 timestamp, inclusive.
- Start time lte (`start_time_lte`, date and time): Only return calls that started at or before this RFC 3339 timestamp, inclusive.
- Expand (`expand`, text): The fields to expand in the response. Currently, the only supported value is `transcript`.
- Starting after (`starting_after`, text): (Pagination option)The ID of the call to start after.
- Ending before (`ending_before`, text): (Pagination option) The ID of the call to end before.
- Limit (`limit`, number): (Pagination option) The number of calls to return per page, ranging between 1 and 100.

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "data": {
    "data": [],
    "has_more": false,
    "next_page": "example"
  }
}
```

### List dataset files

List dataset files.

**Inputs**

- Dataset (`id`, text, required): ID of the dataset to list files from
- Limit (`limit`, number): The number of files to return per page, ranging between 1 and 100.
- Starting after (`starting_after`, text): 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_before`, text): 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**

- `data` (object): Paginated list of files in a dataset

**Example output**

```json
{
  "data": {
    "data": [],
    "has_more": false,
    "next_page": "example"
  }
}
```

### List datasets

List datasets.

**Inputs**

- Limit (`limit`, number): The number of Datasets to return per page, ranging between 1 and 100.
- Starting after (`starting_after`, text): 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_before`, text): 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**

- `data` (object): Paginated list of datasets

**Example output**

```json
{
  "data": {
    "data": [],
    "has_more": false,
    "next_page": "example"
  }
}
```

### List models

List models.

**Inputs**

- Capability (`capability`, text): Filter to `tts` or `stt`. Omit to return both. One of: `tts`, `stt`.

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "data": {
    "data": []
  }
}
```

### List voices

List voices.

**Inputs**

- Limit (`limit`, number): The number of Voices to return per page, ranging between 1 and 100.
- Starting after (`starting_after`, text): 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_before`, text): 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 (`q`, text): Query string to search for voices by name, description, or Voice ID.
- Is owner (`is_owner`, true/false): Whether to only return voices owned your organization.
- Gender (`gender`, text): The gender presentation of the voices to return. One of: `masculine`, `feminine`, `gender_neutral` (Gender neutral).
- Language (`language`, text): 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_archived`, true/false): Defaults to `false`. Set to `true` to include archived voices in the response.
- Expand[] (`expand`, list): Additional fields to include in the response. One or more of: `preview_file_url` (Preview file url).

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "data": {
    "data": [],
    "has_more": false,
    "next_page": "example"
  }
}
```

### Localize voice

Localize voice.

**Inputs**

- Voice (`voice_id`, text, required): ID of the existing voice you want to localize.
- Name (`name`, text, required): Name for the newly localized voice.
- Description (`description`, text): Description for the newly localized voice.
- Tagline (`tagline`, text): Short tagline for the newly localized voice. At most 32.
- Accent (`accent`, text, required): The accent to localize into. Get ids from [GET /accents](/api-reference/accents/list) with `is_localizable=true`. One of: `modern-standard-arabic`.
- Access (`access`, object): Controls who can access this resource. Prefer `"public"` | `"private"`. Deprecated nested `{ "type": "public" | "private" }` is still accepted. One of: `private`, `public`.

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "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 (`id`, text, required): ID of the dataset to update
- Name (`name`, text, required): New name for the dataset
- Description (`description`, text, required): New description for the dataset

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "data": {}
}
```

### Update voice

Update voice.

**Inputs**

- Voice (`id`, text, required): 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 (`name`, text): The name of the voice.
- Tagline (`tagline`, text): A few words describing the voice. At most 32 characters. From 0 to 32.
- Description (`description`, text): A description for the voice, typically longer than the tagline if both are provided.
- Gender (`gender`, text): Gender. One of: `masculine`, `feminine`, `gender_neutral` (Gender neutral).
- Accent (`accent`, text): 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 (`access`, object): Controls who can access this resource. Prefer `"public"` | `"private"`. Deprecated nested `{ "type": "public" | "private" }` is still accepted. One of: `private`, `public`.

**Outputs**

- `data` (object): Api result.

**Example output**

```json
{
  "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"
  }
}
```
