aethexDocs
Dashboard

API Reference

Voices API

Browse the TTS voice catalog and play short previews.Read access. voices:read lists the catalog and looks up individual voices.Preview. tts:use powers POST /voices/preview, which bills per character at the same rate as POST /tts.You see Aethex's global voice catalog plus any private voices on your account. The catalog grows over time as we add new voices, so re-list when you want the latest options rather than hard-coding IDs in your app.

Base URL
https://api.aethexai.com/api/v1
Endpoints
5
Scopes
voices:readtts:use
GET/voices

Browse every voice available to your account.

List Voices

Lists every voice you can use: the global catalog plus any private voices on your account. Filter by language, supports_dialect_style, tag, or country to narrow it down. Results come back in stable order (newest first), so paging with (limit, offset) is safe; keep paging until you receive fewer than limit rows. The response is a flat JSON array; no envelope, no cursor.Voice IDs are UUIDs in the modern API. The id field in every response object is a UUID — copy it directly into your voice_id fields. The sentinel "default" is only accepted on the TTS synthesis endpoint (POST /tts); POST /voices/preview and agent create/update require a real voice UUID (or legacy voice_key) from this list and return a 404/422 not-found error otherwise. Existing agents created with legacy slug-form IDs continue to work without migration. New code should use a UUID from this list.

Path & Query

6
  • languagestringoptional

    Show only voices in this language. Currently english or french. An unknown value returns an empty list so existing dashboards stay working.

  • supports_dialect_stylebooleanoptional

    Show only voices that honor your agent's dialect_style setting (formal / mixed / local). See Dialect style.

  • tagstringoptional

    Show only voices tagged with this token. Case-sensitive; the value must come from GET /voices/tag-vocabulary (any token from any bucket). Empty or whitespace-only input is treated as no filter. An unknown token returns an empty list rather than 422.

  • countrystringoptional

    Show only voices from this country, as an ISO 3166-1 alpha-2 code (NG, FR, US, ...). Case-insensitive. Empty or whitespace-only input is treated as no filter and returns every voice in the catalog. Hit GET /voices/countries for the supported set. An unknown code returns an empty list rather than 422.

  • limitintegeroptional

    How many voices to return per page. Default 100, range 0–500.

  • offsetintegeroptional

    How many voices to skip before this page. Default 0. Pair with limit for paging.

Errors

1
422Invalid pagination

limit is outside 0–500 or offset is negative.

Keep limit between 0 and 500 and use a non-negative offset.

GET/voices/countries

Enumerate the supported `country` codes for the `?country=` filter.

List Countries

Returns the closed set of ISO 3166-1 alpha-2 codes the voice catalog uses, paired with display names. Sorted by code. Use this to populate a country dropdown in your app rather than hard-coding a list. The set covers every country in Europe, the Americas, Africa, and the Middle East (149 codes); Asia outside the Middle East and Oceania may be added in future releases.

GET/voices/tag-vocabulary

Enumerate the closed set of `tag` tokens accepted by the catalog.

List Tag Vocabulary

Returns the canonical vocabulary of voice tags, grouped into four UI-facing buckets: tone, voice_texture, delivery_style, and business_persona. The bucket grouping is purely a UI affordance — the underlying storage is a flat list and any token from any bucket is a valid filter value for the ?tag= filter on GET /voices. Use this endpoint to populate a tag picker in your dashboard or to validate user-supplied tag input client-side before sending it as the ?tag= filter on GET /voices. The vocabulary is static configuration and changes infrequently — safe to cache for the lifetime of a page load.

GET/voices/:voice_id

Look up one voice by its ID.

Get Voice

Returns a single voice by ID. If you have a private voice with the same ID as a global one, the private version wins, so you can override a default without renaming.

Path & Query

1
  • voice_idstringrequired

    The voice identifier — a UUID (preferred), from the id field returned by GET /voices; legacy voice_key slugs are still accepted.

Errors

1
404Voice not found

No voice with this ID is available on your account.

Re-list with GET /voices to pick a currently-available ID.

POST/voices/preview

Hear a voice. Returns a short WAV file.

Preview Voice

Synthesizes a short audio sample so you can hear what a voice sounds like before wiring it up to an agent. Returns a complete audio/wav file. Any voice on your account works; pick any id from GET /voices.Not a free TTS endpoint. The preview caps text at 300 characters and bills at the same per-character rate as POST /tts. For anything longer or production audio, use POST /tts.

Request body

2
  • voice_idstringrequired

    The voice you want to hear. Use any id from GET /voices (a UUID or legacy voice_key). The sentinel "default" is not accepted on this endpoint.

  • textstringoptional

    What the voice should say. 1–300 characters. Defaults to "Hello, this is a sample of my voice."

Errors

3
404Voice not found

The voice_id is not available on your account.

Pick a voice id from GET /voices (a UUID or legacy voice_key). The sentinel "default" is not valid here.

422Validation error

text is empty or longer than 300 characters, or voice_id is missing.

Keep text between 1 and 300 characters. For longer audio, use POST /tts.

429Rate limited

You hit your API key's rate limit.

Honor the Retry-After header and back off.