Voice design

Design a brand-new voice from a natural-language description — timbre, emotion, character, and pacing — speaking the text you provide. No reference audio, no session: it’s a single blocking call that returns the generated audio.

This is the expressive counterpart to a fixed voice catalog: instead of picking from preset attributes, you describe the voice you want (“an old wise wizard, deep gravelly voice, slow and deliberate”) and the platform renders it on a GPU box and streams the result back.

Try it →

Design a voice

POST /api/v1/design

Required scope: generations:write

Request body

{
  "description": "a calm warm female narrator, gentle and clear",
  "text": "Hello there, this is a preview of your new voice."
}

Field	Required	Description
`description`	Yes	Free-form description of the voice — timbre, emotion, character, pacing. (`instruction` is accepted as an alias.)
`text`	Yes	The text the designed voice should speak.
`temperature`	No	Sampling temperature. Default `1.5`.
`top_p`	No	Nucleus sampling top-p. Default `0.6`.
`top_k`	No	Top-k sampling. Default `50`.
`repetition_penalty`	No	Repetition penalty. Default `1.1`.
`max_new_tokens`	No	Decode-length cap. Default `4096`.

Response 200

{
  "audio_base64": "UklGRiQ...AAA=",
  "sample_rate": 24000,
  "duration_seconds": 3.76,
  "gen_ms": 2241.9,
  "rtf": 0.6,
  "format": "wav"
}

Field	Description
`audio_base64`	The generated audio, base64-encoded 24 kHz mono WAV (PCM_16).
`sample_rate`	Sample rate in Hz (`24000`).
`duration_seconds`	Length of the generated clip.
`gen_ms`	Server-side generation time in milliseconds.
`rtf`	Real-time factor (`gen_ms/1000 ÷ duration_seconds`).
`format`	Audio container format (`wav`).

The response also carries an X-Box-Id header identifying the GPU box that served the request.

Example

curl -sS -X POST https://api.casola.ai/api/v1/design \
  -H "Authorization: Bearer avatar_abc12345.def...your-key" \
  -H "content-type: application/json" \
  -d '{
    "description": "an excited e-sports caster, fast and energetic",
    "text": "And he wins it at the buzzer!"
  }'

Decode audio_base64 to a .wav file (or a data:audio/wav;base64,… URI) to play it.

Notes

Blocking, but fast. Voice design runs autoregressively on the GPU box (typically a real-time factor around 0.5), so a few seconds of audio returns in roughly the same wall-clock time. There is no queue or held seat — unlike a live session.
Authoring, then reuse. A designed take is meant to be saved and reused: bake the audio you like into a persona’s voice reference, then serve it via the realtime session path. Design is a one-time authoring step, not a per-utterance call.
Capacity. If every box is momentarily busy you get 429 with a Retry-After; if no box is registered you get 503.