### Install FFmpeg on macOS

Source: https://docs.cartesia.ai/get-started/make-an-api-request

Installs FFmpeg on macOS using the Homebrew package manager. FFmpeg is recommended for handling audio files with the Cartesia API.

```shell
# macOS
brew install ffmpeg
```

--------------------------------

### Install FFmpeg on Debian/Ubuntu

Source: https://docs.cartesia.ai/get-started/make-an-api-request

Installs FFmpeg on Debian or Ubuntu systems using the apt package manager. FFmpeg is recommended for handling audio files with the Cartesia API.

```shell
# Debian/Ubuntu
sudo apt install ffmpeg
```

--------------------------------

### Install FFmpeg on Fedora

Source: https://docs.cartesia.ai/get-started/make-an-api-request

Installs FFmpeg on Fedora systems using the dnf package manager. FFmpeg is recommended for handling audio files with the Cartesia API.

```shell
# Fedora
dnf install ffmpeg
```

--------------------------------

### Install FFmpeg on Arch Linux

Source: https://docs.cartesia.ai/get-started/make-an-api-request

Installs FFmpeg on Arch Linux systems using the pacman package manager. FFmpeg is recommended for handling audio files with the Cartesia API.

```shell
# Arch Linux
pacman -S ffmpeg
```

--------------------------------

### Generate Audio with Python SDK

Source: https://docs.cartesia.ai/get-started/make-an-api-request

This Python script uses the Cartesia SDK to generate an audio file. It requires installing the SDK (`pip install cartesia`) and setting the `CARTESIA_API_KEY` environment variable. The script calls the `client.tts.bytes` method, streams the audio chunks, saves them to a WAV file, and then plays the file using ffplay.

```sh
pip install cartesia

# Or, if you're using uv
uv add cartesia
```

```python
import asyncio
from cartesia import AsyncCartesia
import os
import subprocess

client = AsyncCartesia(
    api_key=os.environ["CARTESIA_API_KEY"],
)


async def main():
    with open("sonic-3.wav", "wb") as f:
        bytes_iter = client.tts.bytes(
            model_id="sonic-3",
            transcript="Welcome to Cartesia Sonic!",
            voice={
                "mode": "id",
                "id": "6ccbfb76-1fc6-48f7-b71d-91ac6298247b",
            },
            language="en",
            output_format={
                "container": "wav",
                "sample_rate": 44100,
                "encoding": "pcm_s16le",
            },
        )

        async for chunk in bytes_iter:
            f.write(chunk)


if __name__ == "__main__":
    asyncio.run(main())

# Play the file
subprocess.run(["ffplay", "-autoexit", "-nodisp", "sonic-3.wav"])
```

```sh
env CARTESIA_API_KEY=YOUR_API_KEY python cartesia.py

# Or, if you're using uv
env CARTESIA_API_KEY=YOUR_API_KEY uv run cartesia.py
```

--------------------------------

### Generate Audio with JavaScript/TypeScript SDK

Source: https://docs.cartesia.ai/get-started/make-an-api-request

This JavaScript code snippet demonstrates how to generate audio using the Cartesia SDK for Node.js. It requires installing the SDK (e.g., `npm install @cartesia/cartesia-js`) and setting the `CARTESIA_API_KEY` environment variable. The code initializes the client, makes an API call to the TTS Bytes endpoint, saves the response to a WAV file, and plays it using `ffplay`.

```sh
# NPM
npm install @cartesia/cartesia-js

# Yarn
yarn add @cartesia/cartesia-js

# Bun
bun add @cartesia/cartesia-js

# PNPM
pnpm add @cartesia/cartesia-js
```

```js
import { CartesiaClient } from "@cartesia/cartesia-js";
import fs from "node:fs";
import { spawn } from "node:child_process";
import process from "node:process";

if (!process.env.CARTESIA_API_KEY) {
  throw new Error("CARTESIA_API_KEY is not set");
}

// Set up the client.
const client = new CartesiaClient({
  apiKey: process.env.CARTESIA_API_KEY,
});

// Make the API call.
const response = await client.tts.bytes({
  modelId: "sonic-3",
  // You can find more voices at https://play.cartesia.ai/voices
  voice: {
    mode: "id",
    id: "694f9389-aac1-45b6-b726-9d9369183238",
  },
  // You can find the supported `output_format`s at https://docs.cartesia.ai/api-reference/tts/bytes
  outputFormat: {
    container: "wav",
    encoding: "pcm_s16le",
    sampleRate: 44100,
  },
  transcript: "Welcome to Cartesia Sonic!",
});

// Write `response` to a file. (We convert the response to a Uint8Array first.)
fs.writeFileSync("sonic-3.wav", await new Response(response).bytes());

// Play the file.
spawn("ffplay", ["-autoexit", "-nodisp", "sonic-3.wav"]);

```

--------------------------------

### POST /tts/bytes

Source: https://docs.cartesia.ai/get-started/make-an-api-request

This endpoint generates audio from text and returns the raw audio bytes. It is suitable for batch processing and saving audio files.

```APIDOC
## POST /tts/bytes

### Description
Generates audio from text and returns the output in raw bytes. Ideal for batch use cases where audio needs to be saved in advance.

### Method
POST

### Endpoint
`/tts/bytes`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **transcript** (string) - Required - The text to convert to speech.
- **model_id** (string) - Required - The ID of the speech synthesis model to use (e.g., "sonic-3").
- **voice** (object) - Required - Specifies the voice to use.
  - **mode** (string) - Required - Mode of voice selection ('id' or 'random').
  - **id** (string) - Required if mode is 'id' - The specific voice ID.
- **language** (string) - Optional - The language of the transcript (e.g., "en").
- **output_format** (object) - Required - Specifies the desired audio output format.
  - **container** (string) - Required - The audio container format (e.g., "wav").
  - **encoding** (string) - Required - The audio encoding format (e.g., "pcm_s16le").
  - **sample_rate** (integer) - Required - The sample rate of the audio in Hz (e.g., 44100).

### Request Example
```json
{
  "transcript": "Welcome to Cartesia Sonic!",
  "model_id": "sonic-3",
  "voice": {
    "mode": "id",
    "id": "694f9389-aac1-45b6-b726-9d9369183238"
  },
  "output_format": {
    "container": "wav",
    "encoding": "pcm_s16le",
    "sample_rate": 44100
  }
}
```

### Response
#### Success Response (200)
- The response body contains the raw audio bytes in the format specified by `output_format`.

#### Response Example
(Binary audio data - e.g., WAV file content)
```

--------------------------------

### Generate Audio with cURL

Source: https://docs.cartesia.ai/get-started/make-an-api-request

This cURL command interacts with the Cartesia AI Text-to-Speech (Bytes) endpoint to generate an audio file. It requires an API key and specifies the desired transcript, model, voice, and output format. The output is saved as a WAV file.

```bash
export CARTESIA_API_KEY=XXX
curl -N -X POST "https://api.cartesia.ai/tts/bytes" \
        -H "Cartesia-Version: 2025-04-16" \
        -H "X-API-Key: $CARTESIA_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"transcript": "Welcome to Cartesia Sonic!", "model_id": "sonic-3", "voice": {"mode":"id", "id": "694f9389-aac1-45b6-b726-9d9369183238"}, "output_format":{"container":"wav", "encoding":"pcm_s16le", "sample_rate":44100}}' > sonic-3.wav
```

--------------------------------

### Generate Access Token (Fetch API - TypeScript)

Source: https://docs.cartesia.ai/get-started/authenticate-your-client-applications

Generate Cartesia Access Tokens using the Fetch API in TypeScript. This example demonstrates making a POST request to the access-token endpoint, including necessary headers like 'Cartesia-Version' and 'Authorization', and a JSON body specifying grants and expiration. The token is extracted from the JSON response.

```typescript
// TTS and STT access
const response = await fetch("https://api.cartesia.ai/access-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cartesia-Version": "2025-04-16",
    Authorization: "Bearer <your_api_key>",
  },
  body: JSON.stringify({
    grants: { tts: true, stt: true },
    expires_in: 60, // 1 minute
  }),
});

// TTS-only access
const responseTTS = await fetch("https://api.cartesia.ai/access-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cartesia-Version": "2025-04-16",
    Authorization: "Bearer <your_api_key>",
  },
  body: JSON.stringify({
    grants: { tts: true },
    expires_in: 60, // 1 minute
  }),
});

const { token } = await response.json();
```

--------------------------------

### Make Authenticated TTS and STT Requests with Bearer Token

Source: https://docs.cartesia.ai/get-started/authenticate-your-client-applications

Demonstrates how to include Bearer token authorization in fetch requests to Cartesia AI TTS and STT endpoints. TTS requests use application/json content type, while STT requests use multipart/form-data for audio file uploads. Both examples show proper header configuration with Authorization bearer token.

```typescript
// Using TTS with access token
const ttsResponse = await fetch("https://api.cartesia.ai/tts/bytes", {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  // ... request configuration
});

// Using STT with access token
const sttResponse = await fetch("https://api.cartesia.ai/stt", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
  body: formData, // multipart/form-data with audio file
});
```

--------------------------------

### Generate Access Token (Python)

Source: https://docs.cartesia.ai/get-started/authenticate-your-client-applications

Generate Cartesia Access Tokens in Python using the Cartesia SDK. The access_token function accepts a grants dictionary and an expires_in parameter to define token permissions and validity. The generated token is returned in the response object.

```python
from cartesia import Cartesia

client = Cartesia(
  token="YOUR_API_KEY"
)

# TTS and STT access
response = client.auth.access_token(
  grants={"tts": True, "stt": True}, # Grant both permissions
  expires_in=60 # Token expires in 60 seconds
)

# TTS-only access
response = client.auth.access_token(
  grants={"tts": True}, # Grant TTS permissions only
  expires_in=60 # Token expires in 60 seconds
)

# The response will contain the access token
print(f"Access Token: {response.token}")
```

--------------------------------

### POST /access-token

Source: https://docs.cartesia.ai/get-started/authenticate-your-client-applications

Generate a new Access Token for client applications. This token can be configured with specific grants (TTS, STT, Agents) and an expiration time.

```APIDOC
## POST /access-token

### Description
Generates a secure Access Token for client applications, allowing them to make API requests without exposing the primary API key. Tokens can be configured with specific permissions (grants) and have a defined expiration.

### Method
POST

### Endpoint
https://api.cartesia.ai/access-token

### Parameters
#### Headers
- **Cartesia-Version** (string) - Required - The API version to use (e.g., "2025-04-16").
- **Content-Type** (string) - Required - Must be "application/json".
- **Authorization** (string) - Required - Bearer token with your API key (e.g., "Bearer sk_car_...").

#### Request Body
- **grants** (object) - Optional - Specifies the permissions the token should have.
  - **tts** (boolean) - Optional - If true, grants access to TTS endpoints.
  - **stt** (boolean) - Optional - If true, grants access to STT endpoints.
  - **agent** (boolean) - Optional - If true, grants access to Agents endpoints.
- **expires_in** (integer) - Optional - The token's validity in seconds. Defaults to a system-defined value if not provided.

### Request Example
```json
{
  "grants": {
    "tts": true,
    "stt": true
  },
  "expires_in": 60
}
```

### Response
#### Success Response (200)
- **token** (string) - The generated Access Token.
- **expires_at** (string) - The expiration timestamp of the token.

#### Response Example
```json
{
  "token": "at_abc123...",
  "expires_at": "2024-01-01T12:00:00Z"
}
```
```

--------------------------------

### Generate Access Token (JavaScript)

Source: https://docs.cartesia.ai/get-started/authenticate-your-client-applications

Generate Cartesia Access Tokens in JavaScript using the Cartesia client library. This method allows specifying grants (e.g., TTS, STT) and expiration time programmatically. Initialize the client with your API key before calling the accessToken method.

```javascript
import { CartesiaClient } from "@cartesia/cartesia-js";

const client = new CartesiaClient({ apiKey: "YOUR_API_KEY" });

// TTS and STT access
await client.auth.accessToken({
  grants: {
    tts: true,
    stt: true
  },
  expires_in: 60
});

// TTS-only access
await client.auth.accessToken({
  grants: {
    tts: true
  },
  expires_in: 60
});
```

--------------------------------

### Generate Access Token (cURL)

Source: https://docs.cartesia.ai/get-started/authenticate-your-client-applications

Generate Cartesia Access Tokens using cURL for various grant types (TTS, STT, or both). This involves making a POST request to the access-token endpoint with appropriate headers and a JSON payload specifying grants and expiration time. Ensure your API key is included in the Authorization header.

```bash
curl --location 'https://api.cartesia.ai/access-token' \
    -H 'Cartesia-Version: 2025-04-16' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer sk_car_...' \
    -d '{ "grants": {"tts": true, "stt": true}, "expires_in": 60}'

# TTS-only access
curl --location 'https://api.cartesia.ai/access-token' \
    -H 'Cartesia-Version: 2025-04-16' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer sk_car_...' \
    -d '{ "grants": {"tts": true}, "expires_in": 60}'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.