Which voice does my avatar speak with? Check voice.status is ready

Your Sume avatar speaks through the TTS voice attached to it, and that voice is usable exactly when the avatar's voice.status is ready. List your avatars at GET /v1/avatar-1.0/avatars, check voice.status on the one you want, then send its avatar_id or avatar_handle on the TTS request. You never need to look up a raw voice id for this route.

Where do I read voice.status?

Each avatar summary in the list has a voice object with a status of processing, ready or failed. It is null for an avatar with no voice. The OpenAPI description says an avatar whose voice is ready is the selector that POST /v1/tts-1.0/generate resolves from avatar_id or avatar_handle, and calls this the public route to a TTS voice.

The list also takes a handle filter, with or without the @, and a status filter that accepts ready as an alias for completed jobs. That status is about the avatar job, so read voice.status on each result.

How do I send the request?

Set avatar_handle (2 to 31 characters, optional @) or avatar_id at the top level of the body. If you also set voice.id, it must equal the avatar's resolved voice id, and if you set both avatar_id and avatar_handle, they must point to the same avatar; otherwise the request fails with 400. Set language for any non-English text.

curl "https://api.sume.com/v1/avatar-1.0/avatars?handle=your_avatar" \
  -H "Authorization: Bearer $SUME_API_KEY"

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: avatar-voice-001" \
  -d '{
    "transcript": "Hello from my avatar.",
    "avatar_handle": "@your_avatar",
    "language": "en"
  }'

Can I make the voice through the API?

No. Voice cloning is done in the Sume app, not through the API; the API uses the voice that the avatar already has. If the voice is not ready, make or fix it in the app, then list the avatar again. Polling the TTS request itself follows Jobs and results.