> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boson.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from OpenAI TTS

> Move an OpenAI text-to-speech integration or app preset to Higgs TTS 3: what to change, what maps, and what differs.

Higgs TTS 3 speaks the OpenAI `POST /v1/audio/speech` request shape. Moving an existing OpenAI TTS integration takes three changes: the base URL, the API key, and the model name. The same three settings fill in the "OpenAI-compatible TTS" option of any app or plugin.

## Boson preset

| Setting | Value |
| - | - |
| Base URL | `https://api.boson.ai/v1` |
| API key | `Authorization: Bearer bai-…` from the [API Keys](https://www.boson.ai/workspace/api-key) page |
| Model | `higgs-tts-3` |
| Voice | `default`, a [preset name](https://docs.boson.ai/models/higgs-tts/voices.md#preset-voices), or a custom `voice_<id>` |
| Response format | `wav` or `mp3`; `pcm` when streaming |

For an app that stores presets:

```jsonc theme={null}
{
  "name": "Boson.ai Higgs TTS 3",
  "base_url": "https://api.boson.ai/v1",
  "model": "higgs-tts-3",
  "voice": "default",
  "response_format": "wav"
}
```

A new account must claim its [free trial credit](https://docs.boson.ai/free-trial-credit.md) before the first call; until then the key returns `429 insufficient_quota`.

## Use the OpenAI SDK

Change the base URL and the key. The `audio.speech.create` call is unchanged.

```python Python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BOSON_API_KEY"],
    base_url="https://api.boson.ai/v1",
)

speech = client.audio.speech.create(
    model="higgs-tts-3",
    voice="default",
    input="Hello, this is a test.",
    response_format="wav",
)
speech.write_to_file("out.wav")
```

```typescript TypeScript theme={null}
import OpenAI from "openai";
import { writeFile } from "node:fs/promises";

const client = new OpenAI({
  apiKey: process.env.BOSON_API_KEY,
  baseURL: "https://api.boson.ai/v1",
});

const speech = await client.audio.speech.create({
  model: "higgs-tts-3",
  voice: "default",
  input: "Hello, this is a test.",
  response_format: "wav",
});
await writeFile("out.wav", Buffer.from(await speech.arrayBuffer()));
```

## What maps and what differs

| OpenAI field | On Higgs TTS 3 |
| - | - |
| `model` | `higgs-tts-3`. `tts-1` and `gpt-4o-mini-tts` are not available. |
| `input` | Same. Up to 5,000 characters, or 50,000 with `stream: true`. May contain [inline tags](https://docs.boson.ai/models/higgs-tts/tags.md). |
| `voice` | Same field, different names. `alloy`, `nova`, and the other OpenAI voices don't exist here; use `default`, a [preset](https://docs.boson.ai/models/higgs-tts/voices.md#preset-voices), or a custom `voice_<id>`. |
| `response_format` | Same values: `mp3` (default), `opus`, `aac`, `flac`, `wav`, `pcm`. |
| `speed` | No documented effect. Pace is set with `<\|prosody:speed_slow\|>` and `<\|prosody:speed_fast\|>` [tags](https://docs.boson.ai/models/higgs-tts/tags.md#prosody) in `input`. |
| `instructions` | Not supported. Delivery is set with [emotion, style, and prosody tags](https://docs.boson.ai/models/higgs-tts/tags.md) in `input`. |
| `stream_format` | Not supported. Stream with `stream: true` and `response_format: "pcm"` instead; see below. |

Fields OpenAI does not have, sent in the same JSON body. With the OpenAI SDKs, pass them through `extra_body` in Python or as extra properties in TypeScript.

| Field | Use it for |
| - | - |
| `ref_audio`, `ref_text` | One-off voice cloning from a clip and its transcript. See [Voices](https://docs.boson.ai/models/higgs-tts/voices.md#reference-voice). |
| `language` | ISO 639-3 code of `input`, for text normalization. OpenAI clients have no equivalent, so do not fill it from your app's UI language setting, which is usually two-letter and returns `400`. Leave it unset unless you know the language. See [Language codes](https://docs.boson.ai/models/higgs-tts/languages.md#language-codes). |
| `normalize` | Turn off spoken-form expansion of numbers and dates with `false`. See [Text normalization](https://docs.boson.ai/models/higgs-tts/overview.md#text-normalization). |
| `stream` | `true` streams raw 16-bit, 24 kHz, mono PCM; requires `response_format: "pcm"`. See [Streaming TTS](https://docs.boson.ai/models/higgs-tts/streaming.md). |
| `timestamps` | When each token is spoken. See [Timestamps](https://docs.boson.ai/models/higgs-tts/timestamps.md). |

Streaming with the Python SDK needs the streaming response wrapper plus `stream` in `extra_body`:

```python theme={null}
with client.audio.speech.with_streaming_response.create(
    model="higgs-tts-3",
    voice="default",
    input="Hello, this is a streaming test.",
    response_format="pcm",
    extra_body={"stream": True},
) as response:
    for chunk in response.iter_bytes(4096):
        play(chunk)  # 16-bit, 24 kHz, mono
```

## Errors an OpenAI client does not expect

The error body has the OpenAI shape, so existing handlers run. Two cases differ:

* **`429` is not always a rate limit.** `error.type` is `insufficient_quota` when the account has no credit, and retrying cannot help. Only `rate_limit_error` is transient. See [Common error types](https://docs.boson.ai/api-reference/errors.md).
* **`400 invalid_field_value` names a field you may not have set on purpose**: a two-letter `language`, a tag that is not on the [Tags](https://docs.boson.ai/models/higgs-tts/tags.md) list, or a voice name carried over from OpenAI. Show `error.message` to the user.

## Checklist for a Boson preset

1. Base URL `https://api.boson.ai/v1`, Bearer key, model `higgs-tts-3`.
2. `voice` as free text, defaulting to `default`, so users can paste a `voice_<id>`. For per-character voices, create one [custom voice](https://docs.boson.ai/models/higgs-tts/voices.md#custom-voices) per character once and cache the IDs rather than sending `ref_audio` on every request.
3. Do not send `language` unless the user set it explicitly, and then as ISO 639-3.
4. `response_format` `wav` or `mp3`; `pcm` plus `stream: true` for streaming.
5. Drop or hide `speed` and `instructions`. If you offer a delivery dropdown, build it from the [Tags](https://docs.boson.ai/models/higgs-tts/tags.md) page and send the tag in `input`.
6. Surface `error.message` on `400` and `429`.

Shipping a Boson preset in your app? [Tell us](https://docs.boson.ai/feedback.md) and we will link it from here.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.