Text to speech API voice id: list avatars where voice.status is ready

On Sume, find a TTS voice by listing avatars with GET /v1/avatar-1.0/avatars and picking one whose voice.status is ready, then pass its avatar_id or avatar_handle on the TTS request. Sume resolves that avatar's voice at submit time. If you already hold a voice id, send it as voice.id; it must be a UUID (8-4-4-4-12 hex) or a Voices library id (voi_ plus 32 hex).

Anything else, such as a voice name from another TTS service, is rejected synchronously with 400 invalid_voice_id before a job is queued or credits are reserved. This is from the TTS request contract in the repository (read 2026-10-09).

The three ways to select

The contract lists the avatar reference as the discoverable selector: a caller that holds only the API contract never needs a voice id it cannot obtain. avatar_id and avatar_handle are top-level request fields, not properties of voice. If you send both, they must resolve to the same avatar.

What a first request looks like

List the avatars, choose one, and send transcript plus the handle. The transcript is required unless you use a transcript_source, and exactly one of the two applies. The maximum is 20,000 characters, at $0.0475 per 1,000 characters.

curl -X POST https://api.sume.com/v1/tts-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tts-first-line-001" \
  -d '{"transcript": "Hello from Sume.", "avatar_handle": "studio_presenter"}'

Common mistakes

Do not send model or model_id to TTS 1.0; it has no engine picker and returns 400. Use the TTS Router at POST /v1/tts-router/generate with a catalog model id if you want to choose the engine. Do not send provider credentials; authenticate with your Sume API key only.

The default output is mp3 at 44,100 Hz and 128 kbps. Ask for wav with pcm_s16le at 44,100 if the audio goes to a timeline or an avatar mux step.

Reading the result

A finished TTS job records the voice it used as { "mode": "id", "id": "..." }, along with model_id, language, output_format, generation_config and speed. Copy the voice object from a job you liked into the next request to keep the same voice.

Check voice.status before you build a batch. An avatar whose voice is not ready cannot supply a voice, and the error comes back before any credit is held, which is cheaper than finding out halfway through a run.

If your integration is an agent, the hosted MCP tool is tts_create (paid, with an idempotency_key), and tts_source_get and tts_source_verify_spine are free reads for scripts that use transcript_source.

Keep the voice selector in one place in your code. When a voice changes, you update one constant instead of hunting through request builders, and the job records tell you which voice each file used.