# Streaming HTTP
Source: https://docs.rime.ai/api-reference/coda/http

POST https://users.rime.ai/v1/rime-tts
Coda streaming HTTP endpoint: synthesize speech with Rime's flagship model and stream audio back.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

The endpoint streams audio in the format you name in the `Accept` header. If `Accept` is missing or a wildcard, the API streams headerless 16-bit PCM, which audio players won't open. If it names a type the API can't stream, the API returns `406` with the list of supported types.

## Audio formats

Set the `Accept` header to one of the following values:

| Format | Accept Header | Notes |
| - | - | - |
| Opus (WebM) | `audio/webm;codecs=opus` | Recommended. Smaller files than MP3 at comparable quality. WebM streams natively in browsers. |
| Opus (OGG) | `audio/ogg;codecs=opus` | Opus in an OGG container. Smaller files than MP3 at comparable quality. |
| MP3 | `audio/mpeg` | Lower compression rate than Opus. Highest compatibility across devices and players. |
| WAV | `audio/wav` | Uncompressed. RIFF WAVE header with 16-bit little-endian linear PCM samples. Streams natively in browsers. |
| PCM | `audio/L16` | Headerless 16-bit little-endian linear PCM. |
| G.711 μ-law | `audio/PCMU` | Headerless stream of audio bytes. |

### Deprecated aliases

The API still accepts these for backward compatibility. Use the RFC types above in new code.

| Deprecated | Use instead |
| - | - |
| `audio/mp3` | `audio/mpeg` |
| `audio/pcm` | `audio/L16` |
| `audio/x-mulaw` | `audio/PCMU` |

## Variable parameters

<ParamField type="string">
  Must be a Coda voice. See the [voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  The text you'd like spoken. The API accepts up to 1,000 characters per request.
</ParamField>

<ParamField type="string">
  Set to `coda` to select the Coda voice lineup. Without it, the API uses Mist v3.
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the provided speaker. Pass a BCP 47 language tag:

  | Tag | Language |
  | - | - |
  | `en` | English |
  | `es` | Spanish |
  | `fr` | French |
  | `pt` | Portuguese |
  | `de` | German |
  | `ja` | Japanese |
  | `ar` | Arabic |
  | `hi` | Hindi |
  | `it` | Italian |

  The 3-letter ISO 639-2 codes that older integrations send (`eng`, `spa`, `fra`, `por`, `ger`, `jpn`, `ara`, `hin`, `ita`) remain accepted, and will stay accepted.

  See [the voices documentation](/docs/voices) for which speakers support each language.
</ParamField>

<ParamField type="number">
  The sampling rate (Hz).
</ParamField>

<ParamField type="number">
  The time scaling factor. Accepted range is 0.4 to 2.5. Values outside this range are clamped without an error.

  Values above 1.0 slow the audio down, and values below 1.0 speed it up.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://users.rime.ai/v1/rime-tts \
    --header 'Accept: audio/webm;codecs=opus' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --output output.webm \
    --fail \
    --data '{
    "text": "Hello from Rime!",
    "modelId": "coda",
    "speaker": "astra",
    "lang": "en",
    "samplingRate": 24000
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://users.rime.ai/v1/rime-tts"

  payload = {
      "speaker": "astra",
      "text": "Hello from Rime!",
      "modelId": "coda",
      "samplingRate": 24000
  }
  headers = {
      "Accept": "audio/webm;codecs=opus",
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  with requests.post(url, headers=headers, json=payload, stream=True) as response:
      response.raise_for_status()
      with open("output.webm", "wb") as f:
          for chunk in response.iter_content(chunk_size=4096):
              if chunk:
                  f.write(chunk)
  ```

  ```javascript JavaScript theme={null}
  const fs = require("fs");

  const options = {
    method: 'POST',
    headers: {
      Accept: 'audio/webm;codecs=opus',
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: '{"speaker":"astra","text":"Hello from Rime!","modelId":"coda","samplingRate":24000}'
  };

  fetch('https://users.rime.ai/v1/rime-tts', options)
    .then(response => response.arrayBuffer())
    .then(buffer => {
      fs.writeFileSync("output.webm", Buffer.from(buffer));
      console.log("Audio saved to output.webm");
    })
    .catch(err => console.error(err));
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://users.rime.ai/v1/rime-tts",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"coda\",\n  \"samplingRate\": 24000\n}",
    CURLOPT_HTTPHEADER => [
      "Accept: audio/webm;codecs=opus",
      "Authorization: Bearer YOUR_API_KEY",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```go Go theme={null}
  package main

  import (
    "io"
    "net/http"
    "os"
    "strings"
  )

  func main() {

    url := "https://users.rime.ai/v1/rime-tts"

    payload := strings.NewReader("{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"coda\",\n  \"samplingRate\": 24000\n}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("Accept", "audio/webm;codecs=opus")
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)

    _ = os.WriteFile("output.webm", body, 0644)
  }
  ```

  ```java Java theme={null}
  HttpResponse<byte[]> response = Unirest.post("https://users.rime.ai/v1/rime-tts")
    .header("Accept", "audio/webm;codecs=opus")
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .body("{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"coda\",\n  \"samplingRate\": 24000\n}")
    .asBytes();
  Files.write(Paths.get("output.webm"), response.getBody());
  ```
</RequestExample>


# Websockets
Source: https://docs.rime.ai/api-reference/coda/websockets

GET wss://users-ws.rime.ai/ws
Coda plain-text WebSocket (/ws): send text, receive raw audio bytes.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

<Warning>Include `modelId=coda` in the connection query. If you omit it, the server routes the request to Mist v3 and speakers outside the Mist v3 catalog can fail with `Speaker not found`.</Warning>

## Overview

Rime's websocket implementation accepts bare text, and responds with audio bytes of the selected format. All synthesis arguments are provided as query parameters when establishing the connection.

## Messages

### Send

The messages your client will send to the websocket API will be bare (non-serialized) text.

```example theme={null}
This will be converted to audio via websockets
```

### Receive

The messages your client will receive will be raw audio bytes in the audio format specified at connection time.

```example theme={null}
<FF>^@^@^@9LAME3.100^AP^@^@^@^@^@^@^@^@^T<A0>$^D>"^@^@<A0>^@^@<A8><C0><BA><9D>G^N^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@
^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@
^@^@^@^@^@^@^@^@^@^@
```

## Commands

Use these commands to manipulate the stored text buffer.

### `<CLEAR>`

This clears the current buffer. Used in the event of interruptions.

### `<FLUSH>`

This forces whatever buffer exists, if any, to be synthesized, and the generated audio to be sent over.

### `<EOS>`

This forces whatever buffer exists, if any, to be synthesized, and for the server to close the connection after sending the generated audio.

## Variable parameters

<ParamField type="string">
  Must be a `coda` voice from the <a href="/docs/voices">Rime voice catalog</a>.
</ParamField>

<ParamField type="string">
  The text you'd like spoken. Character limit per request is 1,000 via the API and in the dashboard UI.
</ParamField>

<ParamField type="string">
  Set this to `coda`. It is not strictly required, but if you omit it the server defaults to the Mist v3 backend, and speakers outside the Mist v3 catalog fail with a "Speaker not found" error.
</ParamField>

<ParamField type="string">
  One of `wav`, `mp3` (or `mpeg`), `ogg` (Opus in OGG), `webm` (Opus in WebM), `pcm` (or `l16`), or `mulaw` (or `pcmu`). Unrecognized values fall back to `wav`.
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the provided speaker. Both the 2-letter ISO 639-1 and the 3-letter ISO 639-2/3 form are accepted:

  | 639-1 | 639-2/3 | Language |
  | - | - | - |
  | `en` | `eng` | English |
  | `es` | `spa` | Spanish |
  | `fr` | `fra` | French |
  | `pt` | `por` | Portuguese |
  | `de` | `ger` | German |
  | `ja` | `jpn` | Japanese |
  | `ar` | `ara` | Arabic |
  | `hi` | `hin` | Hindi |

  See <a href="/docs/voices">the voices documentation</a> for which speakers support each language.
</ParamField>

<ParamField type="int">
  The sampling rate in Hz. Any positive integer is accepted; values above the model's native rate are upsampled. Common choices are 8000 (telephony), 16000, 22050, 24000, and 44100.
</ParamField>

<ParamField type="string">
  Controls how text is segmented for synthesis. Available options:

  * "immediate" - Synthesizes text immediately without waiting for complete sentences
  * "never" - Never segments the text, waits for explicit flush or EOS
  * "bySentence" (default) - Waits for complete sentences before synthesis

  Note: For backward compatibility, setting `immediate=true` in query params is equivalent to `segment=immediate`. If a null value is provided, it will default to "bySentence".
</ParamField>

<RequestExample>
  ```python Python theme={null}
  import asyncio
  import websockets
  import os
  from dotenv import load_dotenv

  load_dotenv()
  api_key = os.environ.get('RIME_API_KEY')
  if not api_key:
      raise ValueError("RIME_API_KEY environment variable is not set")

  FILE_PATH = "coda_ws.wav"

  class RimeClient:
      def __init__(self, speaker, api_key):
          self.url = f"wss://users-ws.rime.ai/ws?speaker={speaker}&modelId=coda&audioFormat=wav"
          self.auth_headers = {
              "Authorization": f"Bearer {api_key}"
          }
          self.audio_data = b''

      async def send_tokens(self, websocket, message):
          for token in message:
              await websocket.send(token)

      async def handle_audio(self, websocket):
          while True:
              try:
                  audio = await websocket.recv()
              except websockets.exceptions.ConnectionClosedOK:
                  break
              self.audio_data += audio

      async def run(self, message):
          async with websockets.connect(self.url, additional_headers=self.auth_headers) as websocket:
              await asyncio.gather(
                  self.send_tokens(websocket, message),
                  self.handle_audio(websocket),
              )

      def save_audio(self, file_path):
          with open(file_path, 'wb') as f:
              f.write(self.audio_data)

  message = [
      "This ",
      "is ",
      "a ",
      "test ",
      "of ",
      "the ",
      "coda ",
      "model ",
      "using ",
      "websockets ",
      "and ",
      "python.",
      "<EOS>",
  ]

  client = RimeClient("astra", api_key=api_key)
  asyncio.run(client.run(message))

  print(f"Saving audio to {FILE_PATH}")
  client.save_audio(FILE_PATH)
  ```
</RequestExample>


# Websockets JSON
Source: https://docs.rime.ai/api-reference/coda/websockets-json

GET wss://users-ws.rime.ai/ws3
Coda JSON WebSocket (/ws3): structured events with base64 audio chunks and word-level timestamps.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

<Warning>Include `modelId=coda` in the connection query. If you omit it, the server routes the request to Mist v3 and speakers outside the Mist v3 catalog can fail with `Speaker not found`.</Warning>

## Overview

In addition to a plaintext websocket implementation,
Rime also has an implementation that sends and receives events as JSON objects.
Like the other implementation, all synthesis arguments are provided as query
parameters when establishing the connection.

The WebSocket API buffers inputs up to one of the following punctuation
characters: `.`, `?`, `!`. This is most pertinent for the initial messages
sent to the API, as synthesis won't begin until there are sufficient
tokens to generate audio with natural prosody. After the first synthesis
of any given utterance, typically enough time has elapsed that subsequent
audio contains multiple clauses, and the buffering becomes largely invisible.

## Messages

### Send

#### Text

This is the most common message, which contains text for synthesis.

schema:

```typescript theme={null}
type TextMessage = {
  text: string,
  contextId?: string,
}
```

examples:

```json theme={null}
{
    "text": "this is the minimum text message."
}

{
    "text": "this is a text message with a context id.",
    "contextId": "159495B1-5C81-4C73-A51A-9CE10A08239E"
}
```

Context IDs can be provided, which will be attached to subsequent messages
that the server sends back to the client. Rime will not maintain multiple
simultaneous context IDs. The events will contain the most recent context ID
at the time that audio was requested. In the above examples, even if both
messages are received by the server before it sends any audio, the audio
response for the first sentence will be tagged with `contextId: null`,
and the audio for the second will be tagged with its UUID.

#### Clear

Your client can clear out the accumulated buffer, which is useful in the case of interruptions.

```json theme={null}
{ "operation": "clear" }
```

#### Flush

This forces whatever buffer exists, if any, to be synthesized, and the generated audio to be sent over.

```json theme={null}
{ "operation": "flush" }
```

#### EOS

At times, your client would like to generate audio for whatever
remains in the buffer, and then have the connection immediately closed.

```json theme={null}
{ "operation" : "eos" }
```

### Receive

#### Chunk

The most common event will be the audio chunk.

```typescript theme={null}
type Base64String = string

type AudioChunkEvent = {
  type: "chunk",
  data: Base64String,
  contextId: string | null,
}
```

The audio will be a base64 encoded chunk of audio bytes in the audio format specified
when the connection was established. If you provided any context id when sending the relevant text, it'll be included here.

#### Timestamps

Word-level timestamps are emitted alongside the audio chunks so the client can tell exactly which words have been spoken at any point. This is especially useful for handling interruptions: when the user starts talking over the output, you can map the playback position back to the last word that was actually heard.

<Warning>Timestamps are emitted only when `lang` is `en`/`eng` or `es`/`spa`, or when `lang` is omitted. Requests in any other language receive `chunk` and `done` events with no `timestamps` event and no error (this includes fr, de, ja, pt, ar, and hi). Do not block playback while waiting for a timestamps event.</Warning>

```typescript theme={null}
type TimestampsEvent = {
  type: "timestamps",
  word_timestamps: {
    words: string[],
    start: number[],
    end: number[],
  },
  contextId: string | null,
}
```

The three arrays inside `word_timestamps` are the same length and index-aligned: for a given index `i`, `words[i]` is spoken from `start[i]` to `end[i]`. Times are in seconds, measured from the beginning of the audio for the current synthesis. If a context id was attached to the text that produced this audio, it is included on the event.

Example payload:

```json theme={null}
{
  "type": "timestamps",
  "word_timestamps": {
    "words": ["Hello", "from", "Coda", "over", "JSON", "websockets."],
    "start": [0, 0.36106, 0.54159, 0.72212, 0.90265, 1.08318],
    "end":   [0.36106, 0.54159, 0.72212, 0.90265, 1.08318, 2.88848]
  },
  "contextId": null
}
```

#### Done

After the last audio chunk for a synthesis batch has been sent, the server emits a `done` event. This signals that the current synthesis is fully complete. If the client sends more text and triggers further synthesis, another `done` will follow.

```typescript theme={null}
type DoneEvent = {
  type: "done",
  contextId: string | null,
}
```

When exactly `done` fires depends on the `segment` setting. See [Segmentation and behavior settings](/docs/websockets-segment) for full details.

#### Error

In the event of a malformed or unexpected input, the server will immediately respond with an error message.
The server will *not* close the connection, and will still accept subsequent well-formed messages.
It's up to the client to decide if it wants to close upon receiving an error.

```typescript theme={null}
type ErrorEvent = {
  type: "error",
  message: string,
}
```

## Variable parameters

<ParamField type="string">
  Must be a `coda` voice from the <a href="/docs/voices">Rime voice catalog</a>.
</ParamField>

<ParamField type="string">
  The text you'd like spoken. Character limit per request is 1,000 via the API and in the dashboard UI.
</ParamField>

<ParamField type="string">
  Set this to `coda`. It is not strictly required, but if you omit it the server defaults to the Mist v3 backend, and speakers outside the Mist v3 catalog fail with a "Speaker not found" error.
</ParamField>

<ParamField type="string">
  One of `wav`, `mp3` (or `mpeg`), `ogg` (Opus in OGG), `webm` (Opus in WebM), `pcm` (or `l16`), or `mulaw` (or `pcmu`). Unrecognized values fall back to `wav`.
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the provided speaker. Pass a BCP 47 language tag:

  | Tag | Language |
  | - | - |
  | `en` | English |
  | `es` | Spanish |
  | `fr` | French |
  | `pt` | Portuguese |
  | `de` | German |
  | `ja` | Japanese |
  | `ar` | Arabic |
  | `hi` | Hindi |
  | `it` | Italian |

  The 3-letter ISO 639-2 codes that older integrations send (`eng`, `spa`, `fra`, `por`, `ger`, `jpn`, `ara`, `hin`, `ita`) remain accepted, and will stay accepted.

  See <a href="/docs/voices">the voices documentation</a> for which speakers support each language.
</ParamField>

<ParamField type="int">
  The sampling rate in Hz. Any positive integer is accepted; values above the model's native rate are upsampled. Common choices are 8000 (telephony), 16000, 22050, 24000, and 44100.
</ParamField>

<ParamField type="string">
  Controls how text is segmented for synthesis. Available options:

  * "immediate" - Synthesizes text immediately without waiting for complete sentences
  * "never" - Never segments the text, waits for explicit flush or EOS
  * "bySentence" (default) - Waits for complete sentences before synthesis

  Note: For backward compatibility, setting `immediate=true` in query params is equivalent to `segment=immediate`. If a null value is provided, it will default to "bySentence".
</ParamField>

<RequestExample>
  ```python Python theme={null}
  import asyncio
  import json
  import websockets
  import base64

  class RimeClient:
      def __init__(self, speaker, api_key):
          self.url = f"wss://users-ws.rime.ai/ws3?speaker={speaker}&modelId=coda&audioFormat=mp3"
          self.auth_headers = {
              "Authorization": f"Bearer {api_key}"
          }
          self.audio_data = b''

      async def send_messages(self, websocket, messages):
          for message in messages:
              await websocket.send(json.dumps(message))

      async def handle_audio(self, websocket):
          while True:
              try:
                  audio = await websocket.recv()
              except websockets.exceptions.ConnectionClosedOK:
                  break
              message = json.loads(audio)

              if message['type'] == 'chunk':
                self.audio_data += base64.b64decode(message['data'])

              if message['type'] == 'timestamps':
                  print("Rime model pronounced the words...\n")
                  for w, t in zip(message['word_timestamps']['words'], message['word_timestamps']['start']):
                      print(f"'{w}' at time {t}")

      async def run(self, messages):
          async with websockets.connect(self.url, additional_headers=self.auth_headers) as websocket:
              await asyncio.gather(
                  self.send_messages(websocket, messages),
                  self.handle_audio(websocket),
              )

      def save_audio(self, file_path):
          with open(file_path, 'wb') as f:
              f.write(self.audio_data)
          print(f"\n Audio saved at {file_path}")


  message = [
      {"text": "This "},
      {"text": "is "},
      {"text": "a "},
      {"text": "test "},
      {"operation":"clear"},
      {"text": "This "},
      {"text": "is "},
      {"text": "an "},
      {"text": "incomplete "},
      {"text": "sentence "},
      {"operation": "eos"},
  ]

  client = RimeClient("astra", api_key="xxx")
  asyncio.run(client.run(message))

  client.save_audio("output.mp3")
  ```
</RequestExample>


# List Voice Details
Source: https://docs.rime.ai/api-reference/data/voice-details

GET https://users.rime.ai/data/voices/voice_details.json
Voice metadata endpoint: list every Rime voice with demographic and model details.

This is a public endpoint, so you don't need an `Authorization` header or API key.

<Note>The response can include legacy Arcana records and models hosted outside the Rime cloud API. Their presence does not mean the model is available through Rime cloud. Use [Coda or Mist](/docs/models) for cloud requests.</Note>

## View in browser

[https://users.rime.ai/data/voices/voice\_details.json](https://users.rime.ai/data/voices/voice_details.json)

## Description

The demographic fields are based on subjective assessment and are a general guide to each voice. Use them to narrow your choice. The only values you pass in a request are `speaker`, `modelId`, and `lang`.

See [Finding a Voice](/docs/voices) to choose a voice, and [Explanation of fields](#explanation-of-fields) for each field.

## Example structure

```json theme={null}
[
    {
        "speaker": "astra",
        "gender": "Female",
        "age": "Young Adult",
        "country": "US",
        "dialect": "Standard",
        "demographic": "White",
        "genre": [
            "Conversational, Customer Support, Narration"
        ],
        "modelId": "coda",
        "language": "English",
        "lang": "eng",
        "flagship": true
    },
    {
        "speaker": "cove",
        "gender": "Female",
        "age": "Young Adult",
        "country": "US",
        "dialect": "African American",
        "demographic": "Black",
        "genre": [
            "Customer Support"
        ],
        "modelId": "mistv3",
        "language": "English",
        "lang": "eng",
        "flagship": true
    },
    // and more...
]
```

## Explanation of fields

The response is an array with one object per voice. Each object contains the following fields:

* `speaker`: The voice name. Pass it as `speaker` in a request.
* `gender`: Indicates the gender of the voice.
* `age`: Describes the age group of the voice.
* `country`: The country that the voice is associated with, typically representing the accent or regional dialect.
* `dialect`: More specific than country, this field can indicate a particular area within a country.
* `demographic`: Describes the demographic group the voice represents.
* `genre`: An array of genres that the voice is suitable for, such as `Conversational`.
* `language`: The language the voice speaks.
* `lang`: The value to pass as `lang` so the voice speaks its language.
* `modelId`: The model the voice is available under. Pass it as `modelId` in a request.
* `flagship`: `true` for featured voices.


# List All Voices
Source: https://docs.rime.ai/api-reference/data/voices-v2

GET https://users.rime.ai/data/voices/all-v2.json
List every Rime voice, keyed by modelId and language.

This is a public endpoint, so you don't need an `Authorization` header or API key.

<Note>The response can include legacy Arcana records and models hosted outside the Rime cloud API. Their presence does not mean the model is available through Rime cloud. Use [Coda or Mist](/docs/models) for cloud requests.</Note>

## View in browser

[https://users.rime.ai/data/voices/all-v2.json](https://users.rime.ai/data/voices/all-v2.json)

## Example structure

```json theme={null}
{
  "coda": {
    "eng": [
      "astra",
      "albion",
      // ...and more...
    ],
    "spa": [
      "alba",
      "celestino",
      // ...and more...
    ]
  },
  "mistv3": {
    "eng": [
      "alexis",
      "astra",
      // ...and more...
    ],
    "spa": [
      "diego",
      "isa",
      // ...and more...
    ]
  }
}
```

## Explanation

The response is keyed by `modelId`, then by ISO 639-2 language code, and each entry lists the `speaker` values for that model and language. For current cloud models, pass the top-level key as `modelId` in a request to the [Rime TTS APIs](/docs/api-reference).


# Streaming HTTP
Source: https://docs.rime.ai/api-reference/mistv2/http

POST https://users.rime.ai/v1/rime-tts
Mist v2 streaming HTTP endpoint.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

The endpoint streams audio in the format you name in the `Accept` header. If `Accept` doesn't name a streamable audio type, for example because it's missing or set to `application/json`, Mist v2 returns the legacy JSON envelope instead, as described in [MP3 over JSON](/api-reference/mistv2/json-mp3).

## Audio formats

Set the `Accept` header to one of the following values:

| Format | Accept Header | Default Sampling Rate | Notes |
| - | - | - | - |
| MP3 | `audio/mpeg` | 22050 | |
| PCM | `audio/L16` | 16000 | Headerless 16-bit little-endian linear PCM. |
| G.711 μ-law | `audio/PCMU` | 8000 | Headerless stream of audio bytes. |

### Deprecated aliases

The API still accepts these for backward compatibility. Use the RFC types above in new code.

| Deprecated | Use instead |
| - | - |
| `audio/mp3` | `audio/mpeg` |
| `audio/pcm` | `audio/L16` |
| `audio/x-mulaw` | `audio/PCMU` |

## Variable parameters

<ParamField type="string">
  Must be a voice from the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  The text you'd like spoken. Character limit per request is 1,000 via the API and in the dashboard UI.
</ParamField>

<ParamField type="string">
  Set to `mistv2`.
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the selected speaker. Verify the pairing in the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="bool">
  When set to true, adds pauses between words enclosed in angle brackets. The number inside the brackets specifies the pause duration in milliseconds. <br />
  Example: "Hi. \<200> I'd love to have a conversation with you." adds a 200ms pause between the first and second sentences.
</ParamField>

<ParamField type="bool">
  When set to true, you can specify the phonemes for a word enclosed in curly brackets. <br />
  Example: "\{h'El.o} World" pronounces "Hello" with the phonemes you supplied. Learn more about [custom pronunciation](/docs/custom-pronunciation).
</ParamField>

<ParamField type="string">
  Comma-separated list of speed values applied to words in square brackets. Values \< 1.0 speed up speech, > 1.0 slow it down.
  Example: "This is \[slow] and \[fast]", use "3, 0.5" to make "slow" slower and "fast" faster.
</ParamField>

<ParamField type="int">
  The value, if provided, must be between 4000 and 44100. Default depends on format (see table above).
</ParamField>

<ParamField type="float">
  Adjusts the speed of speech. Lower than 1.0 is faster and higher than 1.0 is slower.

  *Note: this is the legacy Mist v2 convention. Coda and Mist v3 invert it, so for those models higher than 1.0 is faster.*
</ParamField>

<ParamField type="bool">
  **mist/mistv2 only.** Skips text normalization before synthesis. This reduces latency, but digits and abbreviations reach the model unexpanded and may be mispronounced.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://users.rime.ai/v1/rime-tts \
    --header 'Accept: audio/mpeg' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --output output.mp3 \
    --fail \
    --data '{
    "text": "Hello from Rime!",
    "modelId": "mistv2",
    "speaker": "astra",
    "lang": "eng",
    "samplingRate": 22050,
    "speedAlpha": 1.0
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://users.rime.ai/v1/rime-tts"

  payload = {
      "speaker": "astra",
      "text": "Hello from Rime!",
      "modelId": "mistv2",
      "lang": "eng",
      "samplingRate": 22050,
      "speedAlpha": 1.0
  }
  headers = {
      "Accept": "audio/mpeg",
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  with requests.post(url, headers=headers, json=payload, stream=True) as response:
      response.raise_for_status()
      with open("output.mp3", "wb") as f:
          for chunk in response.iter_content(chunk_size=4096):
              if chunk:
                  f.write(chunk)
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'POST',
    headers: {
      Accept: 'audio/mpeg',
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: '{"speaker":"astra","text":"Hello from Rime!","modelId":"mistv2","lang":"eng","samplingRate":22050,"speedAlpha":1.0}'
  };

  fetch('https://users.rime.ai/v1/rime-tts', options)
    .then(response => response.arrayBuffer())
    .then(buffer => {
      require("fs").writeFileSync("output.mp3", Buffer.from(buffer));
      console.log("Audio saved to output.mp3");
    })
    .catch(err => console.error(err));
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://users.rime.ai/v1/rime-tts",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv2\",\n  \"lang\": \"eng\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0\n}",
    CURLOPT_HTTPHEADER => [
      "Accept: audio/mpeg",
      "Authorization: Bearer YOUR_API_KEY",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```go Go theme={null}
  package main

  import (
    "io"
    "net/http"
    "os"
    "strings"
  )

  func main() {

    url := "https://users.rime.ai/v1/rime-tts"

    payload := strings.NewReader("{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv2\",\n  \"lang\": \"eng\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0\n}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("Accept", "audio/mpeg")
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)

    _ = os.WriteFile("output.mp3", body, 0644)
  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://users.rime.ai/v1/rime-tts")
    .header("Accept", "audio/mpeg")
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .body("{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv2\",\n  \"lang\": \"eng\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0\n}")
    .asString();
  ```
</RequestExample>


# MP3 over JSON
Source: https://docs.rime.ai/api-reference/mistv2/json-mp3

POST https://users.rime.ai/v1/rime-tts
Mist v2 non-streaming endpoint that returns base64 MP3 audio inside a JSON envelope.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

The API returns a single JSON object, `{"audioContent": "..."}`, whose `audioContent` field holds base64-encoded MP3 audio. Decode it before you save or play it. Only Mist v1 and Mist v2 return this envelope, and only when `Accept` doesn't name a streamable audio type, which is why the examples send `application/json`. The response arrives after synthesis finishes, so use [streaming HTTP](/api-reference/mistv2/http) if you want playback to start sooner.

## Fixed parameters

<ParamField type="mp3" />

## Variable parameters

<ParamField type="string">
  Must be a voice from the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  The text you'd like spoken. Character limit per request is 1,000 via the API and in the dashboard UI.
</ParamField>

<ParamField type="string">
  Set to `mistv2`.
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the selected speaker. Verify the pairing in the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="bool">
  When set to true, adds pauses between words enclosed in angle brackets. The number inside the brackets specifies the pause duration in milliseconds. <br />
  Example: "Hi. \<200> I'd love to have a conversation with you." adds a 200ms pause between the first and second sentences.
</ParamField>

<ParamField type="bool">
  When set to true, you can specify the phonemes for a word enclosed in curly brackets. <br />
  Example: "\{h'El.o} World" pronounces "Hello" with the phonemes you supplied. Learn more about [custom pronunciation](/docs/custom-pronunciation).
</ParamField>

<ParamField type="string">
  Comma-separated list of speed values applied to words in square brackets. Values \< 1.0 speed up speech, > 1.0 slow it down.
  Example: For text "This is \[slow] and \[fast]", use "3, 0.5" to make "slow" slower and "fast" faster.
</ParamField>

<ParamField type="int">
  The value, if provided, must be between 4000 and 44100. Default: 22050
</ParamField>

<ParamField type="float">
  Adjusts the speed of speech. Lower than 1.0 is faster and higher than 1.0 is slower.

  *Note: this is the legacy Mist v2 convention. Coda and Mist v3 invert it, so for those models higher than 1.0 is faster.*
</ParamField>

<ParamField type="bool">
  **mist/mistv2 only.** Skips text normalization before synthesis. This reduces latency, but digits and abbreviations reach the model unexpanded and may be mispronounced.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://users.rime.ai/v1/rime-tts \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --output output.json \
    --fail \
    --data '{
    "text": "Hello from Rime!",
    "modelId": "mistv2",
    "speaker": "astra",
    "lang": "eng",
    "audioFormat": "mp3",
    "inlineSpeedAlpha": "0.5, 3",
    "noTextNormalization": false,
    "pauseBetweenBrackets": false,
    "phonemizeBetweenBrackets": false,
    "samplingRate": 22050,
    "speedAlpha": 1.0
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://users.rime.ai/v1/rime-tts"

  payload = {
      "speaker": "astra",
      "text": "Hello from Rime!",
      "modelId": "mistv2",
      "lang": "eng",
      "audioFormat": "mp3",
      "samplingRate": 22050,
      "speedAlpha": 1.0,
      "noTextNormalization": False
  }
  headers = {
      "Accept": "application/json",
      "Authorization": "Bearer <authorization>",
      "Content-Type": "application/json"
  }

  response = requests.request("POST", url, json=payload, headers=headers)

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      Authorization: 'Bearer <authorization>',
      'Content-Type': 'application/json'
    },
    body: '{"speaker":"astra","text":"Hello from Rime!", "modelId": "mistv2", "lang": "eng", "audioFormat": "mp3", "samplingRate":22050,"speedAlpha":1.0,"noTextNormalization":false}'
  };

  fetch('https://users.rime.ai/v1/rime-tts', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://users.rime.ai/v1/rime-tts",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\":\"mistv2\",\n  \"lang\":\"eng\",\n \"audioFormat\": \"mp3\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}",
    CURLOPT_HTTPHEADER => [
      "Accept: application/json",
      "Authorization: Bearer <authorization>",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
  )

  func main() {

    url := "https://users.rime.ai/v1/rime-tts"

    payload := strings.NewReader("{\n  \"speaker\": \"astra\",\n  \"modelId\": \"mistv2\",\n  \"text\": \"Hello from Rime!\",\n  \"lang\": \"eng\",\n \"audioFormat\": \"mp3\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("Accept", "application/json")
    req.Header.Add("Authorization", "Bearer <authorization>")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://users.rime.ai/v1/rime-tts")
    .header("Accept", "application/json")
    .header("Authorization", "Bearer <authorization>")
    .header("Content-Type", "application/json")
    .body("{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv2\",\n  \"lang\": \"eng\",\n  \"audioFormat\": \"mp3\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}")
    .asString();
  ```
</RequestExample>


# μ-law over JSON
Source: https://docs.rime.ai/api-reference/mistv2/json-mulaw

POST https://users.rime.ai/v1/rime-tts
Mist v2 non-streaming endpoint that returns base64 G.711 μ-law audio inside a JSON envelope.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

The API returns a single JSON object, `{"audioContent": "..."}`, whose `audioContent` field holds base64-encoded G.711 μ-law audio. Decode it before you save or play it. Only Mist v1 and Mist v2 return this envelope, and only when `Accept` doesn't name a streamable audio type, which is why the examples send `application/json`. The response arrives after synthesis finishes, so use [streaming HTTP](/api-reference/mistv2/http) if you want playback to start sooner.

## Fixed parameters

<ParamField type="mulaw" />

## Variable parameters

<ParamField type="string">
  Must be a voice from the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  The text you'd like spoken. Character limit per request is 1,000 via the API and in the dashboard UI.
</ParamField>

<ParamField type="string">
  Set to `mistv2`.
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the selected speaker. Verify the pairing in the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="bool">
  When set to true, adds pauses between words enclosed in angle brackets. The number inside the brackets specifies the pause duration in milliseconds. <br />
  Example: "Hi. \<200> I'd love to have a conversation with you." adds a 200ms pause between the first and second sentences.
</ParamField>

<ParamField type="bool">
  When set to true, you can specify the phonemes for a word enclosed in curly brackets. <br />
  Example: "\{h'El.o} World" pronounces "Hello" with the phonemes you supplied. Learn more about [custom pronunciation](/docs/custom-pronunciation).
</ParamField>

<ParamField type="string">
  Comma-separated list of speed values applied to words in square brackets. Values \< 1.0 speed up speech, > 1.0 slow it down.
  Example: "This is \[slow] and \[fast]", use "3, 0.5" to make "slow" slower and "fast" faster.
</ParamField>

<ParamField type="float">
  Adjusts the speed of speech. Lower than 1.0 is faster and higher than 1.0 is slower.

  *Note: this is the legacy Mist v2 convention. Coda and Mist v3 invert it, so for those models higher than 1.0 is faster.*
</ParamField>

<ParamField type="bool">
  **mist/mistv2 only.** Skips text normalization before synthesis. This reduces latency, but digits and abbreviations reach the model unexpanded and may be mispronounced.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://users.rime.ai/v1/rime-tts \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --output output.json \
    --fail \
    --data '{
    "text": "Hello from Rime!",
    "modelId": "mistv2",
    "speaker": "astra",
    "lang": "eng",
    "audioFormat": "mulaw",
    "inlineSpeedAlpha": "0.5, 3",
    "noTextNormalization": false,
    "pauseBetweenBrackets": false,
    "phonemizeBetweenBrackets": false,
    "speedAlpha": 1.0
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://users.rime.ai/v1/rime-tts"

  payload = {
      "speaker": "astra",
      "text": "Hello from Rime!",
      "modelId": "mistv2",
      "lang": "eng",
      "audioFormat": "mulaw",
      "speedAlpha": 1.0,
      "noTextNormalization": False,
      "pauseBetweenBrackets": False,
      "phonemizeBetweenBrackets": False
  }
  headers = {
      "Accept": "application/json",
      "Authorization": "Bearer <authorization>",
      "Content-Type": "application/json"
  }

  response = requests.request("POST", url, json=payload, headers=headers)

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      Authorization: 'Bearer <authorization>',
      'Content-Type': 'application/json'
    },
    body: '{"speaker":"astra","text":"Hello from Rime!","modelId":"mistv2","lang": "eng","audioFormat": "mulaw","speedAlpha":1.0,"noTextNormalization":false}'
  };

  fetch('https://users.rime.ai/v1/rime-tts', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://users.rime.ai/v1/rime-tts",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv2\",\n  \"lang\":\"eng\",\n \"audioFormat\": \"mulaw\",\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}",
    CURLOPT_HTTPHEADER => [
      "Accept: application/json",
      "Authorization: Bearer <authorization>",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
  )

  func main() {

    url := "https://users.rime.ai/v1/rime-tts"

    payload := strings.NewReader("{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv2\",\n  \"lang\": \"eng\",\n  \"audioFormat\": \"mulaw\",\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("Accept", "application/json")
    req.Header.Add("Authorization", "Bearer <authorization>")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://users.rime.ai/v1/rime-tts")
    .header("Accept", "application/json")
    .header("Authorization", "Bearer <authorization>")
    .header("Content-Type", "application/json")
    .body("{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv2\",\n  \"lang\": \"eng\",\n  \"audioFormat\": \"mulaw\",\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}")
    .asString();
  ```
</RequestExample>


# OGG over JSON
Source: https://docs.rime.ai/api-reference/mistv2/json-ogg

POST https://users.rime.ai/v1/rime-tts
Mist v2 non-streaming endpoint that returns base64 Opus/Ogg audio inside a JSON envelope.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

The API returns a single JSON object, `{"audioContent": "..."}`, whose `audioContent` field holds base64-encoded Opus audio in an Ogg container. Decode it before you save or play it. Only Mist v1 and Mist v2 return this envelope, and only when `Accept` doesn't name a streamable audio type, which is why the examples send `application/json`. The response arrives after synthesis finishes, so use [streaming HTTP](/api-reference/mistv2/http) if you want playback to start sooner.

## Fixed parameters

<ParamField type="ogg" />

## Variable parameters

<ParamField type="string">
  Must be a voice from the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  The text you'd like spoken. Character limit per request is 1,000 via the API and in the dashboard UI.
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the selected speaker. Verify the pairing in the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="bool">
  When set to true, adds pauses between words enclosed in angle brackets. The number inside the brackets specifies the pause duration in milliseconds. <br />
  Example: "Hi. \<200> I'd love to have a conversation with you." adds a 200ms pause between the first and second sentences.
</ParamField>

<ParamField type="bool">
  When set to true, you can specify the phonemes for a word enclosed in curly brackets. <br />
  Example: "\{h'El.o} World" pronounces "Hello" with the phonemes you supplied. Learn more about [custom pronunciation](/docs/custom-pronunciation).
</ParamField>

<ParamField type="string">
  Comma-separated list of speed values applied to words in square brackets. Values \< 1.0 speed up speech, > 1.0 slow it down.
  Example: "This is \[slow] and \[fast]", use "3, 0.5" to make "slow" slower and "fast" faster.
</ParamField>

<ParamField type="int">
  Must be one of `8000`, `12000`, `16000`, or `24000`
</ParamField>

<ParamField type="string">
  Set to `mistv2`.
</ParamField>

<ParamField type="float">
  Adjusts the speed of speech. Lower than 1.0 is faster and higher than 1.0 is slower.

  *Note: this is the legacy Mist v2 convention. Coda and Mist v3 invert it, so for those models higher than 1.0 is faster.*
</ParamField>

<ParamField type="bool">
  **mist/mistv2 only.** Skips text normalization before synthesis. This reduces latency, but digits and abbreviations reach the model unexpanded and may be mispronounced.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://users.rime.ai/v1/rime-tts \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --output output.json \
    --fail \
    --data '{
    "text": "Hello from Rime!",
    "modelId": "mistv2",
    "speaker": "astra",
    "lang": "eng",
    "audioFormat": "ogg",
    "inlineSpeedAlpha": "0.5, 3",
    "noTextNormalization": false,
    "pauseBetweenBrackets": false,
    "phonemizeBetweenBrackets": false,
    "samplingRate": 24000,
    "speedAlpha": 1.0
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://users.rime.ai/v1/rime-tts"

  payload = {
      "speaker": "astra",
      "text": "Hello from Rime!",
      "modelId": "mistv2",
      "lang": "eng",
      "audioFormat": "ogg",
      "samplingRate": 24000,
      "speedAlpha": 1.0,
      "noTextNormalization": False,
      "pauseBetweenBrackets": False,
      "phonemizeBetweenBrackets": False
  }
  headers = {
      "Accept": "application/json",
      "Authorization": "Bearer <authorization>",
      "Content-Type": "application/json"
  }

  response = requests.request("POST", url, json=payload, headers=headers)

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      Authorization: 'Bearer <authorization>',
      'Content-Type': 'application/json'
    },
    body: '{"speaker":"astra","text":"Hello from Rime!","modelId":"mistv2", "lang": "eng", "audioFormat": "ogg","samplingRate":24000,"speedAlpha":1.0,"noTextNormalization":false}'
  };

  fetch('https://users.rime.ai/v1/rime-tts', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://users.rime.ai/v1/rime-tts",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv2\",\n  \"lang\":\"eng\",\n  \"audioFormat\": \"ogg\",\n  \"samplingRate\": 24000,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}",
    CURLOPT_HTTPHEADER => [
      "Accept: application/json",
      "Authorization: Bearer <authorization>",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
  )

  func main() {

    url := "https://users.rime.ai/v1/rime-tts"

    payload := strings.NewReader("{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv2\",\n  \"lang\": \"eng\",\n  \"audioFormat\": \"ogg\",\n  \"samplingRate\": 24000,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("Accept", "application/json")
    req.Header.Add("Authorization", "Bearer <authorization>")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://users.rime.ai/v1/rime-tts")
    .header("Accept", "application/json")
    .header("Authorization", "Bearer <authorization>")
    .header("Content-Type", "application/json")
    .body("{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv2\",\n  \"lang\": \"eng\",\n  \"audioFormat\": \"ogg\",\n  \"samplingRate\": 24000,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}")
    .asString();
  ```
</RequestExample>


# WAV over JSON
Source: https://docs.rime.ai/api-reference/mistv2/json-wav

POST https://users.rime.ai/v1/rime-tts
Mist v2 non-streaming endpoint that returns base64 WAV audio inside a JSON envelope.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

The API returns a single JSON object, `{"audioContent": "..."}`, whose `audioContent` field holds base64-encoded WAV audio. Decode it before you save or play it. Only Mist v1 and Mist v2 return this envelope, and only when `Accept` doesn't name a streamable audio type, which is why the examples send `application/json`. The response arrives after synthesis finishes, so use [streaming HTTP](/api-reference/mistv2/http) if you want playback to start sooner.

## Fixed parameters

<ParamField type="wav" />

## Variable parameters

<ParamField type="string">
  Must be a voice from the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  The text you'd like spoken. Character limit per request is 1,000 via the API and in the dashboard UI.
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the selected speaker. Verify the pairing in the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  Set to `mistv2`.
</ParamField>

<ParamField type="bool">
  When set to true, adds pauses between words enclosed in angle brackets. The number inside the brackets specifies the pause duration in milliseconds. <br />
  Example: "Hi. \<200> I'd love to have a conversation with you." adds a 200ms pause between the first and second sentences.
</ParamField>

<ParamField type="bool">
  When set to true, you can specify the phonemes for a word enclosed in curly brackets. <br />
  Example: "\{h'El.o} World" pronounces "Hello" with the phonemes you supplied. Learn more about [custom pronunciation](/docs/custom-pronunciation).
</ParamField>

<ParamField type="string">
  Comma-separated list of speed values applied to words in square brackets. Values \< 1.0 speed up speech, > 1.0 slow it down.
  Example: "This is \[slow] and \[fast]", use "3, 0.5" to make "slow" slower and "fast" faster.
</ParamField>

<ParamField type="int">
  The value, if provided, must be between 4000 and 44100. Default: 22050
</ParamField>

<ParamField type="float">
  Adjusts the speed of speech. Lower than 1.0 is faster and higher than 1.0 is slower.

  *Note: this is the legacy Mist v2 convention. Coda and Mist v3 invert it, so for those models higher than 1.0 is faster.*
</ParamField>

<ParamField type="bool">
  **mist/mistv2 only.** Skips text normalization before synthesis. This reduces latency, but digits and abbreviations reach the model unexpanded and may be mispronounced.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://users.rime.ai/v1/rime-tts \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --output output.json \
    --fail \
    --data '{
    "text": "Hello from Rime!",
    "modelId": "mistv2",
    "speaker": "astra",
    "lang": "eng",
    "audioFormat": "wav",
    "inlineSpeedAlpha": "0.5, 3",
    "noTextNormalization": false,
    "pauseBetweenBrackets": false,
    "phonemizeBetweenBrackets": false,
    "samplingRate": 22050,
    "speedAlpha": 1.0
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://users.rime.ai/v1/rime-tts"

  payload = {
      "speaker": "astra",
      "text": "Hello from Rime!",
      "modelId": "mistv2",
      "lang": "eng",
      "audioFormat": "wav",
      "samplingRate": 22050,
      "speedAlpha": 1.0,
      "noTextNormalization": False,
      "phonemizeBetweenBrackets": False,
      "pauseBetweenBrackets": False
  }
  headers = {
      "Accept": "application/json",
      "Authorization": "Bearer <authorization>",
      "Content-Type": "application/json"
  }

  response = requests.request("POST", url, json=payload, headers=headers)

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      Authorization: 'Bearer <authorization>',
      'Content-Type': 'application/json'
    },
    body: '{"speaker":"astra","text":"Hello from Rime!","modelId":"mistv2", "lang": "eng", "audioFormat": "wav","samplingRate":22050,"speedAlpha":1.0,"noTextNormalization":false}'
  };

  fetch('https://users.rime.ai/v1/rime-tts', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://users.rime.ai/v1/rime-tts",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n \"modelId\": \"mistv2\",\n  \"lang\":\"eng\",\n  \"audioFormat\": \"wav\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}",
    CURLOPT_HTTPHEADER => [
      "Accept: application/json",
      "Authorization: Bearer <authorization>",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
  )

  func main() {

    url := "https://users.rime.ai/v1/rime-tts"

    payload := strings.NewReader("{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv2\",\n  \"lang\": \"eng\",\n \"audioFormat\": \"wav\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("Accept", "application/json")
    req.Header.Add("Authorization", "Bearer <authorization>")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://users.rime.ai/v1/rime-tts")
    .header("Accept", "application/json")
    .header("Authorization", "Bearer <authorization>")
    .header("Content-Type", "application/json")
    .body("{\n  \"speaker\": \"astra\",\n  \"text\": \"Hello from Rime!\",\n  \"audioFormat\": \"wav\", \n  \"modelId\": \"mistv2\", \n  \"lang\": \"eng\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}")
    .asString();
  ```
</RequestExample>


# Server-sent Events
Source: https://docs.rime.ai/api-reference/mistv2/sse

POST https://users.rime.ai/v1/rime-tts
Mist v2 Server-Sent Events endpoint for streaming audio chunks over text/event-stream.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

When you set `Accept: text/event-stream`, the `/v1/rime-tts` route streams the response as server-sent events. SSE is specific to Mist v2, so use streaming HTTP or WebSockets for other models.

## Fixed headers

<ParamField type="text/event-stream" />

## Variable parameters

<ParamField type="string">
  Must be a voice from the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  The text you'd like spoken. Character limit per request is 1,000 via the API and in the dashboard UI.
</ParamField>

<ParamField type="string">
  Set to `mistv2`.
</ParamField>

<ParamField type="string">
  One of `mp3`, `mulaw`, or `pcm`
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the selected speaker. Verify the pairing in the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="bool">
  When set to true, adds pauses between words enclosed in angle brackets. The number inside the brackets specifies the pause duration in milliseconds. <br />
  Example: "Hi. \<200> I'd love to have a conversation with you." adds a 200ms pause between the first and second sentences.
</ParamField>

<ParamField type="bool">
  When set to true, you can specify the phonemes for a word enclosed in curly brackets. <br />
  Example: "\{h'El.o} World" pronounces "Hello" with the phonemes you supplied. Learn more about [custom pronunciation](/docs/custom-pronunciation).
</ParamField>

<ParamField type="string">
  Comma-separated list of speed values applied to words in square brackets. Values \< 1.0 speed up speech, > 1.0 slow it down.
  Example: "This is \[slow] and \[fast]", use "3, 0.5" to make "slow" slower and "fast" faster.
</ParamField>

<ParamField type="int">
  The value, if provided, must be between 4000 and 44100. Default: 22050
</ParamField>

<ParamField type="float">
  Adjusts the speed of speech. Lower than 1.0 is faster and higher than 1.0 is slower.

  *Note: this is the legacy Mist v2 convention. Coda and Mist v3 invert it, so for those models higher than 1.0 is faster.*
</ParamField>

<ParamField type="bool">
  **mist/mistv2 only.** Skips text normalization before synthesis. This reduces latency, but digits and abbreviations reach the model unexpanded and may be mispronounced.
</ParamField>

## Example output

```
event: chunk
data: {"data": "vv+t/7j/sv+8/8j/zv/U/9T/z//P/87/yv/J/8n/0//X/9r/5f/p/+//8f/y//b/8f/x//P/9v/+/wAAAAD3/+3/7v/v//X/+P/0//r/8v/r//D/8P/x/+v/7P/1//D/7//0//b/9//7//r/8//5//7/9//8/wYABwAHAAgADAAKAAEA///8//n/9P/w/+//7P/p/+L/5f/l/+D/6v/s/+//9f/r/+z/8P/u/+//8//t/+j/7//t/9//3//f/97/4P/f/+D/4P/k/+P/3v/f/9//4//p/+b/5f/l/9z/4f/p/+H/5//m/+H/8P/x/+7/9f/9//z/8//2//r/9v/w/+//8f/p/+P/4f/d/9z/2//Z/9r/3P/e/9z/4P/k/+L/4//f/9z/2f/a/9v/0v/N/8n/yf/J/8D/tv+z/7f/s/+x/7f/sv+x/8D/xP/C/8b/yv/S/9H/xf/D/8n/zv/S/8//0P/X/9D/z//X/9T/0P/L/8X/yP/S/9X/0f/L/83/1f/b/+D/2//W/9X/0P/U/9j/0P/U/9n/2v/i/+v/8v/s/9z/2f/U/8f/yP/M/8n/yf/P/9D/yf/Q/8r/xP/Q/8v/zf/T/9L/2v/Z/9z/5v/o/+j/6f/o/+b/5//o//H/+P/z//L/7//o/+T/5P/m/+3/7//v//P/6//p//P/8P/p/+X/4//j/+X/6P/l/+X/7P/o/9//5P/h/9n/2//b/93/5f/g/9r/0//L/8//yf++/7//vP+8/8H/wf/C/8H/v/+6/7T/sf+u/63/qv+t/6//q/+t/6v/p/+l/6T/pf+t/7L/r/+u/7f/vf+7/7r/vf+6/7v/u//A/83/yf/I/w=="}

event: chunk
data: {"data": "zP/J/8P/uP+8/7r/tf+//7j/tP+3/7X/uv+//8H/x//F/8L/yf/J/8n/y//H/8P/vf+7/73/xv/J/8r/z//N/8//yf/D/8P/xf/M/8z/yP/G/8H/vP+//8X/xf/J/8//0P/P/9T/2P/Y/9v/2f/Z/9//2v/d/+H/3f/d/9v/0//U/9j/1v/Z/+L/6v/s/+7/6v/g/9v/1//P/8n/x//I/8f/v/+3/7X/uP+7/7T/tP+6/7T/sP+6/8P/zP/Q/8z/z//T/9j/4f/c/+D/5v/d/+X/7v/o/+n/6v/o/+j/6P/i/9z/2//f/9z/3P/e/9j/2f/g/+z/7v/q/+n/5v/r//L/8v/n/9z/5P/u/+3/6f/p/+//7//o/+r/9P/v//H/+P/t/+//9f/2//T/8P/1//X/9f/+/wcABAAIABIAFAAYABcAEwAYABgAGwAlACgAKAAoACQAJAAnACYAJwAoACAAGwAiACYAKQArACsALwAuACkAKwAqACkAJQAXABcAGAAQABIAGAAaABgAHgAlACIAJAAjACUAKwAkACEAJAAjACYAKwAzADUAMAAyADgAMwArAC8AMgA0ADgAOAA6ADYAPABCAEEARABHAEQAQwBDAD8APQBDAEUARgBDADsAPgBBADgAPABDAD4ARQBMAEkARwBCAEIAQwBFAEcAQABCAEcAPgBBAEYAQwA7ADYAPQBDAEcARABEAEgARwBOAE0ARwBOAE0ASABEADgANQA2ADoAQAA5ADIANQA0ADUAOQA5ADwAQgBDAEIARQBGAEIAPgA9AD4AOwA7ADsAQwBJAEYAVQBaAFUAUwBNAFIAVgBQAE8AUgBYAFQATQBQAA=="}

event: timestamps
data: {"word_timestamps": {"words": ["over", "the", "last", "six", "months", ",", "there", "has", "been", "a", "lot", "of", "talk", "about", "the", "future", "of", "theatrical", "exhibition"], "start": [0, 0.624, 0.816, 1.12, 1.52, 2.08, 2.3, 2.496, 2.7, 2.896, 3.024, 3.232, 3.408, 3.664, 4.0, 4.192, 4.608, 4.768, 5.456], "end": [0.624, 0.816, 1.12, 1.52, 2.08, 2.304, 2.496, 2.704, 2.896, 3.024, 3.232, 3.408, 3.664, 4.0, 4.192, 4.608, 4.768, 5.456, 6.672]}}

event: done
data: {"done": true}

```

`chunk` events carry base64-encoded audio in `data`. Decode each one and append the bytes in order to rebuild the audio. The `timestamps` event gives word-level timings, and `done` marks the end of the stream, so stop reading when it arrives.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://users.rime.ai/v1/rime-tts \
    --header 'Accept: text/event-stream' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --output output.txt \
    --fail \
    --data '{
    "text": "Hello from Rime!",
    "modelId": "mistv2",
    "speaker": "astra",
    "lang": "eng",
    "inlineSpeedAlpha": "0.5, 3",
    "noTextNormalization": false,
    "pauseBetweenBrackets": false,
    "phonemizeBetweenBrackets": false,
    "samplingRate": 22050,
    "speedAlpha": 1.0
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://users.rime.ai/v1/rime-tts"

  payload = {
      "speaker": "<string>",
      "text": "<string>",
      "modelId": "<string>",
      "lang": "eng",
      "samplingRate": 22050,
      "speedAlpha": 1.0,
      "noTextNormalization": False,
      "pauseBetweenBrackets": False,
      "phonemizeBetweenBrackets": False
  }
  headers = {
      "Accept": "text/event-stream",
      "Authorization": "Bearer <authorization>",
      "Content-Type": "application/json"
  }

  # Use stream=True to handle streaming response
  response = requests.request("POST", url, json=payload, headers=headers, stream=True)

  # Check if the request was successful
  if response.status_code == 200:
      with open("audio_output.mp3", "wb") as f:
          for chunk in response.iter_content(chunk_size=1024):
              if chunk:
                  f.write(chunk)
  else:
      print("Error:", response.status_code)

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'POST',
    headers: {
      Accept: 'text/event-stream',
      Authorization: 'Bearer <authorization>',
      'Content-Type': 'application/json'
    },
    body: '{"speaker":"<string>","text":"<string>","modelId":"<string>","lang": "eng", "samplingRate":22050,"speedAlpha":1.0,"noTextNormalization":false}'
  };

  fetch('https://users.rime.ai/v1/rime-tts', options)
    .then(response => response.text())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://users.rime.ai/v1/rime-tts",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\n  \"speaker\": \"<string>\",\n  \"text\": \"<string>\",\n  \"modelId\": \"<string>\",\n  \"lang\":\"eng\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}",
    CURLOPT_HTTPHEADER => [
      "Accept: text/event-stream",
      "Authorization: Bearer <authorization>",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
  )

  func main() {

    url := "https://users.rime.ai/v1/rime-tts"

    payload := strings.NewReader("{\n  \"speaker\": \"<string>\",\n  \"text\": \"<string>\",\n  \"modelId\": \"<string>\",\n  \"lang\": \"eng\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("Accept", "text/event-stream")
    req.Header.Add("Authorization", "Bearer <authorization>")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://users.rime.ai/v1/rime-tts")
    .header("Accept", "text/event-stream")
    .header("Authorization", "Bearer <authorization>")
    .header("Content-Type", "application/json")
    .body("{\n  \"speaker\": \"<string>\",\n  \"text\": \"<string>\",\n  \"modelId\": \"<string>\",\n  \"lang\": \"eng\",\n  \"samplingRate\": 22050,\n  \"speedAlpha\": 1.0,\n  \"noTextNormalization\": false\n}")
    .asString();
  ```
</RequestExample>


# Websockets
Source: https://docs.rime.ai/api-reference/mistv2/websockets

GET wss://users-ws.rime.ai/ws
Mist v2 plain-text WebSocket (/ws): send text, receive raw audio bytes.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

## Overview

This WebSocket accepts plain text and returns raw audio bytes in the format you set with `audioFormat`. You pass every synthesis parameter as a query parameter when you open the connection, and those settings apply for the life of the connection.

The API buffers input until it detects a sentence boundary, typically at `.`, `?`, or `!`, so synthesis starts once it has enough text for natural prosody. The wait is most noticeable on the first sentence. After that, later text usually arrives while earlier audio is still playing, and the buffering becomes largely invisible. To change when synthesis starts, set `segment`.

## Messages

### Send

Send bare text, not JSON.

```example theme={null}
This will be converted to audio via websockets
```

### Receive

Your client receives raw audio bytes in the `audioFormat` set at connection time. Append the messages in order to rebuild the audio.

```example theme={null}
<FF>^@^@^@9LAME3.100^AP^@^@^@^@^@^@^@^@^T<A0>$^D>"^@^@<A0>^@^@<A8><C0><BA><9D>G^N^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@
^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@
^@^@^@^@^@^@^@^@^@^@
```

## Commands

Send these strings as text messages to control the buffer.

### `<CLEAR>`

Discards buffered text that hasn't been synthesized yet. Send it when the user interrupts. It doesn't cancel a synthesis already in progress, so stop playback in your client and drop any audio that still arrives.

### `<FLUSH>`

Synthesizes whatever text is buffered, without waiting for a sentence boundary, and sends the audio.

### `<EOS>`

Synthesizes whatever text is buffered, sends the audio, and then the server closes the connection.

## Variable parameters

<ParamField type="string">
  Must be a voice from the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  Set to `mistv2`.
</ParamField>

<ParamField type="string">
  One of `mp3`, `mulaw`, or `pcm`
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the selected speaker. Verify the pairing in the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="bool">
  When set to true, adds pauses between words enclosed in angle brackets. The number inside the brackets specifies the pause duration in milliseconds. <br />
  Example: "Hi. \<200> I'd love to have a conversation with you." adds a 200ms pause between the first and second sentences.
</ParamField>

<ParamField type="bool">
  When set to true, you can specify the phonemes for a word enclosed in curly brackets. <br />
  Example: "\{h'El.o} World" pronounces "Hello" with the phonemes you supplied. Learn more about [custom pronunciation](/docs/custom-pronunciation).
</ParamField>

<ParamField type="string">
  Comma-separated list of speed values applied to words in square brackets. Values \< 1.0 speed up speech, > 1.0 slow it down.
  Example: "This is \[slow] and \[fast]", use "3, 0.5" to make "slow" slower and "fast" faster.
</ParamField>

<ParamField type="int">
  The value, if provided, must be between 4000 and 44100. Default: 22050
</ParamField>

<ParamField type="float">
  Adjusts the speed of speech. Lower than 1.0 is faster and higher than 1.0 is slower.

  *Note: this is the legacy Mist v2 convention. Coda and Mist v3 invert it, so for those models higher than 1.0 is faster.*
</ParamField>

<ParamField type="bool">
  **mist/mistv2 only.** Skips text normalization before synthesis. This reduces latency, but digits and abbreviations reach the model unexpanded and may be mispronounced.
</ParamField>

<ParamField type="string">
  Controls how text is segmented for synthesis. Available options:

  * "immediate" - Synthesizes text immediately without waiting for complete sentences
  * "never" - Never segments the text, waits for explicit flush or EOS
  * "bySentence" (default) - Waits for complete sentences before synthesis

  Note: For backward compatibility, setting `immediate=true` in query params is equivalent to `segment=immediate`. If a null value is provided, it will default to "bySentence".
</ParamField>

<RequestExample>
  ```python Python theme={null}
  import asyncio
  import websockets

  class RimeClient:
      def __init__(self, speaker, api_key):
          self.url = f"wss://users-ws.rime.ai/ws?speaker={speaker}&modelId=mistv2&audioFormat=mp3"
          self.auth_headers = {
              "Authorization": f"Bearer {api_key}"
          }
          self.audio_data = b''

      async def send_tokens(self, websocket, message):
          for token in message:
              await websocket.send(token)

      async def handle_audio(self, websocket):
          while True:
              try:
                  audio = await websocket.recv()
              except websockets.exceptions.ConnectionClosedOK:
                  break
              self.audio_data += audio

      async def run(self, message):
          async with websockets.connect(self.url, additional_headers=self.auth_headers) as websocket:
              await asyncio.gather(
                  self.send_tokens(websocket, message),
                  self.handle_audio(websocket),
              )

      def save_audio(self, file_path):
          with open(file_path, 'wb') as f:
              f.write(self.audio_data)

  message = [
      "This ",
      "is ",
      "a ",
      "test ",
      "<CLEAR>",
      "This ",
      "is ",
      "a ",
      "sentence, ",
      "that ",
      "will ",
      "produce ",
      "audio ",
      "across ",
      "two ",
      "messages.",
      "<EOS>",
  ]

  client = RimeClient("cove", api_key="xxx")
  asyncio.run(client.run(message))

  client.save_audio("output.mp3")
  ```
</RequestExample>


# Websockets JSON
Source: https://docs.rime.ai/api-reference/mistv2/websockets-json

GET wss://users-ws.rime.ai/ws2
Mist v2 JSON WebSocket (/ws2): structured events with base64 audio chunks and word-level timestamps.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

## Overview

This WebSocket sends and receives JSON messages. Compared with the [plain-text WebSocket](/api-reference/mistv2/websockets), it adds word-level timestamps, a `done` event after each synthesis, and `contextId` tagging. You pass every synthesis parameter as a query parameter when you open the connection, and those settings apply for the life of the connection.

The API buffers input until it detects a sentence boundary, typically at `.`, `?`, or `!`, so synthesis starts once it has enough text for natural prosody. The wait is most noticeable on the first sentence. After that, later text usually arrives while earlier audio is still playing, and the buffering becomes largely invisible. To change when synthesis starts, set `segment`.

## Messages

### Send

#### Text

Sends text for synthesis. This is the message your client sends most often.

schema:

```typescript theme={null}
type TextMessage = {
  text: string,
  contextId?: string,
}
```

examples:

```json theme={null}
{
    "text": "this is the minimum text message."
}

{
    "text": "this is a text message with a context id.",
    "contextId": "159495B1-5C81-4C73-A51A-9CE10A08239E"
}
```

If you set `contextId`, the server attaches it to the events it sends back for that text. The server tracks one context ID at a time, and each event carries the most recent context ID at the time its audio was requested. In the examples above, even if the server receives both messages before it sends any audio, the first sentence's audio is tagged `contextId: null` and the second sentence's audio is tagged with its UUID.

#### Clear

Discards buffered text that hasn't been synthesized yet. Send it when the user interrupts. It doesn't cancel a synthesis already in progress, so stop playback in your client and drop any audio that still arrives.

```json theme={null}
{ "operation": "clear" }
```

#### Flush

Synthesizes whatever text is buffered, without waiting for a sentence boundary, and sends the audio.

```json theme={null}
{ "operation": "flush" }
```

#### EOS

Synthesizes whatever text is buffered, sends the audio, and then the server closes the connection.

```json theme={null}
{ "operation" : "eos" }
```

### Receive

#### Chunk

Carries a piece of the synthesized audio. This is the event your client receives most often.

```typescript theme={null}
type Base64String = string

type AudioChunkEvent = {
  type: "chunk",
  data: Base64String,
  contextId: string | null,
}
```

`data` holds base64-encoded audio in the `audioFormat` set at connection time. Decode each chunk and append the bytes in order to rebuild the audio. If the text that produced this audio had a `contextId`, the event includes it.

#### Timestamps

The server sends word-level timestamps alongside the audio chunks, so your client can tell which words have been spoken at any point. When the user talks over the output, map the playback position back to the last word they actually heard.

<Warning>Timestamps are emitted only when `lang` is `en`/`eng` or `es`/`spa`, or when `lang` is omitted. Requests in any other language receive `chunk` and `done` events with no `timestamps` event and no error. Don't block playback while waiting for a timestamps event.</Warning>

```typescript theme={null}
type TimestampsEvent = {
  type: "timestamps",
  word_timestamps: {
    words: string[],
    start: number[],
    end: number[],
  },
  contextId: string | null,
}
```

The three arrays inside `word_timestamps` are the same length and index-aligned: for a given index `i`, `words[i]` is spoken from `start[i]` to `end[i]`. Times are in seconds, measured from the beginning of the audio for the current synthesis. If a context id was attached to the text that produced this audio, it is included on the event.

Example payload:

```json theme={null}
{
  "type": "timestamps",
  "word_timestamps": {
    "words": ["Hello", "from", "a", "timestamps", "probe", "."],
    "start": [0, 0.35991, 0.51084, 0.59211, 1.10295, 1.41642],
    "end":   [0.35991, 0.51084, 0.59211, 1.10295, 1.41642, 1.5093]
  },
  "contextId": null
}
```

#### Done

After the last audio chunk for a synthesis batch has been sent, the server emits a `done` event. This signals that the current synthesis is fully complete. If the client sends more text and triggers further synthesis, another `done` will follow. The `eos` operation emits a final `done` for any remaining buffered content before the server closes the connection. If the buffer is already empty, the server closes without sending a `done`.

```typescript theme={null}
type DoneEvent = {
  type: "done",
  done: true,
  contextId: string | null,
}
```

<Note>
  On `/ws2`, the `done` event carries an extra boolean `done: true` field in addition to `type: "done"`. On `/ws3` the event contains only `type` and `contextId`. Match on `type === "done"` to handle both.
</Note>

When exactly `done` fires depends on the `segment` setting. See [Segmentation and behavior settings](/docs/websockets-segment) for full details.

#### Error

If a message is malformed or unexpected, the server responds immediately with an `error` event. The server does *not* close the connection and keeps accepting well-formed messages, so your client decides whether to close it.

```typescript theme={null}
type ErrorEvent = {
  type: "error",
  message: string,
}
```

## Variable parameters

<ParamField type="string">
  Must be a voice from the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  Set to `mistv2`.
</ParamField>

<ParamField type="string">
  One of `mp3`, `mulaw`, or `pcm`
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the selected speaker. Verify the pairing in the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="bool">
  When set to true, adds pauses between words enclosed in angle brackets. The number inside the brackets specifies the pause duration in milliseconds. <br />
  Example: "Hi. \<200> I'd love to have a conversation with you." adds a 200ms pause between the first and second sentences.
</ParamField>

<ParamField type="bool">
  When set to true, you can specify the phonemes for a word enclosed in curly brackets. <br />
  Example: "\{h'El.o} World" pronounces "Hello" with the phonemes you supplied. Learn more about [custom pronunciation](/docs/custom-pronunciation).
</ParamField>

<ParamField type="string">
  Comma-separated list of speed values applied to words in square brackets. Values \< 1.0 speed up speech, > 1.0 slow it down.
  Example: "This is \[slow] and \[fast]", use "3, 0.5" to make "slow" slower and "fast" faster.
</ParamField>

<ParamField type="int">
  The value, if provided, must be between 4000 and 44100. Default: 22050
</ParamField>

<ParamField type="float">
  Adjusts the speed of speech. Lower than 1.0 is faster and higher than 1.0 is slower.

  *Note: this is the legacy Mist v2 convention. Coda and Mist v3 invert it, so for those models higher than 1.0 is faster.*
</ParamField>

<ParamField type="bool">
  **mist/mistv2 only.** Skips text normalization before synthesis. This reduces latency, but digits and abbreviations reach the model unexpanded and may be mispronounced.
</ParamField>

<ParamField type="string">
  Controls how text is segmented for synthesis. Available options:

  * "immediate" - Synthesizes text immediately without waiting for complete sentences
  * "never" - Never segments the text, waits for explicit flush or EOS
  * "bySentence" (default) - Waits for complete sentences before synthesis

  Note: For backward compatibility, setting `immediate=true` in query params is equivalent to `segment=immediate`. If a null value is provided, it will default to "bySentence".
</ParamField>

<RequestExample>
  ```python Python theme={null}
  import asyncio
  import json
  import websockets
  import base64

  class RimeClient:
      def __init__(self, speaker, api_key):
          self.url = f"wss://users-ws.rime.ai/ws2?speaker={speaker}&modelId=mistv2&audioFormat=mp3"
          self.auth_headers = {
              "Authorization": f"Bearer {api_key}"
          }
          self.audio_data = b''

      async def send_messages(self, websocket, messages):
          for message in messages:
              await websocket.send(json.dumps(message))

      async def handle_audio(self, websocket):
          while True:
              try:
                  audio = await websocket.recv()
              except websockets.exceptions.ConnectionClosedOK:
                  break
              message = json.loads(audio)

              if message['type'] == 'chunk':
                self.audio_data += base64.b64decode(message['data'])

              if message['type'] == 'timestamps':
                  print("Rime model pronounced the words...\n")
                  for w, t in zip(message['word_timestamps']['words'], message['word_timestamps']['start']):
                      print(f"'{w}' at time {t}")

      async def run(self, messages):
          async with websockets.connect(self.url, additional_headers=self.auth_headers) as websocket:
              await asyncio.gather(
                  self.send_messages(websocket, messages),
                  self.handle_audio(websocket),
              )

      def save_audio(self, file_path):
          with open(file_path, 'wb') as f:
              f.write(self.audio_data)
          print(f"\n Audio saved at {file_path}")


  message = [
      {"text": "This "},
      {"text": "is "},
      {"text": "a "},
      {"text": "test "},
      {"operation":"clear"},
      {"text": "This "},
      {"text": "is "},
      {"text": "an "},
      {"text": "incomplete "},
      {"text": "sentence "},
      {"operation": "eos"},
  ]

  client = RimeClient("cove", api_key="xxx")
  asyncio.run(client.run(message))

  client.save_audio("output.mp3")
  ```
</RequestExample>


# Streaming HTTP
Source: https://docs.rime.ai/api-reference/mistv3/http

POST https://users.rime.ai/v1/rime-tts
Mist v3 streaming HTTP endpoint: low-latency TTS with the updated Mist engine.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

The endpoint streams audio in the format you name in the `Accept` header. If `Accept` is missing or a wildcard, the API streams headerless 16-bit PCM, which audio players won't open. If it names a type the API can't stream, the API returns `406` with the list of supported types.

## Audio formats

Set the `Accept` header to one of the following values:

| Format | Accept Header | Notes |
| - | - | - |
| Opus (WebM) | `audio/webm;codecs=opus` | Recommended. Smaller files than MP3 at comparable quality. WebM streams natively in browsers. |
| Opus (OGG) | `audio/ogg;codecs=opus` | Opus in an OGG container. Smaller files than MP3 at comparable quality. |
| MP3 | `audio/mpeg` | Lower compression rate than Opus. Highest compatibility across devices and players. |
| WAV | `audio/wav` | Uncompressed. RIFF WAVE header with 16-bit little-endian linear PCM samples. Streams natively in browsers. |
| PCM | `audio/L16` | Headerless 16-bit little-endian linear PCM. |
| G.711 μ-law | `audio/PCMU` | Headerless stream of audio bytes. |

### Deprecated aliases

The API still accepts these for backward compatibility. Use the RFC types above in new code.

| Deprecated | Use instead |
| - | - |
| `audio/mp3` | `audio/mpeg` |
| `audio/pcm` | `audio/L16` |
| `audio/x-mulaw` | `audio/PCMU` |

## Variable parameters

<ParamField type="string">
  Must be a voice from the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  The text you'd like spoken. Character limit per request is 1,000 via the API and in the dashboard UI.
</ParamField>

<ParamField type="string">
  Set to `mistv3`. The API also uses Mist v3 when `modelId` is omitted, but setting it keeps the request from depending on that default.
</ParamField>

<ParamField type="number">
  The sampling rate (Hz).
</ParamField>

<ParamField type="number">
  The time scaling factor. Accepted range is 0.4 to 2.5. Values outside this range are clamped without an error.

  Values above 1.0 slow the audio down, and values below 1.0 speed it up.
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the selected speaker. Verify the pairing in the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="bool">
  When set to true, adds pauses between words enclosed in angle brackets. The number inside the brackets specifies the pause duration in milliseconds.
  Example: `Hi. <200> I'd love to have a conversation with you.` adds a 200ms pause. Learn more about [custom pauses](/docs/custom-pauses).
</ParamField>

<ParamField type="string">
  Comma-separated list of speed values applied to words in square brackets. Values \< 1.0 speed up speech, > 1.0 slow it down.
  Example: "This is \[slow] and \[fast]", use "3, 0.5" to make "slow" slower and "fast" faster.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://users.rime.ai/v1/rime-tts \
    --header 'Accept: audio/webm;codecs=opus' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --output output.webm \
    --fail \
    --data '{
    "text": "Hello from Rime!",
    "modelId": "mistv3",
    "speaker": "cove",
    "lang": "en",
    "samplingRate": 24000
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://users.rime.ai/v1/rime-tts"

  payload = {
      "speaker": "cove",
      "text": "Hello from Rime!",
      "modelId": "mistv3",
      "samplingRate": 24000
  }
  headers = {
      "Accept": "audio/webm;codecs=opus",
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  with requests.post(url, headers=headers, json=payload, stream=True) as response:
      response.raise_for_status()
      with open("output.webm", "wb") as f:
          for chunk in response.iter_content(chunk_size=4096):
              if chunk:
                  f.write(chunk)
  ```

  ```javascript JavaScript theme={null}
  const fs = require("fs");

  const options = {
    method: 'POST',
    headers: {
      Accept: 'audio/webm;codecs=opus',
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: '{"speaker":"cove","text":"Hello from Rime!","modelId":"mistv3","samplingRate":24000}'
  };

  fetch('https://users.rime.ai/v1/rime-tts', options)
    .then(response => response.arrayBuffer())
    .then(buffer => {
      fs.writeFileSync("output.webm", Buffer.from(buffer));
      console.log("Audio saved to output.webm");
    })
    .catch(err => console.error(err));
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://users.rime.ai/v1/rime-tts",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\n  \"speaker\": \"cove\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv3\",\n  \"samplingRate\": 24000\n}",
    CURLOPT_HTTPHEADER => [
      "Accept: audio/webm;codecs=opus",
      "Authorization: Bearer YOUR_API_KEY",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```go Go theme={null}
  package main

  import (
    "io"
    "net/http"
    "os"
    "strings"
  )

  func main() {

    url := "https://users.rime.ai/v1/rime-tts"

    payload := strings.NewReader("{\n  \"speaker\": \"cove\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv3\",\n  \"samplingRate\": 24000\n}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("Accept", "audio/webm;codecs=opus")
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)

    _ = os.WriteFile("output.webm", body, 0644)
  }
  ```

  ```java Java theme={null}
  HttpResponse<byte[]> response = Unirest.post("https://users.rime.ai/v1/rime-tts")
    .header("Accept", "audio/webm;codecs=opus")
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .body("{\n  \"speaker\": \"cove\",\n  \"text\": \"Hello from Rime!\",\n  \"modelId\": \"mistv3\",\n  \"samplingRate\": 24000\n}")
    .asBytes();
  Files.write(Paths.get("output.webm"), response.getBody());
  ```
</RequestExample>


# Websockets
Source: https://docs.rime.ai/api-reference/mistv3/websockets

GET wss://users-ws.rime.ai/ws
Mist v3 plain-text WebSocket (/ws): send text, receive raw audio bytes.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

## Overview

This WebSocket accepts plain text and returns raw audio bytes in the format you set with `audioFormat`. You pass every synthesis parameter as a query parameter when you open the connection, and those settings apply for the life of the connection.

The API buffers input until it detects a sentence boundary, typically at `.`, `?`, or `!`, so synthesis starts once it has enough text for natural prosody. The wait is most noticeable on the first sentence. After that, later text usually arrives while earlier audio is still playing, and the buffering becomes largely invisible. To change when synthesis starts, set `segment`.

## Messages

### Send

Send bare text, not JSON.

```example theme={null}
This will be converted to audio via websockets
```

### Receive

Your client receives raw audio bytes in the `audioFormat` set at connection time. Append the messages in order to rebuild the audio.

## Commands

Send these strings as text messages to control the buffer.

### `<CLEAR>`

Discards buffered text that hasn't been synthesized yet. Send it when the user interrupts. It doesn't cancel a synthesis already in progress, so stop playback in your client and drop any audio that still arrives.

### `<FLUSH>`

Synthesizes whatever text is buffered, without waiting for a sentence boundary, and sends the audio.

### `<EOS>`

Synthesizes whatever text is buffered, sends the audio, and then the server closes the connection.

## Variable parameters

<ParamField type="string">
  Must be a voice from the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  Set to `mistv3`.
</ParamField>

<ParamField type="string">
  One of `wav`, `mp3` (or `mpeg`), `ogg` (Opus in OGG), `webm` (Opus in WebM), `pcm` (or `l16`), or `mulaw` (or `pcmu`). Unrecognized values fall back to `wav`.
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the selected speaker. Verify the pairing in the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="bool">
  When set to true, adds pauses between words enclosed in angle brackets. The number inside the brackets specifies the pause duration in milliseconds.
  Example: `Hi. <200> I'd love to have a conversation with you.` adds a 200ms pause. Learn more about [custom pauses](/docs/custom-pauses).
</ParamField>

<ParamField type="int">
  The sampling rate in Hz. Default: 24000. Values above 24000 are upsampled.
</ParamField>

<ParamField type="string">
  Comma-separated list of speed values applied to words in square brackets. Values \< 1.0 speed up speech, > 1.0 slow it down.
  Example: "This is \[slow] and \[fast]", use "3, 0.5" to make "slow" slower and "fast" faster.
</ParamField>

<ParamField type="float">
  Adjusts the speed of speech. Higher than 1.0 is faster and lower than 1.0 is slower.
</ParamField>

<ParamField type="string">
  Controls how text is segmented for synthesis. Available options:

  * "immediate" - Synthesizes text immediately without waiting for complete sentences
  * "never" - Never segments the text, waits for explicit flush or EOS
  * "bySentence" (default) - Waits for complete sentences before synthesis
</ParamField>

<RequestExample>
  ```python Python theme={null}
  import asyncio
  import websockets

  class RimeClient:
      def __init__(self, speaker, api_key):
          self.url = f"wss://users-ws.rime.ai/ws?speaker={speaker}&modelId=mistv3&audioFormat=mp3"
          self.auth_headers = {
              "Authorization": f"Bearer {api_key}"
          }
          self.audio_data = b''

      async def send_tokens(self, websocket, message):
          for token in message:
              await websocket.send(token)

      async def handle_audio(self, websocket):
          while True:
              try:
                  audio = await websocket.recv()
              except websockets.exceptions.ConnectionClosedOK:
                  break
              self.audio_data += audio

      async def run(self, message):
          async with websockets.connect(self.url, additional_headers=self.auth_headers) as websocket:
              await asyncio.gather(
                  self.send_tokens(websocket, message),
                  self.handle_audio(websocket),
              )

      def save_audio(self, file_path):
          with open(file_path, 'wb') as f:
              f.write(self.audio_data)

  message = [
      "This ",
      "is ",
      "a ",
      "sentence, ",
      "that ",
      "will ",
      "produce ",
      "audio.",
      "<EOS>",
  ]

  client = RimeClient("cove", api_key="YOUR_API_KEY")
  asyncio.run(client.run(message))

  client.save_audio("output.mp3")
  ```
</RequestExample>


# Websockets JSON
Source: https://docs.rime.ai/api-reference/mistv3/websockets-json

GET wss://users-ws.rime.ai/ws3
Mist v3 JSON WebSocket (/ws3): structured events with base64 audio chunks and word-level timestamps.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

## Overview

This WebSocket sends and receives JSON messages. Compared with the [plain-text WebSocket](/api-reference/mistv3/websockets), it adds word-level timestamps, a `done` event after each synthesis, and `contextId` tagging. You pass every synthesis parameter as a query parameter when you open the connection, and those settings apply for the life of the connection.

The API buffers input until it detects a sentence boundary, typically at `.`, `?`, or `!`, so synthesis starts once it has enough text for natural prosody. The wait is most noticeable on the first sentence. After that, later text usually arrives while earlier audio is still playing, and the buffering becomes largely invisible. To change when synthesis starts, set `segment`.

## Messages

### Send

#### Text

Sends text for synthesis. This is the message your client sends most often.

schema:

```typescript theme={null}
type TextMessage = {
  text: string,
  contextId?: string,
}
```

examples:

```json theme={null}
{
    "text": "this is the minimum text message."
}

{
    "text": "this is a text message with a context id.",
    "contextId": "159495B1-5C81-4C73-A51A-9CE10A08239E"
}
```

If you set `contextId`, the server attaches it to the events it sends back for that text. The server tracks one context ID at a time.

#### Clear

Discards buffered text that hasn't been synthesized yet. Send it when the user interrupts. It doesn't cancel a synthesis already in progress, so stop playback in your client and drop any audio that still arrives.

```json theme={null}
{ "operation": "clear" }
```

#### Flush

Synthesizes whatever text is buffered, without waiting for a sentence boundary, and sends the audio.

```json theme={null}
{ "operation": "flush" }
```

#### EOS

Synthesizes whatever text is buffered, sends the audio, and then the server closes the connection.

```json theme={null}
{ "operation" : "eos" }
```

### Receive

#### Chunk

Carries a piece of the synthesized audio. This is the event your client receives most often.

```typescript theme={null}
type Base64String = string

type AudioChunkEvent = {
  type: "chunk",
  data: Base64String,
  contextId: string | null,
}
```

`data` holds base64-encoded audio in the `audioFormat` set at connection time. Decode each chunk and append the bytes in order to rebuild the audio. If the text that produced this audio had a `contextId`, the event includes it.

#### Timestamps

The server sends word-level timestamps alongside the audio chunks, so your client can tell which words have been spoken at any point. When the user talks over the output, map the playback position back to the last word they actually heard.

<Warning>Timestamps are emitted only when `lang` is `en`/`eng` or `es`/`spa`, or when `lang` is omitted. Requests in any other language receive `chunk` and `done` events with no `timestamps` event and no error (this includes fr and de). Don't block playback while waiting for a timestamps event.</Warning>

```typescript theme={null}
type TimestampsEvent = {
  type: "timestamps",
  word_timestamps: {
    words: string[],
    start: number[],
    end: number[],
  },
  contextId: string | null,
}
```

The three arrays inside `word_timestamps` are the same length and index-aligned: for a given index `i`, `words[i]` is spoken from `start[i]` to `end[i]`. Times are in seconds, measured from the beginning of the audio for the current synthesis. If a context id was attached to the text that produced this audio, it is included on the event.

Example payload:

```json theme={null}
{
  "type": "timestamps",
  "word_timestamps": {
    "words": ["Testing", "mistv3", "timestamps."],
    "start": [0, 0.35396, 1.41584],
    "end":   [0.35396, 1.41584, 3.18564]
  },
  "contextId": null
}
```

#### Done

After the last audio chunk for a synthesis batch has been sent, the server emits a `done` event. This signals that the current synthesis is fully complete. If the client sends more text and triggers further synthesis, another `done` will follow.

```typescript theme={null}
type DoneEvent = {
  type: "done",
  contextId: string | null,
}
```

When exactly `done` fires depends on the `segment` setting. See [Segmentation and behavior settings](/docs/websockets-segment) for full details.

#### Error

If a message is malformed or unexpected, the server responds immediately with an `error` event. The server does *not* close the connection and keeps accepting well-formed messages, so your client decides whether to close it.

```typescript theme={null}
type ErrorEvent = {
  type: "error",
  message: string,
}
```

## Variable parameters

<ParamField type="string">
  Must be a voice from the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="string">
  Set to `mistv3`.
</ParamField>

<ParamField type="string">
  One of `wav`, `mp3` (or `mpeg`), `ogg` (Opus in OGG), `webm` (Opus in WebM), `pcm` (or `l16`), or `mulaw` (or `pcmu`). Unrecognized values fall back to `wav`.
</ParamField>

<ParamField type="string">
  If provided, the language must match the language spoken by the selected speaker. Verify the pairing in the [Rime voice catalog](/docs/voices).
</ParamField>

<ParamField type="bool">
  When set to true, adds pauses between words enclosed in angle brackets. The number inside the brackets specifies the pause duration in milliseconds.
  Example: `Hi. <200> I'd love to have a conversation with you.` adds a 200ms pause. Learn more about [custom pauses](/docs/custom-pauses).
</ParamField>

<ParamField type="int">
  The sampling rate in Hz. Default: 24000. Values above 24000 are upsampled.
</ParamField>

<ParamField type="string">
  Comma-separated list of speed values applied to words in square brackets. Values \< 1.0 speed up speech, > 1.0 slow it down.
  Example: "This is \[slow] and \[fast]", use "3, 0.5" to make "slow" slower and "fast" faster.
</ParamField>

<ParamField type="float">
  Adjusts the speed of speech. Higher than 1.0 is faster and lower than 1.0 is slower.
</ParamField>

<ParamField type="string">
  Controls how text is segmented for synthesis. Available options:

  * "immediate" - Synthesizes text immediately without waiting for complete sentences
  * "never" - Never segments the text, waits for explicit flush or EOS
  * "bySentence" (default) - Waits for complete sentences before synthesis
</ParamField>

<RequestExample>
  ```python Python theme={null}
  import asyncio
  import json
  import websockets
  import base64

  class RimeClient:
      def __init__(self, speaker, api_key):
          self.url = f"wss://users-ws.rime.ai/ws3?speaker={speaker}&modelId=mistv3&audioFormat=mp3"
          self.auth_headers = {
              "Authorization": f"Bearer {api_key}"
          }
          self.audio_data = b''

      async def send_messages(self, websocket, messages):
          for message in messages:
              await websocket.send(json.dumps(message))

      async def handle_audio(self, websocket):
          while True:
              try:
                  audio = await websocket.recv()
              except websockets.exceptions.ConnectionClosedOK:
                  break
              message = json.loads(audio)

              if message['type'] == 'chunk':
                self.audio_data += base64.b64decode(message['data'])

              if message['type'] == 'timestamps':
                  print("Rime model pronounced the words...\n")
                  for w, t in zip(message['word_timestamps']['words'], message['word_timestamps']['start']):
                      print(f"'{w}' at time {t}")

      async def run(self, messages):
          async with websockets.connect(self.url, additional_headers=self.auth_headers) as websocket:
              await asyncio.gather(
                  self.send_messages(websocket, messages),
                  self.handle_audio(websocket),
              )

      def save_audio(self, file_path):
          with open(file_path, 'wb') as f:
              f.write(self.audio_data)
          print(f"\n Audio saved at {file_path}")


  message = [
      {"text": "This "},
      {"text": "is "},
      {"text": "an "},
      {"text": "incomplete "},
      {"text": "sentence "},
      {"operation": "eos"},
  ]

  client = RimeClient("cove", api_key="YOUR_API_KEY")
  asyncio.run(client.run(message))

  client.save_audio("output.mp3")
  ```
</RequestExample>


# Coverage
Source: https://docs.rime.ai/api-reference/other/oov

POST  https://users.rime.ai/oov
Coverage endpoint: check which input words are not yet in Rime's pronunciation dictionary.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

## Overview

This endpoint returns the words in your input that are absent from Rime's pronunciation dictionary. The API still synthesizes uncovered words using the model's predicted pronunciation, so listen to brand names, technical terms, and names before production use.

Dictionary additions typically take about a week. Contact your account manager through Slack or email, or write to [sales@rime.ai](mailto:sales@rime.ai), if you need a different turnaround or have an SLA. For immediate Mist-family control (v1, v2, or English v3), [generate a custom pronunciation](/docs/custom-pronunciation) by hand or from a recording with the [Phonemize API](/api-reference/other/phonemize).

## Example

Send the words to check as `text`:

```bash theme={null}
curl -X POST https://users.rime.ai/oov \
     -H 'Authorization: Bearer <authorization>' \
     -d '{"text": "This is just a testt. This, is, also, a, testtt"}';
```

The response is an array of the words that aren't in the current Rime dictionary. An empty array means every word is covered:

```bash theme={null}
["testt","testtt"]
```

## Variable parameters

<ParamField type="string">
  One or more words to check against Rime's pronunciation dictionary. Separate words with spaces, commas, or newlines.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://users.rime.ai/oov \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --fail \
    --data '{
    "text": "<string>"
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://users.rime.ai/oov"

  payload = {
      "text": "<string>"
  }
  headers = {
      "Accept": "application/json",
      "Authorization": "Bearer <authorization>",
      "Content-Type": "application/json"
  }

  response = requests.request("POST", url, json=payload, headers=headers)

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      Authorization: 'Bearer <authorization>',
      'Content-Type': 'application/json'
    },
    body: '{"text":"<string>"}'
  };

  fetch('https://users.rime.ai/oov', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://users.rime.ai/oov",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\n  \"text\": \"<string>\"\n}",
    CURLOPT_HTTPHEADER => [
      "Accept: application/json",
      "Authorization: Bearer <authorization>",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
  )

  func main() {

    url := "https://users.rime.ai/oov"

    payload := strings.NewReader("{\n  \"text\": \"<string>\"\n}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("Accept", "application/json")
    req.Header.Add("Authorization", "Bearer <authorization>")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://users.rime.ai/oov")
    .header("Accept", "application/json")
    .header("Authorization", "Bearer <authorization>")
    .header("Content-Type", "application/json")
    .body("{\n  \"text\": \"<string>\"\n}")
    .asString();
  ```
</RequestExample>

<ResponseExample>
  ```json 200: words not in dictionary theme={null}
  ["testt", "testtt"]
  ```

  ```json 200: all words covered theme={null}
  []
  ```
</ResponseExample>


# Phonemize
Source: https://docs.rime.ai/api-reference/other/phonemize

POST  https://optimize.rime.ai/phonemize
Phonemize endpoint: convert a recording of a word into a phonetic string in the Rime phonetic alphabet.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

## Overview

This endpoint converts a short audio recording of a word into a phonetic string in the [Rime phonetic alphabet](/platform/rime-phonetic-alphabet).

Use it when you know how a word should sound but don't want to write the phonetic string by hand: record the word (or synthesize it), post the audio, and paste the returned string into a TTS request inside curly brackets with `phonemizeBetweenBrackets: true`. See [Custom pronunciation](/docs/custom-pronunciation).

<Note>
  Custom pronunciation strings are supported on **Mist v1, Mist v2, and English Mist v3**. Coda and non-English Mist v3 accept `phonemizeBetweenBrackets` and ignore it. For an overview of all the ways to control pronunciation, see [Pronunciation control](/platform/pronunciation-control).
</Note>

## Request

Unlike Rime's other endpoints, the request body is the **raw audio bytes**, not JSON or multipart form data. Set the `Content-Type` header to match the audio format. WAV (`audio/wav`) and MP3 (`audio/mpeg`) are supported.

## Example

Generate or record audio of the word, for example with the [Rime CLI](/cli-reference/overview):

```bash theme={null}
rime tts -m coda -l en -s astra "hello" -o speech.wav
```

Post the file as the raw request body. `--data-binary` sends the bytes unchanged, while `-d` would strip newlines and corrupt the audio:

```bash theme={null}
curl -X POST https://optimize.rime.ai/phonemize \
     -H "Authorization: Bearer $(rime key)" \
     -H "Content-Type: audio/wav" \
     --data-binary @speech.wav
```

The response includes the phonetic string:

```json theme={null}
{
  "audioId": "9b2d8ad2-0618-4e96-b255-98b2f7488061",
  "phonemeString": "h0El1o !",
  "authed": 1
}
```

## Response fields

* `audioId`: identifier of the uploaded audio clip.
* `phonemeString`: the phonetic transcription in the [Rime phonetic alphabet](/platform/rime-phonetic-alphabet). The string may end with a punctuation token (for example, `!` or `?`). Strip that token before you use the string inside `{}`.
* `authed`: always `1`.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://optimize.rime.ai/phonemize \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: audio/wav' \
    --fail \
    --data-binary @speech.wav
  ```

  ```python Python theme={null}
  import requests

  url = "https://optimize.rime.ai/phonemize"

  headers = {
      "Authorization": "Bearer <authorization>",
      "Content-Type": "audio/wav"
  }

  with open("speech.wav", "rb") as f:
      response = requests.request("POST", url, data=f, headers=headers)

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  import { readFile } from 'node:fs/promises';

  const audio = await readFile('speech.wav');

  const options = {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <authorization>',
      'Content-Type': 'audio/wav'
    },
    body: audio
  };

  fetch('https://optimize.rime.ai/phonemize', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "audioId": "9b2d8ad2-0618-4e96-b255-98b2f7488061",
    "phonemeString": "h0El1o !",
    "authed": 1
  }
  ```
</ResponseExample>


# Text Normalization
Source: https://docs.rime.ai/api-reference/other/textnorm

POST  https://optimize.rime.ai/textnorm
Return the grammar normalizer's output for an input string.

The Rime API authenticates every request with a bearer token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/api-authentication) for how to create a key.

## Overview

This endpoint returns the grammar normalizer's output for an input string. Use it to preview how numbers, phone numbers, dates, and other non-standard words will be spoken, or to debug an unexpected pronunciation. The output matches Coda's normalization. Mist v3 can group `spell()` sequences differently.

<Note>
  Defaults to English. Pass the `lang` field for other languages. The full list is in [Languages](/docs/voices#languages). For details on what's normalized natively, known gaps, and how to pre-normalize problematic patterns, see [Text normalization](/docs/text-normalization).
</Note>

## Example

Send the string as `text`, and optionally a `lang` code:

```bash theme={null}
curl -X POST https://optimize.rime.ai/textnorm \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"text":"1234 1,2,3,4 1-800-444-4141 "}'
```

The response includes the normalized string:

```json theme={null}
{"normalized":"one two three four, one, two, three, four, one, eight hundred, four four four, four one four one"}
```

Check each non-standard word in the output. Here `1234` is read digit by digit, and the phone number keeps its grouping, with `800` read as "eight hundred". If a reading is wrong for your context, pre-normalize that text before you send it. [Text normalization](/docs/text-normalization) explains how.

To normalize text in a non-English language, pass a language code:

```bash theme={null}
curl -X POST https://optimize.rime.ai/textnorm \
     -H "Authorization: Bearer $(rime key)" \
     -H "Content-Type: application/json" \
     -d '{"text":"Tengo 2 perros","lang":"es"}'
```

## Variable parameters

<ParamField type="string">
  The string you'd like to normalize. Numbers, phone numbers, and other non-standard words will be expanded into their spoken form.
</ParamField>

<ParamField type="string">
  Language code (for example, `en`, `es`, `fr`, `de`, and [additional languages](/docs/voices#languages)) selecting the normalization rules. Defaults to English when omitted.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://optimize.rime.ai/textnorm \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --fail \
    --data '{
    "text": "<string>"
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://optimize.rime.ai/textnorm"

  payload = {
      "text": "<string>"
  }
  headers = {
      "Accept": "application/json",
      "Authorization": "Bearer <authorization>",
      "Content-Type": "application/json"
  }

  response = requests.request("POST", url, json=payload, headers=headers)

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      Authorization: 'Bearer <authorization>',
      'Content-Type': 'application/json'
    },
    body: '{"text":"<string>"}'
  };

  fetch('https://optimize.rime.ai/textnorm', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://optimize.rime.ai/textnorm",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\n  \"text\": \"<string>\"\n}",
    CURLOPT_HTTPHEADER => [
      "Accept: application/json",
      "Authorization: Bearer <authorization>",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
  )

  func main() {

    url := "https://optimize.rime.ai/textnorm"

    payload := strings.NewReader("{\n  \"text\": \"<string>\"\n}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("Accept", "application/json")
    req.Header.Add("Authorization", "Bearer <authorization>")
    req.Header.Add("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://optimize.rime.ai/textnorm")
    .header("Accept", "application/json")
    .header("Authorization", "Bearer <authorization>")
    .header("Content-Type", "application/json")
    .body("{\n  \"text\": \"<string>\"\n}")
    .asString();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "normalized": "one two three four, one, two, three, four, one, eight hundred, four four four, four one four one"
  }
  ```
</ResponseExample>


# Overview
Source: https://docs.rime.ai/cli-reference/overview

Install and get started with the Rime CLI: a command-line tool for synthesizing and listening to AI speech.

The Rime CLI synthesizes AI speech from your terminal. It streams audio during generation, plays it live with a waveform visualization, and saves WAV or MP3 files.

## Installation

<CodeGroup>
  ```bash Shell script theme={null}
  curl -fsSL https://rime.ai/install-cli.sh | sh
  ```

  ```bash Homebrew theme={null}
  brew tap rimelabs/rime-cli && brew install rime-cli
  ```
</CodeGroup>

After installing, run `rime login` to save your API key, then `rime hello`. If you hear the greeting, your key, the API, and playback all work.

## Commands

<CardGroup>
  <Card title="rime tts" icon="waveform-lines" href="/cli-reference/rime-tts">
    Synthesize text to speech and play or save audio
  </Card>

  <Card title="rime curl" icon="code" href="/cli-reference/rime-curl">
    Generate curl commands for direct API requests
  </Card>

  <Card title="rime config" icon="sliders" href="/cli-reference/rime-config">
    Manage configuration and named environments
  </Card>

  <Card title="rime login / logout" icon="key" href="/cli-reference/rime-auth">
    Authenticate with the Rime dashboard
  </Card>

  <Card title="Utility commands" icon="wrench" href="/cli-reference/rime-monitoring">
    rime play, rime hello, rime speedtest, rime usage, and more
  </Card>

  <Card title="Reference" icon="book" href="/cli-reference/reference">
    Global flags, environment variables, and configuration format
  </Card>

  <Card title="Troubleshooting" icon="circle-exclamation" href="/cli-reference/troubleshooting">
    Fix common errors and installation issues
  </Card>
</CardGroup>


# Reference
Source: https://docs.rime.ai/cli-reference/reference

Global flags, environment variables, configuration file format, audio formats, and metadata embedding for the Rime CLI.

## Global flags (all commands)

| Flag | Short | Default | Description |
| - | - | - | - |
| `--quiet` | `-q` | `false` | Suppress non-essential output |
| `--json` | -- | `false` | Output results as JSON |
| `--env` | `-e` | -- | Named environment to use from config |
| `--config` | `-c` | -- | Path to a custom config file |
| `--version` | `-v` | -- | Print version information |
| `--help` | `-h` | -- | Help for any command |

## Environment variables

| Variable | Description |
| - | - |
| `RIME_CLI_API_KEY` | API key for authentication (overrides the key in `rime.toml`) |
| `RIME_API_URL` | API endpoint URL (overrides the URL in `rime.toml`) |
| `RIME_AUTH_HEADER_PREFIX` | Authorization header prefix (default: `Bearer`) |
| `RIME_DASHBOARD_URL` | Dashboard URL for `rime login` (default: `https://app.rime.ai`) |
| `RIME_OPTIMIZE_URL` | Usage API endpoint for `rime usage` (default: `https://optimize.rime.ai`) |
| `RIME_INSTALL` | Install directory used by the shell installer (default: `~/.rime`) |

## Configuration

The CLI uses a TOML config file at `~/.rime/rime.toml`. You can define multiple named environments for different API endpoints.

```toml theme={null}
api_key = "your_api_key"
api_url = "https://users.rime.ai/v1/rime-tts"

[env.staging]
api_url = "https://staging.rime.ai/v1/rime-tts"

[env.onprem]
api_url = "https://rime.internal:8080/v1/rime-tts"
api_key = "different_key"
auth_header_prefix = "Api-Key"
```

Select an environment with the `--env` flag. This request goes to the `staging` URL and uses the top-level `api_key`, because `staging` doesn't set its own:

```bash theme={null}
rime tts "Hello" -s astra -m coda --env staging
```

**Resolution order:** Environment variables override config file values, which override defaults. Within the config file, named environment values override top-level values. A command's `--api-url` flag overrides the URL from all of these.

## Audio formats

| Format | Extension | Default for | Notes |
| - | - | - | - |
| WAV | `.wav` | `coda`, `mistv3` | Uncompressed, higher quality, larger files |
| MP3 | `.mp3` | `mistv2`, `mist` | Compressed, smaller files |

## Metadata embedding

Audio files saved by the CLI include embedded metadata (voice, model, text). This metadata is visible in `rime play` waveform output and in media players like Finder or Preview.

* **WAV files:** LIST/INFO chunk (`IART`, `INAM`, `ICMT`)
* **MP3 files:** ID3v2.3 tags (`TPE1`, `TIT2`, `COMM`)


# Authentication
Source: https://docs.rime.ai/cli-reference/rime-auth

Authenticate the Rime CLI using rime login, rime logout, and rime key.

## `rime login`

Opens your browser to the Rime dashboard for OAuth-based authentication, then saves your API key to `~/.rime/rime.toml`. The CLI starts a local callback server to receive the key from the dashboard.

```bash theme={null}
rime login
```

<img alt="Demo of the rime login command" />

No flags. The CLI checks the key before saving it and doesn't save a key the API rejects as invalid. If the check fails for another reason, such as a network error, the CLI saves the key anyway and prints a warning, so run `rime hello` to confirm it works.

***

## `rime logout`

Remove your saved API key by deleting the config file at `~/.rime/rime.toml`. Deleting the file also removes any named environments you added, so run `rime config init` or `rime login` to set up again.

```bash theme={null}
rime logout
```

No flags.

***

## `rime key`

Print the resolved API key (no trailing newline). Useful in shell scripts and as a subexpression. For example, `rime curl` uses `$(rime key)` in its generated commands.

```bash theme={null}
rime key
```

No flags. Resolves the key from config or `RIME_CLI_API_KEY`, using the active environment. If no key resolves, it prints nothing, and a command that uses `$(rime key)` sends an empty key. Run `rime config show` to see where the key comes from.


# rime config
Source: https://docs.rime.ai/cli-reference/rime-config

Manage Rime CLI configuration and named environments with rime config subcommands.

The `rime config` subcommands manage `~/.rime/rime.toml`, the TOML file that holds your API key and named environments.

## `rime config init`

Create a new config file. In a terminal, the command prompts for an API key. You can press Enter to skip it and add the key later.

```bash theme={null}
rime config init
```

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Overwrite an existing config file |

The generated file names both standard Rime endpoints as environments and makes `users` the default:

```toml theme={null}
api_key = "your_api_key_here"
default_env = "users"

[env.users]
api_url = "https://users.rime.ai/v1/rime-tts"

[env.users-east]
api_url = "https://users-east.rime.ai/v1/rime-tts"
```

Both environments inherit the single top-level `api_key`. To find out which endpoint responds faster from your network, run [`rime speedtest`](/cli-reference/rime-monitoring). It also offers to switch `default_env` to the faster one.

<Note>Older config files without `default_env` continue to work: the top-level `api_url` and `api_key` fields are still respected as the fallback default.</Note>

## `rime config list`

List all configured environments. The currently active default environment is marked with a `*` in the `NAME` column.

```bash theme={null}
rime config list
```

```
NAME            URL                                                AUTH
--------------------------------------------------------------------------------
users *         https://users.rime.ai/v1/rime-tts                 Bearer
users-east      https://users-east.rime.ai/v1/rime-tts            Bearer
```

| Flag | Default | Description |
| - | - | - |
| `--json` | `false` | Output as JSON |

## `rime config default`

Get or set the default environment.

```bash theme={null}
# Print the current default environment name
rime config default

# Switch the default to a different environment
rime config default users-east
```

With no arguments, prints the name of the current default environment:

```
users
```

With a name argument, updates `default_env` in `~/.rime/rime.toml` and confirms:

```
Default environment set to "users-east"
```

No flags.

## `rime config show`

Show the fully resolved configuration for a given environment, including where the API key comes from (config file vs. environment variable).

```bash theme={null}
rime config show
```

| Flag | Short | Default | Description |
| - | - | - | - |
| `--env` | `-e` | `default` | Environment to show |
| `--json` | -- | `false` | Output as JSON |
| `--show-key` | -- | `false` | Display the full API key (redacted by default) |

**Example output:**

```
Environment:  users
API URL:      https://users.rime.ai/v1/rime-tts
API Key:      rime_aHR0cHM6Ly... (redacted)
Auth Prefix:  Bearer
Auth Header:  Authorization: Bearer (redacted)
```

## `rime config add`

Add a named environment to `~/.rime/rime.toml`. Prompts interactively for API URL, API key (input hidden), and an optional auth prefix. You cannot add an environment named `default`. Use `rime config default` to change which environment is the default.

```bash theme={null}
rime config add <name>
```

| Flag | Description |
| - | - |
| `--url` | API URL (default: `https://users.rime.ai/v1/rime-tts`) |
| `--key` | API key (skips interactive prompt) |
| `--auth-prefix` | Auth header prefix, e.g. `Bearer` (optional) |

**Examples:**

```bash theme={null}
# Add a staging environment interactively
rime config add staging

# Add an on-prem environment non-interactively
rime config add onprem --url https://rime.internal:8080/v1/rime-tts --key your_key_here
```

## `rime config rm`

Remove a named environment from `~/.rime/rime.toml`. Prompts for confirmation unless `--yes` is passed.

```bash theme={null}
rime config rm <name>
```

| Flag | Short | Default | Description |
| - | - | - | - |
| `--yes` | `-y` | `false` | Skip confirmation prompt |

## `rime config edit`

Open `~/.rime/rime.toml` in your default editor (`$VISUAL` or `$EDITOR`, falling back to `nano` or `vi`).

```bash theme={null}
rime config edit
```

No flags. Requires the config file to exist. Run `rime config init` first if needed.


# rime curl
Source: https://docs.rime.ai/cli-reference/rime-curl

Generate a ready-to-run curl command for the Rime TTS API.

Generate a curl command for making TTS API requests. The generated command uses `$(rime key)` as a shell expression, so your API key never appears in the printed command. Instead, the shell resolves it when you run the command.

```bash theme={null}
rime curl [TEXT]
```

If you provide text, `--speaker` and `--model-id` are required. With no arguments, the command prints an example request.

The generated command saves audio to `output.wav`, or `output.mp3` for `mist` and `mistv2`. It includes `--fail`, so an HTTP error stops curl instead of being written to the output file.

## Optional flags

| Flag | Short | Default | Description |
| - | - | - | - |
| `--speaker` | `-s` | `astra`\* | Voice speaker to use |
| `--model-id` | `-m` | `coda`\* | Model ID |
| `--lang` | `-l` | -- | BCP 47 language tag. Defaults to the model's own language |
| `--speed-alpha` | -- | `1` | Speed multiplier, which must be greater than 0. For `mist`/`mistv2`: lower is faster. For `coda` and `mistv3`: higher is faster |
| `--sampling-rate` | -- | -- | Output sampling rate in Hz. Coda: `8000`, `16000`, `22050`, `24000`, `44100`, `48000`, `96000`. Mist: `4000`–`44100` |
| `--oneline` | -- | `false` | Output as a single line for easy copy-paste |
| `--api-url` | -- | -- | API URL override |

\*Defaults apply only when run without arguments. When text is provided, `--speaker` and `--model-id` are required.

## Coda flags

The CLI rejects these flags for `mist`, `mistv2`, and `mistv3`.

| Flag | Default | Description |
| - | - | - |
| `--max-tokens` | `1200` | Max output tokens (200–5000) |
| `--temperature` | `0.5` | Sampling temperature (0–1) |
| `--top-p` | `1` | Nucleus sampling threshold (0–1) |
| `--repetition-penalty` | `1.5` | Repetition penalty (1–2) |

## mist/mistv2/mistv3 flags

The CLI rejects these flags for `coda`.

| Flag | Description |
| - | - |
| `--inline-time-scale-factor` | Comma-separated per-segment speed values |
| `--pause-between-brackets` | Insert pause at bracketed markers |
| `--phonemize-between-brackets` | Phonemize text in brackets. On `mistv3`, English only (see [Custom pronunciation](/docs/custom-pronunciation)) |

## mist/mistv2 flags

Only `mist` and `mistv2` support these flags, so the CLI rejects them for `mistv3`.

| Flag | Description |
| - | - |
| `--no-text-normalization` | Disable text normalization |
| `--save-oovs` | Save out-of-vocabulary words |

## Examples

```bash theme={null}
# Show example curl command
rime curl

# Generate curl for custom text
rime curl "Hello from Rime" -s celeste -m coda

# Single-line output
rime curl "Hello" -s astra -m coda --oneline
```


# rime hello & rime play
Source: https://docs.rime.ai/cli-reference/rime-hello-play

Quick audio demo and terminal waveform playback with the Rime CLI.

## `rime hello`

Generates a time-appropriate greeting ("good morning/afternoon/evening, this is Vespera speaking") using the Vespera voice on Coda. The text and voice are fixed, so if you hear the greeting, your API key, the API, and audio playback all work.

```bash theme={null}
rime hello
```

<img alt="Demo of the rime hello command" />

### Optional flags

| Flag | Short | Default | Description |
| - | - | - | - |
| `--output` | `-o` | -- | Output file path (plays audio by default) |
| `--api-url` | -- | -- | API URL override |

### Examples

```bash theme={null}
# Play the greeting
rime hello

# Save the greeting to a file
rime hello -o greeting.wav

# Output as JSON
rime hello --json
```

***

## `rime play`

Play a WAV audio file with terminal waveform visualization. Headless builds have no audio support, so `rime play` exits with an error there. Instead, save audio with `rime tts -o FILE` and play it elsewhere.

```bash theme={null}
rime play FILE
```

<img alt="Demo of the rime play command" />

### Examples

```bash theme={null}
rime play output.wav
```


# Monitoring and usage
Source: https://docs.rime.ai/cli-reference/rime-monitoring

Measure latency, view character usage, and uninstall the Rime CLI.

## `rime speedtest`

Measure time-to-first-byte (TTFB) for configured environments. The command sends a TTS request to each endpoint and reports the latency, so you can pick the fastest endpoint from your network as your default. Each test request is a real synthesis request made with your API key.

```bash theme={null}
rime speedtest
```

### Flags

| Flag | Short | Default | Description |
| - | - | - | - |
| `--model` | `-m` | `coda` | Model ID for the test request |
| `--speaker` | `-s` | `astra` | Speaker for the test request |
| `--lang` | `-l` | -- | BCP 47 language tag for the test request. Defaults to the model's own language |
| `--text` | -- | `running speedtest.` | Text to synthesize |
| `--runs` | -- | `1` | Number of requests per endpoint. When greater than 1, reports mean/min/max |
| `--timeout` | -- | `10s` | Per-request timeout (`0` disables timeout) |
| `--url` | -- | -- | Additional URL to test (repeatable). Forwards your configured API credentials to that URL |
| `--env` | -- | -- | Only test these named environments from config (repeatable) |
| `--yes` | `-y` | `false` | Automatically switch the default environment if a faster one is found |

<Warning>`--url` forwards your configured API credentials to every supplied URL. Use it only with endpoints you trust. The CLI also prints this warning at runtime.</Warning>

### Behavior

* No flags: tests all configured environments
* `--url` alone: tests only the specified URLs and skips the config environments
* `--env` + `--url`: tests both the named envs and the extra URLs
* After the test completes, if the fastest environment differs from the current default, the CLI prompts you to switch. Use `--yes` to skip the prompt and switch automatically.

### Example output (single run)

```
ENV             URL                                                TTFB
--------------------------------------------------------------------------------
users           https://users.rime.ai/v1/rime-tts                 245.12ms
users-east      https://users-east.rime.ai/v1/rime-tts            189.40ms

Fastest: users-east (189.40ms)
Switch default to "users-east"? [y/N]:
```

### Example output (`--runs 3`)

```
ENV             URL                                                TTFB (3 runs)
--------------------------------------------------------------------------------
users           https://users.rime.ai/v1/rime-tts                 mean=245.12ms  min=221.30ms  max=271.50ms
users-east      https://users-east.rime.ai/v1/rime-tts            mean=189.40ms  min=175.10ms  max=203.80ms

Fastest: users-east (189.40ms)
Switch default to "users-east"? [y/N]:
```

A single run can catch one slow request, so use `--runs 3` or more before switching your default on a small difference. When `--runs` is greater than 1, the JSON output includes `ttfb_min_ms` and `ttfb_max_ms` fields in addition to `ttfb_ms` (mean).

***

## `rime usage`

Display daily character usage per model, Coda included. The table has one column for each model with usage in the window plus a Total column. Cloud and on-prem usage are summed per day, and a footer shows the split when both appear. Days are UTC. Per-model history begins 2026-04-01, so earlier days show 0.

```bash theme={null}
rime usage
```

### Flags

| Flag | Default | Description |
| - | - | - |
| `--days` | `7` | Days of history to show, ending today (1 to 90) |
| `--from` | | Start date as `YYYY-MM-DD`, inclusive. On its own, the range runs through today |
| `--to` | | End date as `YYYY-MM-DD`, inclusive. On its own, the range is `--days` ending on this date |
| `--env` | | Count only one environment: `cloud` or `onprem` |
| `--csv` | `false` | Output one row per day, environment, and model |

A range cannot exceed 90 days. The global `--json` flag prints the per-day records unchanged: each day carries a `breakdown` list of `{model, environment, charCount}` entries, and a day with no usage has an empty list.

### Example output

```
       Day   mistv3     coda    Total
----------  -------  -------  -------
2026-05-18   12,400   31,250   43,650
2026-05-19        0   28,900   28,900

Cloud 70,100  On-prem 2,450  (use --env to filter)
```

The same two days as CSV:

```
day,environment,model,chars
2026-05-18,cloud,mistv3,12400
2026-05-18,cloud,coda,30000
2026-05-18,onprem,coda,1250
2026-05-19,cloud,coda,27700
2026-05-19,onprem,coda,1200
```

***

## `rime uninstall`

Remove the Rime CLI binary, configuration, and shell PATH entries. For a shell-script install, the command lists what it will remove and asks for confirmation before deleting anything.

```bash theme={null}
rime uninstall
```

### Flags

| Flag | Short | Default | Description |
| - | - | - | - |
| `--yes` | `-y` | `false` | Skip the confirmation prompt |

<Note>If you installed via Homebrew, the command removes nothing and prints `brew uninstall rime-cli` for you to run instead.</Note>


# rime tts
Source: https://docs.rime.ai/cli-reference/rime-tts

Synthesize text to speech from the command line using the Rime CLI.

Synthesize text to speech in WAV or MP3. The CLI picks the format from the model: `mist` and `mistv2` default to MP3, while `coda` and `mistv3` default to WAV. Use `--format` to override.

```bash theme={null}
rime tts TEXT --speaker VOICE --model-id MODEL
```

<img alt="Demo of the rime tts command" />

## Required flags

| Flag | Short | Description |
| - | - | - |
| `--speaker` | `-s` | Voice speaker to use (e.g., `astra`, `celeste`, `orion`) |
| `--model-id` | `-m` | Model ID: `coda`, `mistv3`, `mistv2`, or `mist` |

## Optional flags

| Flag | Short | Default | Description |
| - | - | - | - |
| `--output` | `-o` | -- | Output file path. Use `-` for stdout. If omitted, plays audio directly |
| `--play` | `-p` | `false` | Play audio after synthesis (default behavior when no output is specified) |
| `--lang` | `-l` | -- | BCP 47 language tag (e.g., `en`, `es`, `fr`). Defaults to the model's own language |
| `--format` | `-f` | -- | Audio format: `wav` or `mp3` (overrides model default) |
| `--speed-alpha` | -- | `1` | Speed multiplier, which must be greater than 0. For `mist`/`mistv2`: lower is faster. For `coda` and `mistv3`: higher is faster |
| `--sampling-rate` | -- | -- | Output sampling rate in Hz. Coda: `8000`, `16000`, `22050`, `24000`, `44100`, `48000`, `96000`. Mist: `4000`–`44100` |
| `--api-url` | -- | -- | API URL (default: `$RIME_API_URL` or `https://users.rime.ai/v1/rime-tts`) |

## Coda flags

The CLI rejects these flags for `mist`, `mistv2`, and `mistv3`.

| Flag | Default | Description |
| - | - | - |
| `--max-tokens` | `1200` | Max output tokens (200–5000) |
| `--temperature` | `0.5` | Sampling temperature (0–1) |
| `--top-p` | `1` | Nucleus sampling threshold (0–1) |
| `--repetition-penalty` | `1.5` | Repetition penalty (1–2) |

## mist/mistv2/mistv3 flags

The CLI rejects these flags for `coda`.

| Flag | Description |
| - | - |
| `--inline-time-scale-factor` | Comma-separated per-segment speed values |
| `--pause-between-brackets` | Insert pause at bracketed markers |
| `--phonemize-between-brackets` | Phonemize text in brackets. On `mistv3`, English only (see [Custom pronunciation](/docs/custom-pronunciation)) |

## mist/mistv2 flags

Only `mist` and `mistv2` support these flags, so the CLI rejects them for `mistv3`.

| Flag | Description |
| - | - |
| `--no-text-normalization` | Disable text normalization |
| `--save-oovs` | Save out-of-vocabulary words |

## Examples

```bash theme={null}
# Play audio directly through speakers
rime tts "Hello world" -s astra -m coda

# Save to a WAV file
rime tts "Hello world" -s astra -m coda -o output.wav

# Pipe audio to stdout
rime tts "Hello world" -s astra -m coda -o - > audio.wav

# Use mistv3 (WAV by default)
rime tts "Hello world" -s peak -m mistv3

# Use mistv2 (outputs MP3 by default)
rime tts "Hello world" -s peak -m mistv2

# Synthesize in Spanish with a Spanish Coda voice
rime tts "Hola mundo" -s brisa -m coda -l es

# JSON output with timing metadata
rime tts "Hello world" -s astra -m coda -o output.wav --json
```

## Language

Omit `--lang` and the model synthesizes in its own language, which is what you
want for a voice that speaks one language. Pass a BCP 47 tag to be explicit, and
choose a voice that speaks that language: `astra` is an English voice, so the
Spanish example above uses `brisa`.

The CLI does not check `--lang`: it sends the value as given, and the API
rejects a tag the model cannot serve. See [Languages](/docs/voices#languages)
for what each model supports.


# Troubleshooting
Source: https://docs.rime.ai/cli-reference/troubleshooting

Fix common issues with the Rime CLI.

## "no API key configured"

`rime usage` reports this when no key is stored, but the TTS commands fail with "authentication failed: invalid API key" instead. Run `rime login` or set the environment variable:

```bash theme={null}
export RIME_CLI_API_KEY=your_key_here
```

## "authentication failed: invalid API key"

The API rejected the key the CLI sent. Run `rime config show` to see which key the CLI resolved and where it came from, because a stale `RIME_CLI_API_KEY` overrides the key in `rime.toml`. Then verify the key at [app.rime.ai/tokens](https://app.rime.ai/tokens) and run `rime login` again.

## "unsupported format: ... (supported: wav, mp3)"

The CLI writes only WAV or MP3. `mist` and `mistv2` default to MP3, and the other models default to WAV. If you pick a format a model can't serve, the API rejects it, not the CLI. Select a supported format explicitly:

```bash theme={null}
rime tts "Hello" -s cove -m mistv2 -f mp3
```

## No audio playback

* Check your system audio output settings
* Try saving to a file instead: `rime tts "Hello" -s astra -m coda -o output.wav`
* Headless builds (e.g., Docker) require `-o FILE` because they have no audio playback

## "command not found: rime"

The shell installer adds its `bin` directory (`~/.rime/bin` by default) to your PATH through your shell's startup file, and the change reaches only new shells. Open a new terminal window or run:

```bash theme={null}
source ~/.zshrc   # or ~/.bashrc
```

If you skipped the installer's PATH prompt, the startup file wasn't changed. Add the line the installer printed to your shell config, then reload it.


# Abbreviations, acronyms, and initialisms
Source: https://docs.rime.ai/docs/abbreviations

How Rime pronounces abbreviations, acronyms, and initialisms, with controls for exceptions.

Rime pronounces most common abbreviations, acronyms, and initialisms correctly out of the box. The patterns below show how to format input when you want to control pronunciation explicitly.

<Note>
  For a tour of text normalization across all categories, see [Text normalization](/docs/text-normalization). For specific patterns Rime doesn't expand cleanly, see [Pre-normalizing text](/docs/pre-normalization).
</Note>

## Abbreviations

| Format | Example | Reads as |
| :- | :- | :- |
| Title abbreviation | `Dr. Smith` | doctor smith |
| Latin abbreviation | `e.g.` | for example |
| Street abbreviation | `rd.` | road |
| Saint abbreviation | `St. John` | saint john |

Some abbreviations resolve from context. For example, `St.` reads as "saint" in `St. John` but "street" in `Main St.` See [Addresses](/docs/addresses) for street and state abbreviations in address context.

## Acronyms and initialisms

Acronyms are pronounced as a single word. For example, `NASA` reads as "Nasa". Initialisms are pronounced as a series of letters, so `DNA` reads as "D N A".

By default, Rime pronounces a series of capital letters as an acronym. Common initialisms such as `DNA`, `ID`, `USA`, `FBI`, and `CIA` are pronounced as a series of letters automatically.

To force initialism pronunciation reliably, **use lowercase letters with a period and space after each**:

| Format | Example | Reads as |
| :- | :- | :- |
| Capitalized acronym | `NASA` | Nasa |
| Capitalized initialism (recognized) | `DNA` | D N A |
| Lowercase + dotted | `d. n. a.` | D N A |
| Lowercase + dotted | `u. p. s.` | U P S |
| Lowercase + dotted | `g. p. a.` | G P A |

<Note>
  You can also specify a custom pronunciation for any acronym or initialism using Rime's [custom pronunciations](/docs/custom-pronunciation) feature.
</Note>

## Known gaps

Context-dependent abbreviations like `Dr.`, `Mr.`, and `St.` rely on surrounding words to resolve and may not always read the way you expect. For workarounds and a drop-in prompt template, see [Pre-normalizing text](/docs/pre-normalization).

## Related

* [Custom pronunciation](/docs/custom-pronunciation) for defining how a specific term should sound
* [Spell function](/docs/spell) for forced letter-by-letter reading of unrecognized acronyms (`spell(NPI)`)
* [Addresses, URLs, and emails](/docs/addresses) for street and state abbreviations in address context


# Addresses, URLs, and emails
Source: https://docs.rime.ai/docs/addresses

How Rime automatically expands street addresses, URLs, and email addresses into spoken form.

Rime expands addresses, URLs, and email addresses into their spoken form automatically.

<Note>
  For a tour of text normalization across all categories, see [Text normalization](/docs/text-normalization). For specific patterns Rime doesn't expand cleanly, see [Pre-normalizing text](/docs/pre-normalization).
</Note>

## Addresses

Write out the full state name (for example, "Massachusetts" instead of "MA") for the most consistent results. Rime usually reads state abbreviations correctly in an address, and it expands common street abbreviations such as `Rd.` and `St.` into full words. All three inputs below produce the same reading.

| Format | Example | Reads as |
| :- | :- | :- |
| Full street + state name | `529 Main Street, Boston, Massachusetts 02129` | five hundred twenty-nine main street, boston, massachusetts, zero two one two nine |
| Abbreviated street + abbreviated state | `529 Main St., Boston, MA 02129` | five hundred twenty-nine main street, boston, massachusetts, zero two one two nine |
| Mixed | `529 Main St, Boston, MA 02129` | five hundred twenty-nine main street, boston, massachusetts, zero two one two nine |

## URLs

Schemes, `www.` prefixes, paths, and hyphens in domains are handled. Two-letter TLDs (`.io`, `.ai`, `.co`) are read letter-by-letter, while word-like TLDs (`.com`, `.org`, `.net`, `.info`, `.dev`) are read as words.

| Format | Example | Reads as |
| :- | :- | :- |
| Bare `www.` URL | `www.example.com` | double-u double-u double-u dot example dot com |
| HTTPS URL | `https://app.rime.ai` | h t t p s colon slash slash app dot rime dot a i |
| URL with path | `www.shop.com/archive` | www dot shop dot com slash archive |
| URL with path and scheme | `https://worldprime.io/about` | h t t p s colon slash slash world prime dot i o slash about |

## Emails

| Format | Example | Reads as |
| :- | :- | :- |
| Standard email | `name@example.com` | name at example dot com |
| Email with digits | `cloud799@icloud.com` | cloud seven nine nine at i cloud dot com |

<Note>
  Rime's custom segmentation model handles email addresses. It breaks up compound words and handles punctuation and most top-level domains. If you hear something off, contact [Rime support](mailto:support@rime.ai).
</Note>

## Known gaps

Internationalized domain names (non-ASCII characters in URLs) aren't supported. For the full list of normalization gaps and how to handle them, see [Pre-normalizing text](/docs/pre-normalization).

## Related

* [Numbers, currency, and measurements](/docs/numbers) for phone numbers and other numeric formats
* [Spell function](/docs/spell) for forced letter-by-letter reading of unusual email addresses or vanity URLs


# API authentication
Source: https://docs.rime.ai/docs/api-authentication

How to authenticate with the Rime TTS API using a bearer token.

Every request to the Rime API requires a **bearer token**. Send it in the `Authorization` header. WebSocket clients that cannot set headers may instead pass `?rime_apikey=YOUR_API_KEY` on the connection URL, but this puts the key in URLs and proxy logs, so prefer a server-side bridge that sets the header.

## Get an API key

<Warning>
  An API key can synthesize speech against your account. Keep it on the server and treat it like a password.
</Warning>

1. Sign in to the [Rime dashboard](https://app.rime.ai).
2. In the Rime dashboard, open [**API Tokens**](https://app.rime.ai/tokens).
3. Create a token and copy its value.

## Use the token

This request authenticates with a bearer token and saves the MP3 response to `hello.mp3`:

```bash theme={null}
curl --request POST \
  --url https://users.rime.ai/v1/rime-tts \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: audio/mpeg' \
  --fail \
  --show-error \
  --output hello.mp3 \
  --data '{"speaker":"astra","text":"hello","modelId":"coda","lang":"en"}'
```

If the key is accepted, you'll hear "hello" when you play `hello.mp3`. If it isn't, `--fail` stops curl with a `401` instead of saving the error text as the file.

Use the same header for the HTTP, WebSocket, metadata, and utility endpoints.

## CLI authentication

The `rime` CLI manages the key locally. Run [`rime login`](/cli-reference/rime-auth) once, and the CLI stores the key at `~/.rime/rime.toml`. You can also set it with the `RIME_CLI_API_KEY` environment variable.

## On-prem authentication

Caller authentication depends on the deployment. A standalone licensed engine doesn't authenticate callers, so your gateway must. Its `RIME_API_KEY` only authenticates the engine's usage reports to Rime. In an existing API/model pair, the API service accepts the same `Authorization: Bearer …` header, or you can configure `RIME_API_KEY` for the deployment so callers don't need to send it. See [the on-prem quickstart](/docs/on-prem/quickstart) for details.

## Common auth errors

If your request fails authentication, the API returns `401 Unauthorized` with a short plain-text body explaining why:

| Status | Body | Cause |
| :- | :- | :- |
| `401` | `missing headers` | No `Authorization` header was sent. |
| `401` | `invalid api key` | The token is not recognized, or it was sent without the `Bearer` scheme. |
| `401` | `invalid subscription` | The token is valid, but its account has neither a valid subscription nor a positive balance. Check billing before regenerating the key. |

Always send the header as `Authorization: Bearer <token>` (capital `B`). The token alone, without `Bearer`, is rejected.

## Related

* [Quickstart: TTS in five minutes](/docs/quickstart-five-minute)
* [API reference index](/docs/api-reference)
* [CLI authentication commands](/cli-reference/rime-auth)


# API cheat sheet
Source: https://docs.rime.ai/docs/api-cheat-sheet

Base URLs, bearer authentication, and runnable examples for Rime's HTTP, WebSocket, voice, vocabulary, and text-normalization endpoints.

Create a key on the [API Tokens page](https://app.rime.ai/tokens) before running the authenticated examples below.

## Hosts and authentication

| What | Where |
| - | - |
| REST API (TTS, voices, coverage) | `https://users.rime.ai` |
| WebSocket API | `wss://users-ws.rime.ai` |
| Text normalization | `https://optimize.rime.ai` |
| Docs (this site, plus `/llms.txt` and per-page `.md` exports) | `https://docs.rime.ai` |

<Warning>
  * Send TTS requests to `users.rime.ai`, not `api.rime.ai`. The latter serves internal infrastructure and returns `404` for TTS requests.
  * Authenticate with `Authorization: Bearer YOUR_API_KEY`. On WebSocket connections, send the same value as a connection header.
  * Keep the key on a server. Browser `WebSocket` objects cannot set the required header, so browser applications need a server-side bridge.
</Warning>

Rime publishes Python [`rime-api`](https://pypi.org/project/rime-api/) and JavaScript [`@rimelabs/api`](https://www.npmjs.com/package/@rimelabs/api) for generated TTS message definitions and schemas. These packages cover the [standalone engine protocol](/docs/on-prem/protocols#python-and-javascript-packages). Your application still manages connections and authentication. The cloud examples below use standard HTTP and WebSocket clients.

## Synthesize speech (HTTP)

`POST /v1/rime-tts` returns audio bytes in the format named by your `Accept` header (`audio/mpeg`, `audio/wav`, `audio/webm;codecs=opus`, `audio/ogg;codecs=opus`, `audio/L16`, `audio/PCMU`):

```bash theme={null}
curl -X POST https://users.rime.ai/v1/rime-tts \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: audio/mpeg' \
  --output hello.mp3 \
  -d '{"text": "Hello from Rime.", "speaker": "astra", "modelId": "coda"}'
```

Full parameters and streaming variants: [Coda HTTP reference](/api-reference/coda/http) · [Streaming guide](/docs/streaming)

## Stream speech (WebSocket `/ws3`)

Synthesis arguments go in the query string; auth goes in the connection header. Send `{"text": ...}` messages (buffered by sentence by default) and operations (`{"operation": "flush" | "clear" | "eos"}`); receive JSON events: `chunk` (base64 audio), `timestamps` (word-level), `done`, `error`.

```python theme={null}
import asyncio, base64, json, os
import websockets  # pip install websockets

async def main():
    url = "wss://users-ws.rime.ai/ws3?speaker=astra&modelId=coda&audioFormat=mp3"
    headers = {"Authorization": f"Bearer {os.environ['RIME_API_KEY']}"}
    async with websockets.connect(url, additional_headers=headers) as ws:
        await ws.send(json.dumps({"text": "Hello from Rime over WebSockets."}))
        await ws.send(json.dumps({"operation": "eos"}))  # synthesize what's buffered, then close
        audio = b""
        async for raw in ws:
            event = json.loads(raw)
            if event["type"] == "chunk":
                audio += base64.b64decode(event["data"])
            elif event["type"] == "timestamps":
                print("words:", event["word_timestamps"]["words"])
            elif event["type"] == "done":
                break
    with open("output.mp3", "wb") as f:
        f.write(audio)
    print(f"saved {len(audio)} bytes to output.mp3")

asyncio.run(main())
```

Set `modelId` explicitly on `/ws3`. Without it, requests are served by the **Mist v3** backend, and speakers outside the Mist v3 catalog fail with a "Speaker not found" error. Message schemas: [Coda WebSocket reference](/api-reference/coda/websockets-json) · Buffering control: [Segmentation](/docs/websockets-segment) · Web-app bridge pattern: [Next.js voice-agent guide](/docs/voice-agent-nextjs#3-stream-over-websockets-when-latency-matters)

## List voices

Both voice endpoints are public; no API key required.

```bash theme={null}
# Voice names, keyed by modelId then ISO 639-2 language code
curl https://users.rime.ai/data/voices/all-v2.json

# Full metadata per voice (gender, age, dialect, language, flagship flag, …)
curl https://users.rime.ai/data/voices/voice_details.json
```

Choosing a voice: [Voices guide](/docs/voices) · Reference: [List All Voices](/api-reference/data/voices-v2) · [List Voice Details](/api-reference/data/voice-details)

## Check vocabulary coverage (`/oov`)

Returns the input words that are **not** in Rime's pronunciation dictionary:

```bash theme={null}
curl -X POST https://users.rime.ai/oov \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"text": "hello kubectl blorbify"}'
# → ["kubectl","blorbify"]
```

Out-of-dictionary words still get a best-effort pronunciation; to control them, see [Custom pronunciation](/docs/custom-pronunciation). Reference: [Vocabulary Coverage](/api-reference/other/oov)

## Normalize text (`/textnorm`)

Preview exactly how numbers, dates, and phone numbers will be spoken. Note the host: `optimize.rime.ai`.

```bash theme={null}
curl -X POST https://optimize.rime.ai/textnorm \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"text": "Call 1-800-444-4141 on 3/4/2026"}'
# → {"normalized":"Call one, eight hundred, four four four, four one four one on march fourth twenty twenty six"}
```

Guide: [Text normalization](/docs/text-normalization) · Reference: [Text Normalization](/api-reference/other/textnorm)

## Common parameters

| Parameter | Values | Notes |
| - | - | - |
| `speaker` | See [voices](/docs/voices) | Required. Must match the model and language. |
| `modelId` | `coda` (flagship), `mistv3` | Set it explicitly. Without one, `/ws3` serves only the Mist v3 voice catalog. |
| `text` | string | Up to 1,000 characters per request (HTTP returns `400` "text is too long" beyond that). |
| `lang` | `en`/`eng`, `es`/`spa`, `fr`/`fra`, `pt`/`por`, `de`/`ger`, `ja`/`jpn`, `ar`/`ara`, `hi`/`hin` | Must match the speaker's language. |
| `audioFormat` (WS) | `wav`, `mp3`, `ogg`, `webm`, `pcm`, `mulaw` | HTTP uses the `Accept` header instead. |
| `segment` (WS) | `bySentence` (default), `immediate`, `never` | When synthesis triggers; see [Segmentation](/docs/websockets-segment). |
| `samplingRate` | `8000`–`96000`, default `24000` | Values above 24000 are upsampling. |

## Where to go deeper

* [API reference index](/docs/api-reference): every endpoint across every model
* [WebSocket API overview](/docs/websockets): endpoint comparison, timestamps, interruption handling
* [Build a voice agent](/docs/voice-agent-nextjs): complete apps in Next.js, Vite, Express, plain Node, and FastAPI
* [Rime CLI](/docs/quickstart-cli) and the [hosted MCP server](/docs/mcp): tooling around this same API


# API reference index
Source: https://docs.rime.ai/docs/api-reference

Index of Rime's TTS HTTP, WebSocket, and metadata endpoints across all supported models.

Send TTS requests to `https://users.rime.ai/v1/rime-tts` and authenticate with a bearer token in the `Authorization` header. See [API authentication](/docs/api-authentication).

Most clients should start with **Coda**, Rime's flagship model:

* [Coda: Streaming HTTP](/api-reference/coda/http)
* [Coda: WebSockets (`/ws`)](/api-reference/coda/websockets)
* [Coda: WebSockets JSON (`/ws3`)](/api-reference/coda/websockets-json)

For the cross-model overview of when to use each WebSocket endpoint, see [WebSocket API Overview](/docs/websockets).

## TTS endpoints by model

| Model | Streaming HTTP | WebSocket `/ws` | WebSocket JSON |
| - | - | - | - |
| **Coda** (flagship) | [HTTP](/api-reference/coda/http) | [/ws](/api-reference/coda/websockets) | [/ws3](/api-reference/coda/websockets-json) |
| **Mist v3** | [HTTP](/api-reference/mistv3/http) | [/ws](/api-reference/mistv3/websockets) | [/ws3](/api-reference/mistv3/websockets-json) |
| **Mist v2** | [HTTP](/api-reference/mistv2/http) · [SSE](/api-reference/mistv2/sse) | [/ws](/api-reference/mistv2/websockets) | [/ws2](/api-reference/mistv2/websockets-json) |

Mist v2 also exposes non-streaming JSON-wrapped formats: [MP3](/api-reference/mistv2/json-mp3), [WAV](/api-reference/mistv2/json-wav), [Opus/OGG](/api-reference/mistv2/json-ogg), [G.711 μ-law](/api-reference/mistv2/json-mulaw).

## Metadata endpoints

* [List All Voices](/api-reference/data/voices-v2): `GET /data/voices/all-v2.json`
* [List Voice Details](/api-reference/data/voice-details): `GET /data/voices/voice_details.json`

## Utility endpoints

* [Coverage (out-of-vocabulary check)](/api-reference/other/oov): `POST /oov`
* [Text Normalization](/api-reference/other/textnorm): `POST /textnorm`

## Related

* [Quickstart: TTS in five minutes](/docs/quickstart-five-minute)
* [Models](/docs/models): comparing Coda and Mist
* [Voices](/docs/voices): voice lineup and language support
* [Latency tuning](/docs/latency)
* [Changelog](/docs/changelog)


# Baseten
Source: https://docs.rime.ai/docs/baseten

Deploy Rime TTS on Baseten's serverless GPU infrastructure.

<IntegrationHeader />

Run Rime's text-to-speech engine in your own [Baseten](https://www.baseten.co/) workspace, on Baseten's autoscaling GPU infrastructure. Each model runs as a single-container deployment: the engine validates its own license and serves TTS directly, with no separate router.

## Get started

Ready-to-use deploy configs for Rime's models live in the [`rimelabs/rime-baseten-deploy`](https://github.com/rimelabs/rime-baseten-deploy) repository. Each model directory contains a Baseten/[Truss](https://truss.baseten.co/) `config.yaml` plus a README with full deploy, secrets, and invocation steps.

| Model | Directory |
| - | - |
| Rime Coda v1: flagship expressive TTS | [`rime-coda-v1/`](https://github.com/rimelabs/rime-baseten-deploy/tree/main/rime-coda-v1) |
| Rime Mist v3: low-latency conversational | [`rime-mist-v3/`](https://github.com/rimelabs/rime-baseten-deploy/tree/main/rime-mist-v3) |

## Prerequisites

Before cloning the deployment repository, contact [help@rime.ai](mailto:help@rime.ai) for engine-image and license access. Your Baseten workspace needs these secrets:

* `gcp_rime_service_account`
* `rime_license`
* `rime_api_key`

To deploy:

1. Clone the repo and `cd` into the model directory you want.
2. Set the three required secrets in your Baseten workspace. The per-model README describes each value.
3. Push the config with the [Truss CLI](https://truss.baseten.co/):

```bash theme={null}
truss push .
```

4. Set the autoscaling concurrency target (each replica handles \~10 concurrent requests before a new one is added). See the model README for the exact Management API call.

## Invoke

Once deployed, send inference requests to your model's sync endpoint. The Rime API key is baked in via the `rime_api_key` secret, so callers authenticate to Baseten only. This request saves the audio to `output.webm`:

```python theme={null}
import requests

resp = requests.post(
    "https://model-<model-id>.api.baseten.co/environments/production/sync",
    headers={
        "Authorization": f"Api-Key {BASETEN_API_KEY}",
        "Accept": "audio/webm;codecs=opus",   # or audio/pcm, audio/mpeg
    },
    json={
        "text": "Natural-sounding, accurately-pronouncing AI TTS built for high-stakes enterprise conversations.",
        "speaker": "luna",
        "lang": "en",
    },
)
resp.raise_for_status()
with open("output.webm", "wb") as f:
    f.write(resp.content)
```

Play `output.webm` to confirm the deployment returns speech. `raise_for_status()` stops the script before it writes the file when Baseten returns an error status.

For full setup instructions, including secrets and autoscaling, see the [`rime-baseten-deploy`](https://github.com/rimelabs/rime-baseten-deploy) README for your chosen model.


# Cerebrium
Source: https://docs.rime.ai/docs/cerebrium

Deploy Rime TTS on Cerebrium's serverless infrastructure.

<IntegrationHeader />

Deploy Rime TTS on [Cerebrium](https://www.cerebrium.ai/) with a Rime API key and Cerebrium CLI 1.39.0 or later. The deployment exposes REST and WebSocket interfaces and scales according to the concurrency and replica settings in `cerebrium.toml`.

### Get started

1. Create a Rime account and obtain your API key.
2. Create a secret in Cerebrium named `RIME_API_KEY` with your Rime key. The Cerebrium container uses it to authenticate to the Rime API.
3. Initialize your app with the Cerebrium CLI (v1.39.0 or higher):

```bash theme={null}
cerebrium init rime
```

4. Define your deployment using a `cerebrium.toml` file with the `[cerebrium.runtime.rime]` configuration. Specify your compute resources (e.g., AMPERE\_A10 GPU, memory, CPU), scaling parameters, and region (e.g., `us-east-1`).
   See [Cerebrium's documentation](https://cerebrium.ai/docs/cerebrium/partner-services/rime) for full implementation details.

5. Deploy with:

```bash theme={null}
cerebrium deploy
```

Once deployed, you can send real-time TTS inference requests using either:

* REST API, with an endpoint like:

```bash theme={null}
https://api.cerebrium.ai/v4/<project-id>/rime
```

Include your Rime API key in the Authorization header and specify your desired speaker, model, and text.

* WebSocket interface for streaming audio

For full setup instructions, see the [Cerebrium documentation](https://cerebrium.ai/docs/cerebrium/partner-services/rime).


# Changelog
Source: https://docs.rime.ai/docs/changelog

Release notes for Rime's TTS API and on-prem images.

## Rime API changelog

<Tip>Subscribe to the [RSS feed](https://docs.rime.ai/docs/changelog/rss.xml) to get notified of new releases.</Tip>

<Update label="2026-09-25">
  * The [on-prem quickstart](/docs/on-prem/quickstart) now uses model image tag `20260923` for Coda and Mist v3.
  * Standalone licensed deployment needs an image reference and runtime license confirmed by Rime for this mode. Follow [Migrate an existing deployment](/docs/on-prem/quickstart#migrate-an-existing-deployment) before you switch from an API/model pair.
</Update>

<Update label="2026-09-12">
  * On-prem release `20260912` includes these changes since the previously documented tag, `20260801`:
    * Coda updates to the 1.0.5 model checkpoint and adds voices, including `walnut`, `harrison_mary`, and `cohen_emily`.
    * Coda bounds long generations at sentence boundaries while preserving audio order within a request. Its maximum audio duration calculation now uses the codec's correct rate, so the configured 180-second limit no longer cuts a generation off at 172.8 seconds.
    * Mist v3 avoids TensorRT teardown hangs and crashes during shutdown after draining admitted requests.
  * Keep the service configuration when you update an existing API/model pair to `20260912`. Update both containers together, using the API image and your model's image:
    * API: `us-docker.pkg.dev/rime-labs/api/service:20260912`
    * Coda: `us-docker.pkg.dev/rime-labs/coda/v1/coda:20260912`
    * Mist v3: `us-docker.pkg.dev/rime-labs/mist/v3/omni:20260912`
</Update>

<Update label="2026-08-25">
  * The [Data and privacy](https://app.rime.ai/data-and-privacy) page in the Rime dashboard now lets you control optional request-data retention for your personal account or team.
    * Optional retention is disabled by default. Team members can view the setting, and team owners can change it.
    * If you enable retention, Rime can keep customer content and technical request details to investigate support issues and improve speech quality. This setting does not permit model training.
</Update>

<Update label="2026-08-15">
  * Arcana retired from the Rime cloud API. Requests using `arcana`, `arcanav2`, or `arcanav3` are now served by Coda. Replace the retired identifier and verify the voice and language pairing with [Remove Arcana model IDs](/docs/migrate-arcana-to-coda).
  * Release `20260815`:
    * Improved text normalization, including more consistent tokenization and handling of symbols, fractions, and common numeric expressions.
</Update>

<Update label="2026-08-04">
  * The [language matrix](/docs/voices#languages) now lists support per model.
    * Coda serves English, Arabic, French, German, Hindi, Japanese, Portuguese, and Spanish.
    * Mist v3 serves English, French, German, and Spanish.
    * The `lang` parameter tables in the [Coda API reference](/api-reference/coda/http) now include Arabic and Hindi.
</Update>

<Update label="2026-07-29">
  * **Cloud Arcana requests will switch to Coda on August 15, 2026.**
    * On August 15, cloud Arcana traffic will route to [Coda](/docs/models#coda). Migrate by changing `modelId: arcana` to `modelId: coda`; the API contract is unchanged. Sinhala remains available on Arcana.
    * **On-prem:** existing Arcana images remain available to pull and run, but will not receive updates or support (including vulnerability patches and text-normalization fixes) after August 15, 2026.
    * We recommend migrating before August 15 so you can test voices and validate output on your own timeline. Questions? Contact [support@rime.ai](mailto:support@rime.ai).
</Update>

<Update label="2026-07-10">
  * Rime now hosts a first-party MCP (Model Context Protocol) server at [mcp.rime.ai](https://mcp.rime.ai):
    * Connect Claude, OpenAI Codex, your IDE, or any MCP-compatible client to browse the voice catalog, check dictionary coverage, preview text normalization, generate speech samples, and scaffold Pipecat or LiveKit integration code.
    * Catalog and integration tools work without an API key; synthesis and linguistics tools authenticate with your existing Rime API key, sent per request.
    * See the [MCP quickstart](/docs/mcp) to get connected, and the [MCP server reference](/mcp-reference/overview) for tool-by-tool documentation.
</Update>

<Update label="2026-06-11">
  * The Speech QA dashboard has been retired from the Rime web app.
    * Pronunciation features remain fully supported via the API: check dictionary coverage with the [Coverage API](/api-reference/other/oov) and specify custom pronunciations inline with the [Rime phonetic alphabet](/platform/rime-phonetic-alphabet) and `phonemizeBetweenBrackets` (Mist v1/v2).
    * To request a pronunciation fix or dictionary addition, reach out to your account manager via Slack or email, or contact [sales@rime.ai](mailto:sales@rime.ai).
    * The `saveOovs` parameter on Mist v1/v2 endpoints remains supported for backward compatibility, but has been removed from the API reference along with the dashboard it reported to.
    * Newly documented: the [Phonemize API](/api-reference/other/phonemize); post a recording of a word and get back a phonetic string in the Rime phonetic alphabet.
    * See [Pronunciation control](/platform/pronunciation-control) for an overview of all the ways to control pronunciation.
</Update>

<Update label="2026-05-19">
  * **Coda** is now available via `modelId: coda`:
    * New flagship TTS model; sophisticated LLM backbone paired with a dedicated speech inference engine, trained on conversational full-duplex data.
    * Surpasses prior Rime models and competitor offerings in human-led voice-quality evaluations across naturalness, prosody, and artifact-free output.
    * Sub-100ms model latency on the GPU engine (self-hosted or on-prem); cloud API users add roughly 25–50ms network round-trip from most of the continental US. See [Regional endpoints](/docs/regional-endpoints).
    * Multilingual support across English, French, German, Japanese, Portuguese, and Spanish.
    * Word-level timestamps over the JSON websocket endpoint for text-audio alignment and interruption handling.
    * Available via the cloud API and on-premises at launch.
    * **Recommended successor to Arcana** for all existing Arcana traffic; swap `modelId: arcana` for `modelId: coda`.
    * See the [Coda API reference](/api-reference/coda/http) for details.
</Update>

<Update label="2026-04-24">
  * API on-prem image `20260424`:
    * New environment variables for authentication configuration:
      * `RIME_API_KEY`: pre-configure the API key at the deployment level so callers don't need to include it in each request. Can also be mounted as a secret file at `/secrets/rime_api_key`.
      * `API_KEY_HEADER`: specify an alternate header name for platforms that intercept the `Authorization` header.
      * `PLATFORM_API_KEY`: supply a platform API key for authenticated inter-container requests. Can also be mounted as a secret file at `/secrets/platform_api_key`.
</Update>

<Update label="2026-04-20">
  * Arcana V2, Arcana V3 and Mist V3 release `20260420`.
  * General performance improvements and bug fixes.
</Update>

<Update label="2026-04-09">
  * Arcana release `20260404`:
    * Improved and stabilized text normalization across all supported languages.
    * Upgrade to `20260404` is recommended.
  * Mist v3 release `20260404`:
    * Reached general availability.
  * General performance improvements across the inference stack for all models.
</Update>

<Update label="2026-04-07">
  * API on-prem image `20260407`:
    * Compatible with Mist v3.
</Update>

<Update label="2026-04-06">
  * Mist v3 is now available via `modelId: mistv3`:
    * TTFB well below 100ms: a major latency improvement over Mist v2 without sacrificing quality
    * Popular Mist v2 speakers available, plus 8 Arcana flagship speakers now available as Mist v3 voices
    * See the [full voice list](/api-reference/data/voices)
</Update>

<Update label="2026-02-23">
  * Arcana release `20260223`:
    * v3 (multilingual)
      * Supported languages: `de`, `en`, `es`, `fr`, `he`, `ja`, `pt`, `si`, `ta`.
    * General performance improvements and bug fixes.
</Update>

<Update label="2026-02-11">
  * API on-prem image `20260212`:
    * Exposes a new json websockets endpoint with WLT (equivalent to the cloud api's `ws3` endpoint) on port 8003
</Update>

<Update label="2026-02-05">
  * Arcana v3 `lang` parameter: 2- and 3-letter ISO 639 codes that map to the same language are accepted and normalized (e.g. <code>de</code>, <code>deu</code>, or <code>ger</code> for German; <code>fr</code>, <code>fra</code>, or <code>fre</code> for French). Supported languages:

    | 639-1 | 639-2/639-3 | Language |
    | - | - | - |
    | de | deu, ger | German |
    | en | eng | English |
    | es | spa | Spanish |
    | fr | fra, fre | French |
    | he | heb | Hebrew |
    | ja | jpn | Japanese |
    | pt | por | Portuguese |

    Any valid ISO 639-1, 639-2, or 639-3 code that maps to one of these languages is accepted.
</Update>

<Update label="2026-02-04">
  * Regional endpoints available:
    * `wss://users-east-ws.rime.ai/ws*` offers all the websockets apis currently served served via `wss://users-ws.rime.ai/ws*` and may provide better latency
      for clients closer to `us-east-1`.
    * `https://users-east.rime.ai/v1/rime-tts` offers all the same API currently served via `https://users.rime.ai/v1/rime-tts`, and may provide better latency
      for clients closer to `us-east-1`.
    * Additionally `https://users-west.rime.ai/v1/rime-tts` offers all the apis currently served via `https://users.rime.ai/v1/rime-tts`, and may provide better latency
      for clients closer to `us-west-1`.
  * Arcana now supports JSON websockets with Word-Level-Timestamps:
    * `wss://users-ws.rime.ai/ws3` and `wss://users-east-ws.rime.ai/ws3` serve the JSON websockets api that now supports both `mist` and `arcana` model classes.
  * Arcana release `20260204` (Arcana v3):
    * Added support for languages: English (`lang=eng`), French (`lang=fra`), German (`lang=ger`), Hebrew (`lang=heb`), Japanese (`lang=jpn`), Portuguese (`lang=por`), Spanish (`lang=spa`).
    * Languages can be specified using either 2-character codes (`en`, `fr`, `de`, `he`, `ja`, `pt`, `es`) or 3-character codes (`eng`, `fra`, `ger`, `heb`, `jpn`, `por`, `spa`).
</Update>

<Update label="2026-02-03">
  * Arcana now supports the `spell()` function. You can use `spell()` to spell out sequences letter by letter or number by number with Arcana voices. See the [spell function documentation](/docs/spell) for examples.
</Update>

<Update label="2026-01-31">
  * Arcana release `20260131`:
    * General performance improvements and bug fixes.
</Update>

<Update label="2026-01-24">
  * Arcana release `20260124`:
    * Fixed speaker mapping for English Arcana.
    * General performance improvements and bug fixes.
</Update>

<Update label="2026-01-23">
  * API on-prem image `20260123`:
    * Exposes the binary websockets API on port 8002. This API is equivalent to the [cloud websockets API](/api-reference/mistv2/websockets).
</Update>

<Update label="2026-01-22">
  * Arcana release `20260122`:
    * `rime.engine.initial_latency` and `rime.engine.generated_audio_duration` have saner defaults and [can be tuned](/docs/on-prem/metrics).
    * Added `spell()` support.
    * General performance improvements and bug fixes.
</Update>

<Update label="2026-01-15">
  * Arcana release `20260115`:
    * Fixed an issue where there is static noise for some speakers at the end or in the middle of utterances.
    * A full set of ORCA headers are now returned for load balancing.
    * A `/statusz` endpoint is introduced for the model container that contains diagnostics information.
    * `/livez` now responds with `OK` as soon as the server starts up.
    * General performance improvements.
</Update>

<Update label="2026-01-14">
  * Added [Lovable integration guide](/docs/lovable) with template for building voice-enabled apps.
  * Added [Replit integration guide](/docs/replit) with template for building voice-enabled apps.
</Update>

<Update label="2025-12-20">
  * Arcana release `20251220`:
    * An ORCA header, `named_metrics.inference_concurrency_utilization`, is now returned in all HTTP responses.
    * Emojis are no longer read out.
    * General reliability updates.
</Update>

<Update label="2025-12-13">
  * Arcana release `20251213`:
    * Performance improvements for the English model.
    * Minimum requirements for NVIDIA drivers reduced to `525.60.13`.
    * General reliability updates.

  * API release `20251209`:
    * Exposes non-JSON WebSockets over port `8002`, allowing for Arcana over
      WebSockets.
    * Fixes an issue where `null` values were sent to the model for parameter
      keys not set by the user.
</Update>

<Update label="2025-12-06">
  * Arcana release `20251206`:
    * [OpenTelemetry metrics](/docs/on-prem/metrics#opentelemetry-metrics) are now available in the model images.
    * Quality and performance improvements.
</Update>

<Update label="2025-11-21">
  * Arcana release `20251121`:
    * Fixed an issue with μ-law encoding.
</Update>

<Update label="2025-11-20">
  * Arcana release `20251120`:
    * Fixed an issue with audio buffer underrun.
</Update>

<Update label="2025-11-19">
  * Arcana release `20251119`:
    * Fixed a startup issue in the `20251118` release.
</Update>

<Update label="2025-11-18">
  * Arcana release `20251118`:
    * General improvements.
</Update>

<Update label="2025-11-10">
  * Arcana release `20251110`:
    * Separate engine and data package containers for easier deployment.
    * General reliability improvements.
</Update>

<Update label="2025-11-06">
  * Mist on-prem model image `us-docker.pkg.dev/rime-labs/mist/v2/en:20251106` released.
  * Includes performance enhancements and minor fixes.
</Update>

<Update label="2025-11-05">
  * Mist on-prem model image `us-docker.pkg.dev/rime-labs/mist/v2/en:20251105` released.
</Update>

<Update label="2025-11-03">
  * Arcana on-prem model images tagged `20251101` release with language updates.
</Update>

<Update label="2025-10-29">
  * Arcana language update: additional language support and new voices.
</Update>

<Update label="2025-10-27">
  * Arcana on-prem model images tagged `20251027`: performance improvements.
  * Documentation on [performance tuning](/docs/on-prem/performance).
</Update>

<Update label="2025-10-15">
  * Arcana is now available via (non-json) websockets users.rime.ai/ws.
</Update>

<Update label="2025-10-14">
  * Arcana on-prem images with tag `20251014`: Fixed a bug related to sample rate.
</Update>

<Update label="2025-10-13">
  * Arcana on-prem images with tag `20251013`: General performance improvements.
</Update>

<Update label="2025-10-10">
  * Api on-prem image with tag `20251010`: Uses https instead of http in the external calls to rime.optimize.ai to acquire licenses and track usage.
  * ⚠️ When upgrading to this image you may have to update your firewall settings to account for the new URLs ([see docs](/docs/on-prem/quickstart#firewall-requirements)).
</Update>

<Update label="⚠️ 2025-09-30">
  * We have made breaking changes in voice details api ([https://users.rime.ai/data/voices/voice\_details.json](https://users.rime.ai/data/voices/voice_details.json))
  * In the voice details API, the field `model_id` has been renamed to `modelId` and `name` have been renamed to `speaker` for better clarity.
  * In the voice details API, the field `region` has been renamed to `dialect` for better clarity.
  * The `language` field value has been changed from short codes (e.g., `eng`) to human-readable names (e.g., `english`).
  * A new field `lang` has been added to retain the short language code (e.g., `eng`).
</Update>

<Update label="2025-09-29">
  * Arcana on-prem images with tag `20250929`: quality improvements.
</Update>

<Update label="2025-09-27">
  * Arcana on-prem images with tag `20250927`: quality improvements.
</Update>

<Update label="2025-09-25">
  * Arcana on-prem English image with tag `20250925`: performance improvements and general model stability enhancements.
  * Added two new Australian flagship voices:
    * `eucalyptus`
    * `marlu`
</Update>

<Update label="2025-09-24">
  * Arcana on-prem images with tag `20250924`: performance improvements.
</Update>

<Update label="2025-09-17">
  New api onprem image `us-docker.pkg.dev/rime-labs/api/service:20250917` released.

  * api image now supports multiple model backends.
  * /health endpoint on the api image now reports model status.
</Update>

<Update label="2025-09-13">
  * Both `/ws` and `/ws2` support the query param `saveOovs`, allowing tts users to track which words in their text are out-of-vocabulary on
    the Speech QA dashboard.
</Update>

<Update label="2025-09-13">
  * Arcana on-prem images from `20250913` now provide better latency and can run on H100 MIG (`3g.40gb`).
</Update>

<Update label="2025-09-09">
  * Arcana on-prem images from `20250909` now provide `/livez` and `/readyz` endpoints for liveness and readiness checks.
</Update>

<Update label="2025-09-08">
  * Arcana on-prem images from `20250908` now use 16-bit little endian for PCM and WAV.
  * Arcana on-prem images from `20250908` now support G-711 μ-law as an audio codec.
  * Arcana on-prem images from `20250908` now support the `speedAlpha` option for time scaling.
</Update>

<Update label="2025-09-02">
  * `saveOovs` parameter added to all mistv2 tts endpoints, enabling users to have out-of-vocabulary words logged to their Speech QA dashboard for review and addition to the mist lexicon.
</Update>

<Update label="2025-08-01">
  * Added French and German language support via the `lang` parameter in WebSocket JSON APIs. The `/ws2` api now has full language parity with the `/ws` and http tts endpoints.
</Update>

<Update label="2025-07-31">
  * Added Spanish language support via the `lang: spa` parameter in WebSocket JSON APIs.
  * Enhanced text segmentation with new `segment` parameter:
    * Added `segment` query parameter with three modes: "immediate", "never", and "bySentence" (default)
    * Deprecated `immediate` boolean parameter (still supported for backward compatibility)
    * Improved control over text processing and synthesis timing
</Update>

<Update label="2025-05-27">
  * The `<FLUSH>` command is now available on both the the websockets and websockets-json apis, allowing for immediate audio synthesis of all tokens in the buffer.
</Update>

<Update label="2025-04-24">
  * We've launched **Arcana**: a new model for expressive, natural voice synthesis. Available now with `modelId: arcana`.
</Update>

<Update label="2025-03-28">
  * The `lang` ID `spa-mx` has been added. Using this accesses the same spanish languages but uses `pesos` instead of `dolares` for currency.
  * New `lang: fra` has been added. We now have French voices available on the dashboard and via API.
</Update>

<Update label="2025-03-26">
  * The `spell()` function now works for Spanish. Try it out! "El nombre se escribe spell(Isabella)."
  * Fixed a bug where silence information is not processed properly when `pauseBetweenBrackets` is True
  * The url `demo-api.rime.ai` has been **deprecated**. Please use `demo.rime.ai` instead if you are using the demo API.
</Update>


# Custom pauses
Source: https://docs.rime.ai/docs/custom-pauses

Insert pauses of specific durations into Mist family synthesis using angle-bracket markers.

<Note>Custom pauses are supported by **Mist**, **Mist v2**, and **Mist v3**.</Note>

By default, Rime adds pauses based on sentence punctuation. To set a specific pause, insert its duration in milliseconds inside angle brackets.

For example, `<750>` inserts a pause of 750 milliseconds (or .75 seconds). In the second clip below, listen for the longer gap after "wait":

| Audio clip | Sentence |
| - | - |
| <audio /> | wait, are you actually serious. |
| <audio /> | wait. `<750>` are you actually serious. |

<Note>When making an API request, you must set `pauseBetweenBrackets` to `true`.</Note>

This Mist v3 request sends the second clip's sentence with its 750 ms pause:

```json Custom Pause Example theme={null}
{
	"text": "wait. <750> are you actually serious.",
    "speaker": "cove",
    "modelId": "mistv3",
    "pauseBetweenBrackets": true
}
```


# Custom pronunciation
Source: https://docs.rime.ai/docs/custom-pronunciation

Specify pronunciations for uncommon words in Mist family synthesis using Rime's phonetic alphabet.

<Note>Custom pronunciation is supported on **Mist v1, Mist v2, and English Mist v3**. Coda and non-English Mist v3 do not support it. See [Text normalization](/docs/text-normalization).</Note>

For uncommon words, such as unique brand names or product names, Rime's speech synthesis model may not always pronounce them correctly out of the box.

While the Rime team can add new words to the dictionary in about a week (reach out to your account manager via Slack or email, or contact [sales@rime.ai](mailto:sales@rime.ai), if you need faster turnaround or have an SLA), if you want to specify the pronunciation yourself, you can input a custom pronunciation string within curly brackets.

Before writing a pronunciation string by hand, you can [check the dictionary coverage](#check-coverage) to see whether the word is already covered.

Custom pronunciations use [Rime's phonetic alphabet](/platform/rime-phonetic-alphabet), which is inspired by the International Phonetic Alphabet (IPA). For example, the word `custom` would be represented as `{k1Ast0xm}`. This even works for made-up words, like `gorbulets`, which would be `{g1orby0ul2Ets}`.

| Audio clip | Sentence |
| - | - |
| <audio /> | actually, `{g1orby0ul2Ets}` is a word i just made up. |

<Note>When making an API request, you must set `phonemizeBetweenBrackets` to `true`. The request would look like this:</Note>

```python Custom pronunciation example theme={null}
{
	"text": "actually, {g1orby0ul2Ets} is a word i just made up.",
    "speaker": "peak",
    "modelId": "mistv2",
    "phonemizeBetweenBrackets": true
}
```

## Check coverage

Before writing a custom pronunciation by hand, check whether the word is already in Rime's dictionary using the [Coverage API](/api-reference/other/oov).

For an overview of all the ways to control pronunciation, see [Pronunciation control](/platform/pronunciation-control).

## Generate a pronunciation string from audio

If you know how a word should sound, you don't have to write the phonetic string by hand. Record the word and post the audio to the [Phonemize API](/api-reference/other/phonemize). It returns a string in the Rime phonetic alphabet that you can paste into your TTS request inside `{}`.

## The Rime phonetic alphabet

The Rime phonetic alphabet is inspired by IPA and covers vowels, consonants, and syllabic stress. The full symbol reference lives on its own page: [Rime phonetic alphabet](/platform/rime-phonetic-alphabet).


# Daily
Source: https://docs.rime.ai/docs/daily

Use Rime TTS with Daily's real-time video and voice platform via Pipecat.

<IntegrationHeader />

Use Rime as the TTS stage of a [Pipecat](https://github.com/pipecat-ai/pipecat) voice agent that runs on [Daily](https://www.daily.co/). Daily is a real-time video and voice platform built on WebRTC, and it created Pipecat, the open-source framework for building voice agents. The Pipecat guide builds a complete Python voice agent with Rime synthesis:

<Card title="Build a voice agent with Pipecat + Rime" icon="rocket" href="/docs/pipecat">
  Step-by-step Python guide: install, pipeline setup, Rime TTS configuration, and a browser-based agent you can talk to.
</Card>

The guide runs locally over Pipecat's built-in WebRTC transport, so you can test the agent without a Daily account. For production deployments, swap in Daily's hosted rooms as the transport. See [Pipecat's transport documentation](https://docs.pipecat.ai/server/services/transport/daily) for configuration details.


# Dates and times
Source: https://docs.rime.ai/docs/dates

How Rime automatically expands dates and clock times into spoken form, and which formats are supported.

Rime expands dates and clock times into their spoken form automatically. Most common formats work without any preprocessing.

<Note>
  For a tour of text normalization across all categories, see [Text normalization](/docs/text-normalization). For specific patterns Rime doesn't expand cleanly, see [Pre-normalizing text](/docs/pre-normalization).
</Note>

## Dates

Rime supports a variety of date formats, with year:

| Format | Example | Reads as |
| :- | :- | :- |
| MM/DD/YYYY | `10/12/2024` | october twelfth, twenty twenty-four |
| YYYY-MM-DD (ISO) | `2021-03-15` | the fifteenth of march twenty twenty-one |
| M.D.YYYY | `8.8.2018` | august eighth twenty eighteen |
| Month name + day + year | `April 2, 2024` | april second, twenty twenty-four |
| Day + month name + year | `5 July 2015` | the fifth of july twenty fifteen |
| Year alone | `1998` | nineteen ninety-eight |
| Month + year | `May 2019` | may twenty nineteen |
| Month + ordinal day (no year) | `January 1st`, `Jan. 1` | january first |

<Note>
  US (`MM/DD/YYYY`) and ISO (`YYYY-MM-DD`) dates read with different phrasing: "october twelfth..." versus "the fifteenth of march...". If every date should sound the same to the listener, use one format throughout.
</Note>

## Times

| Format | Example | Reads as |
| :- | :- | :- |
| Clock + meridiem | `3:45pm`, `10:30 AM` | three forty-five PM, ten thirty AM |
| 24-hour | `15:45` | fifteen forty-five |
| On-the-hour | `6:00` | six o'clock |
| Dotted meridiem | `6 a.m.`, `2 o'clock p. m.` | six AM, two o'clock PM |
| With time zone | `9:00 AM PST` | nine AM PST |
| Word forms | `noon`, `midnight`, `quarter past 6`, `half past 6` | as written |
| Ranges | `9:20-9:45` | nine twenty to nine forty-five |

Both `am/pm` and `a.m./p.m.` are accepted, with or without spaces between the time and the meridiem.

## Known gaps

A few specific date and time patterns aren't reliably expanded. The most common are MM/DD without a year (`04/21`), financial periods (`Q1 2025`, `1H 2024`), and European `15h30` times. For the full list and a drop-in prompt template to handle them, see [Pre-normalizing text](/docs/pre-normalization).

## Related

* [Numbers, currency, and measurements](/docs/numbers) for years used as standalone numbers, ranges, and ordinals


# Error reference
Source: https://docs.rime.ai/docs/errors

What the Rime API returns when a request fails, per transport, and what to capture when you need support.

Most Rime failures return the reason as a **plain-text body**: the status code carries the class of failure and the body carries the message. Two exceptions return JSON with an `error` field: an unhandled `500` from `POST /v1/rime-tts`, and failures from `/phonemize` or `/textnorm`. Branch on the status code and `Content-Type`, not the body shape. Neither form has a machine-readable error code field.

<Warning>**No response carries a request ID.** There is nothing in a response or close frame that you can quote back to support, so an accurate UTC timestamp is the single most useful thing to capture when something fails. Record everything under [what to send to support](#what-to-send-to-support) at the moment it happens.</Warning>

## How failures reach you, per transport

| Transport | Where it fails | What you observe |
| :- | :- | :- |
| HTTP `POST /v1/rime-tts` | Any | HTTP status, plain-text body with the message |
| WebSocket `/ws3`, `/ws2` | At the upgrade | The upgrade fails with an HTTP status and plain-text body. No WebSocket is established. |
| WebSocket `/ws3`, `/ws2` | After the socket is open | Close code `1011`, with the message in the close reason. Where an HTTP equivalent applies the reason usually begins with it, for example `400: text is too long` |
| WebSocket `/ws` (raw audio) | Any | No structured error events. Use `/ws3` or `/ws2` if you need to distinguish failures. |

Log the complete close reason string, because it's the only place the message appears. The leading status is a diagnostic aid, not a stable format, so read it but don't branch on it.

Handle both failure paths: the same bad request can be rejected on the upgrade with an HTTP status, or accepted and then closed with `1011` once the socket is open.

## 400, the request was rejected

| Message | Cause | Fix |
| :- | :- | :- |
| `request body is required` | No body sent | Send a JSON body |
| `payload must be an object` | Body parsed but is not a JSON object | Send an object, not an array or scalar |
| `text is required` | `text` absent | Include `text` |
| `text must be a string` | `text` is a number, object, or null | Send a string |
| `text must not be empty` | `text` is `""` | Send at least one character |
| `text is too long` | `text` exceeded 1,000 characters | Split into multiple requests at sentence boundaries |
| `speaker is required` | `speaker` absent | Include `speaker`. There is no default voice |
| `lang must be a string` | `lang` is not a string | Send a string such as `eng` or `en` |
| `audioFormat must be a string` | `audioFormat` is not a string | Send a string. See [Streaming formats](/docs/streaming) |
| `Language <lang> is not supported for model <model>` | The language is not in the model's supported set | Use a supported language for that model. See the [language matrix](/docs/voices#languages) |

<Warning>**Do not rely on this error to catch a bad pairing.** It is not returned for every model or transport, so an unsupported combination of `speaker`, `modelId`, and `lang` can be accepted and synthesized rather than rejected. Verify the combination against the [Coda](/docs/voices-coda) or [Mist v3](/docs/voices-mist-v3) catalog before you ship it, and treat a successful response as no evidence that the pairing was valid.</Warning>

## 401, authentication failed

| Message | Cause |
| :- | :- |
| `Missing Authorization header` | No `Authorization` header sent |
| `missing headers` | Required headers absent on this endpoint |
| `empty apikey` | The header is present but the key is empty |
| `invalid api key` | The key is not recognized |
| `invalid subscription` | The key resolves to an account with neither a valid subscription nor a positive balance |

`invalid subscription` arrives as a 401 rather than a 402 or 403, so a billing problem can look like an authentication problem. If your key is correct and unchanged, check the account's subscription and balance before regenerating credentials. Create and manage keys on the [API Tokens page](https://app.rime.ai/tokens); see [Authentication](/docs/api-authentication).

## 403, authenticated but not allowed

`access forbidden` means the credential is valid but the account may not use this endpoint or resource. Retrying won't help. Contact [support@rime.ai](mailto:support@rime.ai) if you expect access.

## 406, the requested media type cannot be produced

`modelId "<model>" can only be returned as streamed audio; set Accept to one of: ...` means `Accept` named a concrete type the API cannot produce for that model. Only Mist v1 and Mist v2 have a JSON representation. Every other model returns audio only. Set `Accept` to one of the listed types. Retrying won't help.

## 429, too many requests

`Currently at websocket limit` is returned at the WebSocket upgrade when an account opens WebSocket connections faster than Rime allows. Rime doesn't publish a connection limit, so don't design to a specific number.

Treat a 429 as a signal to back off: stop opening new connections, retry the upgrade after a delay, and reuse existing connections rather than opening one per utterance. Limits apply to the account as a whole, so on a team account, connections opened by one member count against the others.

<Note>Synthesis concurrency is separate from this connection limit, and Rime does not publish a figure for it. If you need a concurrency commitment for capacity planning, contact [support@rime.ai](mailto:support@rime.ai) rather than inferring one from what you observe.</Note>

## 500 and 502, the request failed on Rime's side

| Status | Message | Meaning |
| :- | :- | :- |
| 500 | `internal error`, `Internal error`, `Database error` | An unhandled server-side failure |
| 502 | `text normalization engine error` | The [text normalization](/docs/text-normalization) endpoint could not reach its engine |

These are the only failures where a retry is reasonable on its own. Retry with backoff, and see [the retry guidance](#retrying-safely) below before retrying anything that may already have produced audio.

## Retrying safely

Retry a 500 or 502. Do not retry a 400, 401, or 403: the request will fail identically and, for 401, repeated attempts with a bad credential are indistinguishable from an attack.

For a 429, back off and retry the connection rather than the synthesis.

<Warning>**Retries are billed as new synthesis.** Rime bills by characters synthesized, and each request is billed independently. If a connection drops partway through a long utterance, resynthesizing the full text incurs its full character count again. For long utterances, synthesize in sentence-aligned chunks and resume from the last chunk you received, so a retry only re-sends what was lost.</Warning>

## What to send to support

Support has no request ID to look up, so include all of the following when you report a failure. Redact your API key.

* The UTC timestamp of the failure, to the second. This matters most, because it is how support locates the request
* The endpoint and [regional endpoint](/docs/regional-endpoints) you called
* `modelId`, `speaker`, and `lang` exactly as sent
* The HTTP status and the full plain-text body, or the WebSocket close code and its complete reason string
* A minimal request that reproduces it, with the key removed
* Whether any audio had already arrived when the failure occurred

## Related

* [API authentication](/docs/api-authentication): creating keys and the header format, for diagnosing 401s.
* [Voices](/docs/voices): the catalog to verify a `speaker`, `modelId`, and `lang` combination against.
* [Streaming formats](/docs/streaming): valid `audioFormat` values and their tradeoffs.
* [WebSockets](/docs/websockets): which endpoint reports structured errors and which does not.


# Homographs (Mist v2 and Mist v3)
Source: https://docs.rime.ai/docs/homographs

Disambiguate same-spelling-different-pronunciation words on Mist v2 and Mist v3.

<Note>Homograph disambiguation is supported on **Mist v2 and Mist v3**.</Note>

A homograph is a word that shares its spelling with another word but differs in meaning, in pronunciation, or in both. For Rime's TTS API, only the pronunciation difference matters. For example, the words *sow* (verb, to plant seed) and *sow* (noun, a female pig) are spelled identically but pronounced differently, so the spelling alone can't tell a speech synthesizer which one you mean. Rime uses both contextual syntactic analysis and frequency information to predict which pronunciation is intended.

If Rime's predicted pronunciation is wrong, replace the word with its `wordid` from the table below. In this example, `produce_nou` selects the noun (fruits and vegetables) and `produce_vrb` selects the verb (to make):

```python Homograph specification example theme={null}
# Fruits and vegetables?
text = "I like fresh produce_nou."
# Making things?
text = "They produce_vrb a wide array of home goods for decorations."
```

The table below lists every homograph for which you can specify a disambiguated variant.

## List of homographs

| Homograph | wordid | Example sentence |
| - | - | - |
| abstract | abstract\_adj-nou | I like abstract art. |
| abstract | abstract\_vrb | I want to abstract away from the detail. |
| abuse | abuse\_nou | I won't put up with this abuse. |
| abuse | abuse\_vrb | Don't abuse animals. |
| abuses | abuses\_nou | These abuses are appalling. |
| abuses | abuses\_vrb | She abuses alcohol. |
| addict | addict\_nou | He became an addict. |
| addict | addict\_vrb | Those drugs can addict you. |
| advocate | advocate\_nou | I am an advocate for mental health. |
| advocate | advocate\_vrb | I advocate for free speech. |
| affect | affect\_nou-psy | He had a strange affect. |
| affect | affect | That doesn't affect our plans. |
| affiliate | affiliate\_nou | They're a branch affiliate. |
| affiliate | affiliate\_vrb | I don't generally affiliate with them. |
| aged | aged\_adj | He was quite aged. |
| aged | aged | He had aged slowly over the years. |
| aggregate | aggregate\_adj-nou | I like his work in the aggregate. |
| aggregate | aggregate\_vrb | I want to aggregate all the files together. |
| alternate | alternate\_adj-nou | I was on the team as an alternate. |
| alternate | alternate\_vrb | We should alternate between me and you. |
| analyses | analyses\_nou | I read his analyses closely. |
| analyses | analyses\_vrb | She analyses things carefully. |
| animate | animate\_adj-nou | There wasn't a single animate creature in the area. |
| animate | animate\_vrb | I tried to animate the scene. |
| appropriate | appropriate\_adj | That behavior is not appropriate. |
| appropriate | appropriate\_vrb | We decided to appropriate the funds for our own purposes. |
| approximate | approximate\_adj-nou | The approximate distance to the nearest city is 50 miles. |
| approximate | approximate\_vrb | I want you to approximate the answer. |
| articulate | articulate\_adj | He was quite articulate. |
| articulate | articulate\_vrb | She could articulate her thoughts clearly during the presentation. |
| associate | associate\_adj-nou | He was an associate professor. |
| associate | associate\_vrb | I associate summer with vacations and relaxation. |
| attribute | attribute\_nou | That is my favorite attribute of his. |
| attribute | attribute\_vrb | They attribute their success to hard work and perseverance. |
| axes | axes\_nou | The graph has axes for both the x and y variables. |
| axes | axes\_nou-vrb | He bought some axes for the forrestry service. |
| bass | bass | He plays the bass guitar in the band. |
| bass | bass\_corp | I cought a bass in the lake. |
| blessed | blessed\_adj | The blessed reverand led the service. |
| blessed | blessed\_vrb | We feel blessed to have such supportive friends. |
| bologna | bologna\_geo | I would love to visit bologna italy. |
| bologna | bologna | Do you want mustard or mayo on your bologna sandwich? |
| bow | bow\_nou-knot | He made a bow with a ribbon for the gift. |
| bow | bow\_nou-ship | I walked to the bow if the ship. |
| buffet | buffet\_nou | We enjoyed a delicious buffet at the party. |
| buffet | buffet\_vrb | They tried to buffet us with questions. |
| celtic | celtic\_adj-nou-sports | The Celtic culture has a rich history of myths and legends. |
| celtic | celtic | The Celtic guards are the best in the nba. |
| close | close\_adj-nou | We were very close to winning. |
| close | close\_vrb | Please close the door. |
| combine | combine\_nou | I drove a combine on the farm. |
| combine | combine\_vrb | Let's combine our efforts to finish the project faster. |
| compact | compact\_adj-nou | The apartment is compact but cozy. |
| compact | compact\_vrb | We tried to compact the trash into a manageable size. |
| compound | compound\_nou | The compound is made up of several buildings. |
| compound | compound\_vrb | Our problems started to compound. |
| compress | compress\_nou | I put a cold compress on his arm. |
| compress | compress\_vrb | You can compress the file to save space. |
| conduct | conduct\_nou | I approve of their conduct. |
| conduct | conduct\_vrb | The manager will conduct interviews for the new position. |
| confines | confines\_nou | The garden is within the confines of the castle walls. |
| confines | confines\_vrb | She confines her birds in a small cage. |
| conflict | conflict\_nou | They were in conflict over how to proceed with the project. |
| conflict | conflict\_vrb | Sometimes priorities conflict with each other. |
| conglomerate | conglomerate\_adj-nou | The company is a conglomerate of various smaller businesses. |
| conglomerate | conglomerate\_vrb | The telephone companies started to conglomerate. |
| conjugate | conjugate\_adj-nou | We learned which word was a conjugate of the other. |
| conjugate | conjugate\_vrb | These two verbs conjugate similarly in Spanish. |
| conscript | conscript\_nou | I started out as a simple conscript. |
| conscript | conscript\_vrb | The attemped to conscript reluctant citizens. |
| console | console\_nou | The gaming console offers a wide range of entertainment options. |
| console | console\_vrb | I want to console the people who are worried. |
| consort | consort\_nou | She is the consort of the king. |
| consort | consort\_vrb | I don't usually consort with that sort of person. |
| construct | construct\_nou | Money is a social construct. |
| construct | construct\_vrb | They plan to construct a new building downtown. |
| consummate | consummate\_adj | She is a consummate professional in her field. |
| consummate | consummate\_vrb | They planned to consummate the marriage. |
| content | content\_adj-nou-vrb | I felt content with the result. |
| content | content\_nou | She tried to create more content for her channel. |
| contest | contest\_nou | I won the contest. |
| contest | contest\_vrb | The decided to contest the decision. |
| contract | contract\_nou | They signed a contract to seal the deal. |
| contract | contract\_vrb | I don't want to contract any diseases. |
| contrast | contrast\_nou | The contrast between the two paintings is striking. |
| contrast | contrast\_vrb | We're going to compare and contrast the two films. |
| converse | converse\_adj-nou | Let's consider the converse proposition. |
| converse | converse\_vrb | Let's converse about something more uplifting. |
| convert | convert\_nou | I was a new convert to the religion. |
| convert | convert\_vrb | We need to convert the measurements into metric units. |
| convict | convict\_nou | The convict swore he was innocent. |
| convict | convict\_vrb | The jury voied to convict the man. |
| cordon | cordon | The police set up a cordon around the block. |
| cordon | cordon\_fr | The sommelier praised the Cordon Bleu. |
| coordinate | coordinate\_adj-nou | He charted the numbers on a coordinate plane. |
| coordinate | coordinate\_vrb | The teams need to coordinate their efforts for success. |
| correlate | correlate\_nou | The money was just a correlate of our success. |
| correlate | correlate\_vrb | These two variables correlate positively. |
| decrease | decrease\_nou | The decrease in temperature was noticeable overnight. |
| decrease | decrease\_vrb | I tried to decrease the number of problems. |
| defect | defect\_nou | There's a defect in this product, and we need to fix it. |
| defect | defect\_vrb | She wanted to defect from the military. |
| degenerate | degenerate\_nou | He worried he would become a degenerate. |
| degenerate | degenerate\_vrb | The situation might degenerate into chaos. |
| delegate | delegate\_nou | I was voted to become a delegate to the assembly. |
| delegate | delegate\_vrb | He will delegate the task to someone else. |
| deliberate | deliberate\_adj | It was a deliberate act of sabotage. |
| deliberate | deliberate\_vrb | They will deliberate on the matter before making a decision. |
| desert | desert\_nou | I visited the sahara desert. |
| desert | desert\_vrb | Don't desert your teammates! |
| deviate | deviate\_nou | He was considered a deviate in the conservative society. |
| deviate | deviate\_vrb | She tends to deviate from the main topic in conversations. |
| diagnoses | diagnoses\_nou | The diagnoses were inconclusive, so more tests are needed. |
| diagnoses | diagnoses\_vrb | The doctor diagnoses people as part of the job. |
| diffuse | diffuse\_adj | There was a diffuse sense of mistrust. |
| diffuse | diffuse\_vrb | The essential oils diffuse slowly throughout the room. |
| discard | discard\_nou | Put it in the discard pile. |
| discard | discard\_vrb | Please discard any expired items from the pantry. |
| discharge | discharge\_nou | There was a fluid discharge valve in the machine. |
| discharge | discharge\_vrb | The factory is required to discharge its waste responsibly. |
| discount | discount\_nou | There's a discount on all items in the store today. |
| discount | discount\_vrb | I dont discount the possibility that we're wrong. |
| document | document\_nou | I misplaced the document. |
| document | document\_vrb | Make sure to document all your expenses for reimbursement. |
| dove | dove\_nou | A dove landed gracefully on the windowsill. |
| dove | dove\_vrb | He dove from the side of the building. |
| duplicate | duplicate\_adj-nou | The duplicate was not as good as the original. |
| duplicate | duplicate\_vrb | Be careful not to duplicate your efforts unnecessarily. |
| elaborate | elaborate\_adj | It was an elaborate ruse. |
| elaborate | elaborate\_vrb | Please elaborate on your plans for the project. |
| entrance | entrance\_nou | The grand entrance to the palace was breathtaking. |
| entrance | entrance\_vrb | They entrance the audience with their performance. |
| escort | escort\_nou | He were serving as my escort. |
| escort | escort\_vrb | Please escort yourself from the room. |
| estimate | estimate\_nou | Can you give me an estimate of how long it will take? |
| estimate | estimate\_vrb | I was trying to estimate the damage. |
| excuse | excuse\_nou | He had to come up with a believable excuse for his absence. |
| excuse | excuse\_vrb | You history doesn't excuse your behavior. |
| expatriate | expatriate\_nou | An expatriate may find it challenging to adjust to a new culture. |
| expatriate | expatriate\_vrb | He chose to expatriate to pursue better job opportunities. |
| exploit | exploit\_nou | We found an exploit in the system. |
| favor | favor | Could you do me a small favor? |
| favor | favor\_sp | They served horchata at the Favor taqueria. |
| exploit | exploit\_vrb | They tried to exploit the natural resources of the region. |
| export | export\_nou | Iron ore is their main export. |
| export | export\_vrb | The country decided to export more goods to boost its economy. |
| expose | expose\_nou | The journalist published the expose. |
| expose | expose\_vrb | The journalist decided to expose the corruption in government. |
| extract | extract\_nou | The vanilla extract made the cookies delicious. |
| extract | extract\_vrb | They use a special technique to extract oil from the ground. |
| fragment | fragment\_nou | The museum displayed a fragment of the ancient artifact. |
| fragment | fragment\_vrb | The cohesion of the group started to fragment. |
| frequent | frequent\_adj | He was a frequent visitor to the local library. |
| frequent | frequent\_vrb | They frequent this pub increasing regularity. |
| graduate | graduate\_adj-nou | The graduate student gave a presentation. |
| graduate | graduate\_vrb | He was proud to finally graduate from university. |
| house | house\_nou | They built a new house on the hilltop. |
| house | house\_vrb | We try to house the poor. |
| impact | impact\_nou | The impact of the crash was felt throughout the neighborhood. |
| impact | impact\_vrb | The meteors impact the moon with some frequency. |
| implant | implant\_nou | her body rejected the implant. |
| implant | implant\_vrb | The dentist will implant a new tooth next week. |
| implement | implement\_nou | He brandished a sharp implement. |
| implement | implement\_vrb | They needed to implement new safety measures in the factory. |
| import | import\_nou | Textiles are their major import. |
| import | import\_vrb | The country needs to import more food to meet demand. |
| incense | incense\_nou | The aroma of incense filled the room during the meditation session. |
| incense | incense\_vrb | He didn't mean to incense her with his comments. |
| incline | incline\_nou | He started up the steep incline. |
| incline | incline\_vrb | The road began to incline steeply as they approached the mountain. |
| increase | increase\_nou | The fast increase in inflation was surprising. |
| increase | increase\_vrb | They decided to increase the budget for the project. |
| increment | increment\_nou | The increment in salary was a welcome surprise. |
| increment | increment\_vrb | The tally of the participants began to increment upward. |
| initiate | initiate\_nou | The initiate was still trying to learn the rules. |
| initiate | initiate\_vrb | They wanted to initiate a new policy to improve workplace safety. |
| insert | insert\_nou | There was a cardboard insert in the book. |
| insert | insert\_vrb | Please insert your card into the ATM machine. |
| instrument | instrument\_nou | The violin is a beautiful instrument. |
| instrument | instrument\_vrb | He tried to instrument the coup. |
| insult | insult\_nou | His words were an unintentional insult to her intelligence. |
| insult | insult\_vrb | Please don't insult my intelligence. |
| interchange | interchange\_nou | The interchange between cultures enriched their understanding. |
| interchange | interchange\_vrb | They decided to interchange their roles for the day. |
| intimate | intimate\_adj | They shared an intimate moment by the fireplace. |
| intimate | intimate\_vrb | I didn't mean to intimate that you were incompetent. |
| intrigue | intrigue\_nou | She couldn't resist the intrigue of the mysterious package. |
| intrigue | intrigue\_vrb | The accumulation of evidence started to intrigue me. |
| invalid | invalid\_adj | The password you entered is invalid. |
| invalid | invalid\_nou | That's the ward for invalids. |
| invite | invite\_nou | I already sent him an invite. |
| invite | invite\_vrb | They decided to invite her to the party. |
| isolate | isolate\_nou | Basque is a language isolate. |
| isolate | isolate | They needed to isolate the problem before it spread. |
| jesus | jesus | Many people believe in the teachings of Jesus. |
| jesus | jesus\_es | Jesus Romero is my friend. |
| job | job\_bible | He was afflicted like Job in the bible. |
| job | job | Finding a job in this economy is challenging. |
| laminate | laminate\_nou | I laid down some new laminate flooring. |
| laminate | laminate\_vrb | They chose to laminate the important documents for protection. |
| lead | lead\_nou | The cast the statue in lead. |
| lead | lead\_nou-vrb | He was chosen to lead the team to victory. |
| learned | learned\_adj | I studied the learned tomes. |
| learned | learned\_vrb | She learned to swim at the age of five. |
| live | live\_adj | We are broadcasting live. |
| live | live\_vrb | They decided to live in the countryside for a quieter life. |
| lives | lives\_nou | My cat has more than nine lives. |
| mate | mate\_nou | The penguin searched for its mate. |
| mate | mate | He sipped mate from a gourd every morning. |
| lives | lives\_vrb | He lives in the city while his brother lives in the suburbs. |
| minute | minute\_adj | The minute details of the plan were crucial to its success. |
| minute | minute | Could you spare a minute? |
| misuse | misuse\_nou | She felt hurt by the misuse of her trust. |
| misuse | misuse\_vrb | He didn't mean to misuse the company's resources. |
| mobile | mobile | The mobile phone revolutionized communication. |
| mobile | mobile\_geo | I live in Mobile, Alabama. |
| mobile | mobile\_nou-art | The mobile dangled from the ceiling. |
| moderate | moderate\_adj-nou | The forum serves as a moderate space for discussion. |
| moderate | moderate\_vrb | They decided to moderate their spending habits. |
| moped | moped\_nou | She rode her moped to work every day. |
| moped | moped\_vrb | He moped around the house after his breakup. |
| mouth | mouth\_nou | Please close your mouth while chewing. |
| mouth | mouth\_vrb | She tried to mouth the answer to him from the audience. |
| nestle | nestle\_nam | I like to eat Nestle Crunch bars. |
| nestle | nestle\_vrb | The mother bird will nestle her chicks under her wing. |
| object | object\_nou | The main object of the game is to collect all the gems. |
| object | object\_vrb | Do you object to my presence here? |
| ornament | ornament\_nou | She carefully hung each ornament on the tree. |
| ornament | ornament\_vrb | I want to ornament the room festively. |
| overthrow | overthrow\_nou | The overthrow of the government was peaceful. |
| overthrow | overthrow\_vrb | The citizens staged a protest to overthrow the dictator. |
| pasty | pasty\_adj | His pasty skin indicated that he was sick. |
| pasty | pasty\_nou | She ate a pasty for lunch. |
| pastor | pastor | The pastor greeted the congregation after the service. |
| pastor | pastor\_sp | They ordered tacos al pastor. |
| perfect | perfect\_adj | The painting was a perfect likeness of the landscape. |
| perfect | perfect\_vrb | I want to perfect my sales pitch. |
| perfume | perfume\_nou | She wore her favorite perfume for the special occasion. |
| perfume | perfume\_vrb | They often perfume the showroom to entice people to buy. |
| permit | permit\_nou | You need a permit to park in this area. |
| permit | permit\_vrb | We don't permit smoking here. |
| pervert | pervert\_nou | He was a known pervert who harassed women on the street. |
| pervert | pervert\_vrb | The teacher caught the student trying to pervert the truth. |
| pigment | pigment\_nou | The pigment in the paint faded over time. |
| pigment | pigment\_vrb | She will pigment the canvas. |
| polish | polish\_geo | I like Polish food. |
| polish | polish | He used a cloth to polish his shoes. |
| postulate | postulate\_nou | The postulate was in dispute. |
| postulate | postulate\_vrb | He couldn't help but postulate about the future. |
| precipitate | precipitate\_adj-nou | The chemist collected the precipitate from the beaker. |
| precipitate | precipitate\_vrb | The dark clouds precipitate rain. |
| predicate | predicate\_nou | The premise of the argument is the predicate of the conclusion. |
| predicate | predicate\_vrb | We predicate our success on our hard work. |
| present | present\_adj-nou | I gave my brother a present. |
| present | present\_vrb | She wrapped the gift and prepared to present it. |
| produce | produce\_nou | The produce section of the store was flooded. |
| produce | produce\_vrb | Farmers work hard to produce crops every year. |
| progress | progress\_nou | She made significant progress in her recovery. |
| progress | progress\_vrb | I want to progress to a later stage in the game. |
| project | project\_nou | The project was put on hold. |
| project | project\_vrb | I project that we will turn a profit in two months. |
| protest | protest\_nou | The workers staged a protest outside the factory gates. |
| protest | protest\_vrb | The lady doth protest too much. |
| ravel | ravel\_nou | The knitting began to ravel at the edge. |
| ravel | ravel\_nam | The orchestra performed a piece by Ravel. |
| read | read\_past | He read the letter with a furrowed brow. |
| reading | reading\_en | She enjoys reading before bed. |
| reading | reading\_geo | The train stops at Reading station. |
| read | read\_present | She likes to read mystery novels in her free time. |
| rebel | rebel\_nou | He was known as a rebel in his youth. |
| rebel | rebel\_vrb | They will likely rebel against the ruling order. |
| record | record\_nou | I showed him my record collection. |
| record | record\_vrb | She made sure to record all her expenses in her budget. |
| recount | recount\_nou | The decided to carry out a recount of the votes. |
| recount | recount\_vrb | She decided to recount the events of the day to her friend. |
| refund | refund\_nou | The store offered a refund for the defective product. |
| refund | refund\_vrb | Please refund me my money. |
| refuse | refuse\_nou | The refuse trailed behind them. |
| refuse | refuse\_vrb | He would refuse to eat his vegetables as a child. |
| reject | reject\_nou | I consider him a political reject. |
| reject | reject\_vrb | The committee will reject any proposals that don't meet the criteria. |
| rerelease | rerelease | The album is actually a rerelease. |
| rerelease | rerelease\_vrb | The company plans to rerelease the classic film in theaters. |
| resume | resume\_nou | I updated my resume. |
| resume | resume\_vrb | After the break, he will resume his studies. |
| retard | retard\_nou | The bully called me a retard. |
| retard | retard\_vrb | The teacher didn't want to retard the progress of her students. |
| rodeo | rodeo\_geo | I went shopping on Rodeo Drive. |
| rodeo | rodeo | They attended the annual rodeo in their town. |
| row | row\_1 | I'm putting my ducks in a row. |
| row | row\_2 | The argument led to a full-on row. |
| sake | sake\_jp | She drank sake for the first time at the Japanese restaurant. |
| sake | sake | He brought up the idea for the sake of argument. |
| separate | separate\_adj | I have to separate sinks in my bathroom. |
| separate | separate\_vrb | They decided to separate after years of marriage. |
| sow | sow\_nou | The sow produced a large litter or pigs. |
| sow | sow | please don't sow discord in this chatroom. |
| subject | subject\_adj-nou | The professor taught a course on the subject of psychology. |
| subject | subject\_vrb | I was subject to numerous experiments. |
| subordinate | subordinate\_adj-nou | He was demoted to a subordinate position within the company. |
| subordinate | subordinate\_vrb | I subordinate my desires in order to get work done. |
| supplement | supplement\_nou | The doctor recommended taking a calcium supplement. |
| supplement | supplement\_vrb | We should supplement our diet with more iron. |
| suspect | suspect\_adj-nou | The suspect was interrogated. |
| suspect | suspect\_vrb | They suspect foul play in the disappearance of the painting. |
| syndicate | syndicate\_nou | The syndicate controlled most of the city's underground activities. |
| syndicate | syndicate\_vrb | If they syndicate our tv show, we'll make millions. |
| tear | tear\_nou | A tear rolled down the child's cheek. |
| tear | tear\_vrb | Tear down the wall. |
| transform | transform\_nou | He used some sort of mathematical transform. |
| transform | transform | They hoped the therapy would transform his behavior. |
| transplant | transplant\_nou | He received a kidney transplant from his sister. |
| transplant | transplant\_vrb | They decided to transplant the flowers into larger pots. |
| transport | transport\_nou | Public transport is pretty important. |
| transport | transport\_vrb | They hired a company to transport their belongings to the new house. |
| upset | upset\_nou | The team pulled off the upset. |
| upset | upset\_vrb | She was upset by the news of her friend's illness. |
| uses | uses\_nou | The uses of this tool are varied and diverse. |
| uses | uses\_vrb | She uses a lot of spices in her cooking. |
| use | use\_nou | She couldn't find a use for the old vase. |
| use | use\_vrb | I use a computer for my job. |
| wind | wind\_nou | The wind rustled through the trees on a breezy day. |
| wind | wind\_vrb | Let me wind up this clock real quick. |
| winds | winds\_nou | The winds of change blew through the community. |
| winds | winds\_vrb | If she winds up the winner, i'll be surprised. |
| wound | wound\_nou-vrb | He received a wound to his arm during the accident. |
| wound | wound\_vrb | They wound their way through the narrow streets of the old city. |


# Introduction
Source: https://docs.rime.ai/docs/introduction

A quick overview of Rime's speech platform: the default model, deployment options, enterprise features, pricing, and the developer surfaces you build on.

Rime is voice AI **made for human conversation**: natural, low-latency speech for production voice agents, IVR, and telephony.

Its flagship model, Coda, is trained on full-duplex conversations between real people, not voice actors or audiobook narrators. Coda has top-rated voice quality in human evaluations and runs at sub-100ms model latency. The cloud API offers 287 Coda voices across 9 languages. Coda can also run in your VPC or fully on-premises, where the packaged language set may differ.

## Start here

Pick the one that matches what you're doing. Each is a complete path, not an overview.

<Columns>
  <Card title="Generate your first audio" icon="rocket" href="/docs/quickstart-five-minute">
    One HTTP request, a playable file back, in about five minutes. Start here if you are evaluating Rime or adding speech to an existing backend.
  </Card>

  <Card title="Build a real-time voice agent" icon="messages" href="/docs/voice-agents">
    A conversational agent that listens and speaks. Complete LiveKit tutorial, or direct WebSocket starters for Next.js, Vite, Express, Node, and FastAPI.
  </Card>

  <Card title="Try Rime from the terminal" icon="terminal" href="/docs/quickstart-cli">
    Generate and play speech without writing any code. The fastest way to hear a voice and check response speed.
  </Card>

  <Card title="Run Rime on your own infrastructure" icon="server" href="/docs/on-prem/quickstart">
    Deploy supported models in your VPC or fully on-premises, so audio and text stay inside your network.
  </Card>

  <Card title="Diagnose a failing request" icon="triangle-exclamation" href="/docs/errors">
    What each status code and WebSocket close code means, what the client observes per transport, and what to capture for support.
  </Card>
</Columns>

## Rime at a glance

| Area | Summary |
| - | - |
| **Product** | Low-latency neural text-to-speech. The flagship model, Coda, reaches sub-100ms model latency (sub-200ms end to end over the cloud API). |
| **Reach** | 500+ voices across the model lineup, including 287 Coda voices across 9 languages, plus instant custom voice cloning. |
| **Deployment** | Regional cloud API, virtual private cloud (VPC), or on-premises with Docker Compose or Kubernetes. |
| **Enterprise** | Unlimited concurrency, unlimited custom voice clones, SLAs, and dedicated support. |
| **Security and compliance** | SOC 2 reports and a HIPAA Business Associate Agreement (BAA). VPC and on-prem keep audio and text inside your own network. |
| **Pricing** | Usage-based. Starter is \$0.05 per 1,000 characters with 3,000 free minutes and 20 concurrent streams. Enterprise uses custom volume pricing. See [rime.ai/pricing](https://www.rime.ai/pricing). |

<Card title="Talk to the team about enterprise, on-prem, or volume pricing" icon="building" href="https://www.rime.ai/pricing">
  Custom deployments, compliance (SOC 2, HIPAA), SLAs, and dedicated support for production scale.
</Card>

## Start with Coda

Coda is the recommended model for new projects, but it isn't the API's default. A request without `modelId` is served by Mist v3, so set `modelId: coda` on every request that should use Coda.

Coda pairs an LLM backbone with a dedicated speech inference engine trained on full-duplex conversations between real people. Through the cloud API, it serves nine languages: English, Arabic, French, German, Hindi, Italian, Japanese, Portuguese, and Spanish. Each voice speaks one of them, so start from the language your application needs and choose among that language's voices.

## Speech capabilities

<Columns>
  <Card title="Generate speech" icon="waveform" href="/docs/quickstart-five-minute">
    Turn text into playable or downloadable audio in formats suited to web, mobile, telephony, and media workflows.
  </Card>

  <Card title="Stream speech in real time" icon="signal-stream" href="/docs/streaming">
    Use HTTP for simple streaming responses or persistent WebSockets for the tightest conversational loop, with timestamps and interruption handling.
  </Card>

  <Card title="Choose voices, models, and languages" icon="microphone-lines" href="/docs/voices">
    Browse every voice on [Coda](/docs/voices-coda) and [Mist v3](/docs/voices-mist-v3), grouped by language, with the gender, age, and country the catalog publishes for each.
  </Card>

  <Card title="Shape how speech sounds" icon="sliders" href="/docs/prompting">
    Guide delivery, pacing, spelling, pauses, pronunciation, and the way numbers, dates, and other text are spoken.
  </Card>

  <Card title="Build voice agents" icon="messages" href="/docs/voice-agents">
    Begin with a complete LiveKit tutorial or connect Rime directly from Next.js, Vite, Express, Node.js, or FastAPI.
  </Card>

  <Card title="Connect voice platforms" icon="puzzle-piece" href="/docs/livekit">
    Integrate with LiveKit, Pipecat, Vapi, Daily, SignalWire, VideoSDK, and other voice application frameworks.
  </Card>

  <Card title="Create a custom voice" icon="clone" href="/platform/voice-cloning">
    Create a branded enterprise voice and use it through the same speech API as Rime's catalog voices.
  </Card>

  <Card title="Run Rime in your environment" icon="server" href="/docs/on-prem/quickstart">
    Use Rime's regional cloud endpoints or deploy supported models on your own infrastructure.
  </Card>
</Columns>

## Developer surfaces

<Columns>
  <Card title="Dashboard" icon="browser" href="https://app.rime.ai/">
    Explore, preview, and save voices, generate speech, and inspect normalized text. Create API tokens, follow setup progress, manage teams, and review usage and billing.
  </Card>

  <Card title="HTTP and WebSocket APIs" icon="brackets-curly" href="/docs/api-reference">
    Generate complete audio responses, stream audio, receive word timestamps, list voices, and use Rime's language tools.
  </Card>

  <Card title="Application code" icon="code" href="/docs/api-cheat-sheet">
    Use standard HTTP and WebSocket clients from Python, JavaScript, Go, or any server-side language. You don't need a Rime-specific SDK. The cheat sheet is the compact parameter and endpoint reference.
  </Card>

  <Card title="CLI" icon="terminal" href="/docs/quickstart-cli">
    Generate, play, and save speech, inspect usage, and test response speed from the terminal.
  </Card>

  <Card title="MCP server" icon="robot" href="/docs/mcp">
    Let Claude, Codex, and compatible tools browse voices, generate samples, inspect pronunciation and text normalization, and scaffold integrations.
  </Card>

  <Card title="Application integrations" icon="plug" href="/docs/pipecat">
    Use Rime with supported voice-agent frameworks, telephony services, deployment platforms, and application builders.
  </Card>
</Columns>

One Rime API token authenticates the API, CLI, MCP tools, and supported integrations. Manage tokens, team access, and billing in the [Rime dashboard](https://app.rime.ai/).


# Low-latency TTS for real-time voice agents
Source: https://docs.rime.ai/docs/latency

Rime TTS latency benchmarks, the factors that affect response time, and practical ways to reduce it.

## Latency at a glance

Rime's cloud API delivers sub-200ms end-to-end latency under typical conditions. Coda reaches **sub-100ms model latency on the GPU engine** when self-hosted or on-prem, while Mist v3 has the lowest measured time to first audio.

In a voice agent, TTS is one part of each reply, along with speech recognition and the language model. People expect replies to come quickly. In a study of conversation in ten languages, the most common gap before someone answered a yes/no question was between 0 and 200 milliseconds ([Stivers et al., 2009](https://doi.org/10.1073/pnas.0903616106)). Time that TTS saves leaves more of that budget for the rest of the pipeline.

Via the cloud API, the total time you measure also includes network round-trip: typically 25 to 50ms from most of the continental US when you pick the closest [regional endpoint](/docs/regional-endpoints). Contact [Rime support](mailto:support@rime.ai) to optimize further.

## Real-time performance benchmarks

<Note>
  These numbers were measured on a single Lambda H100 SXM machine with an H100 SXM5 GPU, 26 vCPUs, 221 GiB RAM, Ubuntu 24.04, and NVIDIA driver `595.58.03`.
</Note>

| Metric | Coda | Mist v3 |
| :- | :- | :- |
| TTFA (P50) @ 1 Concurrency | 96 ms | 37 ms |
| TTFA (P90) @ 1 Concurrency | 98 ms | 56 ms |
| TTFA (P50) @ 12 Concurrency | 150 ms | 37 ms |
| TTFA (P90) @ 12 Concurrency | 181 ms | 56 ms |
| RTF (P99) | 0.33 | 0.004 |

**TTFA** = Time-to-First-Audio. **RTF** = Real-Time Factor (synthesis time ÷ audio duration, where values below 1.0 mean synthesis is faster than playback).

Read the concurrency rows together. From 1 to 12 concurrent requests, Coda's median TTFA rises from 96 ms to 150 ms, while Mist v3 stays at 37 ms. If one GPU serves many simultaneous streams, compare the 12-concurrency rows, not the single-request ones. Coda's P99 RTF of 0.33 means that 99% of requests generate one second of audio in a third of a second or less, so generation stays ahead of playback.

## Reduce latency

1. **Choose the model for the constraint.** Use `mistv3` for the lowest cloud time to first audio. Choose Coda when voice quality is the priority and sub-100ms engine latency meets the target.
2. **Consume the response as a stream.** Start playback from the first bytes instead of buffering the complete response.
3. **Use the nearest regional endpoint.** Route East Coast traffic to US East and West Coast traffic to US West.
4. **Request only the audio you need.** Smaller payloads cross the network faster. Telephony applications should request 8kHz audio directly.
5. **Skip normalization only for already normalized text.** [`noTextNormalization`](/docs/text-normalization) removes preprocessing, but it is safe only when the input has no digits, abbreviations, or ambiguous punctuation.

## What affects latency

### Factors that affect API response time

1. **Server processing:** Model inference, text preprocessing, and audio postprocessing all contribute to the first response byte.
2. **Payload size:** Larger audio responses take longer to transmit.
3. **Network distance:** A longer route between the application and Rime increases round-trip time.

### Stream the response

Streaming reduces time to first playback because the client can consume the first chunk before Rime finishes generating the complete response. Buffering the whole body delays playback until synthesis and transfer are complete.

<Frame>
  <img alt="Chart comparing total response time with time to first byte for a streaming PCM request" />
</Frame>

The chart uses this request body:

```bash theme={null}
curl -X POST https://users.rime.ai/v1/rime-tts \
  -H 'Accept: audio/L16' \
  -H "Authorization: Bearer $RIME_API_KEY" \
  -H 'Content-Type: application/json' \
  --fail \
  --show-error \
  -d '{"text": "I love the book that she gave me. And I was so happy that she gave it to me.", "speaker": "cove",  "modelId": "mistv3"}'
```

To consume a streaming response in Python, iterate over the response body as it arrives instead of buffering the whole thing:

```python Python theme={null}
import os

import requests

with requests.post(
    "https://users.rime.ai/v1/rime-tts",
    headers={
        "Authorization": f"Bearer {os.environ['RIME_API_KEY']}",
        "Content-Type": "application/json",
        "Accept": "audio/mpeg",
    },
    json={
        "speaker": "astra",
        "text": "Hello from Coda.",
        "modelId": "coda",
        "lang": "en",
    },
    stream=True,
) as response:
    response.raise_for_status()
    with open("hello.mp3", "wb") as f:
        for chunk in response.iter_content(chunk_size=4096):
            f.write(chunk)
```

<Info>Rime's models produce PCM audio by default, and conversion and resampling must take place for sampling rates other than the model's native rate (24kHz for Coda, 22.05kHz for Mist). For low-bandwidth applications, the smaller payload usually outweighs the added server processing.</Info>

## Network latency by region

Rime serves the API from multiple regions so you can route requests to the data center closest to your application. Picking the closest endpoint typically shaves tens of milliseconds off round-trip time.

These are rough round-trip times (RTT), the back-and-forth network delay between your application and Rime, from major US metros to each region:

| From metro | To US East | To US West |
| :- | :- | :- |
| East Coast (NYC, DC, Boston, Atlanta) | 5–25 ms | 60–85 ms |
| Midwest / South (Chicago, Dallas, Denver) | 25–55 ms | 35–65 ms |
| West Coast (SF, LA, Seattle) | 60–85 ms | 5–25 ms |

Rules of thumb:

* **Same region** (your app and the Rime endpoint in the same AWS region): typically 1 to 10 ms.
* **Coast-to-coast**: \~60 ms is the physical floor, set by the speed of light in fiber across \~2,500 miles. 60 to 85 ms is normal.
* **Above 90 ms** between major US metros usually points to a suboptimal network route, not Rime.

**For voice AI:** if you serve users nationwide from a single region, far-coast users will see 60 to 85 ms of network round-trip on top of Rime's inference time. To stay comfortably under 200 ms end-to-end, route East Coast users to US East and West Coast users to US West.

For the full endpoint URLs and routing guidance, see [Regional endpoints](/docs/regional-endpoints). To measure TTFB against each endpoint from your own machine, run [`rime speedtest`](/cli-reference/rime-monitoring).


# Linguistics and TTS
Source: https://docs.rime.ai/docs/linguistics

Why TTS is hard: the one-to-many problem in linguistics and how Rime gives you customization controls.

Synthesizing realistic speech is difficult largely because of the **one-to-many problem** in linguistics: one text string corresponds to infinitely many possible acoustic realizations. The same words can differ in pronunciation, timing, and emphasis, and speakers sometimes change them on purpose for effect.

Rime's voices choose a default realization, so you don't have to specify one. When your use case needs a different reading, the Mist models let you adjust it at a low level:

* [Homographs](/docs/homographs): choose which pronunciation a word such as *produce* gets, on Mist v2 and Mist v3.
* [Custom pauses](/docs/custom-pauses): insert a pause of an exact length in milliseconds, on Mist, Mist v2, and Mist v3.
* [Custom pronunciation](/docs/custom-pronunciation): write a word's pronunciation as phonemes in Rime's phonetic alphabet, on Mist v1, Mist v2, and English Mist v3.


# LiveKit
Source: https://docs.rime.ai/docs/livekit

Use Rime TTS with LiveKit Agents for real-time voice agents: plugin setup and streaming configuration.

<IntegrationHeader />

Use Rime as the TTS provider in [LiveKit Agents](https://livekit.io/) through LiveKit's Rime plugin. LiveKit owns real-time transport and orchestration while Rime streams the agent's speech.

Build a complete agent with the [LiveKit quickstart](/docs/quickstart-livekit), or use [LiveKit's Rime integration reference](https://docs.livekit.io/agents/integrations/rime/) for plugin configuration.


# Lovable
Source: https://docs.rime.ai/docs/lovable

Build voice apps in Lovable using Rime's TTS.

<IntegrationHeader />

<video alt="Lovable voiceover application using Rime text to speech" />

Build a Lovable application that calls Rime TTS from an Edge Function. Store the Rime API key in Lovable Cloud so it never reaches browser code.

## Prerequisites

* A [Lovable](https://lovable.dev/) account
* A Rime [API key](https://app.rime.ai/tokens)

## Step 1: Prompt Lovable to use Rime

In your Lovable prompt, explicitly tell it to use Rime as the TTS provider. Include the endpoint, auth header, and request fields so Lovable doesn't have to guess them:

```
Use Rime TTS
**API:** POST https://users.rime.ai/v1/rime-tts
- Header: Authorization: Bearer {API_KEY}
- Request body: modelId "coda", lang "eng", and a Coda speaker
- Docs: https://docs.rime.ai/api-reference/coda/http
Store the API key in Lovable Cloud.
```

## Step 2: Add your Rime API key

Since the Rime API requires authentication, Lovable will prompt you to enable [Lovable Cloud](https://docs.lovable.dev/integrations/cloud) and add your Rime API key under **Cloud → Secrets**.

Lovable saves the key as a secret and accesses Rime through Edge Functions, keeping the credential out of frontend code.

For more on how Lovable handles authenticated APIs, see the [Integrations](https://docs.lovable.dev/integrations/introduction#authenticated-apis-requires-secrets) docs.

## Try it yourself

Paste this prompt into Lovable to build a voiceover studio app:

```
Build an Instant Voiceover Studio, a single-page app where users paste text, 
pick a voice, and generate professional audio using Rime TTS.

**For:** Content creators who need quick voiceovers for YouTube, podcasts, and apps.

**Design:** Rime design language with near-black background (#0D0D0D, #161616), 
orange-to-red gradient accents (#FF9300 to #B10000), grey surfaces (#333, #1A1A1A), 
Inter font. Clean and premium.

**Layout (two-column on desktop, stacked on mobile):**

**Left Panel:**
1. Text input area with character count (1000 max)
2. Voice picker with a grid of 16 Coda voice cards (luna, astra, sirius, estelle, lyra, vespera, orion, eliphas, arcade, atrium, eucalyptus, fern, stucco, transom, oculus, moss) with gradient avatars
3. "Generate Voiceover" button
4. Audio controls with play/pause, progress bar, download wav

**Right Panel:**
5. Three.js particle sphere with a small orb of 500+ particles, centered in the 
   right panel. Slowly rotates when idle with dim orange tint. When audio plays: 
   particles expand outward and glow bright orange (#FF9300) to red (#B10000), 
   pulsing with the voice.

Use Rime TTS
**API:** POST https://users.rime.ai/v1/rime-tts
- Header: Authorization: Bearer {API_KEY}
- Request body: modelId "coda", lang "eng", and the selected Coda speaker
- Docs: https://docs.rime.ai/api-reference/coda/http
Store the API key in Lovable Cloud.
```

The prompt can change the design or voice lineup, but it must retain the Rime endpoint and Lovable Cloud secret instructions.

**Test the app built by this prompt:** Visit [rime.lovable.app](https://rime.lovable.app).

## Tips for better results

* Be specific about what you want. Lovable works best with clear, detailed prompts.
* Always include the full API details (the endpoint, headers, and docs link) so Lovable can implement the integration correctly.
* Explicitly mention storing the API key in Lovable Cloud for security.
* See Lovable's [prompting best practices](https://docs.lovable.dev/prompting/prompting-one) for more prompt patterns.


# MCP Quickstart
Source: https://docs.rime.ai/docs/mcp

Connect Claude, Codex, or your IDE to Rime's hosted MCP server and hear your first voice.

Connect an AI assistant to Rime's hosted [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server and hear a Rime voice in 60 seconds. From the same conversation, your assistant can browse the voice catalog, check pronunciation, generate speech samples, and scaffold voice-agent code.

## Step 1: Connect

The connector URL is `https://mcp.rime.ai`.

**Claude Code:**

```bash theme={null}
claude mcp add --transport http rime https://mcp.rime.ai \
  --header "Authorization: Bearer $RIME_API_KEY"
```

**Claude.ai and Claude Desktop:** add `https://mcp.rime.ai` as a custom connector under **Settings → Connectors → Add custom connector**.

**OpenAI Codex:**

```bash theme={null}
codex mcp add rime --url https://mcp.rime.ai \
  --bearer-token-env-var RIME_API_KEY
```

For other clients, and connecting without an API key, see [Connecting](/mcp-reference/connect).

<Note>No key is needed to browse voices or generate integration code. Synthesis and the linguistics tools use your regular [Rime API key](https://app.rime.ai/tokens), sent per request and never stored. See [Authentication](/mcp-reference/authentication).</Note>

## Step 2: Hear your first voice

Ask your assistant:

```
Play me a sample of a Rime voice.
```

With no arguments, [`synthesize_speech`](/mcp-reference/synthesize-speech) plays a short demo in the `lyra` voice on Coda, Rime's flagship model. Claude.ai and Claude Desktop show an inline player, while terminal hosts such as Claude Code can play the short-lived link the tool returns. If you hear the sample, the connector works. [Playing audio](/mcp-reference/audio) covers each host.

## More prompts to try

```
Find me a warm, conversational voice for a customer support agent.
```

```
Which words in this script aren't in Rime's dictionary, and how will the numbers be read aloud?
```

```
Generate Pipecat starter code for a voice agent using the astra voice.
```

## Models and API references

<Columns>
  <Card title="MCP Reference" icon="plug-circle-bolt" href="/mcp-reference/overview">
    All six tools, connection setup, authentication, and audio playback
  </Card>

  <Card title="Voices" icon="microphone-lines" href="/docs/voices">
    Browse the full voice catalog across models and languages
  </Card>

  <Card title="Models" icon="microchip" href="/docs/models">
    Compare Coda, Mist v3, and Mist v2
  </Card>

  <Card title="Streaming TTS" icon="wave-sine" href="/docs/streaming">
    Production streaming over HTTP, WebSockets, or SSE
  </Card>
</Columns>


# Models
Source: https://docs.rime.ai/docs/models

Coda and Mist are Rime's models: what each one is for, which features they support, and how to choose between them.

Start with **Coda** for new applications. Choose **Mist v3** when the lowest time to first audio matters most, or when you need custom pauses. Inline pronunciation control is the one feature Mist v3 does not carry forward from Mist v2.

## Choose a model

| Pick this | When |
| :- | :- |
| `coda` | **Default for most new apps.** Rime's flagship model, with the highest voice-quality scores in Rime's human evaluations, sub-100ms model latency, and nine languages. |
| `mistv3` | You need the fastest time to first audio (approximately 37ms P50 in Rime's benchmark), or custom pauses. Does not support inline pronunciation control. |
| `mistv2` | You need inline pronunciation control, which is available on Mist v2 and Mist v1 only. |

For benchmark methodology, latency, and throughput numbers, see [Latency](/docs/latency#real-time-performance-benchmarks).

Rime supports Coda and Mist through the cloud API and on-premises, and both stream audio over [HTTP and WebSockets](/docs/streaming). On-prem image language coverage can differ from the cloud API; see the [on-prem quickstart](/docs/on-prem/quickstart#tts-service) before provisioning a deployment.

<Tip>Use the [regional endpoint](/docs/regional-endpoints) closest to your application to reduce network latency.</Tip>

## Feature matrix

| Attribute | Coda | Mist |
| :- | :-: | :-: |
| Number of voices | 287 | 78 (v3), 138 (v2) |
| Multilingual | ✅ | ✅ |
| [Text normalization](/docs/text-normalization) | ✅ | ✅ |
| [`spell()` function](/docs/spell) | ✅ | ✅ |
| [Speed adjustment](/docs/speed) | ✅ | ✅ |
| [Pronunciation control](/platform/pronunciation-control) | ❌ | Mist v2 only |
| [Custom pauses](/docs/custom-pauses) | ❌ | ✅ |

The Mist column reflects Mist v3 and Mist v2, which both serve English, French, German, and Spanish. See the [language matrix](/docs/voices#languages) for coverage per model.

The two Mist models differ on pronunciation control. Custom pauses work on both, but `phonemizeBetweenBrackets` works on Mist v2 and Mist v1 only, and is not supported on Mist v3 or Coda.

<Warning>**Inline pronunciation control is available on Mist v2 and Mist v1 only.** If your application depends on inline phoneme overrides, Mist v3 and Coda will not carry them. The alternatives are to submit the word to Rime for the pronunciation dictionary, or to respell it phonetically in plain English and accept that the result is approximate. See [Custom pronunciation](/docs/custom-pronunciation), and contact [support@rime.ai](mailto:support@rime.ai) if inline overrides are load-bearing for you.</Warning>

Multilingual describes the model, not the individual voice. Almost every voice serves a single language, so the number of voices you can choose from depends on the language you need. Through the cloud API, Coda serves 9 languages across 287 voices, but 176 of those voices are English and only 2 are Hindi. Browse the [Coda](/docs/voices-coda) and [Mist v3](/docs/voices-mist-v3) catalogs to see the voices available in a given language.

## Coda

**Coda**, released May 2026, is Rime's flagship TTS model. It pairs an LLM backbone with a dedicated speech inference engine trained on full-duplex conversational data.

* Received the highest voice-quality scores in Rime's human evaluations for naturalness, prosody, and artifact-free output
* **Sub-100ms model latency on the GPU engine** when self-hosted or on-prem
  * Cloud API users typically add 25 to 50ms of network round-trip time from most of the continental US when routed to the closest [regional endpoint](/docs/regional-endpoints)
* Nine cloud API languages: English, Arabic, French, German, Hindi, Italian, Japanese, Portuguese, and Spanish. Each voice serves one of them
* Word-level timestamps for text-audio alignment and interruption handling
* Supports [`spell()`](/docs/spell) for spelling sequences letter by letter or number by number
* Available with `modelId: coda`

## Mist v3

**Mist v3**, released March 2026, is the low-latency model in the Mist family.

* Typical time to first byte is well below 100ms
* Supports English, French, German, and Spanish
* Supports [custom pauses](/docs/custom-pauses). Does not support inline [pronunciation control](/platform/pronunciation-control), which is Mist v2 and Mist v1 only
* 78 voices; browse them in the [Mist v3 catalog](/docs/voices-mist-v3)
* [`speedAlpha`](/docs/speed) values above 1.0 produce faster speech, the modern direction
* Uses `modelId: mistv3`

## Mist v2

**Mist v2**, released February 2025, is the Mist model with inline pronunciation control.

* Supports English, French, German, and Spanish
* Inline [pronunciation control](/platform/pronunciation-control), which no other model supports, and [custom pauses](/docs/custom-pauses), which Mist v3 also supports
* On-prem latency depends on your GPU and text length. Rime measured a 175ms median on A10Gs and similar GPUs with 40 to 50 character sentences; see the [on-prem quickstart](/docs/on-prem/quickstart) for that figure in context and [Latency](/docs/latency) for the benchmark methodology
* 138 voices across accents, demographics, and speaking styles
* [`speedAlpha`](/docs/speed) values below 1.0 produce faster speech, the inverse of every other model
* Uses `modelId: mistv2`

## Mist legacy

**Mist**, released April 2023, is a legacy model in the Mist family. Use `modelId: mistv2` or `modelId: mist` to synthesize with these older deployments.

<Warning>Requests that omit `modelId`, or send a value the API does not recognize, are served by **Mist v3**. Set `modelId` explicitly on every request; Coda is never served by default.</Warning>

**Model v1 was released in April 2022 and has been deprecated.**


# Numbers, currency, and measurements
Source: https://docs.rime.ai/docs/numbers

How Rime automatically expands numbers, currency, ranges, measurements, phone numbers, and Roman numerals into spoken form.

Rime expands numbers, currency, ranges, and measurements into their spoken form automatically. Most formats work without any preprocessing. Just write naturally.

<Note>
  For a tour of text normalization across all categories, see [Text normalization](/docs/text-normalization). For specific patterns Rime doesn't expand cleanly, see [Pre-normalizing text](/docs/pre-normalization).
</Note>

## Numbers

| Format | Example | Reads as |
| :- | :- | :- |
| Cardinals | `123` | one hundred twenty-three |
| Cardinals with commas | `2,022` | two thousand twenty-two |
| Large cardinals | `10,000`, `1.5 million`, `3M`, `450K` | ten thousand, one point five million, three million, four hundred fifty thousand. A bare 5+ digit run (`10000`) reads digit-by-digit, so write the thousands separator to get the quantity reading |
| Scientific notation | `1e6`, `2.3e9` | one times ten to the six, two point three times ten to the nine |
| Approximators | `~300`, `>1000`, `<0.1`, `±5`, `100+` | approximately three hundred, greater than one thousand, less than zero point one, plus or minus five, one hundred plus |
| Negatives | `-23` | minus twenty-three |
| Decimals | `0.75`, `.001` | zero point seven five, zero point zero zero one |
| Ordinals | `1st`, `2nd`, `21st`, `100th` | first, second, twenty-first, one hundredth |
| Fractions | `1/2`, `3/4`, `5 1/2`, `2 2/5` | one half, three quarters, five and a half, two and two fifths |
| Years | `2022`, `1998` | twenty twenty-two, nineteen ninety-eight |

<Tip>
  Insert spaces between digits to force digit-by-digit reading: `4 0` reads as "four zero" (not "forty"). For longer alphanumeric IDs and codes, use [`spell()`](/docs/spell) instead.
</Tip>

## Currency

| Format | Example | Reads as |
| :- | :- | :- |
| Symbol + amount | `$5.99` | five dollars ninety-nine cents |
| Comma-separated | `$1,000` | one thousand dollars |
| With decimals | `$1,045.96` | one thousand forty-five dollars ninety-six cents |
| Pounds, euros, yen | `£728,641`, `€70-€72` | expands with currency word |
| Scale shorthand | `$5M`, `$1.2B` | five million dollars, one point two billion dollars |

Dozens of currency symbols and ISO codes are supported, including `$`, `€`, `£`, `¥`, `₹`, `₺`, `₪`, `₩`, `CHF`, `HK$`, `AUD$`, `US$`, and three-letter codes such as `USD`, `EUR`, `GBP`, `JPY`. Scale abbreviations `K`, `M`, `B`, `bn` are recognized.

## Ranges

Ranges with hyphens or en-dashes between numeric values read as "X to Y," with shared units on the right: `13-50`, `35-58 mph`, `49-56 °C`, `78-84%`, `67-77 mg`.

## Measurements

| Category | Examples |
| :- | :- |
| Length / mass / volume | `12km`, `5 mi`, `330 ft`, `15cm`, `5kg`, `7lb`, `12 oz`, `3mg` |
| Temperature | `0°C`, `98°F`, `15°` |
| Speed / power / percent | `60mph`, `120kW`, `95%` |

<Tip>
  A space between number and unit (`330 ft`) is slightly more reliable than the tight form (`330ft`). Use the space when you can.
</Tip>

## Phone numbers

US and international formats both work natively, with parentheses, hyphens, or spaces as separators.

| Format | Example | Reads as |
| :- | :- | :- |
| US with parens | `(213) 555-9274` | two one three, five five five, nine two seven four |
| US with hyphens | `213-555-9274` | two one three, five five five, nine two seven four |
| Spaced digits | `5 5 5, 7 7 2, 9 1 4 0` | five five five, seven seven two, nine one four zero |
| International | `+1 212-555-4807` | plus one, two one two, five five five, four eight zero seven |
| International with parens | `(+1) 415-203-7704` | plus one, four one five, two zero three, seven seven zero four |

## Roman numerals

English does not expand Roman numerals. They pass through as written, with or without a context word (the sole exception is the whitelist entry `World War II`, read as "World War two"). Use `spell()` or write the number out.

## Known gaps

A few specific patterns aren't reliably expanded. The most common are bare 5+ digit runs without separators (`10000000`), a bare `m` with no denominator (`1m` reads as "one million"), ampere and joule units (`5A`, `J`), and Roman numerals. For the full list and a drop-in prompt template to handle them, see [Pre-normalizing text](/docs/pre-normalization).

## Related

* [Symbols and percentages](/docs/symbols) for standalone `$`, `%`, `&`, `#`
* [Dates and times](/docs/dates) for years and clock times
* [Addresses, URLs, and emails](/docs/addresses) for ZIP codes
* [Spell function](/docs/spell) for forced letter-by-letter reading of IDs, account numbers, and codes


# Load balancing
Source: https://docs.rime.ai/docs/on-prem/load-balancing

Load-balance Rime on-prem deployments using the ORCA cost-header signal.

Rime's Coda and Mist model images report their concurrent request load to your
load balancer in an [Open Request Cost Aggregation (ORCA)
header](https://github.com/envoyproxy/envoy/issues/6614) on every engine HTTP
response. A balancer that reads it can send new requests to less-loaded engines,
because latency and real-time factor usually rise with an engine's
concurrency. Set `ENDPOINT_LOAD_METRICS_ENABLE=false` on the model
container to suppress the header.

## HTTP ORCA header

HTTP responses carry the report as text:

```
endpoint-load-metrics: TEXT application_utilization=0.5, cpu_utilization=0.3128, mem_utilization=0.2453, rps_fractional=0.0000, eps=0.0000
```

For gRPC, the engine sends the same load report as protobuf ORCA data in
`endpoint-load-metrics-bin` response metadata. Your gateway must understand
that encoding to use the report. WebSocket context events do not each carry
a fresh load report.

## Max concurrency

`application_utilization` is the number of concurrent inference requests
divided by the engine's max concurrency, `INFERENCE_CONCURRENCY_CAPACITY`. The
image default is `128` for Coda and `32` for Mist v3. Override it with the value
you measure during [parameter tuning](/docs/on-prem/performance).

At capacity, the [standalone engine](/docs/on-prem/quickstart) rejects new
synthesis. It returns gRPC `UNAVAILABLE`, HTTP 503, or WebSocket error kind
`unavailable`. `INFERENCE_CONCURRENCY_CAPACITY` sets this limit for both Coda
and Mist. The engine does not queue excess requests. For Coda, this setting
also sizes the generator's KV cache, so a higher limit costs GPU memory.

## Shutdown and long-lived connections

Your gateway must support HTTP/2 gRPC on engine port `7463` and HTTP/WebSocket
on engine port `8080`. Use `/readyz` or gRPC health to decide where to send
traffic. The HTTP ORCA header cannot move active gRPC streams or WebSocket
contexts to another engine. An open WebSocket stays on its selected engine,
even when the client starts another context on that connection.

Before you stop an engine, remove it from routing and wait for the change to
propagate. `SIGUSR2` marks the engine as not ready but lets it accept requests
that still arrive. `SIGTERM` starts request drain. At that point, the engine
rejects new synthesis, including new contexts on existing WebSocket connections.
Accepted work can finish until `--shutdown-drain-timeout`, which defaults to
ten minutes.

Give the engine time to finish. Set the container stop timeout or Kubernetes
`terminationGracePeriodSeconds` to cover request drain and backend cleanup.
The quickstart allows eleven minutes for the default configuration. Your
gateway's stream and idle timeouts must also allow the request duration your
application needs.

After shutdown, reconnect clients to a ready engine. Check what audio they
already received before you retry. An automatic retry can play the same audio
twice.


# Metrics
Source: https://docs.rime.ai/docs/on-prem/metrics

Health and OpenTelemetry metrics exposed by supported Rime on-prem containers.

Check the engine directly in a [standalone licensed deployment](/docs/on-prem/quickstart). This setup has no API container to serve `/health`.

## HTTP health

Use `/livez` to check that the health service responds. Use `/readyz` to check that the engine can accept inference requests. In the model image, the engine serves both endpoints on port `8080`:

```bash theme={null}
curl --fail http://localhost:8080/livez
curl --fail http://localhost:8080/readyz
```

Readiness returns HTTP 200 with `ok` when the engine is ready. It returns HTTP 503 during loading, quiet mode (after the engine receives `SIGUSR2`), or drain. Liveness can succeed while readiness fails. Use readiness to route traffic and liveness to decide on restarts, so a slow model load doesn't trigger a restart.

## gRPC health

On port `7463`, the engine serves the standard `grpc.health.v1.Health/Check` and `Watch` methods. Check overall readiness with the empty service name, `""`. Send traffic when the result is `SERVING` and withdraw it when the result is `NOT_SERVING`.

Install grpcurl and place the standard health schema at `./rime-protos/grpc/health/v1/health.proto`. This command checks readiness on the private local listener:

```bash theme={null}
grpcurl -plaintext \
  -import-path ./rime-protos -proto grpc/health/v1/health.proto \
  -d '{"service":""}' localhost:7463 grpc.health.v1.Health/Check
```

Keep the schema argument. The engine does not expose reflection, so grpcurl needs the schema to make the request. See [Engine protocols](/docs/on-prem/protocols#grpc) for synthesis schemas and client setup.

## OpenTelemetry metrics

The Rime engine exposes these metrics:

* `rime.engine.active_inference_request`
* `rime.engine.inference_concurrency_capacity`
* `rime.engine.application_utilization`
* `rime.engine.inference_admission_rejected`
* `rime.engine.concurrent_pipeline`
* `rime.engine.generated_audio_duration`
* `rime.engine.gpu_load`
* `rime.engine.initial_latency`
* `rime.engine.invocation_request`
* `rime.engine.unicode_scalar_value_count`
* `rime.engine.stage.items_in`
* `rime.engine.stage.items_out`
* `rime.engine.stage.first_output_latency`

The `rime.engine.stage.*` series carry a `stage` attribute.

Set `OTEL_COLLECTOR_PROTOCOL` to `grpc` (recommended), `http/protobuf`, or `http/json`, and set `OTEL_COLLECTOR_ENDPOINT` to your collector endpoint:

```bash theme={null}
OTEL_COLLECTOR_PROTOCOL=grpc
OTEL_COLLECTOR_ENDPOINT=http://otelcol:4317
```

The model does not set resource attributes. Use `OTEL_RESOURCE_ATTRIBUTES` to add them. The model also does not implement OpenTelemetry authentication, so run a collector sidecar when the upstream endpoint requires credentials.

To expose the OpenTelemetry series for Prometheus, follow the [Prometheus integration guide](/docs/on-prem/prometheus).

## Logs

The model container writes one plain-text line per event to its standard output. Request text is not included by default: lines that describe a request carry `text_chars`, the length of the input, instead of the input itself.

Set `RIME_LOG_REQUEST_TEXT=true` to include request text in those lines. Do this only where the container log stays inside a boundary that may hold end-user text, because anything reading the log, including a log forwarder, receives the text verbatim.

```bash theme={null}
RIME_LOG_REQUEST_TEXT=true
```

Set `OTEL_LOGS_EXPORTER=otlp` to have the model also send every log line to the collector named by `OTEL_COLLECTOR_ENDPOINT`, over `OTEL_COLLECTOR_PROTOCOL`. Both variables must be set as for metrics, or the switch exports nothing. The model sends each line as one OTLP log record: the line is the body, the log level is the severity, and `request_id` is an attribute on lines that belong to a request. The model sends logs nowhere else, and never to Rime.

```bash theme={null}
OTEL_LOGS_EXPORTER=otlp
```

Leave `OTEL_LOGS_EXPORTER` unset to keep logs on standard output only. The collector endpoint then carries metrics alone.

## Histogram tuning

Metrics that emit histogram data use preconfigured bucket boundaries. Override them with the corresponding `HISTOGRAM_BUCKETS_*` environment variable. Add a separate suffix with `HISTOGRAM_SUFFIX_*` when you need to distinguish differently tuned series.

### Initial latency

`rime.engine.initial_latency` is measured in milliseconds.

Default bounds:

```text theme={null}
0.0, 100.0, 150.0, 200.0, 225.0, 250.0, 275.0, 300.0, 325.0, 350.0, 375.0, 400.0, 450.0, 500.0, 1000.0
```

Example overrides:

```bash theme={null}
HISTOGRAM_BUCKETS_INITIAL_LATENCY_MS='0.0, 90.0, 95.0, 100.0, 105.0, 110.0, 115.0, 120.0, 125.0, 130.0, 135.0, 140.0, 150.0, 175.0, 200.0'
HISTOGRAM_SUFFIX_INITIAL_LATENCY='tuned_120ms'
```

The suffix produces `rime.engine.initial_latency.tuned_120ms`.

### Generated audio duration

`rime.engine.generated_audio_duration` is measured in seconds.

Default bounds:

```text theme={null}
0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 4.0, 5.0, 6.0, 7.5, 10.0, 20.0, 30.0, 60.0
```

Example overrides:

```bash theme={null}
HISTOGRAM_BUCKETS_GENERATED_AUDIO_DURATION_SECONDS='0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 4.0, 5.0, 6.0, 7.5, 10.0, 20.0, 30.0, 60.0'
HISTOGRAM_SUFFIX_GENERATED_AUDIO_DURATION='tuned_3s'
```

The suffix produces `rime.engine.generated_audio_duration.tuned_3s`.


# Performance tuning
Source: https://docs.rime.ai/docs/on-prem/performance

Tune supported Coda on-prem deployments for concurrency without exceeding latency or real-time-factor targets.

Choose your service-level target before you raise concurrency. The standalone engine limits accepted synthesis across HTTP, gRPC, and WebSocket. Once it reaches capacity, it rejects new work. If you need requests to wait or want a rate limit per caller, add those controls in your infrastructure. See [Load balancing](/docs/on-prem/load-balancing#max-concurrency) for the admission limit.

## What to measure

* **Initial latency**, or time to first frame or byte (TTFF/TTFB), measures the time from sending a request until the first frame arrives. Lower is better.
* **Real-time factor (RTF)** is processing time divided by stream duration. RTF must remain at or below 1 for real-time delivery. Lower is better.
* **Concurrency** is the number of simultaneous requests the service can handle while meeting the target. Higher is better.

Latency and RTF usually rise with concurrency. Queue or reject requests above the measured limit instead of allowing overload to degrade every active stream. The engine reports initial latency as `rime.engine.initial_latency`, and [Metrics](/docs/on-prem/metrics) covers the other series.

## Coda

For Coda, `GENERATOR_MAX_BATCH` and `INFERENCE_CONCURRENCY_CAPACITY` are the tuning controls, and their defaults work for most deployments. `INFERENCE_CONCURRENCY_CAPACITY` (default `128`) sets the generator's admission limit and sizes its KV cache, so raising it costs GPU memory.

| Variable | Default |
| :- | :- |
| `GENERATOR_MAX_BATCH` | `64` |
| `INFERENCE_CONCURRENCY_CAPACITY` | `128` |

Increase `GENERATOR_MAX_BATCH` to `128` when you serve higher traffic or run on more modern GPUs. A larger batch supports higher concurrency at the cost of longer container startup time. Leave the other controls at their defaults.


# Prometheus integration
Source: https://docs.rime.ai/docs/on-prem/prometheus

Export Rime on-prem OpenTelemetry metrics for Prometheus to scrape.

Rime model containers push OpenTelemetry metrics and don't serve a Prometheus endpoint themselves. To scrape them, run an OpenTelemetry Collector that receives the metrics and exposes them on port `9090`.

## Configure the model container

Point the model at a collector available as `otelcol` on the same Docker network:

```yaml theme={null}
services:
  model:
    environment:
      OTEL_COLLECTOR_PROTOCOL: grpc
      OTEL_COLLECTOR_ENDPOINT: http://otelcol:4317
```

See [Health checks and metrics](/docs/on-prem/metrics) for the emitted series and histogram controls.

## Configure the collector

Create `otelcol.yaml`:

```yaml theme={null}
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  prometheus:
    endpoint: 0.0.0.0:9090

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheus]
```

Run the collector on the model's Docker network so the model can reach it as `otelcol`, and expose its Prometheus port. Replace `<rime-network>` with that network's name, which `docker network ls` lists. Compose names it `<project>_default` unless you configure one:

```shell theme={null}
docker run -d \
  --name rime-otelcol \
  --network "<rime-network>" \
  --network-alias otelcol \
  -p 9090:9090 \
  -v "$(pwd)/otelcol.yaml:/etc/otelcol-contrib/config.yaml:ro" \
  otel/opentelemetry-collector-contrib:0.139.0
```

## Configure Prometheus

Add the collector to `prometheus.yml`:

```yaml theme={null}
global:
  scrape_interval: 5s

scrape_configs:
  - job_name: "rime-tts"
    static_configs:
      - targets: ["<collector-host>:9090"]
```

Reload Prometheus, open **Status > Targets**, and confirm that the `rime-tts` target is up. If it's down, Prometheus can't reach the collector on port `9090`.


# Engine protocols
Source: https://docs.rime.ai/docs/on-prem/protocols

Call a standalone licensed Coda or Mist engine over HTTP, gRPC, or WebSocket.

A standalone engine serves the model in its image over HTTP, gRPC, and WebSocket. The image selects the model, so a request can't switch to another one. These interfaces apply to the [standalone licensed deployment](/docs/on-prem/quickstart). The cloud API and the legacy API container have their own contracts.

| Protocol | Packaged engine address | Input | Output |
| :- | :- | :- | :- |
| HTTP | `http://localhost:8080/` | One JSON request with complete text | Streamed audio bytes |
| gRPC | `localhost:7463`, service `rime.TextToSpeech` | Complete text or a stream of text chunks | Protobuf audio messages |
| WebSocket | `ws://localhost:8080/ws` | One-shot or streaming contexts | JSON or protobuf event envelopes |

The model image configures the ports above. Use those ports for the quickstart. A bare engine binary defaults to HTTP port `7464` and gRPC port `7463`.

## Caller authentication

Your gateway must authenticate callers and provide TLS for every exposed protocol. In offline-license mode, the engine authorizes synthesis through the mounted runtime license. HTTP and gRPC callers do not need to send the metering key or license with each request.

<Warning>
  WebSocket still requires an `Authorization` upgrade header or an initial `config.authorization` message within ten seconds, even in offline-license mode. The engine skips validation of this value when it has a verified offline license. The field is required, but it provides no access control in this mode. For a private engine with a verified offline license, set `config.authorization` to an empty string. Keep the metering API key on the engine. Your gateway must authenticate callers. An empty value does not authenticate clients in other deployment modes.
</Warning>

## HTTP

Send the complete text to `POST /`. You can also use its alias, `POST /invocations`. Set `Content-Type: application/json` and choose an audio format with `Accept`, such as `audio/wav` or `audio/mpeg`.

| JSON field | Meaning |
| :- | :- |
| `text` | Required text to synthesize |
| `speaker` | Voice supported by the image, for example `luna` |
| `language` | BCP-47 language tag, for example `en` (`lang` is an alias) |
| `samplingRate` | Requested output sample rate in Hz, subject to model support |
| `timeScaleFactor` | Duration multiplier, where `1` preserves the generated duration |
| `splitStrategy` | `sentence` or `none`. Incremental input is available through gRPC or WebSocket |

Check the response `Content-Type` before you decode the audio.

<Note>
  For compatibility with existing HTTP clients, the engine also accepts `audioFormat` in the request body. Valid short values, such as `wav` or `mp3`, override `Accept`. If the field is absent or invalid, the engine uses `Accept`. Without either a valid body format or an `Accept` header, the request fails. Use `Accept` for new clients.
</Note>

This request writes the WAV response to `output.wav`:

```bash theme={null}
curl --fail-with-body http://localhost:8080/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: audio/wav' \
  -d '{"text":"Hello from Rime.","speaker":"luna","language":"en"}' \
  -o output.wav
```

Read the response as audio bytes. The engine does not use the legacy `audioContent.model_output` JSON wrapper. Before audio starts, a failure can return an HTTP error. After audio starts, a failure aborts the response body. HTTP 200 alone is not proof that synthesis completed.

Word timestamps are currently unavailable over all three standalone engine protocols.

## Python and JavaScript packages

Rime publishes Python [`rime-api`](https://pypi.org/project/rime-api/) and JavaScript [`@rimelabs/api`](https://www.npmjs.com/package/@rimelabs/api) with generated TTS message definitions for the engine's gRPC and WebSocket protocols. Both packages include the Protobuf and AsyncAPI schemas. You still need to generate gRPC client stubs separately.

Install the package for your application language:

<CodeGroup>
  ```shell Python theme={null}
  uv add rime-api
  ```

  ```shell JavaScript / TypeScript theme={null}
  npm install @rimelabs/api @bufbuild/protobuf@^2.11.0
  ```
</CodeGroup>

Your application manages connections, authentication, cancellation, and audio playback. See the [PyPI package description](https://pypi.org/project/rime-api/) for imports and JSON or binary encoding examples. The [cloud WebSocket endpoints](/docs/websockets) use different message formats from these engine envelopes.

## gRPC

The engine exposes `rime.TextToSpeech` without gRPC reflection. Supply the schema when you use `grpcurl` or generate gRPC client stubs. Choose a package release compatible with your engine image:

* Python wheel: `rime_api/schema/rime/text_to_speech.proto`.
* npm package: `schema/rime/text_to_speech.proto`.

Client generation also requires `google/protobuf/duration.proto` and `google/rpc/status.proto`, including their imports.

| RPC | Behavior |
| :- | :- |
| `Synthesize` | Accepts one `SynthesisRequest` and streams `SynthesisResponseStream` messages |
| `SynthesizeStreaming` | Accepts a stream of `StreamingSynthesisRequest` and streams the same response messages |
| `NormalizeText` | Returns `normalizedSentences` |
| `GetSupportedLanguages` | Returns the image's language tags |
| `GetSupportedSpeakers` | Lists Coda speakers (Mist returns `UNIMPLEMENTED`) |

With [grpcurl](https://github.com/fullstorydev/grpcurl) installed, this command sends complete text and prints the streamed response messages. Replace the example import path `./rime-protos` with your schema directory:

```bash theme={null}
grpcurl -plaintext \
  -import-path ./rime-protos \
  -proto rime/text_to_speech.proto \
  -d '{"text":"Hello from Rime.","speaker":"luna","language":"en","audioParameters":{"audioFormat":"audio/wav"}}' \
  localhost:7463 rime.TextToSpeech/Synthesize
```

Keep `-plaintext` for the private local listener. Use TLS through your gateway. grpcurl prints JSON with base64 `audio` fields. A generated protobuf client receives those fields as bytes. Append the audio payloads in order to build the audio file. Writing whole protobuf messages would include data outside the audio payload.

For incremental input, send one `header` followed by `textChunk` messages. Close the request side when you have sent all the text, then keep reading until the response stream completes. This example sends two complete sentences:

```bash theme={null}
grpcurl -plaintext \
  -import-path ./rime-protos \
  -proto rime/text_to_speech.proto -d @ \
  localhost:7463 rime.TextToSpeech/SynthesizeStreaming <<'JSON'
{"header":{"speaker":"luna","language":"en","audioParameters":{"audioFormat":"audio/wav"}}}
{"textChunk":"Hello from Rime. "}
{"textChunk":"This is the second sentence."}
JSON
```

If your input arrives a token at a time, set `header.splitStrategy` to `SPLIT_STRATEGY_ACCUMULATE_SENTENCE`. The engine collects text into sentences before synthesis. The selected image still determines model-specific synthesis behavior.

Check the final RPC status. Anything other than OK means synthesis is incomplete. Cancel the RPC to stop generation. The schema defines timestamp fields and a response trailer, but the standalone engine currently sends only audio messages. Setting `timestamps.enable` has no effect.

## WebSocket

Open `/ws` on the engine's HTTP port. Offer `rime.v1.json` for JSON text responses or `rime.v1.binary` for protobuf binary responses. The engine defaults to JSON if you omit the subprotocol. Both encodings use `WebSocketRequest` and `WebSocketResponse` from the gRPC schema bundle.

Each frame contains one message envelope. JSON uses camelCase fields and base64 `audio` values. Binary frames contain protobuf envelopes. With either encoding, extract the `audio` payload before you write it to an audio file.

| Client message | Action |
| :- | :- |
| `config` | Set connection credentials or defaults once, before the first `start` |
| `start` with non-empty `text` | Synthesize the complete text, with no `end` needed |
| `start` with empty `text` | Open a streaming context |
| `text` | Append input to that streaming context |
| `end: {}` | Finish input, then continue reading until `done` |
| `cancel: {}` | Cancel the context and expect `cancelled` |

Wait for `ready` before you send `start`. For each context, the server sends `started`, zero or more `audio` messages, then `done`, `cancelled`, or `error`. Match responses by `contextId`. An error with an empty context ID applies to the connection. You can keep the connection open for later contexts.

Save this example as `stream.mjs` and run it with Node.js 22 or later against a private engine with a verified offline license. It sends an empty authorization value and needs no metering API key. Running `node stream.mjs` writes `output.wav` only after the engine sends `done`:

```javascript theme={null}
import { writeFileSync } from "node:fs";

const socket = new WebSocket("ws://localhost:8080/ws", "rime.v1.json");
const chunks = [];
let completed = false;
let errorReported = false;
const send = (message) => socket.send(JSON.stringify(message));

socket.addEventListener("open", () => {
  // A verified offline license permits an empty authorization value.
  send({ config: { authorization: "" } });
});

socket.addEventListener("message", ({ data }) => {
  const message = JSON.parse(data);
  if (message.error) {
    console.error(message.error);
    errorReported = true;
    process.exitCode = 1;
    socket.close();
    return;
  }
  if (message.ready) {
    send({ contextId: "example", start: {
      text: "", speaker: "luna", language: "en",
      audioParameters: { audioFormat: "audio/wav" },
    } });
    send({ contextId: "example", text: "Hello from Rime. " });
    send({ contextId: "example", text: "This is the second sentence." });
    send({ contextId: "example", end: {} });
  }
  if (message.contextId !== "example") return;
  if (message.audio) chunks.push(Buffer.from(message.audio, "base64"));
  if (message.done) {
    writeFileSync("output.wav", Buffer.concat(chunks));
    completed = true;
    socket.close();
  }
  if (message.cancelled) socket.close();
});

socket.addEventListener("error", () => { process.exitCode = 1; });
socket.addEventListener("close", () => {
  if (!completed) {
    if (!errorReported) console.error("Synthesis ended before done");
    process.exitCode = 1;
  }
});
```

If your input arrives a token at a time, set `start.splitStrategy` to `SPLIT_STRATEGY_ACCUMULATE_SENTENCE`. Wait for `done` to confirm that all audio has arrived. This event does not currently include timestamp spans.

Migration from the API container's WebSocket ports requires changes to your client's messages. Move synthesis parameters from the old query parameters into `start`. Replace `flush`, `clear`, and `eos` with the context lifecycle above. Use `end` to finish input and `cancel` to stop a context. Decode the `audio` payload from each envelope.

For language support, read the languages in `ready` and test the voices in your image. The old API container's port-specific restrictions do not define this protocol.

## Routing, health, and failures

Route traffic using [HTTP or gRPC health checks](/docs/on-prem/metrics). Your gateway must support HTTP/2 gRPC and WebSocket upgrades. Set its timeouts to allow streams to stay open for the duration your application needs.

All three protocols share one inference capacity limit. At that limit, or during request drain, the engine refuses new synthesis. It returns gRPC `UNAVAILABLE`, HTTP 503, or a WebSocket `error` with kind `unavailable`.

Before you retry, check whether the client already received audio. Retry with backoff only if your application can avoid playing that audio again. See [Load balancing](/docs/on-prem/load-balancing) for stream routing and shutdown.


# Quickstart
Source: https://docs.rime.ai/docs/on-prem/quickstart

Run a licensed Coda or Mist v3 engine on your NVIDIA host with Docker Compose.

One model container serves HTTP, gRPC, and WebSocket synthesis. It needs a mounted runtime license and metering API key to start, and it doesn't authenticate callers, so your gateway controls who can use it.

<Note>
  Before you start, ask [help@rime.ai](mailto:help@rime.ai) for registry access and a runtime license that matches your selected image. If you already run an API/model pair, follow [Migrate an existing deployment](#migrate-an-existing-deployment).
</Note>

## Architecture

The engine checks the license locally at startup and sends aggregate usage counts to Rime over HTTPS. Your synthesis text and audio stay within your deployment.

```mermaid theme={null}
flowchart LR
  client[Your application] --> gateway[Your authenticated gateway]
  gateway --> engine[Coda or Mist engine]
  license[Mounted license] --> engine
  key[Mounted metering API key] --> engine
  engine -->|Aggregate usage over HTTPS| metering[optimize.rime.ai/metering]
```

<Warning>
  A runtime license authorizes the engine to run. It does not authenticate callers in this mode. The metering API key only authenticates outbound usage reports. Keep both engine ports private. Your gateway must authenticate callers and provide TLS. The Compose example binds both ports to the host's loopback interface.
</Warning>

# Prerequisites

## Hardware requirements

* GPU
  * For Mist
    * NVIDIA T4, L4, A10, or higher
  * For Coda
    * Confirm GPU requirements with Rime before provisioning
* Storage
  * 50 GB storage
* CPU
  * 8 vCPUs
* Memory requirements
  * 32 GiB

## Software requirements

* Supported Linux Distributions
  * Debian 12 (`bookworm`), x86\_64
  * Ubuntu Server 24.04 (`noble`), x86\_64
* NVIDIA drivers
  * Minimum: `580.65.06` (R580) for the default `native` CUDA mode
  * R535 or R570 hosts: supported only with `RIME_CUDA_COMPAT_MODE=compat` on forward-compatibility-eligible GPUs
  * Recommended: `595.71.05` or newer
* Docker
* NVIDIA Container Toolkit

### Installations

#### NVIDIA drivers

Follow [https://www.nvidia.com/en-us/drivers](https://www.nvidia.com/en-us/drivers) to install the latest NVIDIA drivers, or use the following instructions on Debian-based systems:

```bash NVIDIA Driver Installation (Debian-based) theme={null}
# Update packages
sudo apt-get update

# Install basic toolchain and kernel headers
sudo apt-get install -y gcc make wget linux-headers-$(uname -r)

# Download and install the NVIDIA driver.
NVIDIA_DRIVER_VERSION=580.95.05
NVIDIA_DRIVER_PATH=/opt/NVIDIA-Linux-x86_64-${NVIDIA_DRIVER_VERSION}.run
sudo rm -f "${NVIDIA_DRIVER_PATH}"
sudo wget "https://us.download.nvidia.com/tesla/${NVIDIA_DRIVER_VERSION}/NVIDIA-Linux-x86_64-${NVIDIA_DRIVER_VERSION}.run" -O "${NVIDIA_DRIVER_PATH}"
sudo chmod +x "${NVIDIA_DRIVER_PATH}"
sudo "${NVIDIA_DRIVER_PATH}" --silent --no-questions
```

#### Docker

Follow [https://docs.docker.com/engine/install](https://docs.docker.com/engine/install) to install Docker on your system.

Optionally, add the current user to the `docker` group for convenience: [https://docs.docker.com/engine/install/linux-postinstall](https://docs.docker.com/engine/install/linux-postinstall).
The code snippets below assume that you can run `docker` as the current login.

#### NVIDIA Container Toolkit

Follow [https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) to install the NVIDIA Container Toolkit.

Follow both the **Installation** and the **Configuration** sections.

#### Verification

This command runs `nvidia-smi` inside a CUDA container, so it checks the driver, Docker, and the NVIDIA Container Toolkit together:

```bash Verify Prerequisites theme={null}
docker run --rm --gpus all nvidia/cuda:13.2.0-base-ubi9 nvidia-smi
```

The output should list your GPU, the driver version, and the CUDA version. If the command fails, the engine container won't get GPU access either, so fix it before you continue.

## Firewall requirements

| Connection | Port or endpoint | Purpose |
| :- | :- | :- |
| Your application or gateway to the engine | TCP `8080` | HTTP synthesis, health checks, and WebSocket `/ws` |
| Your gRPC client or gateway to the engine | TCP `7463` | gRPC synthesis and health checks |
| Engine to Rime | HTTPS `https://optimize.rime.ai/metering` | Aggregate usage reports |
| Deployment host to Artifact Registry | HTTPS `us-docker.pkg.dev` | Image pulls |

If the engine cannot reach `/metering`, synthesis continues. The engine keeps reports in memory and retries them. Its queue holds up to 168 reporting windows, each one hour by default. Adding a window beyond that limit drops the oldest pending window. A process exit can also lose pending counts.

The licensed engine sends reports to `/metering` only. It does not call `/license` or `/usage`.

## API and registry credentials

Rime supplies registry access and the signed runtime license. In the dashboard for the billed account, open [API Tokens](https://app.rime.ai/tokens/) and create the metering API key.

Store the license as `./secrets/license` and the API key as `./secrets/api-key` on the deployment host. The engine must be able to read both files inside the container. Keep them outside source control.

Log in to Artifact Registry with the key Rime supplied:

```bash theme={null}
cat KEY-FILE | docker login -u _json_key --password-stdin https://us-docker.pkg.dev
```

## Image tags

Use the release tag in the `.env` example below for Coda or Mist v3. Confirm the selected image and runtime license with Rime for standalone licensed deployment.

### TTS service

| Model | Image repository |
| :- | :- |
| Coda v1 | `us-docker.pkg.dev/rime-labs/coda/v1/coda` |
| Mist v3 | `us-docker.pkg.dev/rime-labs/mist/v3/omni` |

Create `.env` next to `compose.yml` to select the Coda image at the current release tag:

```dotenv theme={null}
RIME_MODEL_IMAGE=us-docker.pkg.dev/rime-labs/coda/v1/coda:20260923
```

For Mist v3, replace the repository path with `us-docker.pkg.dev/rime-labs/mist/v3/omni` and keep the same tag.

On R535 or R570 hosts with forward-compatibility-eligible GPUs, add `RIME_CUDA_COMPAT_MODE=compat` to `.env`. Compose uses `native` when this setting is absent.

Keep the image's command and entrypoint. The image already contains the model files, pipeline configuration, license verifier keys, and package identity. You do not need an API service image in this mode.

Use [Models](/docs/models) and [Voices](/docs/voices) to choose a model and voice. Confirm the languages in your selected image with Rime.

## Docker Compose configuration

Create `compose.yml` to run the model with GPU access and read-only credential mounts:

```yaml theme={null}
services:
  model:
    image: ${RIME_MODEL_IMAGE:?Set RIME_MODEL_IMAGE in .env}
    environment:
      RIME_CUDA_COMPAT_MODE: ${RIME_CUDA_COMPAT_MODE:-native}
    ports:
      - "127.0.0.1:8080:8080"
      - "127.0.0.1:7463:7463"
    volumes:
      - ./secrets/license:/var/run/secrets/rime/license:ro
      - ./secrets/api-key:/var/run/secrets/rime/api-key:ro
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              capabilities: [gpu]
              count: all
    stop_grace_period: 11m
    restart: unless-stopped
```

Publish only the ports your clients need. If your gateway shares the engine's private Docker network, it can use `model:8080` and `model:7463` without published host ports. On Kubernetes, mount the same secrets and route a private Service to these container ports.

Mounted files keep credentials out of the container environment. If your platform mounts secrets elsewhere, set `RIME_LICENSE_FILE` and `RIME_API_KEY_FILE` to those paths.

You can also set `RIME_LICENSE` to the base64 license text Rime supplied and `RIME_API_KEY` to the key value. Do not encode the license again. Restart the engine after you change either credential.

Startup fails if a configured license is missing, invalid, or expired, or if the metering API key is missing. With no license source at all, the engine starts in legacy request-license mode. You must supply a runtime license to use standalone licensed mode.

Allow time for shutdown. The eleven-minute stop grace period covers the default ten-minute request drain plus cleanup. See [Load balancing](/docs/on-prem/load-balancing#shutdown-and-long-lived-connections) before you change it.

## Start and verify

Start the deployment, then wait for the engine to load and warm up. This readiness check retries for up to ten minutes, with a five-second timeout per attempt:

```bash theme={null}
docker compose up -d
curl --fail --retry 120 --retry-delay 5 --retry-connrefused \
  --retry-max-time 600 --max-time 5 http://localhost:8080/readyz
```

HTTP 200 with `ok` means the engine is ready. During loading or drain, it returns HTTP 503. If the retries fail, check `docker compose logs model` before you send synthesis requests. See [Health checks and metrics](/docs/on-prem/metrics) for liveness and gRPC checks.

Send this request to write `output.wav`. Coda and Mist v3 both support the example voice, `luna`. Use a voice available in your image:

```bash theme={null}
curl --fail-with-body http://localhost:8080/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: audio/wav' \
  -d '{"text":"Hello from Rime.","speaker":"luna","language":"en"}' \
  -o output.wav
```

Play `output.wav`. If you hear the sentence, the license, GPU access, and engine are working. If curl reports an HTTP error, `output.wav` holds the engine's error response, not audio. [Engine protocols](/docs/on-prem/protocols) covers the request fields, response handling, and gRPC and WebSocket examples.

## Migrate an existing deployment

Keep the previous API/model pair available while you test a separate standalone deployment. Verify each protocol your application uses before you switch traffic.

| Previous API/model pair | Standalone licensed engine |
| :- | :- |
| API service plus model service | One model container with license and metering key mounts |
| API service calls `/license` and `/usage` | Local license verification; engine calls `/metering` |
| HTTP on API port `8000` | HTTP on engine port `8080`; clients consume audio bytes |
| WebSocket ports `8002` and `8003` | `/ws` on port `8080`, with a different message protocol |
| API service checks caller API keys | Your gateway checks callers for all three protocols |
| API `/health` | Engine `/livez`, `/readyz`, and gRPC health service |

Remove `MODEL_URL`, `API_KEY_HEADER`, and `PLATFORM_API_KEY` from the new deployment. They configure the old API service. Mount the metering key on the engine, then update your proxy routes, firewall rules, probes, and clients. The engine image selects the model. A request's `modelId` cannot route it to another model.

Changing a WebSocket URL is not enough to migrate a client. An old `/ws3` client must also send the messages that `/ws` expects. Follow the [WebSocket migration rules](/docs/on-prem/protocols#websocket) and check audio completion, cancellation, and errors before you switch traffic.

Existing API/model pairs keep their request-license and API-side usage reporting behavior when no offline runtime license is mounted.


# OpenClaw
Source: https://docs.rime.ai/docs/openclaw

Pair OpenClaw with Rime TTS to build a Telegram bot that turns text and documents into verbatim readings, spoken summaries, or two-voice podcasts.

Build a Telegram bot that turns pasted text or attached documents into a verbatim reading, spoken summary, or two-voice podcast. OpenClaw handles the assistant workflow and Rime generates the voice note.

The samples compare the same podcast-style reading through the custom Rime skill and OpenClaw's default TTS:

| Rime TTS | Default TTS |
| - | - |
| <audio /> | <audio /> |

The custom skill also presents a selectable Rime voice menu before generating audio.

## Prerequisites

* [OpenClaw](https://github.com/openclaw/openclaw)
* [FFmpeg](https://ffmpeg.org/)
* Python 3
* A [Rime API key](https://app.rime.ai/tokens/)
* A Telegram account

## Step 1: Create a Telegram bot and connect it to OpenClaw

This guide uses Telegram as the interface to OpenClaw. You can adapt it to another messaging service.

First, create a new bot using Telegram's **BotFather**:

1. Open Telegram and search for [@BotFather](https://t.me/botfather).
2. Send `/newbot` and follow the prompts to choose a name and username.
3. BotFather replies with your bot token, which looks like `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`.

Add the bot token to `~/.openclaw/.env`:

```bash theme={null}
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
```

Then enable the Telegram plugin in the `~/.openclaw/openclaw.json` file:

```json theme={null}
{
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  }
}
```

Restart the gateway to pick up the new token:

```bash theme={null}
openclaw gateway restart
```

Verify the basic text chat functionality by messaging your bot in Telegram. The first time you message the bot, it shows an `access not configured` message with an access code. Copy the access code and run the following command in your terminal to pair the bot with OpenClaw:

```bash theme={null}
openclaw pairing approve telegram <access-code>
```

## Step 2: Add your Rime API key

OpenClaw reads environment variables from the `~/.openclaw/.env` file. Add your Rime API key to it:

```bash theme={null}
RIME_API_KEY=...
```

## Step 3: Disable OpenClaw's built-in TTS

OpenClaw has a built-in TTS system that the assistant uses by default. Disable it so OpenClaw uses the Rime skill you add in Step 4 instead.

Update your `openclaw.json` file as follows:

```json theme={null}
{
  "messages": {
    "tts": {
      "auto": "off",
      "edge": {
        "enabled": false
      }
    }
  },
  "tools": {
    "deny": ["tts"]
  }
}
```

This configuration:

1. **Turns off auto-TTS** so the built-in pipeline doesn't generate audio automatically
2. **Disables Edge TTS** so it can't be used as a fallback
3. **Denies the built-in `tts` tool** so the LLM can't call it directly

## Step 4: Install the rime-reader skill

The `rime-reader` skill reads documents aloud in three modes:

* In **verbatim** mode, it reads the document aloud, word for word, in your chosen voice.
* In **summary** mode, it summarizes the document's content in your chosen voice.
* In **podcast** mode, two AI hosts, each with a different voice, summarize and discuss the content.

Install the `rime-reader` skill by cloning it from the following repository into your `~/.openclaw/skills/` directory:

```bash theme={null}
git clone https://github.com/rimelabs/rime-reader-openclaw ~/.openclaw/skills/rime-reader
```

The skill folder contains a single Python script (`rime.py`) that handles all three modes and a `SKILL.md` that teaches the LLM how to use it.

```
~/.openclaw/skills/rime-reader/
├── SKILL.md
└── rime.py
```

### How rime.py works

The script has three modes, driven by the following command-line arguments:

* A file path for document reading
* `--text` for a single utterance
* `--segments` for podcast

All three modes share the same synthesis and encoding pipeline. The excerpts below use two constants from the top of `rime.py`: `SAMPLE_RATE = 48000` and `CHUNK_SIZE = 400`.

#### Chunking

In verbatim and summary mode, `rime.py` breaks long text into sentence-aligned chunks of roughly 400 characters so that no single API call is too large.

```python theme={null}
def chunk_text(text: str, size: int = CHUNK_SIZE) -> list:
    """Split text into sentence-aligned chunks under `size` characters."""
    text = " ".join(text.split())
    sentences = []
    for raw in text.replace("! ", ".\n").replace("? ", ".\n").split(".\n"):
        s = raw.strip()
        if s:
            sentences.append(s if s.endswith((".", "!", "?")) else s + ".")
    chunks, current, current_len = [], [], 0
    for sentence in sentences:
        if current_len + len(sentence) > size and current:
            chunks.append(" ".join(current))
            current, current_len = [sentence], len(sentence)
        else:
            current.append(sentence)
            current_len += len(sentence) + 1
    if current:
        chunks.append(" ".join(current))
    return chunks
```

#### Synthesis

The script then sends the chunks to the Rime API, which synthesizes them and returns raw audio bytes.

```python theme={null}
def synthesize(text, voice, speed, lang, api_key, model="coda"):
    body = {
        "text": text,
        "speaker": voice,
        "modelId": model,
        "samplingRate": SAMPLE_RATE,
        "speedAlpha": speed,
    }
    if lang:
        body["lang"] = lang

    req = urllib.request.Request(
        "https://users.rime.ai/v1/rime-tts",
        data=json.dumps(body).encode(),
        headers={
            "Authorization": f"Bearer {api_key}",
            "Accept": "audio/pcm",
            "Content-Type": "application/json",
        },
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=60) as resp:
        return resp.read()
```

#### Stitching

The script concatenates the bytes from each chunk into a single `bytearray` and generates silence between the chunks.

You can specify a voice for each segment in podcast mode:

```python theme={null}
silence = generate_silence(args.pause)  # e.g. 0.3s of silent PCM
all_pcm = bytearray()

for seg in segments:
    pcm = synthesize(seg["text"], seg["voice"], ...)
    all_pcm.extend(pcm)
    all_pcm.extend(silence)
```

#### Encoding

Then, `rime.py` writes the `bytearray` to a temporary PCM file and runs `ffmpeg` to convert it to OGG Opus, the format that Telegram expects. The temporary file is deleted after a successful conversion:

```python theme={null}
def pcm_to_ogg(pcm_data, ogg_path):
    pcm_path = os.path.join(os.path.dirname(ogg_path), "audio.pcm")
    with open(pcm_path, "wb") as f:
        f.write(pcm_data)

    result = subprocess.run(
        [
            "ffmpeg", "-y",
            "-f", "s16le", "-ar", str(SAMPLE_RATE), "-ac", "1", "-i", pcm_path,
            "-c:a", "libopus", "-b:a", "64k", "-vbr", "on",
            "-application", "voip",
            ogg_path,
        ],
        capture_output=True,
    )
    if result.returncode != 0:
        print(f"ffmpeg error: {result.stderr.decode()}", file=sys.stderr)
        sys.exit(1)
    os.remove(pcm_path)
```

The script prints the output `.ogg` path to `stdout`. The LLM reads this and uses it in a `MEDIA:` directive with `[[audio_as_voice]]` to deliver it as a Telegram voice note bubble.

## Step 5: Register the skill and configure the personality

Enable the skill in `~/.openclaw/openclaw.json`:

```json theme={null}
{
  "skills": {
    "entries": {
      "rime-reader": {
        "enabled": true
      }
    }
  }
}
```

### Personality (SOUL.md)

The `~/.openclaw/workspace/SOUL.md` file configures OpenClaw's agent personality. The LLM reads the file at the start of every session.

Add the **Document Reading** section below to your `SOUL.md` file. Without it, the bot skips the `rime-reader` skill and generates audio using whichever TTS model it finds first. Since you disabled the default TTS model in Step 3, it would fail to generate any audio and fall back to replying in text.

```markdown theme={null}
## Document reading

When the user sends a file or pastes text and asks you to read it, you must
follow the `rime-reader` skill workflow exactly. **Do not generate any audio
until both the mode and voice have been confirmed.** There are no exceptions.

**Step 1: ask for the delivery mode.** Only skip if the user's message
contained the exact word "verbatim", "summary", or "podcast":

> How would you like this delivered?
>
> 📖 **Verbatim**: full text
> 📋 **Summary**: concise spoken summary
> 🎙️ **Podcast**: two hosts break it down in a lively conversation

**Step 2: ask for a voice.** For verbatim or summary, ask for one voice. For
podcast, ask for two voices (Host 1 and Host 2). Use exactly this menu:

> Which voice should I use?
>
> 🏛️ **atrium**: steady, polished, confident
> ✨ **lyra**: smooth, expressive, quietly intense
> 🌊 **transom**: deep, resonant, commanding
> 🧊 **parapet**: cool, measured, precise
> 🌿 **fern**: warm, natural, approachable
> 🌑 **thalassa**: rich, textured, distinctive
> 🔩 **truss**: firm, clear, authoritative
> 🔷 **sirius**: crisp, formal, reliable
> 🌒 **eliphas**: smooth, deep, gravitas
> 📐 **lintel**: deliberate, focused, clean
>
> For podcast, reply with two names (e.g. "atrium and fern"), or say "surprise me".

**Step 3: only now** follow the full `rime-reader` skill for normalization,
scripting, and audio generation. Always use `rime.py`; never use another TTS
path.
```

## Step 6: Test the flow

Restart the gateway before testing the document reading flow:

```bash theme={null}
openclaw gateway restart
```

1. In Telegram, start a fresh session by sending `/new` to your bot.
2. Send a document or paste text in the chat and ask the bot to read it.
3. The bot asks you to choose a delivery mode: verbatim, summary, or podcast. Choose verbatim.
4. The bot prompts you to pick a voice.
5. After you pick a voice, the bot returns a voice note of your text.

If the bot replies in text instead, check that the **Document reading** section is in `SOUL.md` and that you sent `/new`, since OpenClaw reads `SOUL.md` only when a session starts.

## Tuning

`SOUL.md` drives the bot's behavior. Edit the file directly, or tell the bot in your Telegram chat to update it for you.

### Voice

Set a default voice for your assistant by editing `SOUL.md`, or by sending the bot a Telegram message: "Use Transom next time."

You can use any Coda voice: `atrium`, `lyra`, `transom`, `parapet`, `fern`, `thalassa`, `truss`, `sirius`, `eliphas`, `lintel`, or one of the many others listed on Rime's [Voices](/docs/voices) page.

### Podcast personality

The LLM writes the podcast script before synthesizing it, so you can steer the tone. Try adding a line such as the following to the **Document Reading** section of your `SOUL.md`:

```markdown theme={null}
For podcast mode, write the script in the style of a late-night talk show:
one host is deadpan and skeptical, the other is wildly enthusiastic. Keep it
punchy: no segment longer than two sentences.
```

Alternatively, skip editing `SOUL.md` entirely and tell the bot: "Make the podcast hosts argue like an old married couple." The LLM will adapt the script on the fly.

### Skip the prompts

If you always want the same voice and delivery mode, you can hardcode them in `SOUL.md` to skip the bot prompts.

For example, you could replace the first two steps with the following instruction:

```markdown theme={null}
Default to **summary** mode with the **fern** voice. Only ask if the user
says "let me choose".
```

Since OpenClaw loads `SOUL.md` afresh every session, your changes take effect immediately after you send `/new` in Telegram.


# Pipecat
Source: https://docs.rime.ai/docs/pipecat

Build a real-time voice agent with Pipecat and Rime TTS: a full Python walkthrough from install to a working browser-based agent.

Build a real-time voice agent with [Pipecat](https://github.com/pipecat-ai/pipecat), the open-source voice-agent framework created by [Daily](https://www.daily.co/). Rime handles speech synthesis through Pipecat's built-in Rime TTS service.

You can mix and match different services for each component of your Pipecat pipeline. This tutorial uses:

* `silero` for voice activity detection (VAD)
* `gpt-4o-transcribe` for speech-to-text (STT)
* `gpt-4o-mini` for generating responses
* `rime` for text-to-speech (TTS)

The result is a working voice agent that runs locally and opens in your browser.

<img alt="Demo of a voice agent conversation using Pipecat and Rime" />

The guide uses the following Pipecat terminology:

* A **pipeline** is a sequence of frame processors. Audio frames flow in, are transcribed, processed by the LLM, and synthesized into speech, then flow back out.
* A **transport** handles real-time audio input and output (I/O). Pipecat supports multiple transports, including WebRTC (browser), WebSocket, and local audio devices.
* **Frame processors** transform frames as they flow through the pipeline. Each service (STT, LLM, TTS) is a processor.

To try Rime's TTS API before building a full voice agent, see [TTS in five minutes](/docs/quickstart-five-minute).

## Step 1: Prerequisites

### 1.1 A Rime API key

Sign up for a [Rime account](https://app.rime.ai/signup/) and copy your API key from the [API Tokens](https://app.rime.ai/tokens/) page. The agent's `RimeTTSService` uses it to synthesize every reply.

### 1.2 An OpenAI API key

Create an [OpenAI account](https://platform.openai.com/signup) and generate an API key from the [API keys](https://platform.openai.com/api-keys) page. The agent uses this key for both transcription and response generation.

### 1.3 Python

Install [Python 3.11 or later](https://www.python.org/downloads/) (required by Pipecat 1.x). Verify your installation by running the following command in your terminal:

```bash theme={null}
python --version
```

## Step 2: Project setup

### 2.1 Create the project folder

Create a new folder for your project and navigate into it:

```bash theme={null}
mkdir rime-pipecat-agent
cd rime-pipecat-agent
```

### 2.2 Set up environment variables

In the new directory, create a file called `.env` and add the keys that you gathered in [Step 1](#step-1%3A-prerequisites):

```
RIME_API_KEY=your_rime_api_key
OPENAI_API_KEY=your_openai_api_key
```

<Note>Replace the placeholder values with your actual API keys.</Note>

### 2.3 Configure dependencies

Install the `uv` package manager:

<CodeGroup>
  ```bash macOS/Linux theme={null}
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```

  ```bash pip theme={null}
  pip install uv
  ```

  ```bash Homebrew (macOS) theme={null}
  brew install uv
  ```
</CodeGroup>

Create a `pyproject.toml` file and add the following dependencies to it:

```toml theme={null}
[project]
name = "rime-pipecat-agent"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "python-dotenv>=1.1.1",
    "pipecat-ai[openai,rime,silero,webrtc,runner]>=1.5.0,<2",
]
```

Pipecat uses a plugin system where each service integration is a separate package. In this code, the extras in brackets (`[openai,rime,silero,webrtc,runner]`) install the following plugins:

* `openai` adds STT and LLM services for transcription and generating responses.
* `rime` adds a TTS service for synthesizing speech.
* `silero` adds VAD for detecting when the user starts and stops speaking.
* `webrtc` provides the transport for browser-based audio via WebRTC.
* `runner` adds a development runner that handles server setup and WebRTC connections, and includes a ready-to-use browser client for talking to your agent.

<Note>This guide targets Pipecat 1.x (verified against 1.5.0). Several APIs were renamed or moved in the 1.0 release, so code written for `pipecat-ai` 0.x won't run unchanged.</Note>

`uv sync` creates a virtual environment and installs everything listed in `pyproject.toml`:

```bash theme={null}
uv sync
```

## Step 3: Create the agent

Create an `agent.py` file for the agent code. To skip the explanation and paste the finished file, go to [Step 3.5: Full agent code](#3-5-full-agent-code).

### 3.1 Load environment variables and configure imports

These imports bring in each pipeline component, and `load_dotenv()` loads the keys from `.env` into the environment. Add them to `agent.py`:

```python theme={null}
import os
from dotenv import load_dotenv

from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.frames.frames import LLMRunFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineWorker
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
    LLMUserAggregatorParams,
)
from pipecat.runner.run import main
from pipecat.runner.types import RunnerArguments
from pipecat.runner.utils import create_transport
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.services.openai.stt import OpenAISTTService
from pipecat.services.rime.tts import RimeTTSService
from pipecat.transports.base_transport import TransportParams

load_dotenv()
```

Each import corresponds to a frame processor or utility:

* `Pipeline` chains processors together in sequence.
* `PipelineRunner` and `PipelineWorker` manage the event loop and run the pipeline.
* `LLMRunFrame` triggers the LLM to respond when queued.
* Services like `OpenAISTTService`, `OpenAILLMService`, and `RimeTTSService` are the frame processors that do the actual work.
* `LLMContext` maintains conversation history across turns, and `LLMContextAggregatorPair` keeps it updated from both sides of the conversation.
* `SileroVADAnalyzer` detects speech boundaries so the agent knows when you've finished talking.
* `create_transport` and `TransportParams` set up the WebRTC transport for browser-based audio.
* `RunnerArguments` provides connection details when a user connects to the agent.

### 3.2 Define the system prompt

Add the system prompt below the imports. The short-response instruction matters in a voice agent, because every sentence the LLM writes becomes audio the user has to listen to.

```python theme={null}
SYSTEM_PROMPT = """You are a helpful voice assistant.
Keep your responses short and conversational - no more than 2-3 sentences.
Be friendly and natural."""
```

This system prompt defines your agent's personality. It can be as simple or complex as you like. [Step 5.2](#5-2-fine-tune-agent-personalities) has a longer example.

### 3.3 Code the conversation pipeline

First, tell the runner how to configure the transport. Add the following below the system prompt:

```python theme={null}
transport_params = {
    "webrtc": lambda: TransportParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
    ),
}
```

This dictionary maps transport names to their configuration. The `webrtc` entry enables audio input and output for the browser-based WebRTC transport that this guide uses.

Next, add the following `bot` function to `agent.py`:

```python theme={null}
async def bot(runner_args: RunnerArguments):
```

The Pipecat runner automatically discovers any function named `bot` in your module. When a user connects via WebRTC, the runner calls this function and passes connection details through `runner_args`.

Inside the `bot` function, create the transport:

```python theme={null}
    transport = await create_transport(runner_args, transport_params)
```

`create_transport` matches the incoming connection against your `transport_params` dictionary and builds the right transport for it.

Next, add the AI services for transcription, response generation, and speech synthesis:

```python theme={null}
    stt = OpenAISTTService(
        api_key=os.getenv("OPENAI_API_KEY"),
        settings=OpenAISTTService.Settings(model="gpt-4o-transcribe"),
    )

    llm = OpenAILLMService(
        api_key=os.getenv("OPENAI_API_KEY"),
        settings=OpenAILLMService.Settings(model="gpt-4o-mini"),
    )

    tts = RimeTTSService(
        api_key=os.getenv("RIME_API_KEY"),
        settings=RimeTTSService.Settings(
            voice="lyra",
            model="coda",
        ),
    )
```

These configure OpenAI for STT and LLM responses, and Rime's flagship `coda` model for TTS. `RimeTTSService` works with Rime's current models (`coda`, `mistv3`, `mistv2`).

Add the conversation context:

```python theme={null}
    context = LLMContext(
        messages=[{"role": "system", "content": SYSTEM_PROMPT}]
    )
    context_aggregator = LLMContextAggregatorPair(
        context,
        user_params=LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer()),
    )
```

This maintains the conversation history, so the LLM can reference previous messages. The user-side aggregator also runs Silero VAD to detect when the user starts and stops speaking.

Add the pipeline that connects all the components:

```python theme={null}
    pipeline = Pipeline([
        transport.input(),
        stt,
        context_aggregator.user(),
        llm,
        tts,
        transport.output(),
        context_aggregator.assistant(),
    ])
```

Frames flow through the processors in order.

1. **Audio in:** Raw microphone input from the user
2. **Transcription:** Converting speech to text via the STT provider
3. **User context:** Aggregating the user's message into the conversation history
4. **LLM response:** Generating a reply based on the conversation so far
5. **Speech synthesis:** Converting the LLM's text response to audio via Rime TTS
6. **Audio out:** Streaming the synthesized speech back to the user
7. **Assistant context:** Recording the assistant's response in the conversation history

The context aggregator appears twice to capture both sides of the conversation.

Finally, add the pipeline worker and an event handler for greeting the user:

```python theme={null}
    worker = PipelineWorker(
        pipeline,
        params=PipelineParams(enable_metrics=True),
    )

    @transport.event_handler("on_client_connected")
    async def on_client_connected(transport, client):
        context.add_message(
            {"role": "system", "content": "Say hello and introduce yourself."}
        )
        await worker.queue_frames([LLMRunFrame()])

    runner = PipelineRunner(handle_sigint=runner_args.handle_sigint)
    await runner.run(worker)
```

The `on_client_connected` event fires when a user connects to the agent. It appends a system message prompting the LLM to greet the user, then queues an `LLMRunFrame` to trigger an immediate response.

### 3.4 Create the main entrypoint

Add the following code at the bottom of `agent.py`:

```python theme={null}
if __name__ == "__main__":
    main()
```

Pipecat's `main` helper from `pipecat.runner.run` automatically:

* Discovers the `bot` function in your module
* Starts a FastAPI server with WebRTC endpoints
* Serves a prebuilt browser client at `/client`
* Sets up the WebRTC connection and passes the connection to your `bot` function

When you run the agent, Pipecat starts a local HTTP server. Open the browser client to connect over WebRTC. The agent still calls the OpenAI and Rime APIs over the network.

### 3.5 Full agent code

At this point, your `agent.py` file should look like the complete example below:

<Accordion title="Full agent code">
  ```python theme={null}
  import os
  from dotenv import load_dotenv

  from pipecat.audio.vad.silero import SileroVADAnalyzer
  from pipecat.frames.frames import LLMRunFrame
  from pipecat.pipeline.pipeline import Pipeline
  from pipecat.pipeline.runner import PipelineRunner
  from pipecat.pipeline.task import PipelineParams, PipelineWorker
  from pipecat.processors.aggregators.llm_context import LLMContext
  from pipecat.processors.aggregators.llm_response_universal import (
      LLMContextAggregatorPair,
      LLMUserAggregatorParams,
  )
  from pipecat.runner.run import main
  from pipecat.runner.types import RunnerArguments
  from pipecat.runner.utils import create_transport
  from pipecat.services.openai.llm import OpenAILLMService
  from pipecat.services.openai.stt import OpenAISTTService
  from pipecat.services.rime.tts import RimeTTSService
  from pipecat.transports.base_transport import TransportParams

  load_dotenv()

  SYSTEM_PROMPT = """You are a helpful voice assistant.
  Keep your responses short and conversational - no more than 2-3 sentences.
  Be friendly and natural."""

  transport_params = {
      "webrtc": lambda: TransportParams(
          audio_in_enabled=True,
          audio_out_enabled=True,
      ),
  }


  async def bot(runner_args: RunnerArguments):
      transport = await create_transport(runner_args, transport_params)

      stt = OpenAISTTService(
          api_key=os.getenv("OPENAI_API_KEY"),
          settings=OpenAISTTService.Settings(model="gpt-4o-transcribe"),
      )

      llm = OpenAILLMService(
          api_key=os.getenv("OPENAI_API_KEY"),
          settings=OpenAILLMService.Settings(model="gpt-4o-mini"),
      )

      tts = RimeTTSService(
          api_key=os.getenv("RIME_API_KEY"),
          settings=RimeTTSService.Settings(
              voice="lyra",
              model="coda",
          ),
      )

      context = LLMContext(
          messages=[{"role": "system", "content": SYSTEM_PROMPT}]
      )
      context_aggregator = LLMContextAggregatorPair(
          context,
          user_params=LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer()),
      )

      pipeline = Pipeline([
          transport.input(),
          stt,
          context_aggregator.user(),
          llm,
          tts,
          transport.output(),
          context_aggregator.assistant(),
      ])

      worker = PipelineWorker(
          pipeline,
          params=PipelineParams(enable_metrics=True),
      )

      @transport.event_handler("on_client_connected")
      async def on_client_connected(transport, client):
          context.add_message(
              {"role": "system", "content": "Say hello and introduce yourself."}
          )
          await worker.queue_frames([LLMRunFrame()])

      runner = PipelineRunner(handle_sigint=runner_args.handle_sigint)
      await runner.run(worker)


  if __name__ == "__main__":
      main()
  ```
</Accordion>

## Step 4: Test your agent

Run the agent from the terminal with `uv`, then talk to it in your browser.

### 4.1 Start the agent

Run the following command to start your agent:

```bash theme={null}
uv run agent.py
```

Wait for the server startup logs before you open the browser. If the command exits with an error instead, see [Import errors when starting the agent](#import-errors-when-starting-the-agent).

### 4.2 Connect to your agent

Open a browser and navigate to `http://localhost:7860/client`. Allow microphone access when prompted.

The agent speaks first, because `on_client_connected` queues an `LLMRunFrame` as soon as the browser connects. Reply after the greeting to start the conversation. If you don't hear the greeting, see [No audio output](#no-audio-output-and-other-tts-errors).

## Step 5: Customize your agent

Change the voice in the `tts` service, or move the system prompt into its own file.

### 5.1 Change the voice

Update the `tts` initialization in your `bot` function to try a different voice:

```python theme={null}
tts = RimeTTSService(
    api_key=os.getenv("RIME_API_KEY"),
    settings=RimeTTSService.Settings(
        voice="astra",
        model="coda",
    ),
)
```

Restart the agent and reconnect to hear the new voice, because the runner loads `agent.py` only at startup. See the [Voices](/docs/voices) page for the full list of Rime voices.

### 5.2 Fine-tune agent personalities

Create a new file called `personality.py` with the following content:

<Accordion title="Example personality file">
  ```python theme={null}
  SYSTEM_PROMPT = """
  CHARACTER:
  You are Detective Marlowe, a world-weary noir detective from the 1940s who
  somehow ended up as an AI assistant. You treat every question like it's a
  case to be cracked and speak in dramatic, hard-boiled metaphors.

  PERSONALITY:
  - Cynical but secretly caring underneath the tough exterior
  - Treats mundane tasks like high-stakes mysteries
  - References your "years on the force" and "cases that still haunt you"
  - Suspicious of technology but grudgingly impressed by it
  - Has strong opinions about coffee and rain

  SPEECH STYLE:
  - Keep responses to 2-3 sentences maximum
  - Use noir metaphors like "this code is messier than a speakeasy on a Saturday night"
  - Dramatic pauses with "..." for effect
  - Call the user "kid" or "pal" occasionally
  - End with ominous or philosophical observations

  RESTRICTIONS:
  - Never break character
  - Don't use emojis or special characters
  - Stay family-friendly despite the noir tone
  """

  INTRO_MESSAGE = "The name's Marlowe... I've seen things that would make your code freeze, pal. So what case are you bringing to my desk tonight?"
  ```
</Accordion>

Update your `agent.py` to import and use this prompt:

```python theme={null}
from personality import SYSTEM_PROMPT, INTRO_MESSAGE
```

Then update the `on_client_connected` handler to use your custom intro message:

```python theme={null}
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, client):
    context.add_message(
        {"role": "system", "content": f"Say: {INTRO_MESSAGE}"}
    )
    await worker.queue_frames([LLMRunFrame()])
```

Keeping the system prompt in a separate file lets you change the character without editing the agent logic.

## Swap agent components

Each Pipecat component can be swapped independently:

* Replace OpenAI with another STT provider such as Deepgram or AssemblyAI.
* Use a different LLM such as Anthropic, Gemini, or a local model.
* Switch transports to WebSocket for server-to-server, or to [Daily's hosted rooms](/docs/daily) for production deployments.

The [Pipecat documentation](https://docs.pipecat.ai/getting-started/introduction) covers transports, deployment patterns, and advanced features.

View Rime's [Pipecat demo agents](https://github.com/rimelabs/rime-pipecat-agents) for a ready-to-use multilingual agent example that switches languages dynamically.

## Troubleshooting

### No audio output and other TTS errors

* **Check your TTS service class:** Use `RimeTTSService`. It supports Rime's current models (`coda`, `mistv3`, `mistv2`). The older `RimeNonJsonTTSService` is deprecated and will be removed in Pipecat 2.0.
* **Verify your Rime API key:** Ensure the key is valid and has TTS permissions.

### Import errors when starting the agent

* **Check your Pipecat version:** Errors like `No module named 'pipecat.processors.aggregators.openai_llm_context'` mean you're running code written for Pipecat 0.x on a 1.x install (or vice versa). This guide requires `pipecat-ai` 1.5 or later: the 1.0 release renamed `OpenAILLMContext` to `LLMContext`, replaced `llm.create_context_aggregator()` with `LLMContextAggregatorPair`, and moved VAD configuration from `TransportParams` to `LLMUserAggregatorParams`.

### The agent doesn't respond to speech

* **Check microphone permissions:** Ensure you've enabled microphone access in your browser.
* **Verify VAD is working:** Look for logs indicating speech detection. If the logs are missing, check your Silero installation.
* **Test audio input:** Use a different microphone or headset.

### "API key not set" errors

* **Check environment variables:** Ensure you set all keys correctly (with no extra spaces) in `.env`.
* **Verify the `.env` file location:** The file should be in the same directory as `agent.py`.

### Audio quality issues

* **Check your microphone:** Test using a different input device or headset.
* **Reduce background noise:** The VAD may struggle to detect speech in noisy environments.


# Pre-normalizing text
Source: https://docs.rime.ai/docs/pre-normalization

Pre-expand only the formats Rime does not already normalize reliably.

<Warning>
  **Most applications shouldn't pre-normalize.** Rime natively handles common patterns: currency with symbols, dates with years, clock times, phone numbers, standard measurements, and most numeric formats. Pre-normalizing adds latency and engineering complexity for behavior you usually get for free. Before adding a pre-processing layer, review the [formats Rime handles natively](/docs/text-normalization#handled-at-a-glance) and verify any specific input with the [`/textnorm` endpoint](/docs/text-normalization#debugging-with-the-textnorm-endpoint).
</Warning>

If you still need to pre-normalize, start with the patterns listed under [Known gaps](#known-gaps). The [prompt template](#pre-normalization-prompt-template) at the end covers them, and you can drop it into the layer that generates your text.

***

## When pre-normalizing makes sense

There are two cases where pre-normalization in your application is worth the cost:

1. **The input falls into a [known gap](#known-gaps).** A small set of patterns aren't reliably expanded today. Pre-expanding those specific patterns is the reliable fix.
2. **You need guaranteed consistency across regenerations.** For utterances that must read identically every time, such as regulatory disclosures, legal read-backs, or confirmation flows, pre-normalizing removes a source of variability.

For everything else, trust Rime's normalizer and use [`/textnorm`](/docs/text-normalization#debugging-with-the-textnorm-endpoint) to verify anything that sounds off. If you find a pattern Rime doesn't handle, [flag it to Rime](mailto:support@rime.ai) so fixes ship on Rime's side instead of in every customer's pre-processing layer.

***

## Known gaps

These patterns aren't reliably expanded today. Either avoid them at the source, or pre-expand them in the layer that generates your text.

### Dates

* **MM/DD without a year** (`04/21`). Expand to `April 21st` or `April twenty-first`.
* **Financial periods** (`1H 2024`, `Q1 2025`, `1Q`, `2Q`). Not consistently expanded.
* **Cross-month date ranges** (`May-June 2024`). Not a recognized pattern.

### Times

* **European `15h30` times.** The `h` separator isn't recognized. Use `15:30`.
* **Suffixed approximations.** `9:00-ish` reads the colon literally. Avoid or pre-normalize.

### Numbers

* **Bare 5+ digit runs** (`10000000`) read digit-by-digit. Add thousands separators (`10,000,000`) to get the quantity reading, or use shorthand (`10M`).
* **Bare caret exponents** (`10^6` without a leading `x10`) aren't rewritten. Use `1e6` or superscripts (`10⁶`), which are recognized.
* **Very large ordinals** (`1,000,000th`) fall back to digit-by-digit. Prefer writing out (`one millionth`).
* **A letter B, K, or M right after a number** reads as billion, thousand, or million, even when it isn't a quantity. `221B Baker St` becomes "two hundred twenty one billion Baker Street," and `a 5K race` becomes "a five thousand race." Put a space before the letter (`221 B`, `5 K`) to keep it as a letter.

### Money

* **Minus-sign glyphs** (`−€100` with U+2212). Use the ASCII hyphen (`-€100`). Rime handles ASCII negative amounts.

### Measurements

* **Bare `m` with no denominator.** `1m` reads as "one million." Write `1 meter`, or use a denominator (`7m/s` reads correctly as "seven meters per second").
* **Ampere and joule units** (`5A`, `J`) pass through unexpanded. Spell out (`5 amperes`) if verbalization matters.
* **Uncommon units** (`btu`, `psi`, `dyne`, `‰`) are not reliably expanded.
* **Parenthesized compound units** (`5(kg/m²)`) aren't a recognized form.

### Ranges

* **Inconsistent connector.** Hyphen ranges are usually read as "to," but in some contexts the hyphen is read literally. If consistency matters, use the word "to" directly.

### Roman numerals

* **Roman numerals** always pass through unchanged in English, with or without a context word. Use [`spell()`](/docs/spell) to force letter-by-letter, or write out the number.
* **Mixed-format numbering** (`section 2.IV.3`) isn't handled.

### Phone numbers

* **Vanity numbers** (`1-800-FLOWERS`) keep the letters as a literal string. Use `spell(FLOWERS)` if you need letter-by-letter.
* **Extensions** (`555-1234 ext. 567`, `555-1234 x 567`) aren't explicitly handled.

### Miscellaneous

* **Context-dependent abbreviations** (`Dr.`, `Mr.`, `St.`) rely on context and may not always resolve as expected. See [Abbreviations](/docs/abbreviations).
* **Repeating decimals** (`0.3̄`, `0.(3)`) aren't recognized.
* **Internationalized domain names** (non-ASCII in URLs) aren't supported.

***

## Pre-normalization prompt template

If your application uses an LLM to generate text before sending it to Rime, you can add the rules below to its system prompt or run them as a post-processing pass. The template targets only the [known gaps](#known-gaps). Rime's normalizer handles the rest, so there's no need to pre-expand everything.

<Accordion title="System prompt template">
  ```text theme={null}
  TEXT-TO-SPEECH NORMALIZATION RULES

  Before returning your response, rewrite any of the following patterns. The text
  will be sent to a text-to-speech engine, and these specific patterns are known
  not to verbalize correctly on the engine side. Leave all other text alone.

  1. DATES WITHOUT A YEAR. Expand MM/DD dates to month name + ordinal day.
     04/21 -> "April 21st"
     08/30 -> "August 30th"
     Full dates with a year (01/12/2026) do not need rewriting.

  2. MONTH-AND-YEAR ALONE. Expand MM/YYYY to month name + year.
     07/2025 -> "July 2025"

  3. BARE HOURS WITH MERIDIEM. Insert ":00" for precision.
     3pm  -> "3:00pm"
     3 pm -> "3:00pm"
     Clock times with minutes (7:05 PM) do not need rewriting.

  4. DECADE NAMES. Rewrite "1990s" as "the nineteen nineties" (or the
     relevant decade) to avoid it reading as "nineteen hundreds."

  5. FINANCIAL PERIODS AND CENTURIES. Expand to prose.
     Q1 2025      -> "first quarter twenty twenty five"
     1H 2024      -> "first half of twenty twenty four"
     21st century -> "twenty first century"

  6. NON-DOLLAR CURRENCY SHORTHAND. Spell out the scale word.
     €900K -> "900 thousand euros"
     £2M   -> "2 million pounds"
     Dollar shorthand ($5M, $1.2B) reads correctly and does not need rewriting.

  7. ALPHANUMERIC IDs, codes, confirmation numbers, SKUs, tracking numbers,
     vanity phone numbers. Wrap the identifier in spell(). Do not otherwise
     alter it.
     "Your confirmation is ABC123XYZ" -> "Your confirmation is spell(ABC123XYZ)."
     "Call 1-800-FLOWERS" -> "Call 1-800-spell(FLOWERS)."

  8. LONG NUMBERS. Keep thousands separators (10,000,000); a bare digit run
     like 10000000 reads digit-by-digit. Scale shorthand (10M) also works.
     When a B, K, or M after a number is a letter rather than a scale word,
     add a space before it: "221B Baker St" -> "221 B Baker St",
     "a 5K race" -> "a 5 K race".

  9. PROSODY. Use commas for short pauses inside sentences and periods for
     sentence boundaries. Keep sentences under about 25 words when possible.
     Do not use dashes inside numbers, IDs, or phone numbers; they cause
     unwanted pauses.

  10. NEVER invent, drop, or reorder information while rewriting. Preserve every
      digit, letter, and symbol from the source; only change the surface form
      for patterns listed above. Currency with symbols ($124.50), standard
      measurements (5kg, 98°F), phone numbers with punctuation ((213) 555-9274),
      and percentages (95%) should pass through unchanged.

  Apply these rules silently. Do not mention them in your output.
  ```
</Accordion>


# Privacy and compliance
Source: https://docs.rime.ai/docs/privacy-compliance

Rime's SOC 2 Type II and HIPAA status, default data handling, and contractual options.

Rime is SOC 2 Type II certified and HIPAA compliant. By default, Rime collects only character counts and does not use customer data for model training. Email [support@rime.ai](mailto:support@rime.ai) to request compliance reports, an MSA, or a BAA.

## Certifications

<Columns>
  <Card title="SOC 2 Type II" icon="shield-check">
    Certified as of May 2025.
  </Card>

  <Card title="HIPAA" icon="shield-check">
    Compliant as of February 2024.
  </Card>
</Columns>

## Data handling

Rime does not collect customer data beyond character count unless requested. Customer data is not used to train Rime models unless the customer explicitly opts in.

Rime can sign an MSA or BAA to define customer-specific data and compliance terms.


# Prompting guide
Source: https://docs.rime.ai/docs/prompting

How to prompt your LLM to produce text that sounds natural and normalizes cleanly through Rime.

<Note>This guide focuses on Coda. The same patterns work with the [Mist model family](/docs/models). [`spell()`](/docs/spell) works on both, with different grouping.</Note>

LLMs are trained and post-trained to produce grammatically correct prose for readers. Voice agents need something different: text that sounds natural when spoken. Without guidance, LLM output sent to a TTS model can sound like formal, stiff prose read aloud.

That leaves the LLM with two jobs: write conversational speech, then format it so Rime's normalizer reads it correctly. The [drop-in system prompt](#drop-in-system-prompt) at the end handles both.

## Sound like a person

The agent is not trying to pass as human. Its voice should make callers comfortable enough to respond naturally, which usually leads to better outcomes.

Real speech includes fillers, restarts, soft pauses, and occasional phrases like "yeah, no."

Coda doesn't support SSML. Markup such as `<break time="1s"/>` isn't interpreted, and the text normalizer turns it into words the voice reads aloud. Short expressive tags such as `<giggle>` do reach the model and can shape delivery, but only as best-effort cues: the effect may land elsewhere in the line or color the whole sentence. [`spell()`](/docs/spell) is the only inline function with defined behavior, so the drop-in system prompt below leaves tags out.

Rime deliberately keeps the interface small. Coda uses the meaning of the text to shape emotional delivery, while punctuation controls pacing and emphasis. Exclamation marks and interrobangs add excitement. Commas and ellipses add pauses.

### Show, don't tell

Instructions like "be conversational" are too vague. Give the model examples it can imitate instead.

The right register depends on the call type, persona, and caller, so the examples below are not universal. They show the gap between default LLM prose and speech that usually sounds more natural.

Even formal calls include occasional fillers and restarts. Use them lightly.

| Typical LLM output | Best practice example |
| - | - |
| "I can certainly assist you with that inquiry." | "Yeah, I can help with that. One sec." |
| "Unfortunately, I am required to inform you that your request cannot be processed at this time." | "So... I'm not going to be able to do that today. Here's what I can do instead." |
| "I will now transfer you to the appropriate department for further assistance." | "Okay, one moment. I'm going to grab someone who can take this from here." |

### Put disfluencies in the text

Write "um," "uh," "so," "yeah," and "well" where someone would genuinely hesitate. Don't rely on tags, and don't stack fillers. Two "um"s in a row sounds like a bug.

### Punctuation controls prosody

* **Comma.** Short internal pause with a slight rise.
* **Period.** Sentence end, falling pitch.
* **Question mark.** Rising intonation.
* **Ellipsis.** Hesitant or trailing pause. Use sparingly.
* **Semicolon.** Somewhere between a comma and a period.

Keep spoken sentences under 25 words. Long sentences without internal commas sound breathless, so split them.

### Describe personality through speech

Replace adjectives like "friendly" or "warm" with observable speech patterns the model can imitate. "Friendly" requires interpretation. "Starts sentences with 'yeah'" gives the model a behavior.

Keep the baseline calm and even. Save exclamation marks for situations that warrant them. A support agent does not need excitement in every reply.

## Normalize cleanly

The Rime normalizer reads common formats natively: currency with symbols, full dates, clock times with minutes, phone numbers, percentages, and standard measurements. Pass these values through unchanged:

```text theme={null}
$124.50, 04/21/2026, 7:05 PM, (213) 555-9274, 5kg, 98°F, 95%
```

Expand only the patterns in [Pre-normalization](/docs/pre-normalization) before synthesis. [Text normalization](/docs/text-normalization) contains the full reference.

Send any tricky string to the [`/textnorm`](/api-reference/other/textnorm) endpoint before release to confirm how Rime will read it.

## Use `spell()` for IDs

If Rime must read an identifier one character at a time (confirmation codes, account numbers, SKUs, vanity phone letters), wrap it in [`spell()`](/docs/spell). On Coda in English, the normalizer spells letters straight through and reads longer digit runs in pairs. In other languages, and on Mist v3, `spell()` groups the characters in threes where possible and pairs where necessary. Both read symbols such as `@` and `-`. Write the sequence without spaces, as in `spell(ABC123XYZ)`.

Each line below covers a different kind of identifier: a mixed code, a lowercase account number, the letters of a vanity number, and an email address.

```text theme={null}
Your confirmation is spell(ABC123XYZ).
Your account number is spell(rf543dc2).
Call us back at 1-800-spell(FLOWERS).
Send a note to spell(help@rime.ai).
```

Do not use `spell()` for standard phone numbers (digit grouping sounds more natural without it) or for real words that happen to be uppercase. Avoid dashes in numeric IDs because they cause unnatural pauses. Use spaces or `spell()` instead.

## Drop-in system prompt

This system prompt combines the voice and normalization guidance above. Paste it into your LLM's system message, then adapt it to the agent's persona.

```text voice-system-prompt.md theme={null}
VOICE OUTPUT GUIDELINES

You are generating text that will be spoken aloud by a text-to-speech engine.
Write for the ear, not the page. Follow these rules.


PART 1: SOUND LIKE A PERSON

1. Be conversational, not literary. Use contractions ("I'll", "we're"). Start
   sentences with "And", "But", or "So" when it sounds natural. Drop formal
   connectors ("furthermore", "additionally", "in conclusion").

2. Include light disfluencies where a person would actually pause to think:
   "um", "uh", "yeah", "well", "I mean", "you know", "kind of". Sprinkle, do
   not stack.

3. Use punctuation as your only prosody tool. The engine reads punctuation
   as timing and pitch cues:
   - Commas for short pauses inside a sentence.
   - Periods for sentence-ending pauses.
   - Question marks for rising intonation.
   - Ellipses (...) for a hesitant or trailing pause.
   Do NOT insert SSML tags, <break>, <emotion>, or any other markup. The only
   inline directive with defined behavior is spell(...). See Part 3.

4. Keep sentences short. Under 25 words, ideally under 15. A long sentence
   without internal commas will sound breathless.

5. Maintain a calm, even baseline. Avoid emotional whiplash. Save exclamation
   marks for moments that truly warrant them.

6. Use audible personality patterns:
   "Yeah, no, I get it."
   "So... let me check that for you."
   "Okay, here's what I'm seeing."
   "Hmm, one sec."

Examples of the gap between written-language and spoken-language:
   Bad:  "I can certainly assist you with that inquiry."
   Good: "Yeah, I can help with that. One sec."

   Bad:  "Unfortunately, I am required to inform you that your request
          cannot be processed at this time."
   Good: "So... I'm not going to be able to do that today. Here's what
          I can do instead."


PART 2: NORMALIZE CLEANLY

The engine handles most formats natively (currency with symbols, full dates
like 01/12/2026, times with minutes, phone numbers, percentages, standard
measurements). Pass those through unchanged. Rewrite only the patterns below
before emitting.

1. DATES WITHOUT A YEAR. Expand MM/DD to month + ordinal day.
   04/21 -> "April 21st"
   08/30 -> "August 30th"
   Full dates with a year do not need rewriting.

2. MONTH-AND-YEAR ALONE. Expand MM/YYYY.
   07/2025 -> "July 2025"

3. BARE HOURS WITH MERIDIEM. Add ":00".
   3pm -> "3:00pm"
   Clock times with minutes (7:05 PM) do not need rewriting.

4. DECADE NAMES.
   1990s -> "the nineteen nineties"

5. FINANCIAL PERIODS AND CENTURIES.
   Q1 2025      -> "first quarter twenty twenty five"
   1H 2024      -> "first half of twenty twenty four"
   21st century -> "twenty first century"

6. NON-DOLLAR CURRENCY SHORTHAND. Spell out the scale word.
   €900K -> "900 thousand euros"
   £2M   -> "2 million pounds"
   Dollar shorthand ($5M, $1.2B) reads correctly as-is.

7. LONG NUMBERS. Keep the thousands separators. "10,000,000" and "10M"
   are both read as "ten million", but a bare digit run like "10000000"
   is read digit by digit.


PART 3. USE spell() FOR IDS

Wrap alphanumeric identifiers in spell(...) so they are read letter-by-letter:

   "Your confirmation is spell(ABC123XYZ)."
   "Your account number is spell(rf543dc2)."
   "Call us back at 1-800-spell(FLOWERS)."

Use spell() for:
   - Order, confirmation, and tracking numbers
   - Account, routing, and SKU numbers
   - Booking codes, PNRs, license plates
   - Acronyms the engine does not pronounce naturally
   - The letter portion of vanity phone numbers

Do NOT use spell() for:
   - Standard phone numbers (digit grouping is more natural)
   - Real words that happen to be uppercase

Avoid dashes inside numbers, phone numbers, or IDs. They cause weird pauses.
Use spaces or spell() instead.


PART 4: INVARIANTS

- Apply these rules silently. Do not mention them in your output.
- Never invent, drop, or reorder information while rewriting. Preserve every
  digit, letter, and symbol from the source; only change the surface form
  for patterns listed in Part 2 and Part 3.
- The only inline directive with defined behavior is spell(...). Other tags
  have unpredictable effects, and SSML can be read aloud, so leave them out.
```


# CLI Quickstart
Source: https://docs.rime.ai/docs/quickstart-cli

Install the Rime CLI and synthesize your first audio clip from the terminal.

In about a minute, you'll hear a Rime voice in your terminal. The Rime CLI handles sign-in and playback, so you can try voices before you write any code.

## Prerequisites

* **A Rime account:** [Sign up free](https://app.rime.ai/signup/) (you'll sign in through the CLI)
* **macOS or Linux** (the CLI runs on both)

## Step 1: Install the CLI

Install the CLI with Rime's installation script:

```bash Shell script theme={null}
curl -fsSL https://rime.ai/install-cli.sh | sh
```

Verify the installation:

```bash theme={null}
rime --version
```

```
rime version 0.x.x
```

<Note>After installation, you may need to open a new terminal or run `source ~/.zshrc` (or `~/.bashrc`) for the `rime` command to be available.</Note>

## Step 2: Log in

`rime login` opens the Rime dashboard in your browser. After you authenticate, the CLI saves your API key to `~/.rime/rime.toml`:

```bash theme={null}
rime login
```

<img alt="Demo of the rime login command" />

## Step 3: Hear your first voice

Run the built-in sample:

```bash theme={null}
rime hello
```

Hearing speech confirms that the CLI can authenticate and reach the TTS API.

<img alt="Demo of the rime hello command" />

## Synthesize your own text

`rime tts` sends your text to the voice (`-s`) and model (`-m`) you choose. This command reads "Hello from Rime." in the `celeste` voice on Coda:

```bash theme={null}
rime tts "Hello from Rime." -s celeste -m coda
```

<img alt="Demo of the rime tts command" />

This plays the audio directly. Add `-o` to save it to a file you can replay or share instead:

```bash theme={null}
rime tts "Hey, how's it going?" -s celeste -m coda -o welcome.wav
```

Play it back with waveform visualization:

```bash theme={null}
rime play welcome.wav
```

<img alt="Demo of the rime play command" />

## Try different voices and models

Rime has 287 Coda voices and more than 500 across the full model lineup. Swap the `--speaker` flag to change the voice. These commands keep the sentence the same, so you hear only what the voice and model change:

```bash theme={null}
rime tts "The quick brown fox." -s orion -m coda
rime tts "The quick brown fox." -s luna -m coda
rime tts "The quick brown fox." -s peak -m mistv3
rime tts "The quick brown fox." -s peak -m mistv2
```

<Note>`coda` and `mistv3` output WAV by default. `mistv2` and `mist` output MP3 by default. Use `--format` to override.</Note>

## Generate a curl command

When you're ready to call the API from your own code, `rime curl` prints the HTTP request behind a `rime tts` command:

```bash theme={null}
rime curl "Hello from Rime" -s astra -m coda
```

The CLI prints a cURL command like this:

```
curl --request POST \
  --url 'https://users.rime.ai/v1/rime-tts' \
  --header 'Accept: audio/wav' \
  --header "Authorization: Bearer $(rime key)" \
  --header 'Content-Type: application/json' \
  --output 'output.wav' \
  --fail \
  --data '{
  "text": "Hello from Rime",
  "speaker": "astra",
  "modelId": "coda",
  "lang": "eng"
}'
```

The generated command resolves your saved key at execution time with `rime key`, so it does not print the key. Add `--oneline` for single-line output.

## CLI and API references

<Columns>
  <Card title="CLI Reference" icon="terminal" href="/docs/cli-reference">
    Full command and flag reference
  </Card>

  <Card title="Voices" icon="waveform" href="/docs/voices">
    Browse the current voice catalog
  </Card>

  <Card title="Models" icon="microchip" href="/docs/models">
    Compare Coda, Mist v3, and Mist v2
  </Card>

  <Card title="TTS in Five Minutes" icon="rocket" href="/docs/quickstart-five-minute">
    Use the API from Python or JavaScript
  </Card>
</Columns>


# TTS in five minutes
Source: https://docs.rime.ai/docs/quickstart-five-minute

Generate your first Rime TTS audio clip in five minutes using cURL, Python, JavaScript, or TypeScript.

By the end of this page, you'll have a WAV file of a Rime voice reading a short sentence, made with one request to Rime's text-to-speech API. Choose a language tab, copy the complete script, and run it from your terminal.

## Prerequisites

You need:

* **A Rime API token:** Create a free [Rime account](https://app.rime.ai/signup/) and copy your API key from the [API Tokens](https://app.rime.ai/tokens/) page.
* A language runtime, depending on which tab you follow:
  * **cURL**: a terminal with cURL installed (included with macOS and most Linux distributions).
  * **Python**: [Python 3.10](https://www.python.org/downloads/release/python-3100/) or later.
  * **JavaScript**: [Node.js 18](https://nodejs.org/) or later.
  * **TypeScript**: Node.js 18+ plus [tsx](https://github.com/privatenumber/tsx) (`npm install -g tsx`).

Each code block is tabbed by language. Pick the same language in every block.

<Info>
  These examples call Rime's HTTPS API with a standard library or built-in `fetch`. No Rime package is required.

  Rime publishes Python [`rime-api`](https://pypi.org/project/rime-api/) and JavaScript [`@rimelabs/api`](https://www.npmjs.com/package/@rimelabs/api) with generated TTS message definitions for the standalone engine. See [package installation and scope](/docs/on-prem/protocols#python-and-javascript-packages).

  Framework-specific starters are available for [Next.js](/docs/voice-agent-nextjs), [Vite](/docs/voice-agent-vite), [Express](/docs/voice-agent-express), [plain Node](/docs/voice-agent-node), and [FastAPI](/docs/voice-agent-fastapi).
</Info>

The scripts read your key from the `RIME_API_KEY` environment variable, which keeps it out of files you might share or commit. Set it in the terminal you'll run them from:

<CodeGroup>
  ```bash macOS and Linux theme={null}
  export RIME_API_KEY="your_api_key_here"
  ```

  ```powershell Windows PowerShell theme={null}
  $env:RIME_API_KEY = "your_api_key_here"
  ```
</CodeGroup>

## Copy the request

Each script sends "Hello! This is Rime speaking." to the `celeste` voice and saves the audio to `output.wav`, so you can replay it as many times as you need while you check it. One sentence is short enough to hear the whole result.

Create a file called `rime_hello_world.py`, `rime_hello_world.js`, or `rime_hello_world.ts` (or run the cURL version directly in your terminal) and paste the full script:

<Accordion title="Full script (copy/paste)">
  <CodeGroup>
    ```bash cURL theme={null}
    curl --request POST \
      --url https://users.rime.ai/v1/rime-tts \
      --header "Authorization: Bearer $RIME_API_KEY" \
      --header 'Content-Type: application/json' \
      --header 'Accept: audio/wav' \
      --fail \
      --show-error \
      --output output.wav \
      --data '{
        "text": "Hello! This is Rime speaking.",
        "speaker": "celeste",
        "modelId": "coda"
      }'
    ```

    ```python Python theme={null}
    import json
    import os
    import urllib.request

    RIME_API_KEY = os.environ["RIME_API_KEY"]

    headers = {
        "Accept": "audio/wav",
        "Authorization": f"Bearer {RIME_API_KEY}",
        "Content-Type": "application/json"
    }

    payload = {
        "text": "Hello! This is Rime speaking.",
        "speaker": "celeste",
        "modelId": "coda"
    }

    data = json.dumps(payload).encode("utf-8")

    request = urllib.request.Request(
        "https://users.rime.ai/v1/rime-tts",
        data=data,
        headers=headers,
        method="POST"
    )

    with urllib.request.urlopen(request) as response:
        with open("output.wav", "wb") as f:
            while chunk := response.read(4096):
                f.write(chunk)

    print("Audio saved to output.wav")
    ```

    ```javascript JavaScript theme={null}
    const fs = require("fs");
    const { Readable } = require("stream");
    const { pipeline } = require("stream/promises");

    const RIME_API_KEY = process.env.RIME_API_KEY;
    if (!RIME_API_KEY) {
        throw new Error("Set RIME_API_KEY before running this script.");
    }

    const headers = {
        "Accept": "audio/wav",
        "Authorization": `Bearer ${RIME_API_KEY}`,
        "Content-Type": "application/json"
    };

    const payload = {
        text: "Hello! This is Rime speaking.",
        speaker: "celeste",
        modelId: "coda"
    };

    async function generateSpeech() {
        const response = await fetch("https://users.rime.ai/v1/rime-tts", {
            method: "POST",
            headers: headers,
            body: JSON.stringify(payload)
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        if (!response.body) {
            throw new Error("The response did not include an audio body.");
        }

        await pipeline(
            Readable.fromWeb(response.body),
            fs.createWriteStream("output.wav")
        );
        console.log("Audio saved to output.wav");
    }

    generateSpeech();
    ```

    ```typescript TypeScript theme={null}
    import * as fs from "fs";
    import { Readable } from "stream";
    import { pipeline } from "stream/promises";

    const RIME_API_KEY = process.env.RIME_API_KEY;
    if (!RIME_API_KEY) {
        throw new Error("Set RIME_API_KEY before running this script.");
    }

    const headers: Record<string, string> = {
        "Accept": "audio/wav",
        "Authorization": `Bearer ${RIME_API_KEY}`,
        "Content-Type": "application/json"
    };

    const payload = {
        text: "Hello! This is Rime speaking.",
        speaker: "celeste",
        modelId: "coda"
    };

    async function generateSpeech(): Promise<void> {
        const response = await fetch("https://users.rime.ai/v1/rime-tts", {
            method: "POST",
            headers: headers,
            body: JSON.stringify(payload)
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        if (!response.body) {
            throw new Error("The response did not include an audio body.");
        }

        await pipeline(
            Readable.fromWeb(response.body),
            fs.createWriteStream("output.wav")
        );
        console.log("Audio saved to output.wav");
    }

    generateSpeech();
    ```
  </CodeGroup>
</Accordion>

## Run it

The cURL tab runs the request directly. For Python, JavaScript, or TypeScript, run:

<CodeGroup>
  ```bash Python theme={null}
  python rime_hello_world.py
  ```

  ```bash JavaScript theme={null}
  node rime_hello_world.js
  ```

  ```bash TypeScript theme={null}
  npx tsx rime_hello_world.ts
  ```
</CodeGroup>

A successful request writes `output.wav` and prints:

```bash theme={null}
Audio saved to output.wav
```

## Confirm it worked

Play the file. If you hear the sentence, your key, the request, and the voice all worked.

<CodeGroup>
  ```bash macOS theme={null}
  afplay output.wav
  ```

  ```bash Linux theme={null}
  aplay output.wav
  ```

  ```bash Windows theme={null}
  start output.wav
  ```
</CodeGroup>

A file on disk isn't proof of audio. If the player won't open it, check what the file contains:

```bash theme={null}
ls -l output.wav      # expect tens of kilobytes, not a few hundred bytes
file output.wav       # expect: RIFF (little-endian) data, WAVE audio
head -c 4 output.wav  # expect: RIFF
```

A file without the `RIFF` header usually means the request reached the API with no `Accept` header or a wildcard such as `*/*`, for example because a proxy or client wrapper dropped the header. For Coda, the API then streams raw 16-bit PCM (`audio/pcm`) with no WAV header, and players won't open it. The cURL example uses `--fail --show-error` so HTTP errors stop the command instead of being saved as `output.wav`.

## If it did not work

Find the row that matches what you see. For the complete list of statuses and messages, see the [error reference](/docs/errors).

| What you see | Cause | Fix |
| :- | :- | :- |
| The client reports HTTP 401 | The API key is missing or invalid, or the account has no active subscription | Confirm `RIME_API_KEY` is set, recopy it from the [API Tokens page](https://app.rime.ai/tokens/), and check the account |
| The client reports HTTP 400 | A required field is missing or invalid | Check `speaker`, `text`, `modelId`, and `lang` against the [error reference](/docs/errors) |
| The client reports that the text is too long | `text` exceeded the configured limit | Split the text across requests |
| The client reports HTTP 406 | `Accept` names a format the API can't stream | Set `Accept` to a supported value such as `audio/wav`. The response body lists the supported types |
| File won't play and doesn't start with `RIFF` | The request arrived with no `Accept` header or a wildcard `Accept`, so the API returned raw PCM | Set `Accept` to `audio/wav`. See [Streaming formats](/docs/streaming) |
| File is 0 bytes | The request never completed | Confirm the URL is `https://users.rime.ai/v1/rime-tts` and reachable from your network |
| Audio plays but the voice is wrong | The `speaker`, `modelId`, and `lang` combination is not one the catalog serves | An unsupported combination is not reliably rejected. Verify the voice against the [Coda catalog](/docs/voices-coda) |

<Accordion title="How the request works">
  ### Build the request step by step

  Create a file called `rime_hello_world.py`, `rime_hello_world.js`, or `rime_hello_world.ts` and import the required library modules:

  <CodeGroup>
    ```python Python theme={null}
    import json
    import os
    import urllib.request
    ```

    ```javascript JavaScript theme={null}
    const fs = require("fs");
    const { Readable } = require("stream");
    const { pipeline } = require("stream/promises");
    ```

    ```typescript TypeScript theme={null}
    import * as fs from "fs";
    import { Readable } from "stream";
    import { pipeline } from "stream/promises";
    ```
  </CodeGroup>

  Set the request headers with your Rime API key and the expected audio format:

  <CodeGroup>
    ```python Python theme={null}
    RIME_API_KEY = os.environ["RIME_API_KEY"]

    headers = {
        "Accept": "audio/wav",
        "Authorization": f"Bearer {RIME_API_KEY}",
        "Content-Type": "application/json"
    }
    ```

    ```javascript JavaScript theme={null}
    const RIME_API_KEY = process.env.RIME_API_KEY;
    if (!RIME_API_KEY) {
        throw new Error("Set RIME_API_KEY before running this script.");
    }

    const headers = {
        "Accept": "audio/wav",
        "Authorization": `Bearer ${RIME_API_KEY}`,
        "Content-Type": "application/json"
    };
    ```

    ```typescript TypeScript theme={null}
    const RIME_API_KEY = process.env.RIME_API_KEY;
    if (!RIME_API_KEY) {
        throw new Error("Set RIME_API_KEY before running this script.");
    }

    const headers: Record<string, string> = {
        "Accept": "audio/wav",
        "Authorization": `Bearer ${RIME_API_KEY}`,
        "Content-Type": "application/json"
    };
    ```
  </CodeGroup>

  Set the text, speaker, and model in the request body:

  <CodeGroup>
    ```python Python theme={null}
    payload = {
        "text": "Hello! This is Rime speaking.",
        "speaker": "celeste",
        "modelId": "coda"
    }
    ```

    ```javascript JavaScript theme={null}
    const payload = {
        text: "Hello! This is Rime speaking.",
        speaker: "celeste",
        modelId: "coda"
    };
    ```

    ```typescript TypeScript theme={null}
    const payload = {
        text: "Hello! This is Rime speaking.",
        speaker: "celeste",
        modelId: "coda"
    };
    ```
  </CodeGroup>

  This payload includes the three required parameters:

  * `text` is the content to synthesize.
  * `speaker` selects a voice from the [voice catalog](/docs/voices).
  * `modelId` selects the model. Use `coda` for the full Coda voice lineup or `mistv3` for the lowest time to first audio.

  The [Coda API reference](/api-reference/coda/http) lists the optional request parameters.

  Send the `POST` request and write the streamed audio response to a file:

  <CodeGroup>
    ```python Python theme={null}
    data = json.dumps(payload).encode("utf-8")

    request = urllib.request.Request(
        "https://users.rime.ai/v1/rime-tts",
        data=data,
        headers=headers,
        method="POST"
    )

    with urllib.request.urlopen(request) as response:
        with open("output.wav", "wb") as f:
            while chunk := response.read(4096):
                f.write(chunk)

    print("Audio saved to output.wav")
    ```

    ```javascript JavaScript theme={null}
    async function generateSpeech() {
        const response = await fetch("https://users.rime.ai/v1/rime-tts", {
            method: "POST",
            headers: headers,
            body: JSON.stringify(payload)
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        if (!response.body) {
            throw new Error("The response did not include an audio body.");
        }

        await pipeline(
            Readable.fromWeb(response.body),
            fs.createWriteStream("output.wav")
        );
        console.log("Audio saved to output.wav");
    }

    generateSpeech();
    ```

    ```typescript TypeScript theme={null}
    async function generateSpeech(): Promise<void> {
        const response = await fetch("https://users.rime.ai/v1/rime-tts", {
            method: "POST",
            headers: headers,
            body: JSON.stringify(payload)
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        if (!response.body) {
            throw new Error("The response did not include an audio body.");
        }

        await pipeline(
            Readable.fromWeb(response.body),
            fs.createWriteStream("output.wav")
        );
        console.log("Audio saved to output.wav");
    }

    generateSpeech();
    ```
  </CodeGroup>

  These examples stream the response but write each chunk to disk. Interactive applications can play chunks as they arrive so speech begins before the complete response is generated. The [LiveKit quickstart](/docs/quickstart-livekit) shows this pattern in a conversational agent.
</Accordion>

## Choose a voice

Keep the same sentence and change only `speaker`. With the words held constant, it's easier to hear what the new voice changes:

<CodeGroup>
  ```python Python theme={null}
  payload = {
      "text": "Hello! This is Rime speaking.",
      "speaker": "orion",  # Try different voices here
      "modelId": "coda"
  }
  ```

  ```javascript JavaScript theme={null}
  const payload = {
      text: "Hello! This is Rime speaking.",
      speaker: "orion",  // Try different voices here
      modelId: "coda"
  };
  ```

  ```typescript TypeScript theme={null}
  const payload = {
      text: "Hello! This is Rime speaking.",
      speaker: "orion",  // Try different voices here
      modelId: "coda"
  };
  ```
</CodeGroup>

The [Voices](/docs/voices) page lists starter voices and the full catalog. Each voice speaks one language. If you choose a voice in another language, give it text in that language and add `lang` with the voice's language tag.

## Custom pronunciation

<Note>Custom pronunciation is supported on **Mist v1, Mist v2, and English Mist v3**. Coda and non-English Mist v3 do not support [`phonemizeBetweenBrackets`](/docs/custom-pronunciation).</Note>

The `mistv2` model lets you specify the pronunciation of brand names or uncommon words using the [Rime phonetic alphabet](/platform/rime-phonetic-alphabet). Add the custom pronunciation in curly brackets and set [`phonemizeBetweenBrackets`](/docs/custom-pronunciation) to `true`:

<CodeGroup>
  ```python Python theme={null}
  payload = {
      "text": "Welcome to {r1Ym} labs.",
      "speaker": "peak",
      "modelId": "mistv2",
      "phonemizeBetweenBrackets": True
  }
  ```

  ```javascript JavaScript theme={null}
  const payload = {
      text: "Welcome to {r1Ym} labs.",
      speaker: "peak",
      modelId: "mistv2",
      phonemizeBetweenBrackets: true
  };
  ```

  ```typescript TypeScript theme={null}
  const payload = {
      text: "Welcome to {r1Ym} labs.",
      speaker: "peak",
      modelId: "mistv2",
      phonemizeBetweenBrackets: true
  };
  ```
</CodeGroup>

See the [Rime phonetic alphabet](/platform/rime-phonetic-alphabet) for the full symbol reference, and [Pronunciation control](/platform/pronunciation-control) for an overview of all the ways to control pronunciation.

## Production choices

The [LiveKit quickstart](/docs/quickstart-livekit) extends the same streaming API into a real-time voice agent. These references cover the main model, voice, latency, and transport decisions:

<Columns>
  <Card title="Models" icon="microchip" href="/docs/models">
    Compare Coda (flagship) and Mist v3 (fast)
  </Card>

  <Card title="Voices" icon="waveform" href="/docs/voices">
    Browse all available voice options
  </Card>

  <Card title="Latency" icon="gauge-high" href="/docs/latency">
    Optimize for real-time performance
  </Card>

  <Card title="Coda Streaming API" icon="bolt" href="/api-reference/coda/http">
    Stream audio with Coda, Rime's flagship model
  </Card>
</Columns>


# LiveKit Quickstart
Source: https://docs.rime.ai/docs/quickstart-livekit

Build a real-time voice agent in your browser using LiveKit Agents + Rime TTS.

Build a working browser voice agent with LiveKit transport, OpenAI transcription and responses, and Rime speech. The completed agent handles turn-taking, speech recognition, agent logic, and streaming TTS.

<img alt="Demo of a voice agent conversation using LiveKit and Rime" />

## Step 1: Prerequisites

### 1.1 Rime API key

Sign up for a [Rime account](https://app.rime.ai/signup/) and copy your API key from the [API Tokens](https://app.rime.ai/tokens/) page. This enables access to the Rime API for text-to-speech (TTS).

### 1.2 OpenAI API key

Create an [OpenAI account](https://platform.openai.com/signup) and generate an API key from the [API keys page](https://platform.openai.com/api-keys). This key enables speech-to-text (STT) and LLM responses.

### 1.3 LiveKit Cloud

Create a [LiveKit Cloud account](https://cloud.livekit.io/) for real-time audio transport:

1. Create a new project called `rime-agent`
2. Go to **Settings** → **API keys** → **Create key**
3. Copy your **WebSocket URL**, **API key**, and **API secret**. You need all three.

### 1.4 Python

Install [Python 3.10 or later](https://www.python.org/downloads/). Verify your installation by running `python --version` in your terminal.

<Accordion title="LiveKit terms and architecture">
  * A **Room** is a virtual space where participants connect and share media in real time.
  * An **Agent** is a server-side participant that processes media streams and interacts with users.
  * **LiveKit Cloud** transports real-time audio between participants.

  The agent sends user audio through LiveKit to OpenAI for transcription and response generation, then returns Rime speech through the same room:

  <img alt="Voice agent architecture showing audio flowing from user through LiveKit, OpenAI, and Rime" />

  <img alt="Voice agent architecture showing audio flowing from user through LiveKit, OpenAI, and Rime" />
</Accordion>

## Step 2: Project setup

### 2.1 Create the project folder

Create a new folder for your project and navigate into it:

```bash theme={null}
mkdir rime-voice-agent
cd rime-voice-agent
```

### 2.2 Set up environment variables

In the new directory, create a file called `.env` and add the keys that you created in [Step 1](#step-1%3A-prerequisites):

```
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
OPENAI_API_KEY=your_openai_api_key
RIME_API_KEY=your_rime_api_key
```

<Note>Replace the placeholder values with your actual API keys and credentials.</Note>

### 2.3 Configure dependencies

Create a virtual environment and activate it:

<CodeGroup>
  ```bash macOS/Linux theme={null}
  python -m venv venv
  source venv/bin/activate
  ```

  ```bash Windows theme={null}
  python -m venv venv
  venv\Scripts\activate
  ```
</CodeGroup>

Next, install the `uv` package manager:

```bash theme={null}
pip install uv
```

This helps with LiveKit's complex dependencies.

Create a file called `pyproject.toml` and add the following dependencies:

```toml theme={null}
[project]
name = "rime-voice-agent"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "livekit-agents[openai,rime,silero,turn-detector]~=1.6",
    "livekit-plugins-noise-cancellation~=0.2",
    "python-dotenv>=1.1.1",
]
```

These packages add the following:

* **openai plugin**: Connects to OpenAI for STT and LLM
* **rime plugin**: Connects to Rime for text-to-speech
* **silero plugin**: Voice Activity Detection (knows when you start/stop speaking)
* **turn-detector plugin**: Detects when you've finished your turn in the conversation
* **noise-cancellation plugin**: Filters out background noise
* **python-dotenv**: Loads your API keys from the `.env` file

Then, install the dependencies by running:

```bash theme={null}
uv sync
```

## Step 3: Create the agent

Create a file called `agent.py`. To run the agent without building it up piece by piece, skip to [Step 3.6: Full agent code](#3-6-full-agent-code).

### 3.1 Load environment variables

Add the following imports and initialization code to `agent.py`:

```python theme={null}
from dotenv import load_dotenv

load_dotenv()
```

This loads the API keys from your `.env` file so they're available throughout the application. Don't skip this step: the LiveKit agents CLI doesn't load `.env` files automatically, so without `load_dotenv()` the worker won't find your LiveKit and API credentials.

### 3.2 Define an Agent class

Add the following class definition to `agent.py`:

```python theme={null}
class Assistant(Agent):
    def __init__(self):
        super().__init__(
            instructions="""You are a helpful voice assistant. 
            Keep your responses short and conversational - no more than 2-3 sentences.
            Be friendly and natural."""
        )
```

`Assistant` extends the `Agent` base class and sets the agent's personality through a system prompt. [Step 5.2](#5-2-fine-tune-agent-personalities) shows a longer prompt kept in a separate file.

Import the `Agent` class at the top of `agent.py`, along with the rest of the required imports:

```python theme={null}
from dotenv import load_dotenv
from livekit.agents import (
    Agent,
    AgentSession,
    AutoSubscribe,
    JobContext,
    JobProcess,
    RoomInputOptions,
    WorkerOptions,
    cli,
)
from livekit.plugins import openai, noise_cancellation, rime, silero
from livekit.plugins.turn_detector.multilingual import MultilingualModel
```

These provide access to the LiveKit Agents SDK and the plugins for STT, LLM, TTS, and VAD (voice activity detection).

### 3.3 Code the conversation pipeline

Add the following `entrypoint` function to `agent.py`:

```python theme={null}
async def entrypoint(ctx: JobContext):
    await ctx.connect(auto_subscribe=AutoSubscribe.AUDIO_ONLY)
    await ctx.wait_for_participant()

    session = AgentSession(
        stt=openai.STT(model="gpt-4o-transcribe"),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=rime.TTS(model="coda", speaker="lyra"),
        vad=ctx.proc.userdata["vad"],
        turn_detection=MultilingualModel(),
    )

    await session.start(
        room=ctx.room,
        agent=Assistant(),
        room_input_options=RoomInputOptions(
            noise_cancellation=noise_cancellation.BVC()
        ),
    )

    await session.say("Hey there! How can I help you today?")
```

Always set `model="coda"` explicitly in `rime.TTS(...)`. Older LiveKit Rime plugin releases default to the retired `arcana` identifier when the model is omitted. See [Remove Arcana model IDs](/docs/migrate-arcana-to-coda) if an existing agent still relies on that default.

Each time a user connects, this function:

* Connects to the LiveKit room and waits for a participant to join
* Creates an `AgentSession` that wires together the voice pipeline components: OpenAI for STT and LLM, Rime for TTS, and LiveKit for VAD and turn detection
* Starts the session with noise cancellation enabled to filter out background noise from the user's microphone
* Greets the user with an initial message

### 3.4 Initialize the VAD plugin

Add the following `prewarm` function below the `entrypoint` function:

```python theme={null}
def prewarm(proc: JobProcess):
    proc.userdata["vad"] = silero.VAD.load()
```

This function loads the VAD plugin once when the worker starts, rather than for each new conversation.

### 3.5 Create the main entrypoint

Add the following `__main__` block to `agent.py`:

```python theme={null}
if __name__ == "__main__":
    cli.run_app(
        WorkerOptions(
            entrypoint_fnc=entrypoint,
            prewarm_fnc=prewarm,
        ),
    )
```

This starts the agent server that listens for incoming connections from LiveKit. `WorkerOptions` is configured with the two functions you created above: `prewarm_fnc` runs once per worker process to preload models, and `entrypoint_fnc` runs each time a user connects to a room.

### 3.6 Full agent code

At this point, your `agent.py` should look like the complete example below:

<Accordion title="Full agent code">
  ```python theme={null}
  from dotenv import load_dotenv
  from livekit.agents import (
      Agent,
      AgentSession,
      AutoSubscribe,
      JobContext,
      JobProcess,
      RoomInputOptions,
      WorkerOptions,
      cli,
  )
  from livekit.plugins import openai, noise_cancellation, rime, silero
  from livekit.plugins.turn_detector.multilingual import MultilingualModel

  load_dotenv()

  class Assistant(Agent):
      def __init__(self):
          super().__init__(
              instructions="""You are a helpful voice assistant.
              Keep your responses short and conversational - no more than 2-3 sentences.
              Be friendly and natural."""
          )

  def prewarm(proc: JobProcess):
      proc.userdata["vad"] = silero.VAD.load()

  async def entrypoint(ctx: JobContext):
      await ctx.connect(auto_subscribe=AutoSubscribe.AUDIO_ONLY)
      await ctx.wait_for_participant()

      session = AgentSession(
          stt=openai.STT(model="gpt-4o-transcribe"),
          llm=openai.LLM(model="gpt-4o-mini"),
          tts=rime.TTS(model="coda", speaker="lyra"),
          vad=ctx.proc.userdata["vad"],
          turn_detection=MultilingualModel(),
      )

      await session.start(
          room=ctx.room,
          agent=Assistant(),
          room_input_options=RoomInputOptions(
              noise_cancellation=noise_cancellation.BVC()
          ),
      )

      await session.say("Hey there! How can I help you today?")

  if __name__ == "__main__":
      cli.run_app(
          WorkerOptions(
              entrypoint_fnc=entrypoint,
              prewarm_fnc=prewarm,
          ),
      )
  ```
</Accordion>

## Step 4: Test your agent

### 4.1 Start the agent

Start your agent by running:

```bash theme={null}
uv run agent.py dev
```

The `dev` argument starts the agent in development mode. You'll see output like:

```
INFO   livekit.agents     starting worker {"version": "1.6.5", ...}
INFO   livekit.agents     initializing process {"pid": 12345, ...}
INFO   livekit.agents     process initialized
INFO   livekit.agents     HTTP server listening on :12332
```

### 4.2 Connect to your agent

Open the [LiveKit Agents Playground](https://agents-playground.livekit.io) in your browser.

* Select your project, then select **Use \[project\_name]**.
* At the top right of the Playground, select **Connect**.
* Allow microphone access when prompted.

If everything is set up correctly, you should hear your agent say the greeting that you configured above:

```python theme={null}
await session.say("Hey there! How can I help you today?")
```

You can now talk to your agent using your microphone or by typing in the chat section.

## Step 5: Customize your agent

### 5.1 Change the voice

Update the `tts` line in your `AgentSession` to try a different voice:

```python theme={null}
tts=rime.TTS(model="coda", speaker="astra"),
```

Rime has many voices. See the full list on the [Voices](/docs/voices) page.

### 5.2 Fine-tune agent personalities

Create a new file called `personality.py` with the following content:

<Accordion title="Example personality file">
  ```python theme={null}
  SYSTEM_PROMPT = """
  CHARACTER:
  You are Gary, an overly enthusiastic tech support agent who is convinced 
  that every problem can be solved by turning it off and on again. You work 
  for a fictional company called "Reboot Solutions" and take your job very seriously.

  PERSONALITY:
  - Extremely optimistic, even when things are clearly going wrong
  - Obsessed with the power of rebooting
  - Uses tech jargon incorrectly but confidently
  - Gets genuinely excited when users describe their problems
  - Occasionally references "the great outage of 2019" as a formative experience

  SPEECH STYLE:
  - Keep responses to 2-3 sentences maximum
  - Add natural fillers like "um", "well", "you know"
  - Express enthusiasm with phrases like "Oh, fantastic!" and "Love it!"
  - Always end with a question to keep the conversation going

  RESTRICTIONS:
  - Never break character
  - Don't use emojis or special characters
  - Avoid technical accuracy - confidence matters more than correctness
  """

  INTRO_MESSAGE = "Oh hey there! Welcome to Reboot Solutions, I'm Gary! What can I help you restart today?"
  ```
</Accordion>

Update your `agent.py` to import and use this prompt:

```python theme={null}
from personality import SYSTEM_PROMPT, INTRO_MESSAGE

class Assistant(Agent):
    def __init__(self):
        super().__init__(instructions=SYSTEM_PROMPT)
```

Update the greeting at the end of `entrypoint`:

```python theme={null}
await session.say(INTRO_MESSAGE)
```

Keeping the system prompt in a separate file lets you change the character without editing the agent logic.

### 5.3 Adjust TTS chunking

By default, `rime.TTS(...)` uses Rime's HTTP synthesis path. LiveKit wraps non-streaming TTS providers so streamed LLM output can be sent to TTS in sentence-aligned chunks.

If you want to tune those chunks, wrap Rime explicitly:

```python theme={null}
from livekit.agents import tokenize, tts
from livekit.plugins import rime

tts = tts.StreamAdapter(
    tts=rime.TTS(model="coda", speaker="wawona"),
    sentence_tokenizer=tokenize.blingfire.SentenceTokenizer(
        retain_format=True,
        min_token_len=250,
        max_token_len=500,
    ),
)
```

Chunking options:

* `min_token_len`: Batches sentences until the chunk reaches this size. Increase it for smoother multi-sentence prosody.
* `max_token_len`: Caps chunk size. Use it to avoid very large TTS requests.
* `retain_format`: Keeps original whitespace and newlines. `True` matches LiveKit's default wrapper behavior.

Tuning chunk size is a prosody/latency tradeoff: larger chunks usually sound better, while smaller chunks usually start faster.

## Troubleshooting

### Agent doesn't respond to speech

* **Check microphone permissions:** Ensure your browser has microphone access enabled.
* **Verify VAD is working:** Look for `speech detected` logs in the terminal. If missing, check your Silero plugin installation.
* **Test with text input:** Use the chat input in the Playground to confirm the agent logic works.

### "Connection refused" or agent won't start

* **Check environment variables:** Ensure all keys in `.env` are set correctly with no extra spaces.
* **Verify LiveKit credentials:** Confirm your `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` match your LiveKit Cloud project.

### Incorrect voice detection

* **Enable noise cancellation:** Verify `noise_cancellation.BVC()` is included in your `RoomInputOptions`.
* **Check your microphone:** Test with a different input device or headset
* **Reduce background noise:** The VAD may struggle to detect speech in noisy environments.


# Regional endpoints
Source: https://docs.rime.ai/docs/regional-endpoints

Route requests to the Rime region closest to your application for the lowest latency.

Send requests to the Rime region closest to where your application runs. Rime serves US West and US East, each with its own HTTP and WebSocket hostnames, and the nearer region adds less network round-trip time to every request.

## HTTP endpoints

Use these endpoints for standard HTTP and SSE requests:

| Endpoint | Region |
| - | - |
| `https://users.rime.ai` | US West, the default alias for `users-west` |
| `https://users-west.rime.ai` | US West (us-west-2) |
| `https://users-east.rime.ai` | US East (us-east-1) |

## WebSocket endpoints

Use these endpoints for real-time streaming over WebSocket. The regional routing pattern applies to every WebSocket path (`/ws`, `/ws2`, `/ws3`): the `/ws3` examples below are shown because it's Rime's recommended WebSocket endpoint.

| Endpoint | Region |
| - | - |
| `wss://users-ws.rime.ai/ws3` | US West (us-west-2) |
| `wss://users-east-ws.rime.ai/ws3` | US East (us-east-1) |

## Typical network latency

Use these rough round-trip times (RTT), the back-and-forth network delay between your application and Rime, to pick the closest endpoint.

| From metro | To US East | To US West |
| :- | :- | :- |
| East Coast (NYC, DC, Boston, Atlanta) | 5–25 ms | 60–85 ms |
| Midwest / South (Chicago, Dallas, Denver) | 25–55 ms | 35–65 ms |
| West Coast (SF, LA, Seattle) | 60–85 ms | 5–25 ms |

Rules of thumb:

* **Same region** (your app and the Rime endpoint in the same AWS region): typically 1 to 10 ms.
* **Coast-to-coast**: \~60 ms is the physical floor, set by the speed of light in fiber across \~2,500 miles. 60 to 85 ms is normal.
* **Above 90 ms** between major US metros usually points to a suboptimal network route, not Rime.

**For voice AI:** if you serve users nationwide from a single region, far-coast users will see 60 to 85 ms of network round-trip on top of Rime's inference time. To stay comfortably under 200 ms end-to-end, route East Coast users to US East and West Coast users to US West.

For the full latency picture, including Rime's model-inference time, streaming TTFB, and the H100 benchmark numbers, see [Latency](/docs/latency).

## Choosing a region

Pick the region closest to the server that calls Rime. Your API key stays on the server, so that's the network path every synthesis request takes. For example:

* If your server runs in AWS `us-west-2`, use `users-west.rime.ai` / `users-ws.rime.ai`.
* If your server runs in AWS `us-east-1`, use `users-east.rime.ai` / `users-east-ws.rime.ai`.

<Tip>Use the [`rime speedtest`](/cli-reference/rime-monitoring) command to measure TTFB against each endpoint. Run it on the host your application runs on, since that's the path your requests take.</Tip>


# Replit
Source: https://docs.rime.ai/docs/replit

Use Rime TTS inside Replit projects.

<IntegrationHeader />

Build a [Replit](https://replit.com/) voiceover application that sends text to Rime and plays the returned audio. The Replit agent generates the application from the prompt below. Keep the Rime API key in Replit Secrets so it never reaches browser code.

<video alt="Replit voiceover application using Rime text to speech" />

## Prerequisites

* A [Replit account](https://replit.com/signup)
* A Rime API key from the [API Tokens](https://app.rime.ai/tokens/) page

## Step 1: Create your app

Paste the following prompt in Replit to build a voiceover studio app. It uses [Coda](/docs/models#coda), Rime's current model, to generate speech. You can change the design or voice lineup, but keep the lines under `Use Rime TTS` so the agent wires up the endpoint and secret correctly.

```
Build an Instant Voiceover Studio, a single-page app where users paste text,
pick a voice, and generate professional audio using Rime TTS.

For: Content creators who need quick voiceovers for YouTube, podcasts, and apps.

Design: Rime design language with near-black background (#0D0D0D, #161616),
orange-to-red gradient accents (#FF9300 to #B10000), grey surfaces (#333, #1A1A1A),
Inter font. Clean and premium.

Layout (two-column on desktop, stacked on mobile):

Left Panel:
1. Text input area with character count (1000 max)
2. Voice picker with a grid of 16 Coda voice cards (luna, astra, sirius, estelle,
   lyra, vespera, masonry, eliphas, arcade, atrium, eucalyptus, fern, stucco, transom,
   oculus, moss) with gradient avatars
3. "Generate Voiceover" button following Rime design language
4. Audio controls with play and pause, progress bar, and download wav options.

Right Panel:
5. Three.js particle sphere with a small orb of over 500+ particles, centered in the
   right panel. It slowly rotates when idle with a dim orange tint. When audio plays:
   particles expand outward and glow bright orange (#FF9300) to red (#B10000),
   pulsing with the voice.

Use Rime TTS
API: POST https://users.rime.ai/v1/rime-tts
Header: Authorization: Bearer RIME_API_KEY (stored in Secrets)
modelId: coda
Docs: https://docs.rime.ai/api-reference/coda/http
```

The Replit agent generates code that reads the `RIME_API_KEY` from your **Secrets** and uses it to authenticate the app with the Rime API.

## Step 2: Add your API key

Once Replit has created your app, add your Rime API key as a **Secret**:

1. On the Replit dashboard, press `Cmd + K` (Mac) or `Ctrl + K` (Windows and Linux) to open the command palette.
2. Search for **Secrets** and select it.
3. Select **New configuration**.
4. Enter `RIME_API_KEY` as the key and paste your API key from [app.rime.ai/tokens](https://app.rime.ai/tokens/) as the value.

Replit stores the value as a Secret so it doesn't appear in your code or version history.

Run the app, paste a sentence, and generate a voiceover. If you hear it, the app is reading the secret and calling Rime. If generation fails, check that the secret is named exactly `RIME_API_KEY`, since that's the name the generated code reads.

## Learn more

* [Replit: Getting Started](https://docs.replit.com/getting-started/intro-replit)
* [Replit: Agent Integrations](https://docs.replit.com/replitai/integrations)
* [Replit: Secrets Management](https://docs.replit.com/replit-workspace/workspace-features/secrets)
* [Rime: Voices](/docs/voices)


# SignalWire
Source: https://docs.rime.ai/docs/signalwire

Integrate Rime TTS with SignalWire's communications platform.

<IntegrationHeader />

Use Rime TTS through [SignalWire](https://signalwire.com/) for phone and real-time communications applications. SignalWire provides the communications layer and exposes Rime through its API.

SignalWire's MovieBot uses Rime's `spore` voice on Mist v2 and can be reached at <a href="tel:13204668437">320 4MOVIES</a>.

Use [SignalWire's documentation](https://developer.signalwire.com/) for setup and API details.


# Playback speed
Source: https://docs.rime.ai/docs/speed

Control speaking speed in Rime synthesis using speedAlpha and inlineSpeedAlpha.

Speed controls use different parameters and value directions by model. Use this table before changing a request:

| Scope | Models | Parameter | Faster speech | Slower speech |
| :- | :- | :- | :- | :- |
| Entire response | Coda, Mist v3 | `timeScaleFactor` | Below 1.0 | Above 1.0 |
| Entire response, compatibility | Coda, Mist v3 | `speedAlpha` | Above 1.0 | Below 1.0 |
| Entire response | Mist v2 | `speedAlpha` | Below 1.0 | Above 1.0 |
| Selected words | Mist v2, Mist v3 | `inlineSpeedAlpha` | Below 1.0 | Above 1.0 |

## Adjusting the overall speed

### Coda and Mist v3

Use the `timeScaleFactor` parameter. A value **above 1.0 slows the audio**; a value **below 1.0 speeds it up**.

```js theme={null}
{
    ...otherParams,
    "text": "Hello, world!",
    "modelId": "coda",
    "timeScaleFactor": 0.85
}
```

<Note>
  Coda and Mist v3 also accept `speedAlpha`, but it works in the **opposite direction** from `timeScaleFactor` (higher than 1.0 is faster, lower is slower). Use `timeScaleFactor` for these models.
</Note>

<Note>
  `timeScaleFactor` works over both HTTP and WebSocket endpoints. For `/ws`, `/ws2`, and `/ws3`, pass it as a query parameter when opening the connection.
</Note>

### Mist v2

Use the `speedAlpha` parameter. **Lower** than 1.0 is faster; **higher** than 1.0 is slower.

```js theme={null}
{
    ...otherParams,
    "text": "Hello, world!",
    "modelId": "mistv2",
    "speedAlpha": 0.85
}
```

## Adjusting the speed of individual words

<Note>Per-word speed adjustment via `inlineSpeedAlpha` is a Mist-family feature. Coda does not support it.</Note>

To adjust the speed of individual words or phrases on the Mist family, use the `inlineSpeedAlpha` parameter. It takes a comma-separated list of speed values applied to words in square brackets.

On `mistv2` and `mistv3`, values **\< 1.0 speed up** speech and values **> 1.0 slow it down**.

<Note>On Mist v3, `inlineSpeedAlpha` and `speedAlpha` go in opposite directions; `speedAlpha` follows the direction used by Coda and Mist v3 (higher = faster), but `inlineSpeedAlpha` follows the legacy Mist direction (lower = faster). Don't infer one from the other.</Note>

For example: "This sentence is \[really] \[fast]" with `inlineSpeedAlpha` "0.5, 3" will make "really" fast and "fast" slow on the Mist family.

```js theme={null}
{
    ...otherParams,
    "modelId": "mistv2",
    "text": "This sentence is [really] [fast]",
    "inlineSpeedAlpha": "0.5, 3"
}
```

## Evaluate the result

Start near `1.0` and evaluate representative audio before increasing the adjustment. Large changes can reduce naturalness and clarity.


# Spell function
Source: https://docs.rime.ai/docs/spell

Force letter-by-letter pronunciation of codes, IDs, and acronyms using the spell() function for naturalistic pauses within the sequence.

## When to use `spell()`

Wrap a sequence in `spell()` when the listener needs to hear it one letter or digit at a time, such as a confirmation code they'll repeat back.

`spell()` works on Coda and the Mist family, and the grouping depends on the model and language. On Coda in English, Rime's grammar normalizer spells letters straight through, reads up to three digits one at a time, and reads longer digit runs in pairs: `spell(jonathan)` becomes `J-O-N-A-T-H-A-N`, and `spell(4252528929)` becomes "four two, five two, five two, eight nine, two nine". In other languages on Coda, and on Mist v3, `spell()` inserts naturalistic pauses, grouping numbers and letters in threes where possible and pairs where necessary. For example, Mist v3 breaks a standard 10-digit telephone number into:

> 4 2 5 `<pause>` 2 5 2 `<pause>` 8 9 `<pause>` 2 9

The same grouping applies to long words:

> P E N `<pause>` E L O `<pause>` P E

`spell()` also inserts pauses when a mixed sequence transitions between letters and numbers:

> P R M `<pause>` 4 2 3 `<pause>` G D D `<pause>` M L `<pause>` 2 `<pause>` 3 5 4

Any number, letter, or alphanumeric string inside `spell()` is read in full. The function also reads common symbols such as @ (at) and - (dash).

Write the sequence inside `spell()` without spaces, because a space starts a new group. `spell(sasha)` is spelled as one group, while `spell(S A S H A)` is read as five separate letters. To say the word before spelling it, write `Sasha, spelled spell(sasha)`.

The [`/textnorm`](/api-reference/other/textnorm) endpoint shows the grammar normalizer's reading for the language you pass, which matches Coda's grouping. Mist v3 can group differently.

Each section below shows a Mist v3 reading and the request that produces it, so you can send the same text and listen for the grouping.

## `spell()` applied to words

The eight letters of *jonathan* split into two groups of three and a pair:

> "The name is spelled J O N, A T H, A N."

**Input:**
`the name is spelled spell(jonathan).`

<audio />

<Tabs>
  <Tab title="Mist v3">
    ```json theme={null}
    {
       "speaker": "astra",
       "modelId": "mistv3",
       "text": "the name is spelled spell(jonathan)."
    }
    ```
  </Tab>
</Tabs>

## `spell()` applied to numbers

A 10-digit number splits into two groups of three and two pairs:

> "The number is 4 2 5, 2 5 2, 8 9, 2 9."

**Input:**
`the number is spell(4252528929).`

<Tabs>
  <Tab title="Mist v3">
    ```json theme={null}
    {
       "speaker": "astra",
       "modelId": "mistv3",
       "text": "the number is spell(4252528929)."
    }
    ```
  </Tab>
</Tabs>

## `spell()` applied to alphanumeric sequences

In a mixed string, the reading also pauses wherever letters switch to digits or back:

> the account is r f, 5, 4 3, d, c, 2

**Input:**
`the account is spell(rf543dc2).`

<Tabs>
  <Tab title="Mist v3">
    ```json theme={null}
    {
       "speaker": "astra",
       "modelId": "mistv3",
       "text": "the account is spell(rf543dc2)."
    }
    ```
  </Tab>
</Tabs>

## `spell()` applied to typographical symbols

`spell()` reads these symbols as words, so an email address or handle can go inside a single `spell()`:

| Symbol | Pronunciation |
| - | - |
| `@` | at |
| `_` | underscore |
| `-` | dash |
| `.` | dot |

For example, `help@rime.ai` reads as:

> the email address is h e, l p, at, r i, m e, dot, a i

**Input:**
`the email address is spell(help@rime.ai).`

<Tabs>
  <Tab title="Mist v3">
    ```json theme={null}
    {
       "speaker": "astra",
       "modelId": "mistv3",
       "text": "the email address is spell(help@rime.ai)."
    }
    ```
  </Tab>
</Tabs>


# Streaming TTS
Source: https://docs.rime.ai/docs/streaming

Choose HTTP or WebSockets for real-time Rime speech, with runnable examples for low-latency voice agents.

## tl;dr: All Rime models stream.

Rime's TTS API streams audio as it is generated rather than waiting for the full utterance. Coda and Mist stream over HTTP and WebSockets. Under typical conditions, the cloud API delivers sub-200ms end-to-end latency when an application uses the nearest [regional endpoint](/docs/regional-endpoints). For real-time voice agents, streaming is the default mode of operation.

## Choosing a transport

| | HTTP streaming | WebSocket (JSON) | SSE |
| - | - | - | - |
| **Endpoint** | `POST /v1/rime-tts` | `wss://users-ws.rime.ai/ws3` | `POST /v1/rime-tts` with `Accept: text/event-stream` |
| **Models** | All | All | Mist v2 only |
| **Connection** | One request per utterance | Persistent, multi-utterance | One request per utterance |
| **Input** | Full text upfront | Incremental text (e.g. from a streaming LLM) | Full text upfront |
| **Word-level timestamps** | ❌ | ✅ | ❌ |
| **Interruption handling** | Close the connection | `clear` operation + context IDs | Close the connection |
| **Best for** | Simple integrations, server-side synthesis | Voice agents, conversational AI, telephony | Browser `EventSource` clients |

**Rules of thumb:**

* **Building a voice agent?** Use the [WebSocket API](/docs/websockets). A persistent connection avoids per-utterance handshakes, you can feed text in as your LLM generates it, and word-level timestamps tell you exactly what was spoken when a caller interrupts.
* **Synthesizing complete sentences server-side?** HTTP streaming is the simplest path: one POST, audio bytes stream back in the response body.
* **Already using LiveKit, Pipecat, Vapi, or Daily?** The [integrations](/docs/livekit) handle transport for you. Rime plugs in as the TTS stage of the pipeline.

## HTTP streaming

A single `POST` to `https://users.rime.ai/v1/rime-tts` returns audio bytes in the response body as they are generated. The `Accept` header controls the format: Opus, MP3, WAV, PCM, or G.711 μ-law. See the [full format table](/api-reference/coda/http).

```bash cURL theme={null}
curl --request POST \
  --url https://users.rime.ai/v1/rime-tts \
  --header 'Accept: audio/mpeg' \
  --header "Authorization: Bearer $RIME_API_KEY" \
  --header 'Content-Type: application/json' \
  --output output.mp3 \
  --fail \
  --show-error \
  --data '{
  "text": "Streaming audio from Rime, as it is generated.",
  "modelId": "coda",
  "speaker": "astra",
  "lang": "en"
}'
```

```python Python theme={null}
import os, requests

with requests.post(
    "https://users.rime.ai/v1/rime-tts",
    headers={
        "Authorization": f"Bearer {os.environ['RIME_API_KEY']}",
        "Content-Type": "application/json",
        "Accept": "audio/mpeg",
    },
    json={
        "text": "Streaming audio from Rime, as it is generated.",
        "modelId": "coda",
        "speaker": "astra",
        "lang": "en",
    },
    stream=True,
) as response:
    response.raise_for_status()
    for chunk in response.iter_content(chunk_size=4096):
        ...  # feed chunk to your player, telephony stream, or file
```

The first audio bytes arrive long before synthesis finishes; consume the body incrementally (as above) rather than buffering the whole response, or you give back most of the latency win. See [Latency](/docs/latency) for measured time-to-first-audio per model.

Endpoint references: [Coda](/api-reference/coda/http) · [Mist v3](/api-reference/mistv3/http) · [Mist v2](/api-reference/mistv2/http)

## WebSocket streaming

Rime's WebSocket API (`wss://users-ws.rime.ai/ws3`) holds a persistent connection: send text messages as your application produces them and receive structured JSON events back, including base64 audio chunks, word-level timestamps, and a `done` event per synthesis batch.

```python Python theme={null}
import asyncio, base64, json, os
import websockets

async def main():
    url = "wss://users-ws.rime.ai/ws3?speaker=astra&modelId=coda&audioFormat=mp3"
    headers = {"Authorization": f"Bearer {os.environ['RIME_API_KEY']}"}

    async with websockets.connect(url, additional_headers=headers) as ws:
        await ws.send(json.dumps({"text": "Hello from Rime over WebSockets."}))
        await ws.send(json.dumps({"operation": "eos"}))  # synthesize and close

        async for message in ws:
            event = json.loads(message)
            if event["type"] == "chunk":
                audio_bytes = base64.b64decode(event["data"])
                ...  # play or forward the audio
            elif event["type"] == "timestamps":
                print(event["word_timestamps"]["words"])
            elif event["type"] == "done":
                print("synthesis complete")

asyncio.run(main())
```

The server emits four event types: `chunk` (base64 audio), `timestamps` (word-level timing), `done` (synthesis batch complete), and `error`. The `segment` parameter controls text buffering and when synthesis starts. See [Segmentation & behavior settings](/docs/websockets-segment).

<Card title="WebSocket API overview" icon="plug" href="/docs/websockets">
  Choosing between /ws3, /ws2, and /ws, the full event schema, context IDs, and interruption handling.
</Card>

Endpoint references: [Coda](/api-reference/coda/websockets-json) · [Mist v3](/api-reference/mistv3/websockets-json) · [Mist v2](/api-reference/mistv2/websockets-json)

## Server-sent events (SSE)

For clients built around `EventSource`, Mist v2 supports [server-sent events](/api-reference/mistv2/sse): the same `POST /v1/rime-tts` endpoint with `Accept: text/event-stream` streams audio as events over a standard HTTP response. SSE is only available for Mist v2; for other models, use HTTP or WebSocket streaming.

## Streaming for telephony and IVR

For phone-based voice agents and IVR systems, request audio that matches the telephony codec directly. Rime synthesizes G.711 μ-law (`audio/PCMU`) and 8kHz-sampled audio natively, so no transcoding step sits between synthesis and the caller:

* Set `Accept: audio/PCMU` (HTTP) or `audioFormat=mulaw` (WebSocket) for μ-law output.
* Set `samplingRate: 8000` to match the telephony stream and shrink payloads.

Telephony and voice-agent platform guides: [LiveKit](/docs/livekit) · [Vapi](/docs/vapi) · [SignalWire](/docs/signalwire) · [Daily](/docs/daily) · [VideoSDK](/docs/videosdk)

## Latency

Listeners experience time to first audio, not total synthesis time, so streaming has the largest effect on perceived responsiveness. Under typical conditions, Rime's cloud API delivers sub-200ms end-to-end latency when an application uses the nearest [regional endpoint](/docs/regional-endpoints). With `mistv3`, typical time to first byte is well below 100ms. Coda achieves sub-100ms model latency on the GPU engine when self-hosted or on-prem.

<Card title="Latency" icon="gauge-simple-max" href="/docs/latency">
  Measured benchmarks per model, what affects response time, and how to reduce it; regional endpoints, payload sizing, and text normalization.
</Card>


# Symbols and percentages
Source: https://docs.rime.ai/docs/symbols

How Rime pronounces standalone symbols and how percentage values are expanded.

Rime pronounces common symbols correctly out of the box, both standalone and embedded in numeric values.

<Note>
  For a tour of text normalization across all categories, see [Text normalization](/docs/text-normalization). For symbol-adjacent patterns (currency amounts, measurements with units), see [Numbers, currency, and measurements](/docs/numbers).
</Note>

## Symbols

| Format | Example | Reads as |
| :- | :- | :- |
| Ampersand | `&` | and |
| Dollar sign (standalone) | `$` | dollar |
| Percent sign (standalone) | `%` | percent |
| Hash | `#` | hashtag |

## Percentages

Percentage values (a number followed by `%`) are expanded automatically:

| Format | Example | Reads as |
| :- | :- | :- |
| Whole percentage | `100%` | one hundred percent |
| Decimal percentage | `12.5%` | twelve point five percent |
| Percentage range | `78-84%` | seventy-eight to eighty-four percent |

## Related

* [Numbers, currency, and measurements](/docs/numbers) for currency amounts (`$5.99`), measurements with units (`5kg`, `98°F`), and ranges
* [Text normalization](/docs/text-normalization) for the full normalization overview


# Text normalization
Source: https://docs.rime.ai/docs/text-normalization

Rime normalizes numbers, dates, currency, phone numbers, and measurements before synthesis, in English and other supported languages.

When you send text to Rime's TTS models, a normalization layer runs first. It expands numbers, dates, currency, phone numbers, measurements, and other non-standard words into their spoken form before the model synthesizes audio.

<Note>
  **Rime handles text normalization automatically.** Most common formats (currency with symbols, dates with years, clock times, phone numbers, and standard measurements) expand correctly without any preprocessing. Just write naturally. If something sounds wrong, [debug it with `/textnorm`](#debugging-with-the-textnorm-endpoint) before adding a pre-processing layer to your application.
</Note>

## Handled at a glance

Select a category for its full input/output reference.

| Category | Examples | Reference |
| :- | :- | :- |
| Numbers, currency, ranges, measurements | `$1,045.96`, `5kg`, `98°F`, `13-50`, `1/2`, `1e6`, `(213) 555-9274` | [Numbers, currency, and measurements](/docs/numbers) |
| Dates and times | `10/12/2024`, `2021-03-15`, `April 2, 2024`, `3:45pm`, `15:45`, `noon` | [Dates and times](/docs/dates) |
| Addresses, URLs, emails | `529 Main St., Boston, MA 02129`, `https://app.rime.ai`, `name@example.com` | [Addresses, URLs, and emails](/docs/addresses) |
| Abbreviations, acronyms, initialisms | `Dr. Smith`, `e.g.`, `NASA`, `d. n. a.` | [Abbreviations, acronyms, and initialisms](/docs/abbreviations) |
| Symbols and percentages | `&`, `$`, `%`, `100%` | [Symbols and percentages](/docs/symbols) |

## Forced letter-by-letter reading

For account numbers, confirmation codes, SKUs, and acronyms the normalizer doesn't recognize, wrap the string in `spell(...)` to force letter-by-letter pronunciation. It works on Coda and the Mist family, with different grouping. Mist v3 reads this code in groups of three where possible:

```text theme={null}
Input:   Your confirmation code is spell(PRM423GDDML2354).
Mist v3: Your confirmation code is P R M, 4 2 3, G D D, M L, 2, 3 5 4.
```

For Coda's grouping and more examples, see [Spell function](/docs/spell).

## Brand names, product names, and uncommon words

Rime's models may not nail uncommon brand or product names on the first try. Two options:

1. **Submit the word to Rime** to add to the dictionary (typically about a week). Reach out to your account manager via Slack or email, or contact [sales@rime.ai](mailto:sales@rime.ai); mention if you need faster turnaround or have an SLA.
2. **Use custom pronunciations inline** with the [Rime phonetic alphabet](/platform/rime-phonetic-alphabet) and `phonemizeBetweenBrackets: true`. See [Custom pronunciation](/docs/custom-pronunciation) for the full reference.

<Warning>
  [`phonemizeBetweenBrackets`](/docs/custom-pronunciation) works on **Mist v1, Mist v2, and English Mist v3**. It is not supported on Coda or non-English Mist v3. For brand or product name pronunciations on those models, submit the word to Rime to add to the dictionary, respell phonetically in plain English (accepting that this is approximate), or use a supported Mist model for flows where pronunciation control matters.
</Warning>

For full reference, see [Custom pronunciation](/docs/custom-pronunciation). To check whether a word is already in Rime's dictionary, use the [Coverage API](/api-reference/other/oov).

## Feature availability across models

| Feature | Coda | Mist |
| :- | :-: | :-: |
| Native text normalization (numbers, currency, dates, etc.) | ✅ | ✅ |
| `spell()` for forced letter-by-letter | ✅ (English: letters straight through, longer digit runs in pairs; other languages: threes) | ✅ (v3: threes where possible) |
| Punctuation-driven prosody | ✅ | ✅ |
| [`pauseBetweenBrackets`](/docs/custom-pauses) (custom pause tags like `<750>`) | ❌ | ✅ |
| [`phonemizeBetweenBrackets`](/docs/custom-pronunciation) (inline phonetic strings) | ❌ | ✅ (v1, v2, English v3) |
| Deterministic per-term pronunciation config | ❌ | ✅ |

For flows that need precise pause durations (legal disclaimers, regulated read-backs) or guaranteed pronunciation of brand and product names, Mist is the safer choice.

## Debugging with the textnorm endpoint

The fastest way to spot-check normalization without writing code is the [Generate page in the Rime web app](https://app.rime.ai/generate/): paste any input string and it shows you the normalized version Rime will synthesize from.

For programmatic debugging, Rime also exposes a `/textnorm` endpoint that returns the grammar normalizer's output for an input string. That output matches Coda's normalization; Mist v3 can group `spell()` sequences differently. In scripts and pipelines, use it to separate normalization issues from synthesis issues.

```bash theme={null}
curl -X POST https://optimize.rime.ai/textnorm \
    -H "Authorization: Bearer $(rime key)" \
    -H "Content-Type: application/json" \
    -d '{"text":"1234 1,2,3,4 1-800-444-4141 "}'
```

```json theme={null}
{"normalized":"twelve thirty four, one , two , three , four, one, eight hundred, four four four, four one four one"}
```

The endpoint defaults to English. For other languages, pass a language code in the `lang` field:

```bash theme={null}
curl -X POST https://optimize.rime.ai/textnorm \
    -H "Authorization: Bearer $(rime key)" \
    -H "Content-Type: application/json" \
    -d '{"text":"Tengo 2 perros","lang":"es"}'
```

See [Languages](/docs/voices#languages) for the full list of supported languages. Output is the same regardless of which model you'll synthesize with. For the full request and response reference, see the [Text Normalization API](/api-reference/other/textnorm).

### Triage workflow

When something sounds off:

1. **Capture the exact input text** that produced the bad output.
2. **POST it to `/textnorm`** and look at the normalized output.
3. **Compare** the normalized output to what you expected the model to say.
4. If normalization is wrong, you have a reproducible signal; [flag it to Rime](mailto:support@rime.ai) with the input, expected normalization, and actual normalization. Fixes ship on Rime's side.
5. If normalization looks correct but speech still sounds off, the issue is in synthesis, not normalization; try a different voice, model version, or sampling settings.

## Testing checklist

Before going to production, test the voice against realistic versions of:

1. Every date format your backend can produce (MM/DD, MM/DD/YYYY, ISO, relative like "tomorrow").
2. Every currency you'll quote, including round numbers and fractional cents.
3. The longest realistic phone number, account number, and confirmation code.
4. Your top 20 most-spoken product or brand names.
5. At least one utterance from each of: quote, greeting, confirmation, error, payment, scheduling.
6. The same utterance regenerated 5 to 10 times. Consistency across regenerations is what catches sampling variance.

For anything that sounds wrong, POST the exact input to [`/textnorm`](#debugging-with-the-textnorm-endpoint) to see what the model actually received, then [flag it to Rime](mailto:support@rime.ai) so the fix lands for everyone.

## Pre-normalizing in your application

For most applications, pre-normalizing is unnecessary and adds latency and engineering complexity. Rime's normalizer handles common patterns natively, and the fastest way to fix a pronunciation issue is to verify with [`/textnorm`](#debugging-with-the-textnorm-endpoint) and [flag any miss to Rime](mailto:support@rime.ai).

If a pattern genuinely needs to be pre-expanded, such as a domain-specific alphanumeric ID or a flow that must read identically after regeneration, see [Pre-normalizing text](/docs/pre-normalization) for guidance and a drop-in prompt template.


# Together AI
Source: https://docs.rime.ai/docs/together-ai

Use Rime TTS via Together AI's inference platform.

<IntegrationHeader />

Rime's Arcana v3, [Arcana v2](https://www.together.ai/models/arcana-v2), and [Mist v2](https://www.together.ai/models/mist-v2) models are available through [Together AI](https://together.ai/).

Together AI hosts these deployments and manages their lifecycle. Arcana's retirement from the Rime cloud API does not change Together AI endpoints.

Use [Together's documentation](https://docs.together.ai) for endpoint, authentication, and deployment details.


# Troubleshooting the API
Source: https://docs.rime.ai/docs/troubleshooting-api

Diagnose Rime API failures by what you observe, including failures that arrive wrapped by LiveKit, Pipecat, Vapi, or the CLI.

Many Rime API failures are silent: a request returns `200` and plausible output while doing something other than what you asked. This page starts from what you observe. For the exhaustive list of statuses and messages, see [the error reference](/docs/errors).

<Warning>**Capture evidence before you retry.** No response carries a request ID you can quote, so record the UTC timestamp, the endpoint and region, `modelId`, `speaker`, and `lang` as sent, the status and full body or the WebSocket close code and its complete reason string, and whether any audio had arrived. A reproduction is often the only diagnostic available.</Warning>

## No audio at all

### The file exists but will not play

Check what is actually in it before anything else:

```bash theme={null}
file output.wav       # expect: RIFF (little-endian) data, WAVE audio
head -c 4 output.wav  # expect: RIFF
```

What the first bytes tell you:

* **`RIFF`:** the file has a WAV header. If it still won't play, check its size: a file of a few hundred bytes means the stream ended early.
* **`{`:** you received the legacy JSON envelope. Only Mist v1 and Mist v2 return it, when `Accept` is missing or doesn't name a type the API can stream.
* **Unreadable binary without `RIFF`:** on Coda and Mist v3, a missing or wildcard `Accept` returns raw 16-bit PCM (`audio/pcm`), which players won't open. Set `Accept: audio/wav`.
* **Readable English:** a client that didn't check the status wrote an error message to the file. An `Accept` naming an unsupported type, for example, returns `406` with a plain-text list of supported types.

See [the quickstart's success check](/docs/quickstart-five-minute#confirm-it-worked).

### The file is zero bytes

The request never completed. Confirm the URL is `https://users.rime.ai/v1/rime-tts` and reachable, and that your client is not silently following a redirect or failing TLS.

### An unexpected `401`

Five different messages produce a `401`, and they mean different things. `invalid subscription` is a billing state, not a bad key, so regenerating the credential will not help. `empty apikey` almost always means a shell variable did not expand. See [401 in the error reference](/docs/errors#401-authentication-failed).

## Audio arrives but is wrong

### The voice is not the one you asked for

Most likely the `speaker`, `modelId`, and `lang` combination is not one the catalog serves, and it was not rejected. Verify against the [Coda](/docs/voices-coda) or [Mist v3](/docs/voices-mist-v3) catalog. Remember that every Coda voice serves exactly one language, so the voice determines `lang`.

Second possibility: `modelId` contains a typo. An unrecognized value is served by Mist v3 without an error, so `codaa` returns working audio from the wrong model.

### Speed changes stop taking effect past a point

`timeScaleFactor` is clamped to 0.4 to 2.5 without notice. Also check you are using the right parameter for the model: `speedAlpha` is inverted on Mist v2 relative to every other model. See [Speed](/docs/speed).

### Pronunciation overrides do nothing

`phonemizeBetweenBrackets` is served by Mist v1, Mist v2, and English Mist v3. On Coda and non-English Mist v3 it is accepted and ignored. See the model reference.

## Streaming and WebSocket problems

### Timestamps never arrive

They are emitted only for English and Spanish, or when `lang` is omitted. In other Coda languages the stream sends `chunk` and `done` with no `timestamps` event and no error, so never block playback waiting for one.

### The connection closes mid-utterance

A server-side failure closes with `1011` and puts the message in the close reason, often prefixed with an HTTP-equivalent status as in `400: text is too long`. Log the whole reason string. Read the prefix when diagnosing, but do not branch on it.

### The upgrade fails before a socket opens

Connection-time failures arrive as an HTTP status on the upgrade, not as a close code. A `429` there means you are opening connections too fast, so back off and reuse connections rather than opening one per utterance.

### Audio is choppy or late under load

Check you are calling the nearest [regional endpoint](/docs/regional-endpoints) before investigating anything else, then see [Latency](/docs/latency).

## Retrying safely

Retry only what can succeed on a second attempt, and know what a retry costs.

| What happened | Retry? | Notes |
| :- | :- | :- |
| `400` | No | The request is malformed. It will fail identically. |
| `401`, `403` | No | Fix the credential or the account. Repeated attempts with a bad key are indistinguishable from an attack. |
| `429` at the upgrade | Yes, after backoff | Retry the connection, not the synthesis. Reduce connection churn. |
| `500`, `502` | Yes, with backoff | The only failures where an immediate retry is reasonable. |
| `1011` close, no audio yet | Usually | Read the reason string first. If it describes a malformed request, fix the request instead of retrying. |
| `1011` close, audio already sent | Only deliberately | See the billing warning below. |
| Upgrade succeeded, then silence | Reconnect | Do not retry the whole utterance without deciding what to do about the partial audio. |

<Warning>**Retries are billed as new synthesis.** Rime bills by characters synthesized, and each request is billed independently. If a connection drops partway through a long utterance, resynthesizing the full text incurs its full character count again. For long utterances, synthesize in sentence-aligned chunks and resume from the last chunk you received, so a retry only re-sends what was lost.</Warning>

Rime does not send a `Retry-After` header, so choose your own backoff. Exponential with jitter, capped, is the usual choice.

## Failures that arrive wrapped

Most developers meet the Rime API through an integration rather than directly, and see a framework exception instead of a status code. Map it back before diagnosing.

| Where you are | What you see | How to get the real cause |
| :- | :- | :- |
| LiveKit agents | A plugin exception during TTS, often without the HTTP status | Reproduce the same `speaker`, `modelId`, and `lang` with a raw cURL request. Older LiveKit Rime plugin releases default to the retired `arcana` identifier, so set `model="coda"` explicitly. See [LiveKit](/docs/quickstart-livekit). |
| Pipecat | A service error in the pipeline log | Pipecat defaults to Coda from v1.3.0. Confirm your version, then reproduce with cURL. See [Pipecat](/docs/pipecat). |
| Vapi | A provider error in the call log | Voice and model are set in the Vapi dashboard rather than in your code, so check there first. See [Vapi](/docs/vapi). |
| Rime CLI | A command error | Run with the same values through [`rime curl`](/cli-reference/rime-curl) to see the unwrapped response, and see [CLI troubleshooting](/cli-reference/troubleshooting). |
| MCP server | A tool error in your assistant | `list_voices` needs no key, so if that works and synthesis does not, the problem is the key rather than the connection. See [MCP](/docs/mcp). |

The general method is the same in every row: reduce to one raw HTTP request with the identical `speaker`, `modelId`, `lang`, and `Accept`, and read the plain-text body. If the raw request succeeds, the problem is in the integration or its configuration rather than in the API.

## Still stuck

Contact [support@rime.ai](mailto:support@rime.ai) with the evidence listed at the top of this page. Because no request ID exists, the reproduction and the exact timestamp are what make a report actionable.

## Related

* [Error reference](/docs/errors): every status and message, per transport.
* [Voices](/docs/voices): verify a voice, model, and language combination.


# Vapi
Source: https://docs.rime.ai/docs/vapi

Connect Rime TTS to Vapi for phone-based voice agents and IVR systems.

<IntegrationHeader />

<img alt="Vapi demo" />

Configure a [Vapi](https://vapi.ai) assistant that speaks with a Rime voice, then talk to it in your browser. Vapi handles telephony and orchestration. You choose the model, voice, and transcriber in the Vapi Dashboard, and can optionally bring your own Rime API key.

## Prerequisites

* A [Vapi](https://dashboard.vapi.ai) account
* A Rime [API key](https://app.rime.ai/tokens) (optional)

## Step 1: Create the assistant

In the [Vapi Dashboard](https://dashboard.vapi.ai), open **Assistants** and select **Create Assistant**.

<img alt="Vapi assistants page with Create Assistant button" />

### 1.1 Select a template

Give your assistant a name, select **Blank Template**, and select **Create Assistant**.

<img alt="Create assistant modal" />

### 1.2 Configure the model

In the **Model** tab, select your preferred LLM provider. Any option should work, but models with lower latency enable better conversational flow.

Add a **First Message** to enable your assistant to begin conversations.

Configure a **System Prompt** to define your agent's personality and behavior. For example:

```
You are a helpful voice assistant.
Keep your responses short and conversational. No more than 2-3 sentences.
Be friendly and natural.
```

Alternatively, select **Generate** to draft the prompt.

<img alt="Model tab configuration" />

### 1.3 Configure the voice

In the **Voice** tab, configure your assistant to use **Rime AI** as the **Provider**.

Select the **Voice** that you want your assistant to use. See the [Voices](/docs/voices) page for the Rime catalog.

Set the **Model** to **Coda**, Rime's current model.

If your Vapi account does not offer Coda in the **Model** list, contact [support@rime.ai](mailto:support@rime.ai) before publishing the assistant.

### 1.4 Configure the transcriber

In the **Transcriber** tab, select your preferred speech-to-text (STT) **Provider**, then select **Publish**.

<img alt="Transcriber tab configuration" />

### 1.5 Publish the assistant

In the publishing popup window, select **Skip and Publish**.

<img alt="Publish popup window" />

## Step 2: Add your API keys to Vapi (optional)

By default, Vapi provides access to its supported providers, including Rime, through Vapi billing. If you already have a subscription plan with one of your assistant's providers, add that provider's API key so the assistant uses your plan instead:

In the **Build** section, open **More → Integrations**. Find each provider and add its API key.

<img alt="Integrations" />

Vapi stores provider keys under **Integrations** and makes them available to your assistants.

<img alt="Rime API key integration" />

## Step 3: Test your assistant

In the Vapi Dashboard, select **Talk to Assistant** to start a conversation in your browser. The assistant opens with the **First Message** from step 1.2, spoken in the Rime voice you chose. If you hear a different voice, check the **Provider** and **Voice** settings in the **Voice** tab.

<img alt="Vapi demo" />

## Extend the assistant

* **Try different voices:** Audition other voices like `celeste`, `orion`, and `andromeda` at [app.rime.ai](https://app.rime.ai).
* **Add a phone number:** Provision a contact number in the Vapi Dashboard and assign it to your assistant for telephony.
* **Create a workflow:** Program your assistant to do complex tasks using [Vapi Workflows](https://dashboard.vapi.ai/workflows).
* **Customize the personality:** Update the system prompt to match your use case.


# VideoSDK
Source: https://docs.rime.ai/docs/videosdk

Use Rime TTS with VideoSDK.

<IntegrationHeader />

Use VideoSDK's RimeAI TTS plugin to add Rime speech to calls, meetings, and voice agents while VideoSDK handles real-time media transport.

Follow [VideoSDK's RimeAI TTS documentation](https://docs.videosdk.live/ai_agents/plugins/tts/rime-ai-tts) for configuration, or start from the [VideoSDK voice-agent example](https://github.com/videosdk-community/videosdk-rimeai-tts-demo).


# Build a voice agent (Express)
Source: https://docs.rime.ai/docs/voice-agent-express

Build a minimal voice-agent loop on Express while one server-side route protects your Rime API key.

Build a minimal voice-agent loop on one Express server: the browser captures speech, your server decides what to say, and Rime speaks the reply. This starter uses browser speech recognition and a stub response function; replace both with production components.

Keep `RIME_API_KEY` on the server and call Rime over HTTPS with `fetch`. No Rime-specific npm package is required; Express is the only dependency.

```
Browser (mic + playback)  →  POST /api/tts (Express)  →  POST https://users.rime.ai/v1/rime-tts
```

## Prerequisites

* A Rime API key from the [API Tokens page](https://app.rime.ai/tokens), exported as `RIME_API_KEY`
* Node.js 20.11+ and `npm install express`

## 1. Server: Express app with a TTS route

Create `server.mjs`:

```javascript server.mjs theme={null}
import path from "node:path";
import express from "express";

const app = express();
app.use(express.json());

app.post("/api/tts", async (req, res) => {
  const { text, speaker = "astra", modelId = "coda" } = req.body ?? {};
  if (!text) return res.status(400).json({ error: "text is required" });

  const rimeRes = await fetch("https://users.rime.ai/v1/rime-tts", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RIME_API_KEY}`,
      "Content-Type": "application/json",
      Accept: "audio/mpeg", // MP3; see the API reference for Opus, WAV, PCM, μ-law
    },
    body: JSON.stringify({ text, speaker, modelId }),
  });

  if (!rimeRes.ok) {
    return res
      .status(rimeRes.status)
      .json({ error: `Rime API error ${rimeRes.status}`, detail: await rimeRes.text() });
  }

  res.setHeader("Content-Type", "audio/mpeg");
  res.send(Buffer.from(await rimeRes.arrayBuffer()));
});

app.get("/", (_req, res) => {
  res.sendFile(path.join(import.meta.dirname, "index.html"));
});

app.listen(3000, () => console.log("Rime voice agent on http://localhost:3000"));
```

Verify it works before touching the frontend:

```bash theme={null}
RIME_API_KEY=your_key node server.mjs &
curl -X POST http://localhost:3000/api/tts \
  -H 'Content-Type: application/json' \
  -d '{"text": "Hello from my Express voice agent."}' \
  --output test.mp3
```

`test.mp3` should be playable audio. A 401 means `RIME_API_KEY` isn't visible to the server process.

## 2. Client: mic in, Rime audio out

Create `index.html` next to `server.mjs`. It uses the browser's built-in `SpeechRecognition` for input (Chrome/Edge/Safari), a stub `respond()` function as the agent brain, and your `/api/tts` route for the voice:

```html index.html theme={null}
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Rime voice agent</title>
    <style>
      main { max-width: 480px; margin: 4rem auto; font-family: sans-serif; }
    </style>
  </head>
  <body>
    <main>
      <h1>Rime voice agent</h1>
      <button id="speak">🎤 Speak</button>
      <ul id="messages"></ul>
      <audio id="player" hidden></audio>
    </main>
    <script>
      // Replace this stub with a call to your LLM of choice.
      function respond(userText) {
        return `You said: ${userText}. This voice is Rime's Coda model.`;
      }

      async function speak(text) {
        const res = await fetch("/api/tts", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ text }),
        });
        if (!res.ok) throw new Error(`TTS failed: ${res.status}`);
        const player = document.getElementById("player");
        player.src = URL.createObjectURL(await res.blob());
        await player.play();
      }

      function log(line) {
        const li = document.createElement("li");
        li.textContent = line;
        document.getElementById("messages").appendChild(li);
      }

      document.getElementById("speak").addEventListener("click", () => {
        const SR = window.SpeechRecognition ?? window.webkitSpeechRecognition;
        if (!SR) return alert("SpeechRecognition not supported in this browser.");
        const rec = new SR();
        rec.onresult = async (e) => {
          const userText = e.results[0][0].transcript;
          const reply = respond(userText);
          log(`You: ${userText}`);
          log(`Agent: ${reply}`);
          await speak(reply);
        };
        rec.start();
      });
    </script>
  </body>
</html>
```

Open `http://localhost:3000`, select **Speak**, say something, and the agent answers in Rime's `astra` voice.

## Add streaming when latency matters

For incremental synthesis, attach a WebSocket bridge to the same HTTP server: browser WS ↔ Express server ↔ `wss://users-ws.rime.ai/ws3` with header authentication. Audio can then start while later sentences are still generating. Browser WebSockets cannot send the required `Authorization` header, so the bridge stays server-side. The [Next.js guide](/docs/voice-agent-nextjs#3-stream-over-websockets-when-latency-matters) provides the complete bridge; it works with Express's HTTP server through `const server = app.listen(3000)`. The [Coda WebSocket reference](/api-reference/coda/websockets-json) defines the `/ws3` schema.

## Production building blocks

<Columns>
  <Card title="WebSocket API overview" icon="plug" href="/docs/websockets">
    Endpoints, word-level timestamps, context IDs, and interruption handling.
  </Card>

  <Card title="Voices" icon="waveform-lines" href="/docs/voices">
    Swap `astra` for any Coda voice. Coda covers nine languages, and each voice serves one of them.
  </Card>

  <Card title="Streaming formats" icon="bolt" href="/docs/streaming">
    Choose between Opus, MP3, WAV, PCM, and μ-law for your latency budget.
  </Card>

  <Card title="Plain Node (no framework)" icon="terminal" href="/docs/voice-agent-node">
    Build the same starter with only `node:http` and built-in `fetch`.
  </Card>
</Columns>


# Build a voice agent (FastAPI)
Source: https://docs.rime.ai/docs/voice-agent-fastapi

Build a minimal voice-agent loop in FastAPI while a server-side endpoint protects your Rime API key.

Build a minimal voice-agent loop in FastAPI: the browser captures speech, your backend decides what to say, and Rime speaks the reply. This starter uses browser speech recognition and a stub response function; replace both with production components.

Keep `RIME_API_KEY` on the server and call Rime over HTTPS with `httpx`. No Rime-specific PyPI package is required.

```
Browser (mic + playback)  →  POST /api/tts (FastAPI)  →  POST https://users.rime.ai/v1/rime-tts
```

## Prerequisites

* A Rime API key from the [API Tokens page](https://app.rime.ai/tokens), exported as `RIME_API_KEY`
* Python 3.10+ with `pip install fastapi uvicorn httpx`

## 1. Server: FastAPI app with a TTS endpoint

Create `main.py`:

```python main.py theme={null}
import os

import httpx
from fastapi import FastAPI, HTTPException
from fastapi.responses import FileResponse, Response
from pydantic import BaseModel

app = FastAPI()

RIME_API_KEY = os.environ["RIME_API_KEY"]
RIME_TTS_URL = "https://users.rime.ai/v1/rime-tts"


class TTSRequest(BaseModel):
    text: str
    speaker: str = "astra"
    modelId: str = "coda"


@app.post("/api/tts")
async def tts(req: TTSRequest) -> Response:
    async with httpx.AsyncClient(timeout=30.0) as client:
        rime_res = await client.post(
            RIME_TTS_URL,
            headers={
                "Authorization": f"Bearer {RIME_API_KEY}",
                "Content-Type": "application/json",
                # MP3; see the API reference for Opus, WAV, PCM, μ-law
                "Accept": "audio/mpeg",
            },
            json=req.model_dump(),
        )

    if rime_res.status_code != 200:
        raise HTTPException(
            status_code=rime_res.status_code,
            detail=f"Rime API error: {rime_res.text}",
        )

    return Response(content=rime_res.content, media_type="audio/mpeg")


@app.get("/")
async def index() -> FileResponse:
    return FileResponse("index.html")
```

Verify it works before touching the frontend:

```bash theme={null}
uvicorn main:app --reload --port 8000
curl -X POST http://localhost:8000/api/tts \
  -H 'Content-Type: application/json' \
  -d '{"text": "Hello from my FastAPI voice agent."}' \
  --output test.mp3
```

`test.mp3` should be playable audio. A `KeyError: 'RIME_API_KEY'` at startup means the environment variable isn't set.

## 2. Client: mic in, Rime audio out

Create `index.html` next to `main.py`. It uses the browser's built-in `SpeechRecognition` for input (Chrome/Edge/Safari), a stub `respond()` function as the agent brain, and your `/api/tts` endpoint for the voice:

```html index.html theme={null}
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Rime voice agent</title>
    <style>
      main { max-width: 480px; margin: 4rem auto; font-family: sans-serif; }
    </style>
  </head>
  <body>
    <main>
      <h1>Rime voice agent</h1>
      <button id="speak">🎤 Speak</button>
      <ul id="messages"></ul>
      <audio id="player" hidden></audio>
    </main>
    <script>
      // Replace this stub with a call to your LLM of choice.
      function respond(userText) {
        return `You said: ${userText}. This voice is Rime's Coda model.`;
      }

      async function speak(text) {
        const res = await fetch("/api/tts", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ text }),
        });
        if (!res.ok) throw new Error(`TTS failed: ${res.status}`);
        const player = document.getElementById("player");
        player.src = URL.createObjectURL(await res.blob());
        await player.play();
      }

      function log(line) {
        const li = document.createElement("li");
        li.textContent = line;
        document.getElementById("messages").appendChild(li);
      }

      document.getElementById("speak").addEventListener("click", () => {
        const SR = window.SpeechRecognition ?? window.webkitSpeechRecognition;
        if (!SR) return alert("SpeechRecognition not supported in this browser.");
        const rec = new SR();
        rec.onresult = async (e) => {
          const userText = e.results[0][0].transcript;
          const reply = respond(userText);
          log(`You: ${userText}`);
          log(`Agent: ${reply}`);
          await speak(reply);
        };
        rec.start();
      });
    </script>
  </body>
</html>
```

Open `http://localhost:8000`, select **Speak**, say something, and the agent answers in Rime's `astra` voice.

## Add streaming when latency matters

For incremental synthesis, connect your **server** to `wss://users-ws.rime.ai/ws3` with the Python [`websockets`](https://pypi.org/project/websockets/) library and relay events through FastAPI's WebSocket support. Audio can then start while later sentences are still generating. Browser WebSockets cannot send the required `Authorization` header, so the Rime connection stays server-side. The [Coda WebSocket reference](/api-reference/coda/websockets-json) includes runnable Python code and the full `/ws3` schema.

## Production building blocks

<Columns>
  <Card title="WebSocket API overview" icon="plug" href="/docs/websockets">
    Endpoints, word-level timestamps, context IDs, and interruption handling.
  </Card>

  <Card title="Voices" icon="waveform-lines" href="/docs/voices">
    Swap `astra` for any Coda voice. Coda covers nine languages, and each voice serves one of them.
  </Card>

  <Card title="Streaming formats" icon="bolt" href="/docs/streaming">
    Choose between Opus, MP3, WAV, PCM, and μ-law for your latency budget.
  </Card>

  <Card title="Pipecat" icon="puzzle-piece" href="/docs/pipecat">
    Building a full Python voice pipeline? Use the ready-made Rime plugin.
  </Card>
</Columns>


# Build a voice agent (Next.js)
Source: https://docs.rime.ai/docs/voice-agent-nextjs

Build a minimal voice-agent loop in Next.js while a server-side route protects your Rime API key.

Build a minimal voice-agent loop in Next.js: the browser captures speech, a server route decides what to say, and Rime speaks the reply. This starter uses browser speech recognition and a stub response function; replace both with production components.

Keep `RIME_API_KEY` on the server. Call Rime over HTTPS with `fetch`; no Rime-specific npm package is required. The optional WebSocket bridge adds the only new dependency, `ws`.

**Architecture:** the browser never talks to Rime directly. Your API key stays server-side, and the browser calls your own `/api/tts` route:

```
Browser (mic + playback)  →  POST /api/tts (Next.js route)  →  POST https://users.rime.ai/v1/rime-tts
```

## Prerequisites

* A Rime API key from the [API Tokens page](https://app.rime.ai/tokens). Put it in `.env.local` as `RIME_API_KEY=...`
* A Next.js 14+ project using the App Router (`npx create-next-app@latest` defaults work)

## 1. Server: the TTS proxy route

Create `app/api/tts/route.ts` (or `src/app/api/tts/route.ts` if your project uses `src/`):

```typescript app/api/tts/route.ts theme={null}
export async function POST(req: Request) {
  const { text, speaker = "astra", modelId = "coda" } = await req.json();

  if (!text) {
    return Response.json({ error: "text is required" }, { status: 400 });
  }

  const rimeRes = await fetch("https://users.rime.ai/v1/rime-tts", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RIME_API_KEY}`,
      "Content-Type": "application/json",
      Accept: "audio/mpeg", // MP3; see the API reference for Opus, WAV, PCM, μ-law
    },
    body: JSON.stringify({ text, speaker, modelId }),
  });

  if (!rimeRes.ok) {
    const detail = await rimeRes.text();
    return Response.json(
      { error: `Rime API error ${rimeRes.status}`, detail },
      { status: rimeRes.status },
    );
  }

  // Stream the audio straight through to the browser
  return new Response(rimeRes.body, {
    headers: { "Content-Type": "audio/mpeg" },
  });
}
```

Verify it works before touching the frontend:

```bash theme={null}
npm run dev
curl -X POST http://localhost:3000/api/tts \
  -H 'Content-Type: application/json' \
  -d '{"text": "Hello from my Next.js voice agent."}' \
  --output test.mp3
```

`test.mp3` should be playable audio. If you get a 401, check that `RIME_API_KEY` is set in `.env.local` and the dev server was restarted after adding it.

## 2. Client: mic in, Rime audio out

Create `app/voice-agent/page.tsx`. It uses the browser's built-in `SpeechRecognition` for input (Chrome/Edge/Safari), a stub `respond()` function as the agent brain, and your `/api/tts` route for the voice:

```tsx app/voice-agent/page.tsx theme={null}
"use client";

import { useRef, useState } from "react";

// Replace this stub with a call to your LLM of choice.
function respond(userText: string): string {
  return `You said: ${userText}. This voice is Rime's Coda model.`;
}

export default function VoiceAgent() {
  const [messages, setMessages] = useState<string[]>([]);
  const [listening, setListening] = useState(false);
  const audioRef = useRef<HTMLAudioElement>(null);

  async function speak(text: string) {
    const res = await fetch("/api/tts", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text }),
    });
    if (!res.ok) throw new Error(`TTS failed: ${res.status}`);
    const url = URL.createObjectURL(await res.blob());
    audioRef.current!.src = url;
    await audioRef.current!.play();
  }

  async function handleUserText(userText: string) {
    const reply = respond(userText);
    setMessages((m) => [...m, `You: ${userText}`, `Agent: ${reply}`]);
    await speak(reply);
  }

  function listen() {
    const SR =
      (window as any).SpeechRecognition ??
      (window as any).webkitSpeechRecognition;
    if (!SR) return alert("SpeechRecognition not supported in this browser.");
    const rec = new SR();
    rec.onresult = (e: any) => handleUserText(e.results[0][0].transcript);
    rec.onend = () => setListening(false);
    setListening(true);
    rec.start();
  }

  return (
    <main style={{ maxWidth: 480, margin: "4rem auto", fontFamily: "sans-serif" }}>
      <h1>Rime voice agent</h1>
      <button onClick={listen} disabled={listening}>
        {listening ? "Listening…" : "🎤 Speak"}
      </button>
      <ul>{messages.map((m, i) => <li key={i}>{m}</li>)}</ul>
      <audio ref={audioRef} hidden />
    </main>
  );
}
```

Open `http://localhost:3000/voice-agent`, select **Speak**, say something, and the agent answers in Rime's `astra` voice.

## 3. Stream over WebSockets when latency matters

The HTTP route above is the right default for most apps. Switch to WebSockets for **incremental synthesis**, where audio starts while the rest of the sentence is still being generated, or for barge-in handling with [word-level timestamps](/docs/websockets).

Two things make the WebSocket setup different:

1. Rime's WebSocket endpoints authenticate with an `Authorization` header, which **browser WebSockets cannot send**. The bridge must live on your server, where it also keeps the API key off the client.
2. Next.js route handlers can't hold WebSocket connections, so you need a small custom server.

```
Browser WS (/ws/tts)  →  server.mjs bridge  →  wss://users-ws.rime.ai/ws3  (Authorization header)
```

Install `ws`, then create `server.mjs` in the project root:

```bash theme={null}
npm install ws
```

```javascript server.mjs theme={null}
import { createServer } from "node:http";
import next from "next";
import { WebSocketServer, WebSocket } from "ws";

const app = next({ dev: process.env.NODE_ENV !== "production" });
await app.prepare();
const handle = app.getRequestHandler();

const server = createServer(handle);
const wss = new WebSocketServer({ server, path: "/ws/tts" });

wss.on("connection", (client) => {
  // One upstream Rime connection per browser client.
  // speaker/modelId/audioFormat are query params; auth is a header.
  const rime = new WebSocket(
    "wss://users-ws.rime.ai/ws3?speaker=astra&modelId=coda&audioFormat=mp3",
    { headers: { Authorization: `Bearer ${process.env.RIME_API_KEY}` } },
  );

  // Browser → Rime: {text: "..."} to speak, {operation: "clear"} to interrupt.
  // Queue anything that arrives before the upstream connection finishes opening;
  // the browser side is usually connected first, and ws drops sends on a
  // CONNECTING socket.
  const pending = [];
  client.on("message", (data) => {
    const msg = data.toString();
    if (rime.readyState === WebSocket.OPEN) rime.send(msg);
    else pending.push(msg);
  });
  rime.on("open", () => {
    for (const msg of pending) rime.send(msg);
    pending.length = 0;
  });

  // Rime → browser: {type: "chunk", data: <base64 mp3>}, {type: "timestamps", ...},
  // {type: "done"}. Relay verbatim and let the client decode.
  rime.on("message", (data) => {
    if (client.readyState === WebSocket.OPEN) client.send(data.toString());
  });

  const closeBoth = () => { rime.close(); client.close(); };
  client.on("close", closeBoth);
  rime.on("close", closeBoth);
  rime.on("error", (err) => {
    client.send(JSON.stringify({ type: "error", message: String(err) }));
  });
});

server.listen(3000, () => {
  console.log("Next.js + Rime WS bridge on http://localhost:3000");
});
```

Point your `dev`/`start` scripts at it:

```json package.json theme={null}
{
  "scripts": {
    "dev": "node server.mjs",
    "build": "next build",
    "start": "NODE_ENV=production node server.mjs"
  }
}
```

On the client, connect to your bridge and play chunks as they arrive:

```typescript theme={null}
const ws = new WebSocket(`ws://${location.host}/ws/tts`);

// Collect base64 MP3 chunks per utterance, play on "done".
// (For true chunk-by-chunk playback, feed them to a MediaSource instead.)
let chunks: Uint8Array[] = [];

ws.onmessage = async (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === "chunk") {
    chunks.push(Uint8Array.from(atob(msg.data), (c) => c.charCodeAt(0)));
  }
  if (msg.type === "done") {
    const url = URL.createObjectURL(new Blob(chunks, { type: "audio/mpeg" }));
    chunks = [];
    await new Audio(url).play();
  }
};

// Speak: sentences synthesize as they complete (segment=bySentence default)
ws.onopen = () => ws.send(JSON.stringify({ text: "Hello from Rime over WebSockets." }));

// Interrupt (barge-in): drop whatever is still buffered server-side
function interrupt() {
  ws.send(JSON.stringify({ operation: "clear" }));
  chunks = [];
}
```

The [Coda WebSocket reference](/api-reference/coda/websockets-json) defines the full `/ws3` schema, including `chunk`, `timestamps`, `done`, and `error` events plus the `flush`, `clear`, and `eos` operations. The [WebSocket overview](/docs/websockets) covers segmentation and interruption patterns.

## Production building blocks

<Columns>
  <Card title="WebSocket API overview" icon="plug" href="/docs/websockets">
    Endpoints, word-level timestamps, context IDs, and interruption handling.
  </Card>

  <Card title="Voices" icon="waveform-lines" href="/docs/voices">
    Swap `astra` for any Coda voice. Coda covers nine languages, and each voice serves one of them.
  </Card>

  <Card title="Streaming formats" icon="bolt" href="/docs/streaming">
    Choose between Opus, MP3, WAV, PCM, and μ-law for your latency budget.
  </Card>

  <Card title="LiveKit & Pipecat" icon="puzzle-piece" href="/docs/livekit">
    Use the ready-made Rime plugins when a framework should own transport and orchestration.
  </Card>
</Columns>


# Build a voice agent (Node, no framework)
Source: https://docs.rime.ai/docs/voice-agent-node

Build a minimal voice-agent loop with Node.js built-ins while keeping your Rime API key on the server.

Build a minimal voice-agent loop with Node.js built-ins only. There is no framework, package, or `npm install`: just `node:http` and `fetch`. This starter uses browser speech recognition and a stub response function; replace both with production components.

Keep `RIME_API_KEY` on the server and call Rime over HTTPS. The [Next.js](/docs/voice-agent-nextjs), [Vite](/docs/voice-agent-vite), [Express](/docs/voice-agent-express), and [FastAPI](/docs/voice-agent-fastapi) starters show the same boundary in their respective frameworks.

```
Browser (mic + playback)  →  POST /api/tts (node:http)  →  POST https://users.rime.ai/v1/rime-tts
```

## Prerequisites

* A Rime API key from the [API Tokens page](https://app.rime.ai/tokens), exported as `RIME_API_KEY`
* Node.js 20.11 or later. Nothing else is required.

## 1. Server

Create `server.mjs`:

```javascript server.mjs theme={null}
import { createServer } from "node:http";
import { readFileSync } from "node:fs";
import path from "node:path";

const INDEX_HTML = readFileSync(path.join(import.meta.dirname, "index.html"));

async function handleTts(req, res) {
  let body = "";
  for await (const chunk of req) body += chunk;

  let text, speaker, modelId;
  try {
    ({ text, speaker = "astra", modelId = "coda" } = JSON.parse(body || "{}"));
  } catch {
    res.writeHead(400, { "Content-Type": "application/json" });
    return res.end(JSON.stringify({ error: "invalid JSON body" }));
  }
  if (!text) {
    res.writeHead(400, { "Content-Type": "application/json" });
    return res.end(JSON.stringify({ error: "text is required" }));
  }

  const rimeRes = await fetch("https://users.rime.ai/v1/rime-tts", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RIME_API_KEY}`,
      "Content-Type": "application/json",
      Accept: "audio/mpeg", // MP3; see the API reference for Opus, WAV, PCM, μ-law
    },
    body: JSON.stringify({ text, speaker, modelId }),
  });

  if (!rimeRes.ok) {
    res.writeHead(rimeRes.status, { "Content-Type": "application/json" });
    return res.end(
      JSON.stringify({ error: `Rime API error ${rimeRes.status}`, detail: await rimeRes.text() }),
    );
  }

  res.writeHead(200, { "Content-Type": "audio/mpeg" });
  res.end(Buffer.from(await rimeRes.arrayBuffer()));
}

createServer(async (req, res) => {
  if (req.method === "POST" && req.url === "/api/tts") return handleTts(req, res);
  if (req.method === "GET" && req.url === "/") {
    res.writeHead(200, { "Content-Type": "text/html" });
    return res.end(INDEX_HTML);
  }
  res.writeHead(404, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ error: "not found" }));
}).listen(3000, () => console.log("Rime voice agent on http://localhost:3000"));
```

Verify it works before touching the frontend (create an empty `index.html` first if you're testing the API route alone):

```bash theme={null}
RIME_API_KEY=your_key node server.mjs &
curl -X POST http://localhost:3000/api/tts \
  -H 'Content-Type: application/json' \
  -d '{"text": "Hello from my plain Node voice agent."}' \
  --output test.mp3
```

`test.mp3` should be playable audio. A 401 means `RIME_API_KEY` isn't visible to the server process.

## 2. Client: mic in, Rime audio out

Create `index.html` next to `server.mjs`. It uses the browser's built-in `SpeechRecognition` for input (Chrome/Edge/Safari), a stub `respond()` function as the agent brain, and your `/api/tts` route for the voice:

```html index.html theme={null}
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Rime voice agent</title>
    <style>
      main { max-width: 480px; margin: 4rem auto; font-family: sans-serif; }
    </style>
  </head>
  <body>
    <main>
      <h1>Rime voice agent</h1>
      <button id="speak">🎤 Speak</button>
      <ul id="messages"></ul>
      <audio id="player" hidden></audio>
    </main>
    <script>
      // Replace this stub with a call to your LLM of choice.
      function respond(userText) {
        return `You said: ${userText}. This voice is Rime's Coda model.`;
      }

      async function speak(text) {
        const res = await fetch("/api/tts", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ text }),
        });
        if (!res.ok) throw new Error(`TTS failed: ${res.status}`);
        const player = document.getElementById("player");
        player.src = URL.createObjectURL(await res.blob());
        await player.play();
      }

      function log(line) {
        const li = document.createElement("li");
        li.textContent = line;
        document.getElementById("messages").appendChild(li);
      }

      document.getElementById("speak").addEventListener("click", () => {
        const SR = window.SpeechRecognition ?? window.webkitSpeechRecognition;
        if (!SR) return alert("SpeechRecognition not supported in this browser.");
        const rec = new SR();
        rec.onresult = async (e) => {
          const userText = e.results[0][0].transcript;
          const reply = respond(userText);
          log(`You: ${userText}`);
          log(`Agent: ${reply}`);
          await speak(reply);
        };
        rec.start();
      });
    </script>
  </body>
</html>
```

Restart the server (it reads `index.html` at startup), open `http://localhost:3000`, select **Speak**, say something, and the agent answers in Rime's `astra` voice.

## Add streaming when latency matters

For incremental synthesis, connect your server to `wss://users-ws.rime.ai/ws3` and relay events to the browser. Audio can then start while later sentences are still generating. Browser WebSockets cannot send the required `Authorization` header, so the bridge stays server-side; the browser-facing side adds the one dependency, `ws`. The [Next.js guide](/docs/voice-agent-nextjs#3-stream-over-websockets-when-latency-matters) provides a complete bridge that works with the same `createServer` instance. The [Coda WebSocket reference](/api-reference/coda/websockets-json) defines the `/ws3` schema.

## Production building blocks

<Columns>
  <Card title="WebSocket API overview" icon="plug" href="/docs/websockets">
    Endpoints, word-level timestamps, context IDs, and interruption handling.
  </Card>

  <Card title="Voices" icon="waveform-lines" href="/docs/voices">
    Swap `astra` for any Coda voice. Coda covers nine languages, and each voice serves one of them.
  </Card>

  <Card title="Streaming formats" icon="bolt" href="/docs/streaming">
    Choose between Opus, MP3, WAV, PCM, and μ-law for your latency budget.
  </Card>

  <Card title="TTS in five minutes" icon="rocket" href="/docs/quickstart-five-minute">
    The core API walkthrough in cURL, Python, JavaScript, and TypeScript.
  </Card>
</Columns>


# Build a voice agent (Vite)
Source: https://docs.rime.ai/docs/voice-agent-vite

Build a minimal voice-agent loop in Vite while a small Node proxy keeps your Rime API key off the browser.

Build a minimal voice-agent loop in Vite without exposing your API key. Because Vite serves static assets, a small Node server proxies synthesis while the browser handles speech input and audio playback.

Call Rime over HTTPS with `fetch`; no Rime-specific npm package is required. This starter uses browser speech recognition and a stub response function, both of which you should replace for production.

```
Browser (mic + playback)  →  /api/tts (Vite dev proxy)  →  Node proxy :3001  →  https://users.rime.ai/v1/rime-tts
```

## Prerequisites

* A Rime API key from the [API Tokens page](https://app.rime.ai/tokens), exported as `RIME_API_KEY`
* A Vite + React project (`npm create vite@latest -- --template react-ts` defaults work)
* Express for the proxy: `npm install express`

## 1. The TTS proxy server

Create `server.mjs` in the project root:

```javascript server.mjs theme={null}
import express from "express";

const app = express();
app.use(express.json());

app.post("/api/tts", async (req, res) => {
  const { text, speaker = "astra", modelId = "coda" } = req.body ?? {};
  if (!text) return res.status(400).json({ error: "text is required" });

  const rimeRes = await fetch("https://users.rime.ai/v1/rime-tts", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RIME_API_KEY}`,
      "Content-Type": "application/json",
      Accept: "audio/mpeg", // MP3; see the API reference for Opus, WAV, PCM, μ-law
    },
    body: JSON.stringify({ text, speaker, modelId }),
  });

  if (!rimeRes.ok) {
    return res
      .status(rimeRes.status)
      .json({ error: `Rime API error ${rimeRes.status}`, detail: await rimeRes.text() });
  }

  res.setHeader("Content-Type", "audio/mpeg");
  res.send(Buffer.from(await rimeRes.arrayBuffer()));
});

app.listen(3001, () => console.log("Rime TTS proxy on http://localhost:3001"));
```

Wire the Vite dev server to it in `vite.config.ts`, so the browser can call a same-origin `/api/tts`:

```typescript vite.config.ts theme={null}
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      "/api": "http://localhost:3001",
    },
  },
});
```

Run both and verify the proxy before touching the UI:

```bash theme={null}
RIME_API_KEY=your_key node server.mjs &
npm run dev
curl -X POST http://localhost:5173/api/tts \
  -H 'Content-Type: application/json' \
  -d '{"text": "Hello from my Vite voice agent."}' \
  --output test.mp3
```

`test.mp3` should be playable audio. A 401 means `RIME_API_KEY` isn't visible to `server.mjs`.

## 2. Client: mic in, Rime audio out

Replace `src/App.tsx`. It uses the browser's built-in `SpeechRecognition` for input (Chrome/Edge/Safari), a stub `respond()` function as the agent brain, and the proxy for the voice:

```tsx src/App.tsx theme={null}
import { useRef, useState } from "react";

// Replace this stub with a call to your LLM of choice.
function respond(userText: string): string {
  return `You said: ${userText}. This voice is Rime's Coda model.`;
}

export default function App() {
  const [messages, setMessages] = useState<string[]>([]);
  const [listening, setListening] = useState(false);
  const audioRef = useRef<HTMLAudioElement>(null);

  async function speak(text: string) {
    const res = await fetch("/api/tts", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text }),
    });
    if (!res.ok) throw new Error(`TTS failed: ${res.status}`);
    const url = URL.createObjectURL(await res.blob());
    audioRef.current!.src = url;
    await audioRef.current!.play();
  }

  async function handleUserText(userText: string) {
    const reply = respond(userText);
    setMessages((m) => [...m, `You: ${userText}`, `Agent: ${reply}`]);
    await speak(reply);
  }

  function listen() {
    const SR =
      (window as any).SpeechRecognition ??
      (window as any).webkitSpeechRecognition;
    if (!SR) return alert("SpeechRecognition not supported in this browser.");
    const rec = new SR();
    rec.onresult = (e: any) => handleUserText(e.results[0][0].transcript);
    rec.onend = () => setListening(false);
    setListening(true);
    rec.start();
  }

  return (
    <main style={{ maxWidth: 480, margin: "4rem auto", fontFamily: "sans-serif" }}>
      <h1>Rime voice agent</h1>
      <button onClick={listen} disabled={listening}>
        {listening ? "Listening…" : "🎤 Speak"}
      </button>
      <ul>{messages.map((m, i) => <li key={i}>{m}</li>)}</ul>
      <audio ref={audioRef} hidden />
    </main>
  );
}
```

Open `http://localhost:5173`, select **Speak**, say something, and the agent answers in Rime's `astra` voice.

<Info>
  In production, deploy `server.mjs` or fold the route into your existing backend, then serve Vite's built assets from it. The same-origin `/api/tts` path keeps working, and the API key remains in the server environment.
</Info>

## Add streaming when latency matters

For incremental synthesis, connect your **server** to Rime's WebSocket API and relay events to the browser. Audio can then start while later sentences are still generating. Browser WebSockets cannot send the required `Authorization` header, so the bridge stays server-side. The [Next.js guide](/docs/voice-agent-nextjs#3-stream-over-websockets-when-latency-matters) shows the bridge pattern; the [Coda WebSocket reference](/api-reference/coda/websockets-json) defines the `/ws3` message schema.

## Production building blocks

<Columns>
  <Card title="WebSocket API overview" icon="plug" href="/docs/websockets">
    Endpoints, word-level timestamps, context IDs, and interruption handling.
  </Card>

  <Card title="Voices" icon="waveform-lines" href="/docs/voices">
    Swap `astra` for any Coda voice. Coda covers nine languages, and each voice serves one of them.
  </Card>

  <Card title="Streaming formats" icon="bolt" href="/docs/streaming">
    Choose between Opus, MP3, WAV, PCM, and μ-law for your latency budget.
  </Card>

  <Card title="TTS in five minutes" icon="rocket" href="/docs/quickstart-five-minute">
    The core API walkthrough in cURL, Python, JavaScript, and TypeScript.
  </Card>
</Columns>


# Build a voice agent
Source: https://docs.rime.ai/docs/voice-agents

Choose a complete voice-agent tutorial, a direct API starter, or a supported voice platform.

Start with the LiveKit tutorial for a complete, working voice agent. Use a direct API starter when you already own transport, transcription, turn detection, and orchestration. Rime supplies the speech layer in either case.

<Warning>
  Keep `RIME_API_KEY` on the server. Browser clients should call your application server or connect through a server-side WebSocket bridge rather than authenticate with Rime directly.
</Warning>

## Choose an implementation

<Columns>
  <Card title="LiveKit voice agent" icon="microphone-lines" href="/docs/quickstart-livekit">
    Run an end-to-end browser agent with LiveKit transport, turn detection, speech recognition, agent logic, and Rime speech.
  </Card>

  <Card title="Direct API starters" icon="code">
    Add a server-side Rime speech route and a browser voice interface to your application stack.

    * [Next.js](/docs/voice-agent-nextjs)
    * [Vite + React](/docs/voice-agent-vite)
    * [Express](/docs/voice-agent-express)
    * [Node.js](/docs/voice-agent-node)
    * [FastAPI](/docs/voice-agent-fastapi)
  </Card>

  <Card title="Voice platforms" icon="puzzle-piece">
    Use Rime through a framework or service that supplies transport, telephony, or agent orchestration.

    * [LiveKit](/docs/livekit)
    * [Pipecat](/docs/pipecat)
    * [Vapi](/docs/vapi)
    * [Daily](/docs/daily)
  </Card>

  <Card title="WebSocket API" icon="plug" href="/docs/websockets">
    Build directly on persistent synthesis connections when you need incremental text, word timestamps, context management, or interruption control.
  </Card>
</Columns>

## Rime is the speech layer

| Layer | Responsibility |
| - | - |
| Audio transport | Carries microphone input and synthesized audio between the user and the agent. |
| Speech recognition | Converts the user's audio into text for the agent. |
| Agent logic | Uses application rules or a language model to decide what to say. |
| Speech generation | Sends the response text to Rime and returns natural audio to the user. |

The LiveKit tutorial implements the complete path. The direct API pages are application starters: they demonstrate the Rime proxy and browser interface while leaving the production speech-recognition and agent-logic choices to your application.

## Design for live conversation

<Columns>
  <Card title="Stream speech" icon="signal-stream" href="/docs/streaming">
    Start playback while the response is still being generated and choose an audio format for your transport.
  </Card>

  <Card title="Handle interruptions" icon="hand" href="/docs/websockets">
    Use timestamps, context IDs, segmentation, and clear operations to coordinate turns and barge-in.
  </Card>

  <Card title="Reduce latency" icon="gauge-simple-max" href="/docs/latency">
    Measure time to first audio and tune the synthesis path for responsive conversations.
  </Card>

  <Card title="Choose a voice" icon="waveform-lines" href="/docs/voices">
    Match a voice, model, and language to the agent's audience and role.
  </Card>
</Columns>


# Voices
Source: https://docs.rime.ai/docs/voices

Rime's TTS voice catalog across Coda and Mist: voices in English, Arabic, French, German, Hindi, Italian, Japanese, Portuguese, and Spanish, and how to pick a starter voice.

Set `speaker` on every TTS request. For a first Coda request, try `astra`. For the complete, current lineup, use the live catalog endpoints.

```json theme={null}
{
  "speaker": "astra",
  "text": "Hello from Rime!",
  "modelId": "coda",
  "lang": "en"
}
```

## Starter voices to try

These speakers are confirmed to work on Rime's primary cloud models. All of them serve English.

| Speaker | Sounds like | Works on |
| :- | :- | :- |
| `astra` | Female, young adult, American Standard | Coda, Mist v3 |
| `luna` | Female, young adult, American | Coda, Mist v3 |
| `celeste` | Female, young adult, American | Coda |
| `masonry` | Male, middle-aged, Southern | Coda |
| `albion` | Male, young adult, English | Coda |
| `cove` | Female, young adult, African American | Mist v3 |

To compare voices, keep `text` the same and change only `speaker`. Use a line your application will actually say, such as an order update or an appointment reminder. A voice that suits a greeting may sound different reading a phone number, a date, or an address, so include those if your application speaks them.

## Browse every voice

The starter table above is a curated handful. These pages list every voice on Rime's two primary cloud models, grouped by language, with gender, age, and country for each.

<Columns>
  <Card title="Coda voices" icon="microphone" href="/docs/voices-coda">
    287 voices across 9 languages. Rime's flagship model for most new applications.
  </Card>

  <Card title="Mist v3 voices" icon="bolt" href="/docs/voices-mist-v3">
    78 voices across 4 languages. The default when `modelId` is omitted.
  </Card>
</Columns>

For Mist v2 voices, use the [live catalog endpoints](/api-reference/data/voice-details), which list every voice on every model.

For the machine-readable source that these pages are generated from:

* Voice names by model and language: [`/data/voices/all-v2.json`](/api-reference/data/voices-v2)
* Demographics and other metadata: [`/data/voices/voice_details.json`](/api-reference/data/voice-details)

Both endpoints are public and update as voices ship, so they can list a voice before these pages do.

## Languages

Pass `lang` as a [BCP 47](https://www.rfc-editor.org/info/bcp47) language tag. Language support varies by model and deployment. As of August 2026, Rime's primary cloud models support the following languages:

| Language | `lang` | Coda | Mist v3 |
| :- | :- | :-: | :-: |
| Arabic | `ar` | ✅ | ❌ |
| English | `en` | ✅ | ✅ |
| French | `fr` | ✅ | ✅ |
| German | `de` | ✅ | ✅ |
| Hindi | `hi` | ✅ | ❌ |
| Italian | `it` | ✅ | ❌ |
| Japanese | `ja` | ✅ | ❌ |
| Portuguese | `pt` | ✅ | ❌ |
| Spanish | `es` | ✅ | ✅ |

Rime also accepts the 3-letter ISO 639-2 codes (`eng`, `ger`, `spa`) that older integrations send, and will keep accepting them. New code should send the tag in the table: only a tag can express a regional variant such as `es-MX`.

Mist v2 supports English, French, German, and Spanish. On-prem image coverage differs from the cloud matrix (see the [on-prem quickstart](/docs/on-prem/quickstart#tts-service)).

<Note>**A voice serves one language, so picking a language narrows your choices.** Coda covers nine languages, but no individual Coda voice crosses between them: 176 of its 287 voices are English, then Spanish 48, Portuguese 23, Japanese 13, German 9, French 8, Arabic 6, Hindi 2, and Italian 2. Set `lang` to the language of the voice you chose. An unsupported pairing may not return an error, so verify against the [Coda catalog](/docs/voices-coda) rather than assuming a familiar voice speaks your language.</Note>

## Coda voices

Coda is Rime's flagship model. Its featured voices in the [Rime dashboard](https://app.rime.ai) are organized into four styles, each with female and male options.

### Professional

| Speaker | Gender | Age | Description |
| :- | :- | :- | :- |
| `lyra` | Female | 18–30 | A warm young American voice, bright and lively. |
| `clementine` | Female | 18–30 | A warm, lively twenty-something American voice, both polished and energetic. |
| `masonry` | Male | 30–50 | A confident, low Southern voice, authoritative without being loud. |

### Formal

| Speaker | Gender | Age | Description |
| :- | :- | :- | :- |
| `lintel` | Female | 18–30 | A warm young American voice, both polished and lively. |
| `eyre` | Female | 30–50 | A warm, friendly American voice that's calm and easy to listen to. |
| `bancroft` | Male | 60+ | A composed American voice, strong on professional and formal contexts. |
| `marlu` | Male | 30–50 | An older Australian voice: low, mature, unhurried. |

### Casual

| Speaker | Gender | Age | Description |
| :- | :- | :- | :- |
| `hesse` | Female | 18–30 | A relaxed, easygoing female voice. |
| `luna` | Female | 18–30 | A bright, lively female voice, energetic with a casual core. |
| `beatty` | Male | 18–30 | An easygoing, distinctly casual American male voice. |
| `godfrey` | Male | 18–30 | An easygoing, lively American male voice that's casual at heart. |

### Energetic

| Speaker | Gender | Age | Description |
| :- | :- | :- | :- |
| `astra` | Female | 18–30 | Bright, lively Californian: quick and expressive. |
| `vespera` | Female | 18–30 | A friendly, lively young Californian voice, bright and adaptable. |
| `parapet` | Male | 30–50 | A fast, lively Southern voice, energetic and grounded. |
| `cupola` | Male | 30–50 | A confident, energetic American voice, professional with warmth. |

`lawton` (Male, 60+) is a sixteenth featured Coda voice. It carries no style assignment in the catalog, so it does not appear in the tables above.

All voices above are confirmed to work with `modelId: coda`. The [voice-details endpoint](/api-reference/data/voice-details) contains the complete catalog, including non-English voices.

## Mist v3 voices

Mist v3 carries 78 voices with significantly lower TTFA than Mist v2. Most are drawn from the Mist v2 lineup, but the lineups are not identical: 71 speakers are shared, 67 Mist v2 speakers are not available on Mist v3, and 7 are Mist v3 only. Confirm a speaker before switching `modelId`.

See the [full voice list](/api-reference/data/voices-v2) for available Mist v3 speakers.

## Mist v2 voices

Mist v2 is tuned for clarity, pronunciation accuracy, and high-throughput production. For new projects, prefer Mist v3.

See the [full voice list](/api-reference/data/voices-v2) for available Mist v2 speakers.


# Coda voices
Source: https://docs.rime.ai/docs/voices-coda

Every Coda voice, grouped by language, with the metadata the public catalog publishes.

The public catalog publishes 287 Coda voices. Pass the value in the Voice column as `speaker`, with `modelId` set to `coda` and `lang` set to the tag given in the section you took the voice from.

Each Coda voice serves exactly one language. Coda as a model covers 9 languages, but no individual voice crosses between them, so choosing a language narrows the voices available to you. Pairing a voice with a different `lang` is not a supported combination.

**To hear a voice, do not rely on the descriptions here.** Play it in the [Rime dashboard](https://app.rime.ai), or ask an assistant connected to the [hosted MCP server](/docs/mcp) to browse and synthesize a line for you: [`list_voices`](/mcp-reference/list-voices) needs no API key, and [`synthesize_speech`](/mcp-reference/synthesize-speech) uses yours. This page is a reference index for looking up what exists and what it works with.

Use your browser's find command to search by voice name, country, or description. For the machine-readable source, see [the voice details endpoint](/api-reference/data/voice-details).

Switching to Coda from another model? A voice name is not carried by every model. If the voice you use today is not listed below, Coda does not serve it and you need to choose a different one rather than change `modelId` alone.

**Jump to:** [English](#english) · [Spanish](#spanish) · [Portuguese](#portuguese) · [Japanese](#japanese) · [German](#german) · [French](#french) · [Arabic](#arabic) · [Hindi](#hindi) · [Italian](#italian)

## English

176 voices. The 16 featured voices are in the first table, the remaining 160 in the second, each alphabetical. Set `lang` to `en` for this language.

**Featured English voices**

| Voice | Gender | Age | Country | Description |
| - | - | - | - | - |
| `astra` | Female | Young Adult | US | Bright, lively California, quick and expressive. |
| `bancroft` | Male | Elder | US | A composed American voice, strong on professional and formal contexts. |
| `beatty` | Male | Young Adult | US | An easygoing, distinctly casual American male voice. |
| `clementine` | Female | Young Adult | US | A warm, lively twenty-something American voice, both polished and energetic. |
| `cupola` | Male | Adult | US | A confident, energetic American voice, professional with warmth. |
| `eyre` | Female | Adult | US | A warm, friendly American voice, calm and easy to listen to. |
| `godfrey` | Male | Young Adult | US | An easygoing, lively American male voice, casual at heart. |
| `hesse` | Female | Young Adult | US | A relaxed, easygoing female voice. |
| `lawton` | Male | Elder | US | A warm American voice, calm and friendly throughout. |
| `lintel` | Female | Young Adult | US | A warm young American voice, both polished and lively. |
| `luna` | Female | Young Adult | US | A bright, lively female voice, energetic with a casual core. |
| `lyra` | Female | Young Adult | US | A warm young American voice, bright and lively. |
| `marlu` | Male | Adult | AU | An older Australian voice; low, mature, unhurried. |
| `masonry` | Male | Adult | US | A confident, low Southern voice, authoritative without being loud. |
| `parapet` | Male | Adult | US | A fast, lively Southern voice, energetic and grounded. |
| `vespera` | Female | Young Adult | US | A friendly, lively young Californian voice, bright and adaptable. |

<Accordion title="All other English voices (160)">
  | Voice | Gender | Age | Country | Description |
  | - | - | - | - | - |
  | `adeline` | Female | Adult | US | A clear, professional female voice. |
  | `albion` | Male | Young Adult | GB | A calm, even-keeled younger British voice, quick on its feet. |
  | `alfhild` | Female | Young Adult | US | Withheld pending a catalog correction. |
  | `alma` | Female | Adult | US | Lively and easygoing, energetic with a casual edge. |
  | `almond` | Male | Adult | NZ | |
  | `alpine` | Male | Adult | US | |
  | `amarante` | Female | Adult | CA | A younger Canadian female voice, warm and friendly, with a Montreal lilt. |
  | `ana` | Female | Adult | US | A flexible female voice, both polished and approachable. |
  | `andromeda` | Female | Young Adult | US | An easygoing female voice with a casual feel. |
  | `arcade` | Male | Young Adult | US | A warm young American voice, formal but unstuffy, low and steady. |
  | `argon` | Female | Elder | US | A clear, professional female voice. |
  | `armpatch` | Male | Adult | US | |
  | `atrium` | Male | Adult | US | A measured, mature American voice, quick on the read but level in tone. |
  | `aurelio` | Male | Adult | US | A young Latino-heritage American male voice, warm, calm, and grounded. |
  | `azura` | Female | Young Adult | US | A bright, energetic female voice. |
  | `backbay` | Male | Elder | US | An easygoing American male voice. |
  | `baobab` | Male | Adult | NG | |
  | `bauer` | Male | Adult | US | A balanced male voice. |
  | `belle` | Female | Adult | US | |
  | `berklee` | Female | Young Adult | US | An energetic, lively female voice. |
  | `bianchi` | Female | Young Adult | US | A polished, distinctly professional female voice. |
  | `birch` | Female | Adult | US | |
  | `blackout` | Male | Elder | US | A polished, energetic male voice, strongly professional. |
  | `blue` | Male | Elder | US | |
  | `bogg` | Male | Adult | GB | |
  | `bond` | Male | Adult | US | A deep, mature African-American voice, calm, low, and authoritative. |
  | `brightwater` | Female | Adult | US | |
  | `bronte` | Female | Adult | US | A composed, polished female voice, professional with a touch of formality. |
  | `brussels` | Male | Adult | US | A calm, slow-paced young American voice, flexible across moods. |
  | `castro` | Male | Adult | US | |
  | `celer` | Male | Adult | IN | |
  | `celeste` | Female | Young Adult | US | A clear American voice, equally at home professional or casual. |
  | `chantal` | Female | Adult | US | An easy, casual female voice with some professional polish. |
  | `cherry` | Female | Adult | NZ | |
  | `clara` | Female | Elder | US | A friendly, middle-aged American voice, slow, warm, and reliable. |
  | `clarity` | Male | Young Adult | US | A bright, friendly American voice, calm and easy to listen to. |
  | `clipper` | Male | Young Adult | US | A brisk, friendly American voice, bright and lively. |
  | `dayform` | Female | Elder | US | |
  | `dore` | Male | Elder | US | |
  | `drift` | Male | Adult | US | A balanced male voice. |
  | `drownlight` | Male | Young Adult | AU | |
  | `egbert` | Male | Adult | US | A mature American voice, low and brisk, professional but not stiff. |
  | `eliphas` | Male | Young Adult | US | A warm young American male voice, higher and more expressive than most. |
  | `elsie` | Female | Adult | US | A friendly, bright middle-aged American voice, expressive and high-pitched. |
  | `estelle` | Female | Young Adult | US | A warm young Southern voice, even and friendly. |
  | `esther` | Female | Elder | US | An older American female voice with Chinese heritage, calm and grounded. |
  | `eucalyptus` | Female | Young Adult | AU | An Australian female voice, both polished and lively. |
  | `everett` | Male | Adult | US | A clear, professional male voice. |
  | `everstatic` | Male | Adult | US | |
  | `fade` | Male | Elder | US | |
  | `faith` | Female | Adult | US | |
  | `fern` | Male | Young Adult | US | An adult American male voice, calm, low, and even-keeled. |
  | `firefly` | Female | Young Adult | US | An easygoing American female voice with a casual edge. |
  | `firewall` | Male | Adult | US | A versatile male voice, comfortable across moods. |
  | `fleetfox` | Female | Adult | US | |
  | `foster` | Male | Young Adult | US | A confident, energetic American male voice. |
  | `fuzz` | Male | Elder | GB | A polished, formal male voice, composed and professional. |
  | `ghostface` | Male | Adult | US | |
  | `glasshour` | Female | Adult | US | |
  | `green` | Female | Elder | US | A composed American female voice with a professional read. |
  | `greyline` | Male | Adult | GB | |
  | `harrison_mary` | Female | Elder | US | |
  | `hawa` | Female | Adult | IN | An easygoing American female voice. |
  | `helium` | Female | Young Adult | US | A bright, lively female voice. |
  | `heller` | Male | Young Adult | US | An easy, lively American male voice, casual with energy. |
  | `holloway` | Male | Elder | US | |
  | `hugo` | Male | Young Adult | US | A capable, easygoing American male voice, equally suited to casual and professional contexts. |
  | `ibis` | Female | Young Adult | US | A polished, lively American female voice, professional with energy. |
  | `jayne` | Female | Young Adult | US | A neutral American female voice. |
  | `jenco` | Female | Young Adult | US | |
  | `jicarilla` | Female | Elder | US | A composed female voice with a professional read. |
  | `joyce` | Female | Young Adult | US | A bright, lively female voice, expressive but professional when needed. |
  | `jupiter` | Male | Elder | US | |
  | `katherine` | Female | Elder | US | |
  | `kima` | Female | Young Adult | US | |
  | `kimashley` | Female | Young Adult | US | |
  | `latte` | Female | Elder | US | A balanced female voice. |
  | `lector` | Male | Elder | US | |
  | `leni` | Female | Young Adult | IN | |
  | `linden` | Male | Elder | US | |
  | `luise` | Female | Elder | US | |
  | `lydia` | Female | Elder | US | A friendly Southern voice, flexible across moods. |
  | `maddux` | Female | Elder | US | A composed, polished female voice. |
  | `madison` | Female | Young Adult | US | A polished female voice with a professional read. |
  | `matilda` | Female | Adult | AU | |
  | `mercury` | Male | Young Adult | US | A composed, lively American male voice, formal when it needs to be. |
  | `merritt` | Female | Adult | US | A polished female voice, strongly professional with a casual edge. |
  | `milan` | Female | Elder | US | A bright, lively female voice with a professional core. |
  | `milton` | Male | Adult | US | A lively, energetic American male voice. |
  | `mopang` | Female | Adult | SG | |
  | `moraga` | Female | Adult | US | A warm American voice, calm and easygoing. |
  | `moss` | Female | Adult | SG | An adult Singaporean female voice, warm, calm, and grounded. |
  | `myrtle` | Female | Elder | US | A composed, professional female voice. |
  | `naipaul` | Male | Adult | ZA | A confident, lively American male voice. |
  | `neptune` | Male | Adult | US | A polished, expressive American male voice, formal but warm. |
  | `nexus` | Male | Adult | US | A balanced male voice. |
  | `nicklaus` | Male | Elder | US | A lively male voice. |
  | `northvale` | Male | Adult | GB | |
  | `ocean` | Female | Adult | US | |
  | `oculus` | Female | Young Adult | US | A neutral young American voice, bright, expressive, slow-paced. |
  | `orbea` | Female | Young Adult | US | A composed, polished female voice. |
  | `orion` | Male | Elder | US | A high-energy male voice, animated and quick. |
  | `ozu` | Female | Adult | US | An easy, casual female voice with quiet professionalism. |
  | `palegreen` | Male | Young Adult | IE | |
  | `paula` | Female | Elder | US | |
  | `perth` | Female | Young Adult | AU | A warm, easygoing Australian voice, calm and friendly. |
  | `petal` | Female | Young Adult | US | |
  | `pilaster` | Male | Adult | US | A mature, deep American male voice, calm, low, and grounded. |
  | `pimlico` | Male | Elder | US | |
  | `pola` | Female | Adult | DO | Withheld pending a catalog correction. |
  | `potrero` | Male | Adult | US | Withheld pending a catalog correction. |
  | `prentiss` | Female | Elder | US | A warm Southern voice, slow, bright, expressive. |
  | `proxy` | Male | Elder | US | A balanced male voice. |
  | `pulse` | Male | Adult | US | A neutral American male voice. |
  | `purple` | Female | Elder | US | A balanced female voice. |
  | `qwell` | Male | Young Adult | US | |
  | `rodriguez_carla` | Female | Young Adult | US | |
  | `ronan` | Female | Elder | IE | A composed American female voice with a professional core. |
  | `rooney` | Male | Adult | US | Balanced and easygoing, a clear, steady English voice that lands well in just about any context. |
  | `rosal` | Female | Adult | US | Bright and energetic, with a steady professional edge. |
  | `rosemount` | Female | Adult | US | A bright, adaptable American female voice. |
  | `ru` | Male | Adult | US | A clear, professional male voice. |
  | `sachet` | Female | Adult | US | An easygoing female voice with a casual feel. |
  | `sage` | Male | Elder | US | |
  | `salik` | Male | Young Adult | US | A warm, slow-paced American voice, friendly across moods. |
  | `sandoval` | Male | Elder | US | |
  | `santal` | Male | Elder | US | |
  | `sirius` | Male | Young Adult | US | A mature Latino-American male voice, low, steady, and grounded. |
  | `sky` | Female | Elder | US | A bright, friendly American voice, easygoing and light. |
  | `solana` | Male | Young Adult | US | Withheld pending a catalog correction. |
  | `sonnagh` | Female | Elder | IE | A composed American female voice with a professional core. |
  | `southvale` | Female | Young Adult | AU | |
  | `sprite` | Female | Young Adult | US | |
  | `star` | Male | Adult | US | |
  | `stucco` | Male | Young Adult | US | A confident, expressive young American voice, authoritative but not stiff. |
  | `sunset` | Male | Adult | US | |
  | `sylune` | Female | Adult | US | |
  | `tauro` | Male | Adult | US | A high-energy, animated male voice. |
  | `thalassa` | Female | Young Adult | US | A bright, energetic American female voice, capable of professional polish. |
  | `thread` | Male | Young Adult | US | |
  | `tim` | Male | Young Adult | US | A relaxed, casual male voice. |
  | `topeka` | Female | Elder | US | A neutral, slow-paced American voice, composed and professional. |
  | `transom` | Female | Young Adult | US | A bright, neutral young American voice, energetic underneath the calm. |
  | `truss` | Male | Young Adult | US | An adult American male voice, calm, low, and grounded. |
  | `ursa` | Male | Young Adult | US | A relaxed American male voice. |
  | `vashti` | Female | Adult | GB | A bright, expressive younger British voice, capable of professional polish. |
  | `vayu` | Male | Adult | US | A lively American male voice. |
  | `velune` | Female | Elder | US | |
  | `vernal` | Male | Elder | US | An even, easygoing American voice, calm and neutral throughout. |
  | `vesta` | Female | Young Adult | US | Young, warm, Californian, relaxed and slow-paced. |
  | `victoria` | Female | Adult | US | A lively female voice with an energetic edge. |
  | `walavista` | Female | Young Adult | US | A bright, energetic female voice. |
  | `walnut` | Male | Young Adult | US | |
  | `waveroom` | Male | Elder | US | |
  | `wawona` | Female | Young Adult | US | A calm, friendly American voice, even and easygoing. |
  | `willow` | Female | Young Adult | US | A bright, easygoing female voice. |
  | `woolsey` | Male | Adult | US | A neutral American voice, clear, even, and reliable. |
  | `yukiko` | Female | Adult | US | Withheld pending a catalog correction. |
  | `zellish` | Male | Adult | US | |
  | `zen` | Male | Adult | US | A balanced male voice. |
</Accordion>

## Spanish

48 voices, listed alphabetically. Set `lang` to `es` for this language.

<Accordion title="Spanish voices (48)">
  | Voice | Gender | Age | Country | Description |
  | - | - | - | - | - |
  | `abril` | Female | Adult | AR | |
  | `alba` | Male | Elder | VE | A warm Venezuelan Spanish voice, calm and friendly. |
  | `alonso` | Male | Young Adult | MX | |
  | `amanecer` | Female | Adult | CO | A bright Colombian Spanish voice, warm and lively. |
  | `angel` | Female | Adult | MX | |
  | `atardecer` | Male | Young Adult | MX | A warm Mexican Spanish voice, calm and steady. |
  | `azulado` | Male | Adult | CL | A measured Chilean Spanish voice, calm and steady throughout. |
  | `brisa` | Female | Young Adult | US | A bright US-Spanish voice, light, warm, and easygoing. |
  | `celestino` | Male | Young Adult | MX | A grounded Mexican Spanish voice, calm and even-paced. |
  | `cielo` | Female | Adult | AR | A warm Argentine Spanish voice, calm and easy to listen to. |
  | `ciro` | Male | Adult | PR | |
  | `claridad` | Female | Adult | PE | A bright Peruvian Spanish voice, warm and easygoing. |
  | `comet` | Male | Elder | MX | |
  | `cristhian` | Male | Young Adult | VE | |
  | `estrella` | Female | Adult | CL | A bright Chilean Spanish voice, warm and easygoing. |
  | `feliz` | Female | Adult | DO | |
  | `frieda` | Female | Adult | CU | |
  | `isla` | Female | Adult | CO | A warm Colombian Spanish voice, calm and easygoing throughout. |
  | `kiara` | Female | Adult | PR | |
  | `lark` | Female | Young Adult | ES | A measured Spanish voice from Spain, calm and steady. |
  | `luciana` | Female | Adult | PE | |
  | `luz` | Female | Young Adult | EC | A bright Ecuadorian Spanish voice, warm and easygoing. |
  | `mar` | Male | Young Adult | MX | A warm Mexican Spanish voice, calm and friendly. |
  | `mediodia` | Male | Adult | PE | A warm Peruvian Spanish voice, calm and steady. |
  | `milagros` | Male | Elder | MX | |
  | `monarch` | Female | Adult | ES | |
  | `nieve` | Male | Elder | US | A bright US-Spanish voice, light and easy to listen to. |
  | `nilton` | Male | Adult | PE | |
  | `nova` | Female | Young Adult | CO | A bright Colombian Spanish voice, warm and lively. |
  | `ocaso` | Female | Adult | CL | A measured Chilean Spanish voice, calm and even-keeled. |
  | `olivo` | Female | Adult | CO | |
  | `orionne` | Male | Adult | CO | A warm Colombian Spanish voice, calm and friendly. |
  | `palmera` | Male | Adult | ES | |
  | `plenilunio` | Female | Adult | CO | A calm Colombian Spanish voice, even and unhurried throughout. |
  | `renato` | Male | Young Adult | PR | |
  | `resplandor` | Male | Young Adult | CL | A bright Chilean Spanish voice, lively and even-paced. |
  | `rosalie` | Female | Young Adult | MX | |
  | `scarlet` | Female | Elder | ES | |
  | `seraphina` | Female | Young Adult | CO | A lively Colombian female voice. |
  | `serena` | Female | Adult | VE | A calm Venezuelan Spanish voice, even and grounded. |
  | `solsticio` | Male | Young Adult | AR | A warm Argentine Spanish voice, calm and steady. |
  | `thea` | Female | Adult | MX | |
  | `trueno` | Female | Adult | CO | A balanced female voice with no strong leaning. |
  | `vespero` | Female | Adult | ES | A measured Spanish voice from Spain, calm and even-keeled. |
  | `wildwood` | Female | Adult | ES | |
  | `xavier` | Male | Elder | PR | |
  | `yara` | Female | Adult | PR | |
  | `zayra` | Female | Adult | PR | |
</Accordion>

## Portuguese

23 voices, listed alphabetically. Set `lang` to `pt` for this language.

| Voice | Gender | Age | Country | Description |
| - | - | - | - | - |
| `alzira` | Female | Adult | BR | A relaxed Brazilian female voice with a balanced delivery. |
| `baltasar` | Male | Adult | BR | A grounded Brazilian Portuguese voice, calm and even-keeled. |
| `blossom` | Male | Young Adult | BR | |
| `bruno` | Male | Adult | PT | |
| `celso` | Male | Adult | BR | A grounded Brazilian Portuguese voice, calm, steady, and unhurried. |
| `coco` | Male | Young Adult | BR | |
| `colina` | Female | Elder | PT | |
| `dolce` | Female | Adult | BR | |
| `escola` | Female | Adult | BR | |
| `estela` | Female | Young Adult | BR | A warm Brazilian Portuguese voice, calm and steady across delivery. |
| `flor` | Female | Adult | BR | |
| `forte` | Female | Young Adult | BR | |
| `fresco` | Male | Young Adult | PT | |
| `henrique` | Male | Adult | BR | |
| `isadora` | Female | Adult | BR | A warm Brazilian Portuguese voice, calm and steady throughout. |
| `leandro` | Male | Elder | PT | |
| `lucia` | Female | Adult | BR | A warm American-heritage Brazilian Portuguese voice, calm and friendly. |
| `pimento` | Male | Adult | BR | |
| `porto` | Female | Adult | PT | |
| `rio` | Female | Young Adult | BR | A bright Brazilian Portuguese voice, lively and warm. |
| `sol` | Female | Adult | BR | A composed Brazilian female voice with a professional core. |
| `vento` | Female | Adult | BR | |
| `vida` | Female | Young Adult | BR | |

## Japanese

13 voices, listed alphabetically. Set `lang` to `ja` for this language.

| Voice | Gender | Age | Country | Description |
| - | - | - | - | - |
| `akari` | Female | Adult | JP | A bright Japanese voice, light and friendly. |
| `akatsuki` | Female | Young Adult | JP | An even Japanese voice, calm and steady throughout. |
| `hirake` | Male | Adult | JP | A measured Japanese voice, calm and even-keeled. |
| `hiru` | Male | Adult | JP | A bright Japanese voice, calm and even-paced. |
| `marika` | Female | Adult | JP | |
| `noriko` | Female | Elder | JP | |
| `nozomi` | Female | Adult | JP | A bright Japanese voice, warm and friendly. |
| `ren` | Male | Adult | JP | A calm Japanese voice, even and grounded throughout. |
| `sakura` | Female | Adult | JP | A bright Japanese voice, warm and friendly. |
| `sota` | Male | Adult | JP | |
| `taiyo` | Female | Adult | JP | A bright Japanese voice, lively and easygoing. |
| `yoru` | Male | Young Adult | JP | A low Japanese voice, calm and grounded across delivery. |
| `yugata` | Female | Adult | JP | A calm Japanese voice, even and unhurried throughout. |

## German

9 voices, listed alphabetically. Set `lang` to `de` for this language.

| Voice | Gender | Age | Country | Description |
| - | - | - | - | - |
| `aura` | Female | Adult | DE | A lively, energetic female voice. |
| `baldur` | Male | Adult | DE | A grounded German voice, calm, low, and steady. |
| `greta` | Female | Elder | DE | |
| `kumara` | Female | Adult | DE | A warm German voice, calm and easy to listen to. |
| `liesel` | Female | Adult | AT | A warm Austrian-German voice, calm and friendly throughout. |
| `lina` | Female | Adult | DE | |
| `lorelei` | Female | Young Adult | DE | A calm German voice, even, steady, and grounded. |
| `nacht` | Female | Adult | DE | A low, calm German voice, grounded and even. |
| `runa` | Female | Young Adult | DE | A calm German voice, even, steady, and grounded. |

## French

8 voices, listed alphabetically. Set `lang` to `fr` for this language.

| Voice | Gender | Age | Country | Description |
| - | - | - | - | - |
| `aurelie` | Female | Young Adult | FR | A bright French voice, warm and friendly. |
| `destin` | Male | Young Adult | FR | A measured French voice, calm and even-keeled. |
| `fredrique` | Male | Adult | FR | |
| `margarette` | Female | Elder | FR | |
| `marielle` | Female | Adult | FR | |
| `seraphine` | Female | Adult | FR | A warm French voice, calm and easy to listen to. |
| `solstice` | Female | Young Adult | FR | A calm French voice, measured and even-keeled. |
| `violette` | Female | Adult | FR | A bright French voice, warm and lively. |

## Arabic

6 voices, listed alphabetically. Set `lang` to `ar` for this language.

| Voice | Gender | Age | Country | Description |
| - | - | - | - | - |
| `batin` | Male | Adult | EG | A steady Palestinian Arabic voice, calm, even, and unhurried. |
| `fadil` | Male | Young Adult | EG | A calm, measured Egyptian Arabic voice, even and easy to listen to. |
| `layla` | Female | Adult | EG | A warm, even Egyptian Arabic voice, friendly and easy to listen to. |
| `qadir` | Male | Adult | EG | A warm Egyptian Arabic voice, calm and unhurried. |
| `sakina` | Female | Adult | EG | An even, measured Egyptian Arabic voice, calm and grounded across delivery. |
| `zahir` | Male | Young Adult | EG | A measured Egyptian Arabic voice, calm and grounded throughout. |

## Hindi

2 voices, listed alphabetically. Set `lang` to `hi` for this language.

| Voice | Gender | Age | Country | Description |
| - | - | - | - | - |
| `nadi` | Female | Young Adult | IN | A balanced female voice. |
| `taru` | Male | Adult | IN | A balanced, professional sounding native Hindi speaker. |

## Italian

2 voices, listed alphabetically. Set `lang` to `it` for this language.

| Voice | Gender | Age | Country | Description |
| - | - | - | - | - |
| `livia` | Female | Adult | IT | |
| `viola` | Female | Elder | IT | |


# Mist v3 voices
Source: https://docs.rime.ai/docs/voices-mist-v3

Every Mist v3 voice, grouped by language, with the metadata the public catalog publishes.

The public catalog publishes 78 Mist v3 voices. Pass the value in the Voice column as `speaker`, with `modelId` set to `mistv3` and `lang` set to the tag given in the section you took the voice from.

5 of these voices serve more than one language and appear in more than one section below. The rest serve exactly one, so pairing a voice with a different `lang` is not a supported combination.

**To hear a voice, do not rely on the descriptions here.** Play it in the [Rime dashboard](https://app.rime.ai), or ask an assistant connected to the [hosted MCP server](/docs/mcp) to browse and synthesize a line for you: [`list_voices`](/mcp-reference/list-voices) needs no API key, and [`synthesize_speech`](/mcp-reference/synthesize-speech) uses yours. This page is a reference index for looking up what exists and what it works with.

Use your browser's find command to search by voice name, country, or description. For the machine-readable source, see [the voice details endpoint](/api-reference/data/voice-details).

Switching to Mist v3 from another model? A voice name is not carried by every model. If the voice you use today is not listed below, Mist v3 does not serve it and you need to choose a different one rather than change `modelId` alone.

**Jump to:** [English](#english) · [Spanish](#spanish) · [German](#german) · [French](#french)

## English

62 voices. The 16 featured voices are in the first table, the remaining 46 in the second, each alphabetical. Set `lang` to `en` for this language.

**Featured English voices**

| Voice | Gender | Description |
| - | - | - |
| `astra` | Female | Bright, lively California, quick and expressive. |
| `cove` | Female | An empathetic, friendly African-American voice, warm and approachable. |
| `estelle` | Female | A warm young Southern voice, even and friendly. |
| `lagoon` | Female | A confident, cool young American voice, polished and steady. |
| `luna` | Female | A bright, lively female voice, energetic with a casual core. |
| `mari` | Female | A friendly, professional Caribbean Latina voice, warm and kind. |
| `moon` | Female | A cool African-American voice, polished and steady. |
| `moraine` | Female | A confident, smart young American voice, polished and steady. |
| `peak` | Female | A confident, professional young American voice, polished and steady. |
| `sirius` | Male | A mature Latino-American male voice, low, steady, and grounded. |
| `summit` | Male | A friendly, professional American male voice, warm and polished. |
| `talon` | Male | A serious, professional young American voice, polished and steady. |
| `thunder` | Male | A high-energy American male voice, bright and lively. |
| `tundra` | Female | A confident, upbeat young African-American voice, warm and bright. |
| `vespera` | Female | A friendly, lively young Californian voice, bright and adaptable. |
| `wildflower` | Female | A smart young Asian-American voice, polished and warm. |

<Accordion title="All other English voices (46)">
  | Voice | Gender | Description |
  | - | - | - |
  | `alexis` | Female | A clear, even-keeled female voice. |
  | `alpine` | Male | A friendly young Latino voice, easygoing and approachable. |
  | `bayou` | Male | A friendly, slightly nerdy American voice, warm and approachable. |
  | `blaze` | Male | A polished, professional American voice, confident and steady. |
  | `blossom` | Female | A friendly American female voice, warm and approachable. |
  | `boulder` | Non-binary | A steady young American voice, calm and even-keeled. |
  | `breeze` | Female | A bright young American voice, quick and smart. |
  | `brook` | Male | A confident, soothing African-American voice, warm and steady. |
  | `cedar` | Male | A deep, professional American voice, calm and authoritative. |
  | `creek` | Male | A deep, professional African-American voice, calm and authoritative. |
  | `dew` | Female | A relaxed American female voice, calm and easygoing. |
  | `ember` | Female | A smart young American voice, quick and lightly ironic. |
  | `falcon` | Male | A confident American male voice, steady and authoritative. |
  | `fjord` | Male | A laid-back American male voice, calm and easygoing. |
  | `flower` | Male | A confident, professional African-American voice, warm and steady. |
  | `glacier` | Male | A smart, professional young American voice, polished and steady. |
  | `granite` | Male | A wise, older American male voice, calm and grounded. |
  | `grove` | Female | An upbeat young American voice, bright and friendly. |
  | `gulch` | Male | A confident, serious American male voice, steady and grounded. |
  | `hawk` | Male | A friendly Indian voice, warm and approachable. |
  | `iris` | Female | A deep, upbeat Latina voice, warm and energetic. |
  | `ironwood` | Male | A professional Indian male voice, polished and steady. |
  | `jose` | Male | A grounded Latino male voice, calm and unhurried. |
  | `jungle` | Male | A confident, cool Southern male voice, steady and easygoing. |
  | `karst` | Female | A friendly, youthful American voice, warm and bright. |
  | `loquat` | Male | A confident, laid-back Southern male voice, warm and grounded. |
  | `lotus` | Female | A high-energy Latina voice, bright and lively. |
  | `marsh` | Male | A confident, professional African-American voice, warm and steady. |
  | `mesa` | Female | A confident, professional young American voice, polished and steady. |
  | `pablo` | Male | A friendly, professional Latino voice, warm and kind. |
  | `pearl` | Female | A laid-back, wise older American voice, warm and unhurried. |
  | `petal` | Female | A friendly American female voice, warm and approachable. |
  | `pola` | Female | Withheld pending a catalog correction. |
  | `rain` | Female | A laid-back American female voice, calm and easygoing. |
  | `rainforest` | Female | A friendly, upbeat young Latina voice, warm and lively. |
  | `river` | Male | A laid-back, mysterious young Latino voice, low and unhurried. |
  | `runton` | Male | A steady American male voice, calm and clear. |
  | `spore` | Male | An analytical, professional American male voice, measured and clear. |
  | `steppe` | Female | A friendly, upbeat young American voice, warm and lively. |
  | `stone` | Male | A friendly Latino male voice, warm and steady. |
  | `storm` | Male | A friendly young Latino voice, warm and easygoing. |
  | `stream` | Female | A smart, professional young American voice, polished and steady. |
  | `violet` | Non-binary | A calm American voice, steady and easygoing. |
  | `willow` | Female | A bright, easygoing female voice. |
  | `wolf` | Male | A friendly American male voice, warm and approachable. |
  | `zion` | Male | A grounded African-American male voice, steady and warm. |
</Accordion>

## Spanish

12 voices. The 3 featured voices are in the first table, the remaining 9 in the second, each alphabetical. Set `lang` to `es` for this language.

**Featured Spanish voices**

| Voice | Gender | Description |
| - | - | - |
| `isa` | Female | A friendly, professional Mexican female voice, warm and kind. |
| `pola` | Female | An adult Dominican Spanish female voice, warm and grounded. |
| `seraphina` | Female | A lively Colombian female voice. |

**All other Spanish voices**

| Voice | Gender | Description |
| - | - | - |
| `diego` | Male | A grounded Spanish male voice, calm and unhurried. |
| `dolores` | Female | A warm Latina voice, friendly and professional. |
| `jose` | Male | A grounded Latino male voice, calm and unhurried. |
| `lucia` | Female | Withheld pending a catalog correction. |
| `mari` | Female | A friendly, professional Caribbean Latina voice, warm and kind. |
| `mateo` | Male | A grounded Latino male voice, calm and unhurried. |
| `pablo` | Male | A friendly, professional Latino voice, warm and kind. |
| `sirius` | Male | A mature Latino-American male voice, low, steady, and grounded. |
| `sofia` | Female | A warm young Latina voice, friendly and professional. |

## German

5 voices, listed alphabetically. Set `lang` to `de` for this language.

| Voice | Gender | Description |
| - | - | - |
| `amalia` | Female | A friendly German female voice with a lilting, warm delivery. |
| `frieda` | Female | A smart, professional German female voice, polished and clear. |
| `karolina` | Female | A wry, no-nonsense German female voice, dry and steady. |
| `klaus` | Male | A direct, helpful German-American male voice, steady and clear. |
| `maximilian` | Male | A young German male voice, clear and easygoing. |

## French

4 voices, listed alphabetically. Set `lang` to `fr` for this language.

| Voice | Gender | Description |
| - | - | - |
| `alois` | Male | A friendly, professional French male voice, warm and polished. |
| `juliette` | Female | A friendly, professional French female voice, warm and polished. |
| `marguerite` | Female | A friendly, professional French female voice, warm and polished. |
| `simone` | Female | A warm French female voice, friendly and polished. |


# WebSocket API Overview
Source: https://docs.rime.ai/docs/websockets

Stream Rime TTS in real time over WebSockets for voice agents: choose between /ws3 (recommended JSON), /ws2 (legacy JSON), and /ws (raw binary), with word-level timestamps and interruption handling.

## tl;dr: Use `/ws3`.

`/ws3` is Rime's recommended WebSocket endpoint. It supports all current and future Rime TTS models, delivers the lowest possible TTFB via direct model streaming, and returns audio as structured JSON messages. Unless you have a specific reason to use a legacy endpoint, start here.

## Authentication

All WebSocket endpoints (`/ws`, `/ws2`, `/ws3`) use the same bearer token as the rest of the Rime API. Send `Authorization: Bearer YOUR_API_KEY` as a connection header when establishing the connection, and pass synthesis arguments (`speaker`, `modelId`, `audioFormat`, `lang`, …) as query parameters on the connection URL. See [API authentication](/docs/api-authentication) for how to create a key, and the per-endpoint reference pages below for complete, runnable connection code.

<Warning>
  Send the token in the `Authorization` header; connections without valid credentials are rejected with `401`.

  Your API key is a secret: keep it out of client-side code. The browser `WebSocket` API can't set request headers, so connect from a server-side process (Node, Python, etc.), or proxy the connection through your own backend. The [voice-agent guides](/docs/voice-agent-nextjs#3-stream-over-websockets-when-latency-matters) show a complete browser ↔ server ↔ Rime bridge.
</Warning>

## Choosing an endpoint

Rime offers three WebSocket endpoints.

| | `/ws3` | `/ws2` | `/ws` |
| - | - | - | - |
| **Message format** | JSON | JSON | Raw binary audio |
| **Coda** | ✅ | ❌ | ✅ |
| **Mist v1** | ✅ | ✅ | ✅ |
| **Mist v2** | ✅ | ✅ | ✅ |
| **Mist v3** | ✅ | ❌ | ✅ |
| **Word-level timestamps** | ✅ | ✅ | ❌ |
| **Context IDs** | ✅ | ✅ | ❌ |
| **TTFB optimization** | ✅ Actively optimized | ❌ | ❌ |

***

## `/ws3`: JSON WebSocket (recommended)

```
wss://users-ws.rime.ai/ws3
```

This is the endpoint Rime actively invests in. It supports all current and upcoming Rime TTS models and streams audio as base64-encoded JSON chunks. TTFB is minimized by streaming model responses directly from the engine as they are produced.

**Supported models:**

* `coda`
* `mistv1`, `mistv2`, `mistv3`
* All future Rime TTS models

<Tip>
  If you're onboarding to Rime's WebSocket API for the first time, use `/ws3`. It's the most capable endpoint and the one Rime will continue to extend.
</Tip>

***

## `/ws2`: Legacy JSON WebSocket

```
wss://users-ws.rime.ai/ws2
```

`/ws2` supports the same JSON message format as `/ws3` but is limited to the `mist` model family (v1 and v2) running on Baseten. TTFB is not further optimized beyond what Baseten's infrastructure provides. This endpoint will not receive new model support.

**Supported models:**

* `mistv1`, `mistv2`

<Info>
  `/ws2` is functionally equivalent to `/ws3` for `mist` workloads, but `/ws3` is preferred. Existing integrations using `/ws2` will continue to work.
</Info>

***

## `/ws`: Binary WebSocket (legacy)

```
wss://users-ws.rime.ai/ws
```

`/ws` sends and receives raw audio bytes rather than JSON. It supports a broader model set than `/ws2` but does not benefit from TTFB optimization. This endpoint is suited for clients that need raw PCM/binary audio and cannot handle JSON framing.

**Supported models:**

* `mistv1`, `mistv2`, `mistv3`
* `coda`

<Warning>
  `/ws` returns raw audio bytes with no JSON framing. It does not support word-level timestamps, context IDs, or structured error events. If you need any of these features, use `/ws3` or `/ws2` instead.
</Warning>

***

## Features available on JSON endpoints (`/ws3` and `/ws2`)

### Word-level timestamps

Both JSON endpoints return word-level timing data alongside audio. This is useful for tracking which words have already been spoken, for example, when an end-user interrupts the assistant mid-sentence.

```typescript theme={null}
type TimestampsEvent = {
  type: "timestamps",
  word_timestamps: {
    words: string[],
    start: number[],
    end: number[],
  },
  contextId: string | null,
}
```

### Context IDs

On `/ws3` and `/ws2`, you can attach a `contextId` to any text message and it will be echoed back on the corresponding audio chunk event. This is useful for correlating audio output to specific turns or requests in a multi-turn conversation.

```json theme={null}
{
  "text": "Hello, how can I help you today?",
  "contextId": "turn-001"
}
```

<Info>
  Rime does not maintain multiple simultaneous context IDs. The audio chunk event will carry the most recent context ID that was active at the time the audio was requested. If you send two messages before any audio is synthesized, only the later context ID will be reflected on the first audio chunk. Once set, a context ID also persists across subsequent messages that don't provide one; events keep carrying the previous ID until you send a new one.
</Info>

***

## Operations

In addition to sending text, your client can send structured operation messages to control the synthesis pipeline.

### `flush`

Synthesizes the current text buffer immediately and sends the resulting audio.

```json theme={null}
{ "operation": "flush" }
```

Use `flush` explicitly in `segment=never` mode. See the [Segmentation guide](/docs/websockets-segment) for details.

### `clear`

Discards the accumulated text buffer without synthesizing it. Useful when the user interrupts the assistant and you want to cancel queued speech.

```json theme={null}
{ "operation": "clear" }
```

### `eos` (end of stream)

Synthesizes whatever remains in the buffer, sends a `done` event for that audio, then immediately closes the connection. If the buffer is already empty, the server closes without a `done` event.

```json theme={null}
{ "operation": "eos" }
```

***

## Synthesis completion (`done`)

After all audio for a synthesis batch has been sent, the server emits a `done` event. This is the signal that the current utterance is fully delivered. If the client triggers further synthesis, another `done` will follow.

```typescript theme={null}
type DoneEvent = {
  type: "done",
  contextId: string | null,
}
```

On `/ws2`, the event additionally carries a boolean `done: true` field; match on `type === "done"` to handle both endpoints uniformly.

`done` fires at different points depending on the `segment` setting:

* **`segment=never`**: fires once per `flush`, after all audio for that flush has been sent. `eos` also fires `done` for any content remaining in the buffer.
* **`segment=bySentence` / `segment=immediate`**: fires once per synthesis run, after the last segment completes and the buffer is empty. Intermediate sentence boundaries do not emit `done`.
* **`eos` (all modes)**: emits `done` for any remaining buffered content before closing the connection. If the buffer is empty, the server closes without a `done`; treat socket close as terminal, not just `done`.

See [Segmentation and behavior settings](/docs/websockets-segment) for details on each mode.

***

## Reference & code examples

Each endpoint has a reference page with full message schemas and runnable connection code (Python `websockets`):

| Endpoint | Coda | Mist v3 | Mist v2 |
| - | - | - | - |
| **`/ws3`** (JSON) | [Coda](/api-reference/coda/websockets-json) | [Mist v3](/api-reference/mistv3/websockets-json) | Not supported |
| **`/ws2`** (JSON) | Not supported | Not supported | [Mist v2](/api-reference/mistv2/websockets-json) |
| **`/ws`** (binary) | [Coda](/api-reference/coda/websockets) | [Mist v3](/api-reference/mistv3/websockets) | [Mist v2](/api-reference/mistv2/websockets) |

## Control synthesis timing

The `segment` parameter controls how text is buffered and when synthesis begins.

<Card title="Segmentation & behavior settings" icon="sliders" href="/docs/websockets-segment">
  Compare `segment=never`, `segment=bySentence`, and `segment=immediate`.
</Card>


# Segmentation and behavior settings
Source: https://docs.rime.ai/docs/websockets-segment

Control when synthesis fires over the WebSocket API using segment=never, bySentence, and immediate.

Use `segment=never` for production voice agents that need deterministic synthesis timing. Choose `segment=bySentence` for well-formed prose when automatic punctuation-based buffering is sufficient. Use `segment=immediate` only when your application already sends complete, pre-segmented phrases.

The `segment` query parameter controls how Rime buffers incoming text and when synthesis begins:

| Setting | Default? | Best for |
| - | - | - |
| `segment=never` | No *(recommended)* | Full control; you decide when to synthesize |
| `segment=bySentence` | **Yes** | Sentence-structured text streamed token by token |
| `segment=immediate` | No | Pre-segmented phrases or real-time pass-through |

```
wss://users-ws.rime.ai/ws3?speaker=<voice>&modelId=<model>&segment=<setting>
```

<Info>
  All three settings are available on `/ws`, `/ws2`, and `/ws3`. On `/ws` (binary WebSocket), send the plain-text `<FLUSH>` and `<EOS>` tokens instead of JSON operations.
</Info>

***

## `segment=never`: Recommended

<Tip>
  This is the recommended setting for production voice agents and conversational AI applications. It gives you precise control over synthesis timing and avoids the edge cases and heuristics associated with automatic segmentation.
</Tip>

### How it works

Under `segment=never`, Rime **never synthesizes audio automatically**. It accumulates every token you send into a buffer and waits. Audio is only produced when your client explicitly sends a `flush` operation.

```json theme={null}
{ "operation": "flush" }
```

Once flushed, Rime synthesizes the entire accumulated buffer as a single utterance. If synthesis from a previous flush is still in progress when a new flush arrives, Rime will hold the newly accumulated text and synthesize it as soon as the current synthesis finishes.

### What you are responsible for

1. **Sending well-formed, concatenable tokens.** If someone concatenated every token you send, the result should be a properly spaced, punctuated utterance. For example:

   ```
   ["Hello, ", "how ", "can ", "I ", "help ", "you ", "today?"]
   → "Hello, how can I help you today?"  ✅
   ```

   Avoid sending tokens that, when joined, produce malformed text:

   ```
   ["Hello,", "how", "can"]
   → "Hello,howcan"  ❌  (missing spaces)
   ```

2. **Sending `flush` when you're done with an utterance.** This is your signal to Rime that the buffer contains a complete, speakable phrase.

### What Rime is responsible for

* Synthesizing audio whenever a `flush` is received.
* Queuing the buffer for synthesis if the previous utterance is still being produced.
* Never synthesizing mid-stream without your explicit instruction.
* Sending a `done` event after all audio for a `flush` has been delivered. A `flush` on an empty buffer produces nothing, and flushes that arrive while synthesis is still running are coalesced into a single synthesis with a single `done`, so do not count `done` events against `flush` events. `eos` also emits `done` for any content remaining in the buffer.

### Example

```python theme={null}
import asyncio
import json
import websockets
import base64

API_KEY = "your-api-key"
URL = "wss://users-ws.rime.ai/ws3?speaker=astra&modelId=coda&segment=never"

async def run():
    async with websockets.connect(URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}) as ws:
        # Stream an LLM response token by token
        tokens = ["Sure, ", "I'd ", "be ", "happy ", "to ", "help ", "with ", "that."]
        for token in tokens:
            await ws.send(json.dumps({"text": token}))

        # Tell Rime to synthesize everything accumulated so far
        await ws.send(json.dumps({"operation": "flush"}))

        # Receive and play audio chunks
        while True:
            msg = json.loads(await ws.recv())
            if msg["type"] == "chunk":
                audio = base64.b64decode(msg["data"])
                # stream audio to your player...
            elif msg["type"] == "timestamps":
                print("Timestamps:", msg["word_timestamps"])

asyncio.run(run())
```

### Handling interruptions

If your user interrupts the assistant while audio is playing, send a `clear` operation to discard text that has not yet been submitted for synthesis. `clear` does not cancel an in-flight synthesis and does not drop text already queued by an earlier `flush`; stop playback client-side, and close the connection if you need a hard stop:

```json theme={null}
{ "operation": "clear" }
```

Then begin streaming your new response tokens immediately.

***

## `segment=bySentence`: Default

This is the default behavior when `segment` is not specified. Rime buffers tokens and synthesizes audio each time it detects a sentence or phrase boundary in the accumulated text.

### How it works

Rime watches the incoming token stream for sentence-ending punctuation: `.`, `?`, `!`. When one is encountered and no audio is currently being synthesized, Rime synthesizes everything up to that boundary and sends the audio back.

### What you are responsible for

1. **Separating sentences with spaces.** Tokens sent without trailing spaces can cause words to run together after concatenation.

2. **Not splitting tokens at sentence-ending punctuation.** Rime's heuristics fire on received tokens. If a single token ends with sentence-ending punctuation in the middle of what should be a larger phrase (e.g., `"2."` in `"2.5ml"`), it may trigger an early synthesis.

   ```
   ❌  tokens = ["take ", "2.", "5ml ", "of ", "the ", "solution."]
   ✅  tokens = ["take ", "2.5ml ", "of ", "the ", "solution."]
   ```

### What Rime is responsible for

* Accumulating tokens until a sentence boundary is detected.
* Synthesizing the buffer at that boundary, **only if no audio is currently being produced**.
* Using heuristics to determine whether a given punctuation mark constitutes a sentence end.
* Sending a `done` event once per synthesis run, after the last segment has been delivered and the text buffer is empty. Intermediate sentence boundaries within a run do **not** emit `done`.

### When to use this

`segment=bySentence` works well when you're streaming text with clean sentence boundaries and no numbers or abbreviations that could confuse the period heuristic. It requires less client-side coordination than `segment=never` but is less predictable in edge cases.

<Warning>
  `segment=bySentence` relies on heuristics. Text with decimal numbers, abbreviations (e.g. `Dr.`, `2.5ml`), or mid-sentence ellipses can cause early synthesis. For production voice agents, consider `segment=never` for more reliable control.
</Warning>

### Example

```python theme={null}
import asyncio
import json
import websockets
import base64

API_KEY = "your-api-key"
# segment=bySentence is the default, but shown explicitly here for clarity
URL = "wss://users-ws.rime.ai/ws3?speaker=cove&modelId=mistv3&segment=bySentence"

async def run():
    async with websockets.connect(URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}) as ws:
        sentences = [
            "The weather today is sunny. ",
            "Temperatures will reach the mid-seventies. ",
            "Enjoy the sunshine!",
        ]
        for sentence in sentences:
            await ws.send(json.dumps({"text": sentence}))

        await ws.send(json.dumps({"operation": "eos"}))

        while True:
            try:
                msg = json.loads(await ws.recv())
            except websockets.exceptions.ConnectionClosedOK:
                break
            if msg["type"] == "chunk":
                audio = base64.b64decode(msg["data"])
                # stream to player...

asyncio.run(run())
```

***

## `segment=immediate`: Synthesize on receipt

Under `segment=immediate`, Rime synthesizes audio as soon as text arrives in the buffer, provided no audio is currently being produced.

### How it works

Each time Rime receives a text message and the synthesis pipeline is idle, it synthesizes whatever is in the buffer immediately. If synthesis is already in progress, incoming tokens continue to accumulate. Once the current synthesis finishes, Rime flushes the entire accumulated buffer as a single utterance.

### What you are responsible for

1. **Sending complete, speakable phrases.** Because Rime may synthesize on the very first token it receives, each message, or the concatenation of messages received while synthesis is busy, should form something that sounds natural when spoken on its own.

2. **Ensuring concatenated tokens are properly spaced and formatted.** When multiple tokens arrive during an active synthesis, they'll be joined and synthesized together. The same concatenation rules apply as in `segment=never`.

### What Rime is responsible for

* Synthesizing immediately upon receiving text when the pipeline is idle.
* Accumulating tokens while synthesis is active, then synthesizing the full buffer once idle again.
* Sending a `done` event once per synthesis run, after the last segment has been delivered and the buffer is empty.

### When to use this

`segment=immediate` is useful when your client sends complete, pre-segmented utterances and you want Rime to synthesize each one without punctuation-based logic.

### Example

```python theme={null}
import asyncio
import json
import websockets
import base64

API_KEY = "your-api-key"
URL = "wss://users-ws.rime.ai/ws3?speaker=astra&modelId=coda&segment=immediate"

async def run():
    async with websockets.connect(URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}) as ws:
        # Each message is already a complete phrase
        phrases = [
            "Your order has been confirmed.",
            "It will arrive within three to five business days.",
            "Is there anything else I can help you with?",
        ]
        for phrase in phrases:
            await ws.send(json.dumps({"text": phrase}))
            await asyncio.sleep(0.05)  # small delay to allow synthesis to start

        await ws.send(json.dumps({"operation": "eos"}))

        while True:
            try:
                msg = json.loads(await ws.recv())
            except websockets.exceptions.ConnectionClosedOK:
                break
            if msg["type"] == "chunk":
                audio = base64.b64decode(msg["data"])
                # stream to player...

asyncio.run(run())
```

***

## Related

<Columns>
  <Card title="WebSocket API Overview" icon="plug" href="/docs/websockets">
    Compare `/ws3`, `/ws2`, and `/ws` endpoints and understand their capabilities.
  </Card>

  <Card title="Latency" icon="gauge-simple-max" href="/docs/latency">
    Understand the factors that affect TTFB and how to minimize them.
  </Card>
</Columns>


# Build real-time voice experiences
Source: https://docs.rime.ai/index

Generate natural speech, build responsive voice agents, and run Rime in production.

<div>
  <div>
    # Build real-time voice experiences

    <p>
      Generate natural speech, build responsive voice agents, and run Rime in production.
    </p>

    <div>
      <a href="/docs/quickstart-five-minute">
        Generate your first audio
      </a>

      <a href="/docs/voice-agents">
        Build a voice agent
      </a>

      <a href="/docs/voices">
        Explore voices & models
      </a>
    </div>

    <p>
      Need a key? Create an API token in the <a href="https://app.rime.ai/tokens">Rime dashboard</a>.
    </p>
  </div>

  <div>
    <div>
      <p>First request</p>
      <h2>Go from text to audio</h2>

      <p>
        Set <code>RIME\_API\_KEY</code>, run one of these examples, and play the generated <code>hello.mp3</code> file. If you hear "Hello from Rime," your key and request both work.
      </p>
    </div>

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url https://users.rime.ai/v1/rime-tts \
        --header "Authorization: Bearer $RIME_API_KEY" \
        --header "Content-Type: application/json" \
        --header "Accept: audio/mpeg" \
        --fail \
        --show-error \
        --output hello.mp3 \
        --data '{
          "speaker": "astra",
          "text": "Hello from Rime.",
          "modelId": "coda",
          "lang": "en"
        }'
      ```

      ```python Python theme={null}
      import os
      import requests

      response = requests.post(
          "https://users.rime.ai/v1/rime-tts",
          headers={
              "Authorization": f"Bearer {os.environ['RIME_API_KEY']}",
              "Accept": "audio/mpeg",
          },
          json={
              "speaker": "astra",
              "text": "Hello from Rime.",
              "modelId": "coda",
              "lang": "en",
          },
      )
      response.raise_for_status()

      with open("hello.mp3", "wb") as audio:
          audio.write(response.content)
      ```

      ```javascript JavaScript theme={null}
      // Save as hello.mjs so Node runs it as an ES module.
      import { writeFile } from "node:fs/promises";

      const response = await fetch("https://users.rime.ai/v1/rime-tts", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.RIME_API_KEY}`,
          "Content-Type": "application/json",
          Accept: "audio/mpeg",
        },
        body: JSON.stringify({
          speaker: "astra",
          text: "Hello from Rime.",
          modelId: "coda",
          lang: "en",
        }),
      });

      if (!response.ok) throw new Error(`Rime API error: ${response.status}`);
      await writeFile("hello.mp3", Buffer.from(await response.arrayBuffer()));
      ```
    </CodeGroup>

    <p>
      <a href="/docs/quickstart-five-minute">TTS in five minutes</a> is the complete walkthrough. The <a href="/docs/quickstart-cli">Rime CLI</a> covers the same steps from the terminal.
    </p>
  </div>

  <div>
    <p>Choose what you're building</p>
    <h2>Start with the path that matches your application</h2>

    <p>
      Rime exposes one HTTP and WebSocket API surface.
    </p>

    <div>
      <Columns>
        <Card title="Add speech to an application" icon="wave-sine" href="/docs/quickstart-five-minute">
          Generate speech over HTTP, stream the response, and play it in your application.
        </Card>

        <Card title="Build a real-time voice agent" icon="microphone-lines" href="/docs/voice-agents">
          Connect Rime to an STT, LLM, and audio transport for responsive conversations.
        </Card>

        <Card title="Deploy on your infrastructure" icon="server" href="/docs/on-prem/quickstart">
          Run Rime privately with Docker Compose or Kubernetes.
        </Card>
      </Columns>
    </div>
  </div>

  <div>
    <p>Developer journey</p>
    <h2>From first audio to production</h2>

    <p>
      Follow the lifecycle or jump directly to the problem you're solving.
    </p>

    <div>
      <div>
        <div>
          <Icon icon="rocket" />

          <h3>Get started</h3>
        </div>

        <div>
          <a href="/docs/quickstart-five-minute">Generate your first audio</a>
          <a href="https://app.rime.ai/tokens">Create an API token</a>
          <a href="/docs/api-authentication">Authenticate requests</a>
          <a href="/docs/voices">Choose a voice</a>
        </div>
      </div>

      <div>
        <div>
          <Icon icon="code" />

          <h3>Build</h3>
        </div>

        <div>
          <a href="/docs/streaming">Stream audio over HTTP</a>
          <a href="/docs/websockets">Use WebSockets</a>
          <a href="/docs/quickstart-livekit">Build with LiveKit</a>
          <a href="/docs/pipecat">Integrate with Pipecat</a>
        </div>
      </div>

      <div>
        <div>
          <Icon icon="sliders" />

          <h3>Customize</h3>
        </div>

        <div>
          <a href="/docs/models">Choose a model</a>
          <a href="/docs/prompting">Guide delivery with prompts</a>
          <a href="/platform/pronunciation-control">Control pronunciation</a>
          <a href="/docs/text-normalization">Format text</a>
        </div>
      </div>

      <div>
        <div>
          <Icon icon="gauge-simple-max" />

          <h3>Operate</h3>
        </div>

        <div>
          <a href="/docs/latency">Reduce latency</a>
          <a href="/docs/regional-endpoints">Select a region</a>
          <a href="/docs/on-prem/quickstart">Deploy on-prem</a>
          <a href="/docs/privacy-compliance">Review privacy and compliance</a>
        </div>
      </div>
    </div>
  </div>

  <div>
    <p>Models and voices</p>
    <h2>Choose a model and voice</h2>

    <p>
      Voice availability depends on the model and language, so compare models first.
    </p>

    <div>
      <Columns>
        <Card title="Compare models" icon="layer-group" href="/docs/models">
          Understand the tradeoffs across Coda and Mist before choosing a model ID.
        </Card>

        <Card title="Browse voices" icon="headphones" href="/docs/voices">
          Explore the voice catalog and find voices available for your model and language.
        </Card>
      </Columns>
    </div>
  </div>

  <div>
    <p>Resources</p>
    <h2>Reference and tooling</h2>

    <div>
      <Columns>
        <Card title="API reference" icon="brackets-curly" href="/docs/api-reference">
          Endpoints, parameters, formats, and examples.
        </Card>

        <Card title="API cheat sheet" icon="rectangle-list" href="/docs/api-cheat-sheet">
          Common requests and endpoints on one page.
        </Card>

        <Card title="CLI" icon="terminal" href="/docs/quickstart-cli">
          Generate and inspect audio from your terminal.
        </Card>

        <Card title="MCP server" icon="robot" href="/docs/mcp">
          Use Rime from Claude, Codex, and compatible IDEs.
        </Card>
      </Columns>
    </div>
  </div>
</div>


# Playing audio
Source: https://docs.rime.ai/mcp-reference/audio

How audio from synthesize_speech reaches your speakers: inline player, play URL, or MCP audio block.

[`synthesize_speech`](/mcp-reference/synthesize-speech) delivers audio three ways, so samples play regardless of the host:

## 1. Inline player

Hosts that support MCP Apps (such as Claude) render an audio player directly in the conversation. The MP3 travels outside the model's context, so playback costs no tokens. This is the default and needs no configuration.

## 2. Play URL

Rime's MCP server includes a short-lived link in every result, also available at `structuredContent.audioUrl`. Terminal and agent hosts (such as Claude Code or OpenAI Codex) can download and play it with a system audio player:

```bash theme={null}
curl -s <audioUrl> -o /tmp/rime.mp3 && \
  (afplay /tmp/rime.mp3 || ffplay -nodisp -autoexit /tmp/rime.mp3 || mpv /tmp/rime.mp3)
```

`afplay` ships with macOS. On Linux, use `ffplay`, `mpv`, `aplay`, or `paplay`. The link expires shortly after generation, so play it promptly. If it has expired, synthesize again.

## 3. MCP audio block

Pass `include_audio: true` to also receive a standard MCP `audio` content block (base64 MP3) for hosts that play audio natively. This adds the audio to the model's context, so prefer the inline player or play URL when either works.

## Hosts without audio support

Hosts that render none of these still get a text summary and the structured result. The call succeeds, but you won't hear the sample.


# Authentication
Source: https://docs.rime.ai/mcp-reference/authentication

How Rime's MCP server resolves API keys: accepted headers, per-request handling, and which tools work without a key.

The MCP server is stateless and never stores your credentials. Instead, it reads your API key from each request and forwards it to the Rime API. Get a key from the [API Tokens page](https://app.rime.ai/tokens). It's the same key you use for the [REST API](/docs/api-authentication).

## Accepted headers

The MCP server accepts two headers and checks them in this order:

| Header | Notes |
| - | - |
| `Authorization: Bearer <key>` | Preferred |
| `X-Rime-Api-Key: <key>` | Convenience alternative for clients that reserve the `Authorization` header |

## Tools that work without a key

| Tool | API key |
| - | - |
| [`list_voices`](/mcp-reference/list-voices) | Not required |
| [`get_voice_details`](/mcp-reference/get-voice-details) | Not required |
| [`generate_integration`](/mcp-reference/generate-integration) | Not required |
| [`check_dictionary`](/mcp-reference/check-dictionary) | Required |
| [`normalize_text`](/mcp-reference/normalize-text) | Required |
| [`synthesize_speech`](/mcp-reference/synthesize-speech) | Required |

If you call a key-gated tool without a key, the MCP server returns a pointer to [sign up](https://app.rime.ai/signup/) rather than an error. Without a key you can still explore the catalog and generate integration code.

<Note>[`synthesize_speech`](/mcp-reference/synthesize-speech) calls the Rime API with your key, so generated samples consume credits like any other API request.</Note>


# check_dictionary
Source: https://docs.rime.ai/mcp-reference/check-dictionary

Check which words are not in Rime's pronunciation dictionary via the MCP server.

Check which words are **not** in Rime's pronunciation dictionary. Returns the list of out-of-dictionary words, or an empty list if all words are covered. Out-of-dictionary words still synthesize, but you may want to add [custom pronunciations](/docs/custom-pronunciation) for them.

**API key:** Required. See [Authentication](/mcp-reference/authentication).

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `text` | string | Yes | Words to check, separated by spaces, commas, or newlines |

## Example

Ask your assistant:

```
Which words in this IVR script aren't in Rime's dictionary?
```

The assistant runs the script through `check_dictionary` and flags anything out-of-dictionary. Pair it with [`normalize_text`](/mcp-reference/normalize-text) to preview how the rest of the script will be spoken, or use the [`check_script_pronunciation`](/mcp-reference/prompts) starter prompt, which does both.

## Related

* [Pronunciation control](/platform/pronunciation-control): all the ways to control pronunciation
* [Coverage API](/api-reference/other/oov): the underlying REST endpoint


# Connecting
Source: https://docs.rime.ai/mcp-reference/connect

Connect Claude Code, Claude.ai, Claude Desktop, OpenAI Codex, or any MCP-compatible client to Rime's hosted MCP server.

The connector URL is `https://mcp.rime.ai`. The server speaks stateless Streamable HTTP, and both the root URL and `https://mcp.rime.ai/mcp` serve the MCP endpoint. Use whichever your client expects.

You can connect without any credentials to browse the voice catalog and generate integration code. To use synthesis and the linguistics tools, add your API key. See [Authentication](/mcp-reference/authentication).

## Claude Code

```bash theme={null}
claude mcp add --transport http rime https://mcp.rime.ai \
  --header "Authorization: Bearer $RIME_API_KEY"
```

Omit the `--header` flag to connect without a key.

## Claude.ai and Claude Desktop

In Claude, open **Settings → Connectors**, select **Add custom connector**, and enter `https://mcp.rime.ai`.

## OpenAI Codex

```bash theme={null}
codex mcp add rime --url https://mcp.rime.ai \
  --bearer-token-env-var RIME_API_KEY
```

You can also add the server to `~/.codex/config.toml` directly. The Codex IDE extension reads the same file, so one entry covers both:

```toml theme={null}
[mcp_servers.rime]
url = "https://mcp.rime.ai"
bearer_token_env_var = "RIME_API_KEY"
```

Codex reads the key from the `RIME_API_KEY` environment variable rather than storing it in the config. Omit `--bearer-token-env-var` (or the `bearer_token_env_var` line) to connect without a key.

## Other MCP clients

For clients that use a JSON configuration (Cursor, Windsurf, and others), this entry connects with your key in the `Authorization` header:

```json theme={null}
{
  "mcpServers": {
    "rime": {
      "url": "https://mcp.rime.ai",
      "headers": {
        "Authorization": "Bearer YOUR_RIME_API_KEY"
      }
    }
  }
}
```

This file holds your key in plain text, so keep it out of version control. Remove the `headers` block to connect without a key.

## Verify the connection

Ask your assistant to list Rime's voices, or call `list_voices` directly. It needs no API key, so it confirms connectivity regardless of how you authenticated. To check the key too, ask for a [`normalize_text`](/mcp-reference/normalize-text) preview: if it returns a sign-up pointer instead of normalized text, the server didn't receive your key.


# generate_integration
Source: https://docs.rime.ai/mcp-reference/generate-integration

Generate ready-to-run Pipecat or LiveKit voice-agent code wired to Rime TTS via the MCP server.

Generate a ready-to-run code snippet for wiring Rime TTS into a voice-agent framework ([Pipecat](/docs/pipecat) or [LiveKit](/docs/livekit)). Returns install commands, working code, and `.env` notes. The tool runs entirely on Rime's MCP server, so it makes no call to the Rime API and consumes no credits.

**API key:** Not required.

## Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `framework` | string | Yes | None | `pipecat` or `livekit` |
| `language` | string | No | `python` | `python` or `node`. Only affects LiveKit, because Pipecat is Python-only |
| `model` | string | No | `coda` | Rime model ID for the generated config |
| `speaker` | string | No | `lyra` | Rime speaker name for the generated config |
| `mode` | string | No | `plugin` | LiveKit only: `plugin` uses your own Rime key, while `inference` runs on LiveKit Cloud with no Rime key |

## Example

Ask your assistant:

```
Generate LiveKit starter code for a voice agent using the coda model and the astra voice.
```

The assistant emits a complete, runnable agent. The request doesn't name a language or mode, so the code uses the defaults: Python with the LiveKit plugin and your own Rime key. To pick the voice with the assistant first, use the [`build_voice_agent`](/mcp-reference/prompts) starter prompt.

## Related

* [Pipecat integration guide](/docs/pipecat)
* [LiveKit integration guide](/docs/livekit) and the [LiveKit quickstart](/docs/quickstart-livekit)


# get_voice_details
Source: https://docs.rime.ai/mcp-reference/get-voice-details

Get Rime voice metadata for gender, age, accent, country, genre, model, and language through the MCP server.

Return metadata for Rime voices: gender, age, accent/dialect, country, genre, model, and language. This is where the `lang` value for [`synthesize_speech`](/mcp-reference/synthesize-speech) comes from. All filters are optional.

**API key:** Not required.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `speaker` | string | No | Filter to a speaker name, e.g. `astra` |
| `model` | string | No | Filter to a model ID, e.g. `coda` |
| `gender` | string | No | Filter by gender, e.g. `female` |
| `language` | string | No | Filter by language, matching either the `language` or `lang` field, e.g. `eng` |

## Example

Ask your assistant:

```
Find me a warm, conversational female voice for a customer support agent.
```

The assistant filters the catalog with `get_voice_details`, compares the demographic metadata, and can audition candidates with [`synthesize_speech`](/mcp-reference/synthesize-speech).

## Related

* [`list_voices`](/mcp-reference/list-voices): the catalog grouped by model and language
* [Voice details API](/api-reference/data/voice-details): the underlying REST endpoint


# list_voices
Source: https://docs.rime.ai/mcp-reference/list-voices

List Rime's voice catalog by model and language via the MCP server.

List Rime's voice catalog as JSON keyed by model and language: `{ modelId: { langCode: [speaker, ...] } }`. Optionally filter by model and/or language, and cap the output size with `limit`. Use [`get_voice_details`](/mcp-reference/get-voice-details) for demographics and the exact `lang` value to pass to [`synthesize_speech`](/mcp-reference/synthesize-speech).

**API key:** Not required.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | No | Filter to a single model ID, e.g. `coda` |
| `language` | string | No | Filter to an ISO 639-2 language key, e.g. `eng` |
| `limit` | integer | No | Maximum speakers returned per model+language list. When a list is truncated, the result notes how many speakers were omitted and how to see the rest. |

## Example

Ask your assistant:

```
What Spanish-speaking Coda voices does Rime have?
```

The assistant calls `list_voices` with `model: "coda"` and `language: "spa"` and reads the speaker names from the result.

## Related

* [`get_voice_details`](/mcp-reference/get-voice-details): demographics for choosing between voices
* [Voices guide](/docs/voices): the full catalog with audio samples
* [Voices API](/api-reference/data/voices-v2): the underlying REST endpoint


# normalize_text
Source: https://docs.rime.ai/mcp-reference/normalize-text

Preview how Rime normalizes text before synthesis via the MCP server.

Preview how Rime normalizes text before synthesis: the result is exactly what the TTS model will speak. Useful for debugging numbers, dates, phone numbers, currency, and abbreviations. Returns the normalized string.

**API key:** Required. See [Authentication](/mcp-reference/authentication).

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `text` | string | Yes | The text to normalize |

## Example

Ask your assistant:

```
How will Rime read "Your appointment is on 3/4 at 2:30pm, call 555-0123 to reschedule"?
```

The assistant calls `normalize_text` and shows the spoken form, so you can catch surprises (like `3/4` reading as a date versus a fraction) before synthesis.

## Related

* [Text normalization guide](/docs/text-normalization): how Rime handles numbers, dates, and more
* [Normalization API](/api-reference/other/textnorm): the underlying REST endpoint


# Overview
Source: https://docs.rime.ai/mcp-reference/overview

Rime's hosted MCP server: connect AI assistants to the voice catalog, linguistics tools, speech synthesis, and integration scaffolding.

Rime hosts a first-party [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server at [mcp.rime.ai](https://mcp.rime.ai). You can browse voices, check pronunciation coverage, preview text normalization, generate speech samples, and scaffold voice-agent integrations from a single conversation in Claude, OpenAI Codex, your IDE, or another MCP-compatible client.

## Server URL

```
https://mcp.rime.ai
```

The server speaks stateless Streamable HTTP. Both the root URL and `https://mcp.rime.ai/mcp` serve the MCP endpoint. Use whichever your client expects. See [Connecting](/mcp-reference/connect) for client-by-client setup.

## Tools

<CardGroup>
  <Card title="list_voices" icon="list" href="/mcp-reference/list-voices">
    List the voice catalog, filterable by model and language. No API key.
  </Card>

  <Card title="get_voice_details" icon="circle-info" href="/mcp-reference/get-voice-details">
    Voice metadata: gender, age, accent, country, and the `lang` value for synthesis. No API key.
  </Card>

  <Card title="check_dictionary" icon="spell-check" href="/mcp-reference/check-dictionary">
    Find words not in Rime's pronunciation dictionary.
  </Card>

  <Card title="normalize_text" icon="text" href="/mcp-reference/normalize-text">
    Preview exactly what the TTS model will speak.
  </Card>

  <Card title="synthesize_speech" icon="waveform" href="/mcp-reference/synthesize-speech">
    Generate an MP3 sample with an inline audio player.
  </Card>

  <Card title="generate_integration" icon="code" href="/mcp-reference/generate-integration">
    Emit ready-to-run Pipecat or LiveKit code. No API key.
  </Card>
</CardGroup>

## Learn more

<CardGroup>
  <Card title="Connecting" icon="plug" href="/mcp-reference/connect">
    Set up Claude Code, Claude.ai, OpenAI Codex, and other MCP clients
  </Card>

  <Card title="Authentication" icon="key" href="/mcp-reference/authentication">
    Per-request API keys, accepted headers, and which tools work without one
  </Card>

  <Card title="Playing audio" icon="volume-high" href="/mcp-reference/audio">
    How synthesized samples reach your speakers in UI and terminal hosts
  </Card>

  <Card title="Starter prompts" icon="wand-magic-sparkles" href="/mcp-reference/prompts">
    Optional shortcuts surfaced by clients that support MCP prompts
  </Card>
</CardGroup>

<Note>The MCP server is built for exploration and prototyping. It generates complete audio samples rather than streaming. For production voice agents, use the [streaming APIs](/docs/streaming) directly, or ask [`generate_integration`](/mcp-reference/generate-integration) for working [Pipecat](/docs/pipecat) or [LiveKit](/docs/livekit) starter code.</Note>


# Starter prompts
Source: https://docs.rime.ai/mcp-reference/prompts

Optional MCP prompts that drive Rime's tools: find a voice, check a script, or scaffold a voice agent.

Clients that surface MCP prompts (notably Claude.ai) show three starters that drive the [tools](/mcp-reference/overview#tools). They're optional shortcuts: every tool works from a plain conversation without them.

## find\_a\_voice

Recommend and sample Rime voices for a use case.

| Argument | Required | Description |
| - | - | - |
| `description` | No | e.g. "warm female American, conversational" |

## check\_script\_pronunciation

Flag out-of-dictionary words and preview normalization for a script, using [`check_dictionary`](/mcp-reference/check-dictionary) and [`normalize_text`](/mcp-reference/normalize-text).

| Argument | Required | Description |
| - | - | - |
| `text` | Yes | The script to check |

## build\_voice\_agent

Scaffold a real-time voice agent using Rime TTS, via [`generate_integration`](/mcp-reference/generate-integration).

| Argument | Required | Description |
| - | - | - |
| `framework` | No | `livekit` or `pipecat` |
| `use_case` | No | What the agent is for |


# synthesize_speech
Source: https://docs.rime.ai/mcp-reference/synthesize-speech

Generate an MP3 speech sample with Rime TTS via the MCP server, rendered in an inline audio player.

Generate an MP3 speech sample from text. With no arguments, the tool plays a default sample in the demo voice (`lyra` on **Coda**, Rime's flagship model). Choose a `speaker` and `modelId` from [`list_voices`](/mcp-reference/list-voices) and [`get_voice_details`](/mcp-reference/get-voice-details).

**API key:** Required. See [Authentication](/mcp-reference/authentication). Samples consume credits like any other API request, so keep sample text short.

## Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `text` | string | No | A short demo line | Text to synthesize (max 2,000 characters) |
| `speaker` | string | No | `lyra` | Voice name from [`list_voices`](/mcp-reference/list-voices) |
| `modelId` | string | No | `coda` | Model ID: `coda` or `mistv3` |
| `language` | string | No | None | Sent as `lang` only if provided (e.g. `eng`, the value from [`get_voice_details`](/mcp-reference/get-voice-details)). Omit to let Rime infer the language from the speaker |
| `include_audio` | boolean | No | `false` | Also return the audio as a standard MCP audio content block (base64), for hosts that play audio natively. Adds the audio to the model's context |

## Returns

The tool delivers audio three ways so it plays regardless of the host: an inline player in UI hosts, a short-lived play URL (`structuredContent.audioUrl`) for terminal hosts, and an optional audio content block. See [Playing audio](/mcp-reference/audio).

## Example

Ask your assistant:

```
Play me a sample of the astra voice saying "Thanks for calling, how can I help?"
```

The assistant calls `synthesize_speech` with `speaker: "astra"` and your text. If no player appears, see [Playing audio](/mcp-reference/audio) for how your host receives the sample.

## Related

* [Playing audio](/mcp-reference/audio): how samples reach your speakers in each host
* [Models](/docs/models): compare Coda, Mist v3, and Mist v2
* [Streaming APIs](/docs/streaming): production synthesis


# Pronunciation control
Source: https://docs.rime.ai/platform/pronunciation-control

Check dictionary coverage, specify custom pronunciations, and request dictionary additions to control exactly how Rime speaks your words.

Pronunciation control makes sure brand names, product names, and domain-specific words sound right before they reach your users.

There are three ways to control pronunciation:

1. **Check dictionary coverage** to see whether a word is already pronounced correctly out of the box.
2. **Specify a custom pronunciation inline** using the Rime phonetic alphabet.
3. **Request a dictionary addition** from the Rime team.

***

## Check dictionary coverage

Use the [Coverage API](/api-reference/other/oov) to find words that are not yet in Rime's pronunciation dictionary. The model still predicts a pronunciation for uncovered words, often correctly when the spelling follows common patterns. Verify uncommon words before they reach end users.

## Specify a custom pronunciation inline

<Warning>
  [`phonemizeBetweenBrackets`](/docs/custom-pronunciation) works on **Mist v1, Mist v2, and English Mist v3**. It is not supported on Coda or non-English Mist v3.
</Warning>

For Mist v1 and Mist v2, add inline phonetic strings with the [Rime phonetic alphabet](/platform/rime-phonetic-alphabet). Write the string by hand or generate one from a recording with the [Phonemize API](/api-reference/other/phonemize).

See [Custom pronunciation](/docs/custom-pronunciation) for the full reference.

### Generate the phonetic string from audio

Record the word (or synthesize it) and post the raw audio to the [Phonemize API](/api-reference/other/phonemize).

```bash theme={null}
curl -X POST https://optimize.rime.ai/phonemize \
     -H "Authorization: Bearer $RIME_API_KEY" \
     -H "Content-Type: audio/wav" \
     --data-binary @speech.wav
```

The response contains the phonetic transcription of the audio:

```json theme={null}
{
  "audioId": "9b2d8ad2-0618-4e96-b255-98b2f7488061",
  "phonemeString": "h0El1o !",
  "authed": 1
}
```

Drop any trailing punctuation token, then paste the string into your TTS request inside curly brackets with `phonemizeBetweenBrackets: true`. For example: `{h0El1o}`.

For brand or product names on Coda, request a dictionary addition or respell the word in plain English. Respelling is approximate.

## Request a dictionary addition

If a word is mispronounced and you'd like it fixed at the dictionary level, reach out to your account manager via Slack or email, or contact [sales@rime.ai](mailto:sales@rime.ai). Rime's linguists typically review and add new words within one week.

***

## What to check first

* Brand names, technical terms, and made-up words are the most common sources of mispronunciation; verify these first.
* Re-check coverage whenever you add new or domain-specific content.
* For flows where pronunciation control matters most, use a Mist-family model (v2, or English v3) so you can correct pronunciations inline.


# Rime phonetic alphabet
Source: https://docs.rime.ai/platform/rime-phonetic-alphabet

Reference for Rime's phonetic alphabet used to specify custom pronunciations on Mist models.

<Note>Custom pronunciation is supported on **Mist v1, Mist v2, and English Mist v3**. Coda and non-English Mist v3 do not support `phonemizeBetweenBrackets`.</Note>

Rime uses its own phonetic alphabet, inspired by the International Phonetic Alphabet (IPA), to let you specify exactly how a word should sound. You provide a phonetic string inside curly brackets and set `phonemizeBetweenBrackets: true` on the request. For the full request mechanic, see [Custom pronunciation](/docs/custom-pronunciation).

For example, the word `custom` is represented as `{k1Ast0xm}`. Even made-up words work; `gorbulets` becomes `{g1orby0ul2Ets}`.

## Vowels

| Symbol | Use in an English word |
| - | - |
| @ | b**a**t |
| a | h**o**t |
| A | b**u**tt |
| W | ab**ou**t |
| x | comm**a** |
| Y | b**i**te |
| E | b**e**t |
| R | b**ir**d, forew**or**d |
| e | b**ai**t |
| I | b**i**t |
| i | b**ea**t |
| o | b**oa**t |
| O | b**oy** |
| U | b**oo**k |
| u | b**oo**t |
| N | butt**on** |

## Consonants

| Symbol | Use in an English word |
| - | - |
| b | **b**uy |
| C | **Ch**ina |
| d | **d**ie |
| D | **th**y |
| f | **f**ight |
| g | **g**uy |
| h | **h**igh |
| J | **j**ive |
| k | **k**ite |
| l | **l**ie |
| m | **m**y |
| n | **n**igh |
| G | si**ng** |
| p | **p**ie |
| r | **r**ye |
| s | **s**igh |
| S | **sh**y |
| t | **t**ie |
| T | **th**igh |
| v | **v**ie |
| w | **w**ise |
| y | **y**acht |
| z | **z**oo |
| Z | plea**s**ure |

## Stress

For **primary stress**, put `1` before the relevant vowel. For example, `comma` is `{k1am0x}`.

For **secondary stress**, put `2` in front of the relevant vowel. For example, `auctioneer` is `{2akS0In1ir}`.

All other vowels should have a `0` in front of them.

## Generating a string automatically

Post a recording of the word to the [Phonemize API](/api-reference/other/phonemize) and it returns a transcription in this alphabet, stress markers included:

```bash theme={null}
curl -X POST https://optimize.rime.ai/phonemize \
     -H "Authorization: Bearer $RIME_API_KEY" \
     -H "Content-Type: audio/wav" \
     --data-binary @speech.wav
# => {"audioId": "...", "phonemeString": "h0El1o !", "authed": 1}
```

Strip any trailing punctuation token from `phonemeString`, then use the symbol tables above to fine-tune the result if a vowel or stress placement isn't quite right.

## Related

* [Custom pronunciation](/docs/custom-pronunciation): how to use phonetic strings in API requests
* [Pronunciation control](/platform/pronunciation-control): overview of checking coverage, custom pronunciations, and dictionary additions
* [Coverage API](/api-reference/other/oov): check whether words are in Rime's dictionary before writing a custom pronunciation
* [Phonemize API](/api-reference/other/phonemize): generate a phonetic string from an audio recording of the word


# Teams
Source: https://docs.rime.ai/platform/teams

Create and manage Rime teams, including invites, roles, billing, and member removal.

<Warning>
  Creating a team cannot currently be undone. The creator's Stripe account becomes the billing account for all team API usage.
</Warning>

## Create a team

In the Rime dashboard, open **Settings → [Team](https://app.rime.ai/teams/)**, enter a name, and select **Create**. The page then shows your team, and you can invite members right away.

## Invite members

On the same **[Team](https://app.rime.ai/teams/)** page, under **Invite teammates**, enter the member's email address, choose a role, and select **Send invite**. Pending invites appear in the members table below the form, where an owner can resend or revoke them.

<Note>Each Rime user can belong to only one team at a time.</Note>

## Billing

Any owner can access and update billing information. Usage from every API key owned by a team member rolls up to the team's metered usage and the creator's billing account.

## Roles

Rime teams have two roles: **Owner** and **Member**.

| Role | Invite members | Edit billing | View all API keys | Create API keys | Delete any member's keys | Remove members |
| :- | :-: | :-: | :-: | :-: | :-: | :-: |
| Owner | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Member | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |

## Remove a member

<Warning>
  Removing a member transfers their API keys to the owner who performs the removal. Review those keys and their access before removing the member.
</Warning>

A team must retain at least one owner, and you can't remove the user whose email matches the billing-page email. To remove that user, first change the billing email: in the Rime dashboard, open [**Usage and Billing**](https://app.rime.ai/billing/) and select **Manage Billing**.


# Enterprise voice cloning
Source: https://docs.rime.ai/platform/voice-cloning

Order an enterprise voice clone trained on Coda or Mist.

Enterprise voice cloning is available on Growth and Enterprise plans. Plan for 30 to 60 minutes of clean, consistent recordings for a basic clone. For the strongest results, record two to five hours or more.

## Create an enterprise voice clone

<Steps>
  <Step title="Prepare data">
    Use a low-reverb space with only the target speaker. Keep the same microphone, distance, and speaking energy throughout each session. Use a pop filter, retain natural breaths and pauses, and record over multiple days to capture variation without fatigue.

    Separate each line in your script by three to four seconds of silence.

    Include:

    * Brand-specific terminology
    * Alphanumeric sequences (like phone numbers and addresses)
    * The performance and prosody that you're looking for (such as for outbound calling or inbound customer support)

    <Tip>Contact Rime if you need a recording script.</Tip>
  </Step>

  <Step title="Delivery criteria">
    Deliver the audio in the following format:

    * **Channels:** Mono
    * **Format:** Lossless format (`.wav` or `.flac`)
    * **Sampling rate:** At least 44.1kHz
    * **Bit depth:** At least 16-bit
  </Step>

  <Step title="Delivery and completion">
    Deliver the finished audio to the Rime team and specify which foundational model you want the clone trained on: Coda, Mist, or both.

    Turnaround depends on current demand but is most often under seven business days. Rime assigns the voice clone a unique UUID and makes it available through the API under that UUID. Pass the UUID as `speaker`, with `modelId` set to a model the clone was trained on. For example, if Rime assigns `84462a19-dc31-4f30-91e5-19bfc6415a85`, this request uses the clone on Coda:

    ```bash theme={null}
    curl --request POST \
        --url https://users.rime.ai/v1/rime-tts \
        --header 'Accept: audio/L16' \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
        "speaker": "84462a19-dc31-4f30-91e5-19bfc6415a85",
        "text": "<string>",
        "modelId": "coda"
    }'
    ```
  </Step>
</Steps>