Migrate from OpenAI TTS

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 page
Model	`higgs-tts-3`
Voice	`default`, a preset name, or a custom `voice_<id>`
Response format	`wav` or `mp3`; `pcm` when streaming

For an app that stores presets:

{
  "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 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.

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")

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.
`voice`	Same field, different names. `alloy`, `nova`, and the other OpenAI voices don’t exist here; use `default`, a preset, 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 in `input`.
`instructions`	Not supported. Delivery is set with emotion, style, and prosody tags 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.
`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.
`normalize`	Turn off spoken-form expansion of numbers and dates with `false`. See Text normalization.
`stream`	`true` streams raw 16-bit, 24 kHz, mono PCM; requires `response_format: "pcm"`. See Streaming TTS.
`timestamps`	When each token is spoken. See Timestamps.

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

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.
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 list, or a voice name carried over from OpenAI. Show error.message to the user.

Checklist for a Boson preset

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

Shipping a Boson preset in your app? Tell us and we will link it from here.

Get started

Account & billing

Higgs Realtime

Higgs TTS 3

Higgs Avatar

Help