Voices

The Voices API lets you search, filter, and inspect voices from the catalog, audition preview audio, and retrieve the voice ID required for speech synthesis.

Authentication and Scopes

Access permissions depend on whether the voice is public or private:

• Public voices: Can be listed and previewed without authentication. This allows direct audio playback in web browsers and client applications.
• Private voices: Require an API key passed in the standard HTTP Authorization header:

Authorization: Bearer <API_KEY>

• Required Scope: The API key must include the voices scope (or have unrestricted access). If the scope is missing, the API returns HTTP 403 Forbidden (insufficient_scope).

List Voices

Retrieve a paginated list of available voices.

GET /v1/voices

Query Parameters

All query parameters are optional:

Response Structure

The endpoint returns a list envelope object:

Voice Object

Each item in data, as well as the response from GET /v1/voices/{voice_id}, contains the following fields:

Retrieve a Single Voice

Fetch metadata and status for a specific voice by its identifier.

GET /v1/voices/{voice_id}

Access and Visibility

• Returns the voice object if the voice is public or owned by the authenticated caller.
• If the voice does not exist, or is private and belongs to another account, the endpoint returns HTTP 404 Not Found (voice_not_found). Private voices belonging to other accounts are indistinguishable from nonexistent voices.

Preview Voice Audio

Audition a pre-rendered audio sample of a voice before using it.

GET /v1/voices/{voice_id}/preview

Audio Specifications and Headers

• Audio format: Standard WAV (audio/wav).
• Cache-Control: public, max-age=300.
• Public voices: Unauthenticated access is allowed so that web players and client applications can stream the sample directly.
• Private voices: Requires an authenticated API key with the voices scope belonging to the voice owner.
• Rate limit: Keyless preview requests are limited to 60 requests per minute per IP address. If this limit is exceeded, the endpoint returns HTTP 429 Too Many Requests with a Retry-After: 60 header.

Choosing a Voice for Synthesis

To synthesize speech using a selected voice:

1. Find a voice: Call GET /v1/voices with appropriate dialect, gender, or use-case filters.
2. Verify readiness: Ensure the voice object has "status": "ready". Voices with status "processing" or "failed" cannot synthesize speech.
3. Audition the sample: Stream audio from preview_url or GET /v1/voices/{voice_id}/preview to evaluate the voice.
4. Send the synthesis request: Pass the voice id in the voice field of your speech synthesis request:

curl -X POST "https://api.sawtakarabi.ai/v1/audio/speech" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "arabic-tts-1",
    "voice": "<VOICE_ID>",
    "input": "مرحبا بك",
    "response_format": "wav"
  }' \
  --output speech.wav

If the voice parameter is omitted, the speech synthesis endpoint uses the system default voice.

Error Reference

The Voices API returns standard error responses: