API reference

Audio endpoints

POST /v1/audio/speech turns text into speech (OpenAI's request shape plus voice design, cloning, language and emotion), and /v1/audio/voices saves voice samples to clone — create, list, retrieve, rename, download and delete them.

Text to speech follows OpenAI's speech API, so the official SDKs work against https://lovelyrouter.com/v1. The guide, with the models, their voices and examples, is Text to speech. Authenticate with your API key as Authorization: Bearer $LOVELY_API_KEY (Authentication).

Create speech#

POST/v1/audio/speech

Speaks input and returns the audio file. The length in seconds is in the x-lovely-audio-seconds header and the call's id in x-lovely-request-id. Billed per second of audio made (at least one second); a request that fails is not charged.

Body parameters

modelstringRequired

qwen3-tts or zonos2 (GET /v1/models lists them with their prices).

inputstringRequired

The text to speak, up to 4,096 characters.

voicestring or object

A preset voice of the model, an OpenAI voice name (alloy, nova, onyx, … map to a preset), or a saved voice's id (voice_…, also as {"id": "voice_…"}). Optional: without it the model picks a preset for language, or qwen3-tts designs a voice from instructions.

instructionsstring

qwen3-tts only, up to 1,000 characters. With a voice: how to speak (emotion, pace, volume, a whisper). Without one: a description of the voice to make.

languagestring

An ISO code (en, zh, ja, ko, de, fr, pt-br, …) or auto (default). Setting it helps with short texts and numbers.

response_formatstringDefault mp3

mp3, opus, aac, flac, wav or pcm (16-bit, 24 kHz mono).

speednumberDefault 1.0

0.25 to 4.0; the pitch stays the same.

emotionstring or object

zonos2 only: happy, sad, angry or surprised, or weights from 0 to 1 such as {"happy": 0.7}.

seedinteger

For repeatable output, 0 to 2147483647.

reference_audiostring

A one-off voice to clone: an https URL, a data: URL or base64 of a 3–15 s clip (WAV, MP3, M4A, OGG, FLAC or WebM, up to 10 MB). Not with voice.

reference_textstring

What reference_audio says (qwen3-tts clones more closely with it).

consentboolean

Required with reference_audio: you confirm the voice is yours or you have the speaker's permission.

Errors use the usual shape: 400 invalid_request_error with param naming the field (an unknown voice, instructions on zonos2, emotion on qwen3-tts, a missing consent), 402 without balance, 404 for an unknown model or someone else's voice, 502 when the speech failed (nothing charged).

Shell

curl https://lovelyrouter.com/v1/audio/speech \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-tts",
    "input": "Hello! Nice to meet you.",
    "voice": "serena",
    "instructions": "Friendly and upbeat"
  }' \
  --output hello.mp3

The voice object#

Attributes

idstring

voice_ followed by 24 characters. Use it as voice.

objectstring

Always voice.

namestring

Up to 80 characters.

transcriptstring | null

What the sample says.

typestring

The sample's format, such as audio/wav.

bytesinteger

The sample's size.

audio_urlstring

Downloads the sample (with your API key).

created_atinteger

Unix seconds.

The voice object

{
  "id": "voice_8f2c4a1e9b7d3f60a5c2e1d4",
  "object": "voice",
  "name": "Narrator",
  "transcript": "Thanks for listening. See you next week on the show.",
  "type": "audio/wav",
  "bytes": 482044,
  "audio_url": "https://lovelyrouter.com/v1/audio/voices/voice_8f2c4a1e9b7d3f60a5c2e1d4/audio",
  "created_at": 1792915200
}

Save a voice#

POST/v1/audio/voices

Saves a voice sample and returns 201 with the voice object. Send multipart (the sample as file) or JSON (audio as an https or data: URL). Free; up to 100 voices per account, kept until you delete them.

Body parameters

namestringRequired

Up to 80 characters.

filefile (or `audio` string)Required

3 to 15 seconds of one person speaking clearly, without music: WAV, MP3, M4A, OGG/Opus, FLAC or WebM, up to 10 MB.

transcriptstring

What the sample says, up to 1,000 characters.

consentbooleanRequired

true: the voice is yours, or you have the speaker's permission to clone it.

cURL

curl https://lovelyrouter.com/v1/audio/voices \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F name="Narrator" \
  -F transcript="Thanks for listening. See you next week on the show." \
  -F consent=true \
  -F file=@narrator.wav