### Install Cartesia TypeScript Library

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

This command installs the Cartesia TypeScript library using npm. It is a prerequisite for using the library in your TypeScript projects.

```sh
npm i -s @cartesia/cartesia-js
```

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

### Handling Binary Responses

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

Examples demonstrating how to convert binary responses into downloadable files using different formats like ReadableStream, ArrayBuffer, Blob, and Bytes (UIntArray8).

```APIDOC
## Handling Binary Responses

### ReadableStream

```ts
const response = await client.agents.downloadCallAudio(...);
const stream = response.stream();
const reader = stream.getReader();
const chunks = [];

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  chunks.push(value);
}

const blob = new Blob(chunks);
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
```

### ArrayBuffer

```ts
const response = await client.agents.downloadCallAudio(...);
const arrayBuffer = await response.arrayBuffer();
const blob = new Blob([arrayBuffer]);
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
```

### Bytes (UIntArray8)

```ts
const response = await client.agents.downloadCallAudio(...);
const bytes = await response.bytes();
const blob = new Blob([bytes]);
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
```
```

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

### Converting Binary Response to Text

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

Examples showing how to convert binary responses into text using different data formats like ReadableStream, ArrayBuffer, Blob, and Bytes (UIntArray8).

```APIDOC
## Convert binary response to text

### ReadableStream

```ts
const response = await client.agents.downloadCallAudio(...);
const stream = response.stream();
const text = await new Response(stream).text();
```

### ArrayBuffer

```ts
const response = await client.agents.downloadCallAudio(...);
const arrayBuffer = await response.arrayBuffer();
const text = new TextDecoder().decode(arrayBuffer);
```

### Blob

```ts
const response = await client.agents.downloadCallAudio(...);
const blob = await response.blob();
const text = await blob.text();
```

### Bytes (UIntArray8)

```ts
const response = await client.agents.downloadCallAudio(...);
const bytes = await response.bytes();
const text = new TextDecoder().decode(bytes);
```
```

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

### GET /pronunciationDicts

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Lists all pronunciation dictionaries for the authenticated user.

```APIDOC
## GET /pronunciationDicts

### Description
Lists all pronunciation dictionaries for the authenticated user.

### Method
GET

### Endpoint
/pronunciationDicts

### Parameters
#### Query Parameters
- **...params** (object) - Optional - Additional parameters for filtering or pagination.

### Response
#### Success Response (200)
- **pronunciationDicts** (array) - A list of pronunciation dictionaries.

#### Response Example
```json
{
  "pronunciationDicts": [
    { ... },
    { ... }
  ]
}
```
```

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

### Real-time Speech-to-Text Streaming with Cartesia JS

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

Demonstrates how to perform real-time Speech-to-Text (STT) using a streaming WebSocket connection. This example includes sending audio chunks and receiving interim and final transcripts with word-level timestamps. It requires the '@cartesia/cartesia-js' library and Node.js 'fs' module. Inputs are audio file path and API key. Outputs are console logs of the transcription process and the final transcript.

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

async function streamingSTTExample() {
    const client = new CartesiaClient({
        apiKey: process.env.CARTESIA_API_API_KEY,
    });

    // Create websocket connection with endpointing parameters
    const sttWs = client.stt.websocket({
        model: "ink-whisper",
        language: "en", // Language of your audio
        encoding: "pcm_s16le", // Audio encoding format (required)
        sampleRate: 16000, // Audio sample rate (required)
        minVolume: 0.1, // Volume threshold for voice activity detection (0.0-1.0)
        maxSilenceDurationSecs: 2.0, // Maximum silence duration before endpointing
    });

    // Concurrent audio sending
    async function sendAudio() {
        try {
            const audioBuffer = fs.readFileSync("audio.wav");
            const chunkSize = 3200; // ~200ms chunks for more realistic streaming

            console.log("Starting audio stream...");

            for (let i = 0; i < audioBuffer.length; i += chunkSize) {
                const chunk = audioBuffer.subarray(i, i + chunkSize);
                const arrayBuffer = chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength);

                await sttWs.send(arrayBuffer);
                console.log(`Sent chunk ${Math.floor(i / chunkSize) + 1}`);

                // Simulate real-time audio capture delay
                await new Promise((resolve) => setTimeout(resolve, 100));
            }

            await sttWs.finalize();
            console.log("Audio streaming completed");
        } catch (error) {
            console.error("Error sending audio:", error);
        }
    }

    // Concurrent transcript receiving with word-level timestamps
    async function receiveTranscripts(): Promise<string> {
        return new Promise((resolve) => {
            let fullTranscript = "";

            sttWs.onMessage((result) => {
                if (result.type === "transcript") {
                    const status = result.isFinal ? "FINAL" : "INTERIM";
                    console.log(`[${status}] "${result.text}"`);

                    // Handle word-level timestamps if available
                    if (result.words && result.words.length > 0) {
                        console.log("Word-level timestamps:");
                        result.words.forEach((word) => {
                            console.log(`  "${word.word}": ${word.start.toFixed(2)}s - ${word.end.toFixed(2)}s`);
                        });
                    }

                    if (result.isFinal) {
                        fullTranscript += `${result.text} `;
                    }
                } else if (result.type === "flush_done") {
                    console.log("Flush completed - sending done command");
                    sttWs.done().catch(console.error);
                } else if (result.type === "done") {
                    console.log("Transcription completed");
                    resolve(fullTranscript.trim());
                } else if (result.type === "error") {
                    console.error(`Error: ${result.message}`);
                    resolve("");
                }
            });
        });
    }

    try {
        console.log("Starting STT processing...");

        // Run audio sending and transcript receiving concurrently
        const [, finalTranscript] = await Promise.all([sendAudio(), receiveTranscripts()]);

        console.log(`\nFinal transcript: ${finalTranscript}`);

        // Clean up
        sttWs.disconnect();

        return finalTranscript;
    } catch (error) {
        console.error("STT processing error:", error);
        sttWs.disconnect();
        throw error;
    }
}

// Run the example
streamingSTTExample().catch(console.error);

```

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

### List Agent Calls

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Lists calls sorted by start time in descending order for a specific agent. Supports pagination and expansion of transcripts.

```APIDOC
## GET /agents/calls

### Description
Lists calls sorted by start time in descending order for a specific agent. `agent_id` is required and if you want to include `transcript` in the response, add `expand=transcript` to the request. This endpoint is paginated.

### Method
GET

### Endpoint
/agents/calls

### Parameters
#### Query Parameters
- **request** (Cartesia.ListCallsRequest) - Required - Parameters for listing calls.
  - **agentId** (string) - Required - The ID of the agent.
  - **expand** (string) - Optional - Include 'transcript' in the response.
- **requestOptions** (Agents.RequestOptions) - Optional - Options for the request.

### Response
#### Success Response (200)
- **response** (core.Page<Cartesia.AgentCall>) - A paginated list of agent calls.

### Request Example
```typescript
const response = await client.agents.listCalls({
    agentId: "agent_id",
});
for await (const item of response) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.agents.listCalls({
    agentId: "agent_id",
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}
```

### Response Example
(Response structure depends on core.Page<Cartesia.AgentCall>)
```

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

### Voice Management - List and Search Voices with Cartesia JS

Source: https://context7.com/cartesia-ai/cartesia-js/llms.txt

This example shows how to list and search available voices using the Cartesia JavaScript SDK. It covers filtering by gender, star status, ownership, and uses pagination to retrieve results. The code iterates through paginated results and demonstrates manual pagination control.

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

const client = new CartesiaClient({ token: process.env.CARTESIA_API_KEY });

async function listVoices() {
    // Paginated voice listing with filters
    const voicesPage = await client.voices.list({
        gender: "female",
        isStarred: true,
        isOwner: false,
        limit: 20
    });

    console.log("Available voices:");
    for await (const voice of voicesPage) {
        console.log(`- ${voice.name} (ID: ${voice.id})`);
        console.log(`  Description: ${voice.description}`);
        console.log(`  Language: ${voice.language}`);
        if (voice.embedding) {
            console.log(`  Embedding: [${voice.embedding.length} dimensions]`);
        }
    }

    // Manual pagination
    let page = await client.voices.list({ limit: 10 });
    while (page.hasNextPage()) {
        console.log("Fetching next page...");
        page = await page.getNextPage();
    }
}

listVoices();

```

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

### List Available Agent Templates in Cartesia JS

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Retrieves a list of public agent templates provided by Cartesia. These templates serve as starting points for creating new agents.

```typescript
await client.agents.templates();
```

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

### Voice Management - Create, Update, Get, and Delete with Cartesia JS

Source: https://context7.com/cartesia-ai/cartesia-js/llms.txt

This snippet illustrates voice management operations including creating a new custom voice by cloning from audio samples, updating its metadata, retrieving its details, and finally deleting it. It requires audio files for cloning and your Cartesia API key.

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

const client = new CartesiaClient({ token: process.env.CARTESIA_API_KEY });

async function createCustomVoice() {
    try {
        // Clone voice from audio sample
        const newVoice = await client.voices.create({
            name: "Custom Voice 2025",
            description: "A custom voice cloned from audio sample",
            language: "en",
            files: [
                fs.createReadStream("voice_sample1.wav"),
                fs.createReadStream("voice_sample2.wav")
            ]
        });

        console.log("Voice created successfully!");
        console.log("Voice ID:", newVoice.id);
        console.log("Voice Name:", newVoice.name);

        // Update voice metadata
        const updated = await client.voices.update(newVoice.id, {
            name: "Updated Voice Name",
            description: "Updated description",
            isStarred: true
        });

        console.log("Voice updated:", updated.name);

        // Get specific voice details
        const voice = await client.voices.get(newVoice.id);
        console.log("Voice details:", voice);

        // Delete voice when no longer needed
        await client.voices.delete(newVoice.id);
        console.log("Voice deleted");
    } catch (error) {
        console.error("Voice operation failed:", error);
    }
}

createCustomVoice();

```

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

### Iterate Paginated API Responses in TypeScript

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

This TypeScript example shows how to handle paginated API responses using an async iterator. It demonstrates fetching a list of calls and iterating through each item directly. Alternatively, it shows how to manually manage pagination by checking for the next page and fetching it.

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

const client = new CartesiaClient({ token: "YOUR_TOKEN" });
const response = await client.agents.listCalls({
    agentId: "agent_id",
});
for await (const item of response) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.agents.listCalls({
    agentId: "agent_id",
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}
```

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

### GET /fine-tunes/{id}/voices

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Lists all voices created from a specific fine-tune.

```APIDOC
## GET /fine-tunes/{id}/voices

### Description
Lists all voices created from a specific fine-tune.

### Method
GET

### Endpoint
/fine-tunes/{id}/voices

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the fine-tune to list voices from.

#### Request Body
- **request** (object) - Optional - Parameters for listing voices.
  - **...params** (object) - Additional parameters for listing.

### Response
#### Success Response (200)
- **voices** (array) - A list of voices associated with the fine-tune.

#### Response Example
```json
{
  "voices": [
    { ... },
    { ... }
  ]
}
```
```

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

### Agents API

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Endpoints for managing agents, including adding/removing metrics, listing, and getting deployments.

```APIDOC
## POST /agents/{agentId}/metrics/{metricId}

### Description
Add a metric to an agent. Once the metric is added, it will be run on all calls made to the agent automatically from that point onwards.

### Method
POST

### Endpoint
/agents/{agentId}/metrics/{metricId}

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the agent.
- **metricId** (string) - Required - The ID of the metric.

#### Query Parameters
- **requestOptions** (Agents.RequestOptions) - Optional - Additional request options.

### Request Example
```json
{
  "agentId": "agent_id",
  "metricId": "metric_id"
}
```

### Response
#### Success Response (200)
- **None** (void)

#### Response Example
```json
null
```
```

```APIDOC
## DELETE /agents/{agentId}/metrics/{metricId}

### Description
Remove a metric from an agent. Once the metric is removed, it will no longer be run on all calls made to the agent automatically from that point onwards. Existing metric results will remain.

### Method
DELETE

### Endpoint
/agents/{agentId}/metrics/{metricId}

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the agent.
- **metricId** (string) - Required - The ID of the metric.

#### Query Parameters
- **requestOptions** (Agents.RequestOptions) - Optional - Additional request options.

### Request Example
```json
{
  "agentId": "agent_id",
  "metricId": "metric_id"
}
```

### Response
#### Success Response (200)
- **None** (void)

#### Response Example
```json
null
```
```

```APIDOC
## GET /agents/{agentId}/deployments

### Description
List of all deployments associated with an agent.

### Method
GET

### Endpoint
/agents/{agentId}/deployments

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the agent.

#### Query Parameters
- **requestOptions** (Agents.RequestOptions) - Optional - Additional request options.

### Request Example
```json
{
  "agentId": "agent_demo"
}
```

### Response
#### Success Response (200)
- **deployments** (Cartesia.Deployment[]) - An array of deployments.

#### Response Example
```json
{
  "deployments": [
    {
      "id": "deployment_id_1",
      "name": "Deployment 1"
    },
    {
      "id": "deployment_id_2",
      "name": "Deployment 2"
    }
  ]
}
```
```

```APIDOC
## GET /agents/deployments/{deploymentId}

### Description
Get a deployment by its ID.

### Method
GET

### Endpoint
/agents/deployments/{deploymentId}

### Parameters
#### Path Parameters
- **deploymentId** (string) - Required - The ID of the deployment.

#### Query Parameters
- **requestOptions** (Agents.RequestOptions) - Optional - Additional request options.

### Request Example
```json
{
  "deploymentId": "ad_abc123"
}
```

### Response
#### Success Response (200)
- **deployment** (Cartesia.Deployment) - The requested deployment object.

#### Response Example
```json
{
  "id": "ad_abc123",
  "name": "My Deployment"
}
```
```

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

### GET /fine-tunes/{id}

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Retrieves a specific fine-tune by its ID.

```APIDOC
## GET /fine-tunes/{id}

### Description
Retrieves a specific fine-tune by its ID.

### Method
GET

### Endpoint
/fine-tunes/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the fine-tune to retrieve.

### Response
#### Success Response (200)
- **fineTune** (object) - Details of the requested fine-tune.

#### Response Example
```json
{
  "fineTune": { ... }
}
```
```

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

### Importing Cartesia SDK Request/Response Types in TypeScript

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

Shows how to import and use TypeScript interfaces for Cartesia SDK requests and responses. This allows for type-safe API interactions. It requires the '@cartesia/cartesia-js' library. The example demonstrates defining a request object with the correct type.

```typescript
import { Cartesia } from "@cartesia/cartesia-js";

const request: Cartesia.ListCallsRequest = {
    ...
};

```

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

### List Agent Calls in Cartesia JS

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Lists calls sorted by start time in descending order for a specific agent. Transcripts can be included by adding `expand=transcript` to the request. This endpoint supports pagination.

```typescript
const response = await client.agents.listCalls({
    agentId: "agent_id",
});
for await (const item of response) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.agents.listCalls({
    agentId: "agent_id",
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}
```

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

### Get Voice

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Retrieves the details of a specific voice by its ID.

```APIDOC
## GET /voices/{id}

### Description
Retrieves the details of a specific voice using its unique ID.

### Method
GET

### Endpoint
/voices/{id}

### Parameters
#### Path Parameters
- **id** (Cartesia.VoiceId) - Required - The ID of the voice to retrieve.

#### Query Parameters
- **requestOptions** (Voices.RequestOptions) - Optional - Options for the request.

### Request Example
```typescript
await client.voices.get("voice-id-to-retrieve");
```

### Response
#### Success Response (200)
- **voice** (Cartesia.Voice) - The details of the requested voice.

#### Response Example
```json
{
  "id": "voice-id-to-retrieve",
  "name": "Example Voice",
  "description": "A sample voice",
  "gender": "male",
  "language": "en-US"
}
```
```

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

### FineTunes API

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Endpoints for managing fine-tunes, including listing and creation.

```APIDOC
## GET /fine-tunes

### Description
Paginated list of all fine-tunes for the authenticated user.

### Method
GET

### Endpoint
/fine-tunes

### Parameters
#### Query Parameters
- **request** (Cartesia.ListFineTunesRequest) - Optional - Parameters for listing fine-tunes.
- **requestOptions** (FineTunes.RequestOptions) - Optional - Options for the request.

### Response
#### Success Response (200)
- **fineTunes** (array) - A list of fine-tune objects.
- **pagination** (object) - Pagination details for the fine-tune list.

#### Response Example
```json
{
  "fineTunes": [
    {
      "id": "ft-123",
      "model": "base-model-v1",
      "status": "succeeded",
      "createdAt": "2023-10-27T11:00:00Z"
    }
  ],
  "pagination": {
    "nextCursor": "cursor-xyz",
    "hasNextPage": false
  }
}
```
```

```APIDOC
## POST /fine-tunes

### Description
Create a new fine-tune.

### Method
POST

### Endpoint
/fine-tunes

### Parameters
#### Request Body
- **request** (Cartesia.CreateFineTuneRequest) - Required - The request body for creating a fine-tune.
- **requestOptions** (FineTunes.RequestOptions) - Optional - Options for the request.

### Request Example
```json
{
  "trainingFileId": "file-id-train",
  "validationFileId": "file-id-validation",
  "model": "base-model-v1"
}
```

### Response
#### Success Response (200)
- **fineTune** (Cartesia.FineTune) - The created fine-tune object.

#### Response Example
```json
{
  "id": "ft-456",
  "model": "base-model-v1",
  "status": "pending",
  "createdAt": "2023-10-27T11:15:00Z"
}
```
```

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

### Instantiate and Use Cartesia Client for TTS

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

This TypeScript code demonstrates how to instantiate the CartesiaClient with an API token and then use it to generate TTS audio bytes. It specifies model, transcript, voice, language, output format, and save options.

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

const client = new CartesiaClient({ token: "YOUR_TOKEN" });
await client.tts.bytes({
    modelId: "sonic-2",
    transcript: "Hello, world!",
    voice: {
        mode: "id",
        id: "694f9389-aac1-45b6-b726-9d9369183238",
    },
    language: "en",
    outputFormat: {
        container: "wav",
        sampleRate: 44100,
        encoding: "pcm_f32le",
    },
    save: true,
});
```

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

### Initialize Cartesia Client

Source: https://context7.com/cartesia-ai/cartesia-js/llms.txt

Initializes the Cartesia client for API authentication. Supports direct API token, environment variables, and custom configurations like API version, timeouts, retries, and custom headers.

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

// Basic initialization
const client = new CartesiaClient({
    token: "YOUR_API_KEY"
});

// Or use environment variable
// Set CARTESIA_API_KEY in your environment
const client = new CartesiaClient();

// With custom configuration
const client = new CartesiaClient({
    token: "YOUR_API_KEY",
    cartesiaVersion: "2025-04-16",
    timeoutInSeconds: 30,
    maxRetries: 3,
    headers: {
        "X-Custom-Header": "custom-value"
    }
});
```

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

### Get Agent Details

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Returns the details of a specific agent.

```APIDOC
## GET /agents/{agentId}

### Description
Returns the details of a specific agent. To create an agent, use the CLI or the Playground for the best experience and integration with Github.

### Method
GET

### Endpoint
/agents/{agentId}

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the agent.

#### Query Parameters
- **requestOptions** (Agents.RequestOptions) - Optional - Options for the request.

### Response
#### Success Response (200)
- **response** (Cartesia.AgentSummary) - The details of the specified agent.

### Request Example
```typescript
await client.agents.get("agent_123");
```

### Response Example
(Response structure depends on Cartesia.AgentSummary)
```

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

### Save Binary Response to File in Deno

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

Demonstrates saving binary responses to files in a Deno environment. It shows methods for `ReadableStream`, `ArrayBuffer`, `Blob`, and `Uint8Array`.

```typescript
const response = await client.agents.downloadCallAudio(...);

const stream = response.stream();
const file = await Deno.open('path/to/file', { write: true, create: true });
await stream.pipeTo(file.writable);
```

```typescript
const response = await client.agents.downloadCallAudio(...);

const arrayBuffer = await response.arrayBuffer();
await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
```

```typescript
const response = await client.agents.downloadCallAudio(...);

const blob = await response.blob();
const arrayBuffer = await blob.arrayBuffer();
await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
```

```typescript
const response = await client.agents.downloadCallAudio(...);

const bytes = await response.bytes();
await Deno.writeFile('path/to/file', bytes);
```

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

### Get Specific Agent Call

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Retrieves the details of a specific agent call.

```APIDOC
## GET /agents/calls/{callId}

### Description
Retrieves the details of a specific agent call.

### Method
GET

### Endpoint
/agents/calls/{callId}

### Parameters
#### Path Parameters
- **callId** (string) - Required - The ID of the call.

#### Query Parameters
- **requestOptions** (Agents.RequestOptions) - Optional - Options for the request.

### Response
#### Success Response (200)
- **response** (Cartesia.AgentCall) - The details of the specified agent call.

### Request Example
```typescript
await client.agents.getCall("ac_abc123");
```

### Response Example
(Response structure depends on Cartesia.AgentCall)
```

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

### Get API Status - TypeScript

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Retrieves the current status and information about the Cartesia API. This function does not require any parameters other than optional request options.

```typescript
await client.apiStatus.get();
```

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

### Trigger File Download in Browser

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

Shows how to trigger a file download in a browser environment using a `Blob`. This method is efficient for client-side downloads.

```typescript
const response = await client.agents.downloadCallAudio(...);

const blob = await response.blob();
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
```

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

### Get Specific Agent Call Details in Cartesia JS

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Retrieves the details of a specific agent call using its unique call ID.

```typescript
await client.agents.getCall("ac_abc123");
```

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

### Save Binary Response to File in Bun

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

Illustrates how to save binary responses to a file using Bun. It supports saving directly from `ReadableStream`, `ArrayBuffer`, `Blob`, and `Uint8Array`.

```typescript
const response = await client.agents.downloadCallAudio(...);

const stream = response.stream();
await Bun.write('path/to/file', stream);
```

```typescript
const response = await client.agents.downloadCallAudio(...);

const arrayBuffer = await response.arrayBuffer();
await Bun.write('path/to/file', arrayBuffer);
```

```typescript
const response = await client.agents.downloadCallAudio(...);

const blob = await response.blob();
await Bun.write('path/to/file', blob);
```

```typescript
const response = await client.agents.downloadCallAudio(...);

const bytes = await response.bytes();
await Bun.write('path/to/file', bytes);
```

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

### POST /infill/bytes

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Generates audio that smoothly connects two existing audio segments. This is useful for inserting new speech between existing speech segments while maintaining natural transitions. The cost is 1 credit per character of the infill text plus a fixed cost of 300 credits. Infilling is only available on `sonic-2`.

```APIDOC
## POST /infill/bytes

### Description
Generates audio that smoothly connects two existing audio segments. This is useful for inserting new speech between existing speech segments while maintaining natural transitions.

**The cost is 1 credit per character of the infill text plus a fixed cost of 300 credits.**

Infilling is only available on `sonic-2` at this time.

At least one of `left_audio` or `right_audio` must be provided.

### Method
POST

### Endpoint
/infill/bytes

### Parameters
#### Request Body
- **leftAudio** (stream) - Optional - The left audio segment.
- **rightAudio** (stream) - Optional - The right audio segment.
- **modelId** (string) - Required - The model ID to use (e.g., "sonic-2").
- **language** (string) - Required - The language of the transcript.
- **transcript** (string) - Required - The text to be infilled.
- **voiceId** (string) - Required - The ID of the voice to use.
- **outputFormatContainer** (string) - Optional - The container format for the output audio (e.g., "mp3").
- **outputFormatSampleRate** (integer) - Optional - The sample rate for the output audio.
- **outputFormatBitRate** (integer) - Optional - The bit rate for the output audio.

### Request Example
```json
{
  "leftAudio": "<stream>",
  "rightAudio": "<stream>",
  "modelId": "sonic-2",
  "language": "en",
  "transcript": "middle segment",
  "voiceId": "694f9389-aac1-45b6-b726-9d9369183238",
  "outputFormatContainer": "mp3",
  "outputFormatSampleRate": 44100,
  "outputFormatBitRate": 128000
}
```

### Response
#### Success Response (200)
- **audio** (binary) - The generated infill audio.

#### Response Example
(Binary audio data)
```

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

### POST /fine-tunes

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Creates a new fine-tune with the specified parameters. This allows for custom model training.

```APIDOC
## POST /fine-tunes

### Description
Creates a new fine-tune with the specified parameters. This allows for custom model training.

### Method
POST

### Endpoint
/fine-tunes

### Parameters
#### Request Body
- **name** (string) - Required - The name of the fine-tune.
- **description** (string) - Optional - A description for the fine-tune.
- **language** (string) - Required - The language of the dataset.
- **modelId** (string) - Required - The ID of the base model to use.
- **dataset** (string) - Required - The dataset to use for fine-tuning.

### Request Example
```json
{
  "name": "name",
  "description": "description",
  "language": "language",
  "modelId": "model_id",
  "dataset": "dataset"
}
```

### Response
#### Success Response (200)
- **fineTune** (object) - Details of the created fine-tune.

#### Response Example
```json
{
  "fineTune": { ... }
}
```
```

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

### Get Specific Agent Metric by ID - TypeScript

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Retrieves a single metric by its unique identifier. This function is essential for accessing the details of a specific metric, identified by `metricId`.

```typescript
await client.agents.getMetric("am_abc123");
```

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

### Download Audio Response as ArrayBuffer in JavaScript

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

This code shows how to download an audio response as an ArrayBuffer, convert it to a Blob, and initiate a file download. It fetches the response, converts it to an ArrayBuffer, creates a Blob from the buffer, generates an object URL, and triggers the download. Remember to call URL.revokeObjectURL() to release the object URL.

```javascript
const response = await client.agents.downloadCallAudio(...);

const arrayBuffer = await response.arrayBuffer();
const blob = new Blob([arrayBuffer]);
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
```

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

### Get Agent Deployment by ID - TypeScript

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Fetches a specific deployment for an agent using its unique deploymentId. The function requires the deploymentId as a string and supports optional request options.

```typescript
await client.agents.getDeployment("ad_abc123");
```

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

### Create Fine-Tune using Cartesia API

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Creates a new fine-tune for audio models. Requires specifying name, description, language, model ID, and dataset. The request body is of type Cartesia.CreateFineTuneRequest.

```typescript
await client.fineTunes.create({
    name: "name",
    description: "description",
    language: "language",
    modelId: "model_id",
    dataset: "dataset",
});
```

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

### Pagination

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

Demonstrates how to handle paginated list endpoints using the Cartesia JS SDK, providing both automatic iteration and manual page-by-page control.

```APIDOC
## Pagination

List endpoints are paginated. The SDK provides an iterator so that you can simply loop over the items:

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

const client = new CartesiaClient({ token: "YOUR_TOKEN" });
const response = await client.agents.listCalls({
    agentId: "agent_id",
});
for await (const item of response) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.agents.listCalls({
    agentId: "agent_id",
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}
```
```

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

### Get Voice - Cartesia JS

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Retrieves a specific voice by its ID. This is a simple read operation requiring the voice ID and optional request options. Dependencies include the Cartesia client.

```typescript
await client.voices.get("id");
```

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

### Get Specific Agent Details in Cartesia JS

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Retrieves the details of a specific agent using its unique ID. Agent creation is recommended via CLI or Playground for optimal integration.

```typescript
await client.agents.get("agent_123");
```

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

### Consume Binary Response in TypeScript

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

Demonstrates how to consume binary data from an endpoint using `BinaryResponse`. It shows methods like `.stream()`, `.arrayBuffer()`, `.blob()`, and `.bytes()`. Note that the response body can only be consumed once.

```typescript
const response = await client.agents.downloadCallAudio(...);
const stream: ReadableStream<Uint8Array> = response.stream();
// const arrayBuffer: ArrayBuffer = await response.arrayBuffer();
// const blob: Blob = response.blob();
// const bytes: Uint8Array = response.bytes();
// You can only use the response body once, so you must choose one of the above methods.
// If you want to check if the response body has been used, you can use the following property.
const bodyUsed = response.bodyUsed;
```

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

### Create a Dataset with Cartesia JS

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Creates a new dataset using the Cartesia JavaScript client. Requires a name and description for the dataset. It accepts optional request options for fine-grained control over the request.

```typescript
await client.datasets.create({
    name: "name",
    description: "description",
});
```

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

### Get Agent Phone Numbers - TypeScript

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Retrieves the phone numbers associated with a specific agent. Requires an agent ID as input. This function is part of the Cartesia JS SDK's agent management capabilities.

```typescript
await client.agents.phoneNumbers("agent_demo");
```

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

### Manage AI Agents (TypeScript)

Source: https://context7.com/cartesia-ai/cartesia-js/llms.txt

This snippet shows how to manage AI agents using the Cartesia JS SDK. It covers listing agents, retrieving specific agent details, updating agent configurations, and listing available agent templates. It requires the Cartesia JS SDK and a valid API key.

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

const client = new CartesiaClient({ token: process.env.CARTESIA_API_KEY });

async function manageAgents() {
    // List all agents
    const agents = await client.agents.list();
    console.log("Available agents:", agents.data.length);

    agents.data.forEach(agent => {
        console.log(`- ${agent.name} (ID: ${agent.id})`);
        console.log(`  Status: ${agent.status}`);
        console.log(`  Voice: ${agent.ttsVoice}`);
    });

    // Get specific agent details
    const agent = await client.agents.get("agent_123");
    console.log("\nAgent details:");
    console.log("Name:", agent.name);
    console.log("System Prompt:", agent.systemPrompt);
    console.log("TTS Voice:", agent.ttsVoice);
    console.log("TTS Language:", agent.ttsLanguage);

    // Update agent configuration
    const updated = await client.agents.update("agent_123", {
        ttsVoice: "694f9389-aac1-45b6-b726-9d9369183238",
        ttsLanguage: "en"
    });
    console.log("Agent updated:", updated.name);

    // List agent templates for quick setup
    const templates = await client.agents.templates();
    console.log("\nAvailable templates:");
    templates.data.forEach(template => {
        console.log(`- ${template.name}: ${template.description}`);
    });
}

manageAgents();

```

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

### Configure Request Timeout in TypeScript

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

This TypeScript example shows how to set a custom timeout for API requests. The SDK has a default timeout of 60 seconds, but you can adjust this using the `timeoutInSeconds` option in the request configuration. This allows you to control how long the SDK waits for a response before timing out.

```typescript
const response = await client.tts.bytes(..., {
    timeoutInSeconds: 30 // override timeout to 30s
});
```

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

### Customize Fetch Client in Cartesia.js

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

Shows how to customize the underlying HTTP client or Fetch function used by the Cartesia.js SDK. This is useful for environments where the default fetch implementation might not be compatible or when specific fetch behavior is required.

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

const client = new CartesiaClient({
    ...
    fetcher: // provide your implementation here
});
```

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

### Send Additional Query Parameters in API Requests with TypeScript

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/README.md

This TypeScript example demonstrates how to append custom query string parameters to an API request. The `queryParams` option in the request configuration allows you to provide an object where keys and values are directly translated into URL query parameters. This is helpful for filtering or modifying requests.

```typescript
const response = await client.tts.bytes(..., {
    queryParams: {
        'customQueryParamKey': 'custom query param value'
    }
});
```

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

### Text-to-Speech WebSocket Streaming with Cartesia JS

Source: https://context7.com/cartesia-ai/cartesia-js/llms.txt

Implements low-latency bidirectional Text-to-Speech streaming using WebSockets. It supports context management for natural conversation flow and provides word-level timestamps. Requires the '@cartesia/cartesia-js' library and a Cartesia API key.

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

const client = new CartesiaClient({ token: process.env.CARTESIA_API_KEY });

async function websocketTTS() {
    // Create WebSocket connection
    const ws = await client.tts.websocket({
        container: "raw",
        encoding: "pcm_f32le",
        sampleRate: 44100
    });

    // Send first message with context
    const stream1 = await ws.send({
        modelId: "sonic-2",
        voice: { mode: "id", id: "694f9389-aac1-45b6-b726-9d9369183238" },
        transcript: "Hello! This is the first part of our conversation.",
        contextId: "conversation-123",
        addTimestamps: true,
        language: "en"
    });

    // Handle audio and timestamps
    stream1.on("message", (msg) => console.log("Message:", msg));
    stream1.on("timestamps", (timestamps) => {
        timestamps.words.forEach(word => {
            console.log(`Word: "${word.word}" at ${word.start}s - ${word.end}s`);
        });
    });

    // Wait for audio source to be ready
    await stream1.source.waitUntilReady();
    console.log("Audio stream ready for playback");

    // Continue conversation with same context for natural flow
    await ws.continue({
        modelId: "sonic-2",
        voice: { mode: "id", id: "694f9389-aac1-45b6-b726-9d9369183238" },
        transcript: "And this is the continuation with the same voice context.",
        contextId: "conversation-123",
        language: "en"
    });

    // Cancel specific context if needed
    await ws.cancel({ contextId: "conversation-123" });

    // Disconnect when done
    ws.disconnect();
}

websocketTTS().catch(console.error);
```

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

### Text-to-Speech Synthesis (Bytes)

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Synthesize speech from text and return the audio as a binary response. Supports various output formats and sample rates.

```APIDOC
## POST /tts/bytes

### Description
Synthesizes speech from text and returns the audio as a binary response. Supports various output formats and sample rates.

### Method
POST

### Endpoint
/tts/bytes

### Parameters
#### Request Body
- **modelId** (string) - Required - The ID of the TTS model to use (e.g., "sonic-2").
- **transcript** (string) - Required - The text to synthesize into speech.
- **voice** (object) - Required - Voice configuration.
  - **mode** (string) - Required - Mode of voice selection ('id' or 'name').
  - **id** (string) - Required if mode is 'id' - The ID of the voice.
  - **name** (string) - Required if mode is 'name' - The name of the voice.
- **language** (string) - Required - The language of the transcript (e.g., "en").
- **outputFormat** (object) - Required - The desired output audio format.
  - **container** (string) - Required - The audio container format (e.g., "mp3", "wav").
  - **sampleRate** (number) - Required - The sample rate of the audio (e.g., 44100).
  - **bitRate** (number) - Optional - The bit rate of the audio (e.g., 128000).

### Request Example
```typescript
await client.tts.bytes({
    modelId: "sonic-2",
    transcript: "Hello, world!",
    voice: {
        mode: "id",
        id: "694f9389-aac1-45b6-b726-9d9369183238",
    },
    language: "en",
    outputFormat: {
        container: "mp3",
        sampleRate: 44100,
        bitRate: 128000,
    },
});
```

### Response
#### Success Response (200)
- **audio_data** (binary) - The synthesized speech as binary audio data.
```

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

### Create a Fine-Tune with Cartesia JS

Source: https://github.com/cartesia-ai/cartesia-js/blob/main/reference.md

Creates a new fine-tune job using the Cartesia JavaScript client. This operation requires specific parameters defined in `Cartesia.FineTuneRequest` and accepts optional request options.