Skip to content

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.

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

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.

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 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.
model_not_found, rate and balance errors As on every Keln endpoint (errors & limits).

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.