REVERIE · TTS

Speaker registry

Register and manage speakers from reference audio. A new or restored speaker is loaded automatically and can be used by inference and streaming without a separate load request.

WARNING

Every /v1/tts/speakers endpoint requires a Dev API key in the x-api-key header. Customer-tier keys are rejected.

Speaker object

Field	Type	Default	Description
name	string	-	Unique speaker identifier
reference	string	-	Storage key of the reference audio
transcript	string	-	Transcript of the reference audio
gender	string	-	Speaker gender
created_at	string	-	ISO creation timestamp
updated_at	string	-	ISO update timestamp
client	string	-	API key client name that created the speaker
version	integer	-	Revision counter; increments on update
deleted	boolean	-	Whether the speaker is soft-deleted

List and get speakers

GEThttps://api.lucidweights.ai/v1/tts/speakers

GEThttps://api.lucidweights.ai/v1/tts/speakers/{name}

The list returns {"speakers": [...]}. Both endpoints exclude soft-deleted speakers by default; pass include_deleted=true to include or fetch them. The single-speaker endpoint returns 404 when the name is not found.

Example

curl "https://api.lucidweights.ai/v1/tts/speakers?include_deleted=false" \
  -H "x-api-key: YOUR_DEV_API_KEY"

Create a speaker

POSThttps://api.lucidweights.ai/v1/tts/speakers

Send multipart/form-data, not JSON. A successful request returns the new speaker object with HTTP 201. An invalid name, unsupported language, or invalid audio returns 400; a duplicate name returns 409.

Field	Type	Default	Description
name	string	required	Unique identifier: lowercase letters, digits, and hyphens only
transcript	string	required	Exact transcript of the reference audio, 1–500 characters
audio	file	required	WAV, MP3, or FLAC reference clip, at most 5 MB
language_code	string	required	Supported language spoken in the reference clip
gender	string	required	Speaker gender

NOTE

WAV duration must be 3–30 seconds. The API checks file size, but does not enforce duration for MP3 or FLAC; keep those clips within 3–30 seconds too.

Example

curl -X POST "https://api.lucidweights.ai/v1/tts/speakers" \
  -H "x-api-key: YOUR_DEV_API_KEY" \
  -F "name=alice" \
  -F "transcript=Hello, my name is Alice." \
  -F "audio=@/path/to/alice_reference.wav" \
  -F "language_code=en" \
  -F "gender=female"

Update a speaker

PUThttps://api.lucidweights.ai/v1/tts/speakers/{name}

Send multipart form data with transcript, audio, or both. At least one is required. The same transcript and audio limits apply. The engine cache is invalidated and the speaker reloads automatically. Returns the updated speaker object, or 404 if missing.

Example

curl -X PUT "https://api.lucidweights.ai/v1/tts/speakers/alice" \
  -H "x-api-key: YOUR_DEV_API_KEY" \
  -F "audio=@/path/to/alice_new_reference.wav"

Delete and restore

DELETEhttps://api.lucidweights.ai/v1/tts/speakers/{name}

POSThttps://api.lucidweights.ai/v1/tts/speakers/{name}/restore

Delete is soft: it sets deleted: true and removes the speaker from the active engine cache. Restore sets it back to false and reloads the speaker. Both return the speaker object, or 404 if not found.

Preview a speaker

GEThttps://api.lucidweights.ai/v1/tts/speakers/{name}/preview

Generate a short sample outside the main inference queue. This GET request takes query parameters and returns raw audio/wav bytes.

Field	Type	Default	Description
text	string	required	Text to synthesize
api_key	string	required	Dev API key in the query string
language	string	en	ISO 639-1 language code
custom_pronunciations	string	-	JSON-encoded pronunciation overrides

WARNING

The preview key is part of the URL. Do not share, bookmark, or log preview URLs. Missing or invalid keys return 401; a valid non-Dev key returns 403. Invalid pronunciation JSON returns 400.

Example

curl -G "https://api.lucidweights.ai/v1/tts/speakers/alice/preview" \
  --data-urlencode "text=This is a preview" \
  --data-urlencode "language=en" \
  --data-urlencode "api_key=YOUR_DEV_API_KEY" \
  --output preview.wav