# Speech
`POST /v1/audio/speech` converts text into spoken audio, using one voice or a conversation between two. It accepts
OpenAI's speech request format, so you can use the OpenAI SDKs by changing the base URL to Keln's. API keys, rate limits
and balance work the same as for chat completions.
=== "Python"
```python
from openai import OpenAI
client = OpenAI(base_url="https://api.keln.ai/v1", api_key="sk-keln-…")
with client.audio.speech.with_streaming_response.create(
model="google/gemini-3.8-flash-tts",
voice="Kore",
input="Hello from Keln. This sentence was text a moment ago.",
instructions="Speak warmly, at an easy pace.",
) as resp:
resp.stream_to_file("speech.mp3")
```
=== "TypeScript"
```typescript
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.keln.ai/v1", apiKey: "sk-keln-…" });
const resp = await client.audio.speech.create({
model: "google/gemini-3.8-flash-tts",
voice: "Kore",
input: "Hello from Keln. This sentence was text a moment ago.",
instructions: "Speak warmly, at an easy pace.",
});
fs.writeFileSync("speech.mp3", Buffer.from(await resp.arrayBuffer()));
```
=== "cURL"
```bash
curl https://api.keln.ai/v1/audio/speech \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "google/gemini-3.8-flash-tts", "voice": "Kore", "input": "Hello from Keln. This sentence was text a moment ago.", "instructions": "Speak warmly, at an easy pace."}' \
--output speech.mp3
```
The answer is the audio itself, in MP3 by default or another requested format. Usage details are in its headers
([Billing](#billing)).
The examples use `google/gemini-3.8-flash-tts`. Other speech models in [`GET /v1/models`](models.md) accept the same
request. Change the `model` id and select a `voice` from that model's `supported_voices`.
## Request
Send the request as a JSON body, as with OpenAI.
| Field | Contract |
|---|---|
| `model` | Required. A speech model id from [`GET /v1/models`](models.md): the rows whose `output_modalities` is `["speech"]`. Keln returns `400 wrong_endpoint` for a chat model on this endpoint, and for a speech model on chat completions. |
| `input` | Required. The text to speak, up to 4,096 characters, or a list of turns for a conversation: see [Two voices](#two-voices). |
| `voice` | Optional. One of the model's `supported_voices` from [`GET /v1/models`](models.md), in any letter case. Leave it out and the model's default voice speaks. OpenAI's voice names, such as `alloy`, return `400 voice_not_supported`; a custom voice object returns `400 param_not_supported`. |
| `instructions` | Optional. How to say the text, such as `Speak slowly, in a calm and friendly tone.`, up to 4,096 characters. The model follows it as direction and doesn't read it aloud. |
| `response_format` | `mp3` (the default), `opus`, `flac`, `wav` or `pcm`. See [Formats](#formats). `aac` returns `400 param_not_supported`. |
| `speed` | `1` or left out. These models have no speed setting, so any other value from 0.25 to 4 returns `400 param_not_supported`: ask for a pace in `instructions` instead. |
| `stream_format` | `audio` or left out. `sse` returns `400 stream_not_supported`: the audio comes back whole. |
| `provider`, `session_id`, `trace`, `user` | Accepted. Keln removes them before forwarding the request ([privacy](../capabilities/privacy.md)). |
`input_references` (voice cloning) returns `400 param_not_supported`. Keln returns `400 invalid_request` for any other
field.
### Two voices
For a conversation, send `input` as a list of turns. Each turn has `text` and can have its own `voice` and
`instructions`. Instructions for a turn override the request-level `instructions`. Each request supports at most two
voices, and the 4,096-character limit applies across all turns.
```bash
curl https://api.keln.ai/v1/audio/speech \
-H "Authorization: Bearer $KELN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemini-3.8-flash-tts",
"input": [
{"text": "Did the build pass?", "voice": "Puck"},
{"text": "It did. Every test is green.", "voice": "Kore", "instructions": "Sound relieved."}
],
"response_format": "wav"
}' \
--output dialogue.wav
```
When using different voices, set a `voice` for each turn or provide a request-level `voice` for turns without one.
## Formats
| `response_format` | What comes back | `Content-Type` |
|---|---|---|
| `mp3` | MP3, 24 kHz mono at 64 kbit/s. | `audio/mpeg` |
| `opus` | Opus at 32 kbit/s, in an Ogg file. | `audio/ogg` |
| `flac` | FLAC, lossless, 24 kHz 16-bit mono. | `audio/flac` |
| `wav` | WAV, 24 kHz 16-bit mono. | `audio/wav` |
| `pcm` | The raw samples, as OpenAI's `pcm` is: 24 kHz, 16-bit signed little-endian, mono, no header. | `audio/pcm;rate=24000;channels=1` |
A `wav` answer passes the model's own WAV file through byte for byte, so it keeps any content credentials its maker
signed into it: a C2PA manifest stating that the audio is AI-generated. Keln encodes MP3, Opus and FLAC from the
samples, and those files, like `pcm`, can't carry that manifest.
## Limits
- **4,096 characters of text per request**, OpenAI's limit, across all turns. Longer text returns `400 invalid_request`;
split it and join the audio.
- **Two voices per request.** A third returns `400 speech_shape_not_supported`.
- **Voices and languages depend on the model.** [`GET /v1/models`](models.md) lists each model's `supported_voices`,
and each model's page on [keln.ai/models](https://keln.ai/models) lists its languages.
## Billing
Keln bills speech models **per token**: the text in, with any `instructions`, at the model's input price, and the audio out
at its output price. One second of audio is 25 audio tokens. [`GET /v1/models`](models.md) lists both prices per token
in `pricing.prompt` and `pricing.completion`; [Models & pricing](../models-pricing.md) shows them per million tokens,
and the audio per minute.
The answer's headers show the billed usage:
| Header | Value |
|---|---|
| `x-keln-usage-prompt-tokens` | Text tokens, the text and the `instructions` |
| `x-keln-usage-completion-tokens` | Audio tokens |
| `x-keln-usage-cost` | The exact charge, in USD |
| `x-keln-audio-seconds` | The audio's length, in seconds |
Before sending the text, Keln reserves an estimated cost against your balance, as it does for chat tokens. It then
bills the tokens reported by the model.
## Errors
| Code | Meaning |
|---|---|
| `voice_not_supported` | The voice isn't one of the model's `supported_voices`. |
| `speech_shape_not_supported` | More than two voices in one request. |
| `param_not_supported` | A field this endpoint doesn't take as sent: `speed` other than 1, `aac`, a custom voice, or `input_references`. |
| `stream_not_supported` | `stream_format: "sse"`. |
| `wrong_endpoint` | A chat model on this endpoint, or a speech model on chat completions. |
| `invalid_request` | A field Keln doesn't take, or a malformed one: no `input`, empty text, text over 4,096 characters, an unknown `response_format`, or turns in different voices with a turn left without one. |
| `503` | Keln couldn't serve the request just now. Retry shortly. |
| `model_not_found`, rate and balance errors | As on every Keln endpoint ([errors & limits](errors.md)). |
Keys and budgets work the same as on chat completions. Keln stores neither the text nor the audio. Speech is the one
exception to zero data retention, on the model maker's side: see [Privacy](../capabilities/privacy.md#text-to-speech).
Speech
POST /v1/audio/speech converts text into spoken audio, using one voice or a conversation between two. It accepts
OpenAI's speech request format, so you can use the OpenAI SDKs by changing the base URL to Keln's. API keys, rate limits
and balance work the same as for chat completions.
fromopenaiimportOpenAIclient=OpenAI(base_url="https://api.keln.ai/v1",api_key="sk-keln-…")withclient.audio.speech.with_streaming_response.create(model="google/gemini-3.8-flash-tts",voice="Kore",input="Hello from Keln. This sentence was text a moment ago.",instructions="Speak warmly, at an easy pace.",)asresp:resp.stream_to_file("speech.mp3")
importfsfrom"node:fs";importOpenAIfrom"openai";constclient=newOpenAI({baseURL:"https://api.keln.ai/v1",apiKey:"sk-keln-…"});constresp=awaitclient.audio.speech.create({model:"google/gemini-3.8-flash-tts",voice:"Kore",input:"Hello from Keln. This sentence was text a moment ago.",instructions:"Speak warmly, at an easy pace.",});fs.writeFileSync("speech.mp3",Buffer.from(awaitresp.arrayBuffer()));
curlhttps://api.keln.ai/v1/audio/speech\-H"Authorization: Bearer $KELN_API_KEY"\-H"Content-Type: application/json"\-d'{"model": "google/gemini-3.8-flash-tts", "voice": "Kore", "input": "Hello from Keln. This sentence was text a moment ago.", "instructions": "Speak warmly, at an easy pace."}'\--outputspeech.mp3
The answer is the audio itself, in MP3 by default or another requested format. Usage details are in its headers
(Billing).
The examples use google/gemini-3.8-flash-tts. Other speech models in GET /v1/models accept the same
request. Change the model id and select a voice from that model's supported_voices.
Request
Send the request as a JSON body, as with OpenAI.
Field
Contract
model
Required. A speech model id from GET /v1/models: the rows whose output_modalities is ["speech"]. Keln returns 400 wrong_endpoint for a chat model on this endpoint, and for a speech model on chat completions.
input
Required. The text to speak, up to 4,096 characters, or a list of turns for a conversation: see Two voices.
voice
Optional. One of the model's supported_voices from GET /v1/models, in any letter case. Leave it out and the model's default voice speaks. OpenAI's voice names, such as alloy, return 400 voice_not_supported; a custom voice object returns 400 param_not_supported.
instructions
Optional. How to say the text, such as Speak slowly, in a calm and friendly tone., up to 4,096 characters. The model follows it as direction and doesn't read it aloud.
response_format
mp3 (the default), opus, flac, wav or pcm. See Formats. aac returns 400 param_not_supported.
speed
1 or left out. These models have no speed setting, so any other value from 0.25 to 4 returns 400 param_not_supported: ask for a pace in instructions instead.
stream_format
audio or left out. sse returns 400 stream_not_supported: the audio comes back whole.
provider, session_id, trace, user
Accepted. Keln removes them before forwarding the request (privacy).
input_references (voice cloning) returns 400 param_not_supported. Keln returns 400 invalid_request for any other
field.
Two voices
For a conversation, send input as a list of turns. Each turn has text and can have its own voice and
instructions. Instructions for a turn override the request-level instructions. Each request supports at most two
voices, and the 4,096-character limit applies across all turns.
curlhttps://api.keln.ai/v1/audio/speech\-H"Authorization: Bearer $KELN_API_KEY"\-H"Content-Type: application/json"\-d'{ "model": "google/gemini-3.8-flash-tts", "input": [ {"text": "Did the build pass?", "voice": "Puck"}, {"text": "It did. Every test is green.", "voice": "Kore", "instructions": "Sound relieved."} ], "response_format": "wav" }'\--outputdialogue.wav
When using different voices, set a voice for each turn or provide a request-level voice for turns without one.
Formats
response_format
What comes back
Content-Type
mp3
MP3, 24 kHz mono at 64 kbit/s.
audio/mpeg
opus
Opus at 32 kbit/s, in an Ogg file.
audio/ogg
flac
FLAC, lossless, 24 kHz 16-bit mono.
audio/flac
wav
WAV, 24 kHz 16-bit mono.
audio/wav
pcm
The raw samples, as OpenAI's pcm is: 24 kHz, 16-bit signed little-endian, mono, no header.
audio/pcm;rate=24000;channels=1
A wav answer passes the model's own WAV file through byte for byte, so it keeps any content credentials its maker
signed into it: a C2PA manifest stating that the audio is AI-generated. Keln encodes MP3, Opus and FLAC from the
samples, and those files, like pcm, can't carry that manifest.
Limits
4,096 characters of text per request, OpenAI's limit, across all turns. Longer text returns 400 invalid_request;
split it and join the audio.
Two voices per request. A third returns 400 speech_shape_not_supported.
Voices and languages depend on the model.GET /v1/models lists each model's supported_voices,
and each model's page on keln.ai/models lists its languages.
Billing
Keln bills speech models per token: the text in, with any instructions, at the model's input price, and the audio out
at its output price. One second of audio is 25 audio tokens. GET /v1/models lists both prices per token
in pricing.prompt and pricing.completion; Models & pricing shows them per million tokens,
and the audio per minute.
The answer's headers show the billed usage:
Header
Value
x-keln-usage-prompt-tokens
Text tokens, the text and the instructions
x-keln-usage-completion-tokens
Audio tokens
x-keln-usage-cost
The exact charge, in USD
x-keln-audio-seconds
The audio's length, in seconds
Before sending the text, Keln reserves an estimated cost against your balance, as it does for chat tokens. It then
bills the tokens reported by the model.
Errors
Code
Meaning
voice_not_supported
The voice isn't one of the model's supported_voices.
speech_shape_not_supported
More than two voices in one request.
param_not_supported
A field this endpoint doesn't take as sent: speed other than 1, aac, a custom voice, or input_references.
stream_not_supported
stream_format: "sse".
wrong_endpoint
A chat model on this endpoint, or a speech model on chat completions.
invalid_request
A field Keln doesn't take, or a malformed one: no input, empty text, text over 4,096 characters, an unknown response_format, or turns in different voices with a turn left without one.
503
Keln couldn't serve the request just now. Retry shortly.
Keys and budgets work the same as on chat completions. Keln stores neither the text nor the audio. Speech is the one
exception to zero data retention, on the model maker's side: see Privacy.