Voice design

Synthesize a speaker from a written description, create a voice from a preview, and speak in it by id.

Overview

Voice design lets you synthesize a speaker from a written description. POST /v1/audio/voices/design takes the description and returns previews. POST /v1/audio/voices creates a voice from a preview's design_id, and the voice's id then goes in voice on POST /v1/audio/speech like a preset id.

A designed voice belongs to no real person. Use it when no preset fits the character you want and the voice does not have to be a particular person's. To reproduce a specific speaker, see Voice cloning.

Design previews

curl https://api.sprag.ai/v1/audio/voices/design \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SPRAG_API_KEY" \
  -d '{
    "model": "chorus",
    "description": "Calm middle-aged British woman, warm and unhurried, slight vocal fry",
    "input": "Welcome back. Let me pull up your account.",
    "n": 3
  }'

Field	Required	Type	Notes
`model`	Yes	string	`chorus`.
`description`	Yes	string	The voice, in words.
`input`	No	string	The text the previews speak. When omitted, the previews speak a short script of the model's own.
`n`	No	integer	The number of previews to synthesize. Defaults to `1`.

The response is a list of previews. Each preview carries its audio inline as base64.

{
  "object": "list",
  "input": "Welcome back. Let me pull up your account.",
  "data": [
    {
      "object": "audio.voice_design",
      "id": "design_5f3c...",
      "audio": "<base64 wav>",
      "media_type": "audio/wav",
      "expires_at": 1758672000
    }
  ]
}

expires_at is the unix second until which the preview is guaranteed to remain usable for creating a voice. Create the voice before then.

Create a voice from a preview

To create a voice from a preview, send its id as design_id to POST /v1/audio/voices with a name. The request takes no model and no transcript.

curl https://api.sprag.ai/v1/audio/voices \
  -H "Authorization: Bearer $SPRAG_API_KEY" \
  -F design_id=design_5f3c... \
  -F name=Marin

Field	Required	Notes
`design_id`	Yes	The preview's `id`.
`name`	Yes	A display name, unique among your organization's voices.
`description`	No	Free-form notes, returned on the voice.

The response is a voice with category set to designed.

{
  "object": "audio.voice",
  "id": "voice_9a1b...",
  "name": "Marin",
  "created_at": 1758067200,
  "description": null,
  "category": "designed"
}

A name already in use returns 409. A preview from another organization, or one past its expires_at, returns 404. If your organization already holds as many voices as its plan allows, the request returns HTTP 403 with the error code voice_limit_exceeded.

Speak in a designed voice

Pass the voice's id as voice on POST /v1/audio/speech, with model set to chorus.

curl https://api.sprag.ai/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SPRAG_API_KEY" \
  -d '{
    "model": "chorus",
    "input": "Your table is ready.",
    "voice": "voice_9a1b...",
    "response_format": "mp3"
  }' \
  --output marin.mp3

If the request carries your API key, GET /v1/audio/voices?model=chorus lists the voices your organization created after the presets. DELETE /v1/audio/voices/{voice_id} deletes a voice.

Write a description

Name age, gender, accent, and timbre. A description that names all four is more repeatable than adjectives alone. Compare "friendly" with "friendly, bright American man in his twenties, slightly clipped".

These four descriptions are close to the length and specificity the model responds to:

A weathered old sea captain, seventy years old, thick gravelly rasp, heavy West Country accent. Slow, salt-worn, every sentence sounds like a warning.

A film-noir private detective narrating in voiceover. Male, forties, low and smoky, close to the microphone, world-weary and dry. Almost a whisper, no theatricality.

An old monk chanting in a stone monastery. Male, eighty years old. Extremely low, slow and resonant, the voice worn smooth by decades of repetition.

A colossal ancient genie made of starlight, newly released after a thousand years. Enormous booming male voice, vast and echoing, amused and grandly theatrical, unhurried.

Describe a person and a situation rather than a list of traits. The model responds to a coherent target better than to a set of independent dials. Point each description at one register. If a preview comes back wrong, rewrite the description in the register you want rather than patching it.

Reproducibility

Each design request synthesizes new speakers, and the same description varies between requests. Request several previews and create a voice from the one that fits. A created voice is the same speaker on every speech request.