list_voices

pro.aicut/aicut · Verify this server

The WHOLE voice catalogue - every voice aicut can speak with, across all three TTS providers: ElevenLabs (the platform's stock voices AND this account's own cloned and custom ones), OpenAI, and Amazon Polly. Free, instant, creates nothing. THIS IS WHERE EVERY VOICE ID COMES FROM. `generate_audio`'s `voice`, `generate_fake_text_video`'s `voice_left` / `voice_right`, and `generate_image_story`'s `voice` all want an id from this list. Do not invent one, and do not assume `list_models` publishes the set - it publishes none. IT IS PAGED, AND YOU WILL NOT SEE THE WHOLE CATALOGUE IN ONE CALL. 339 voices do not fit in a tool result, so an answer is at most `limit` entries (default 20, max 100). READ `total_matching` AND `has_more` ON EVERY ANSWER BEFORE YOU SAY ANYTHING TO THE USER. `total_matching` is how many voices match your filters in total; if `has_more` is true you have seen a slice and NOT the set, and telling the user "there is no X voice" on that basis is wrong. To continue, call again with `cursor` set to the `next_cursor` you were given and the SAME `provider` / `usable_for` / `language` - changing a filter invalidates the cursor and is a 400, not a silent restart. NARROW BEFORE YOU PAGE, AND RAISE `limit` WHEN THE NARROWED SET IS THE ANSWER. Page one of 230 ElevenLabs voices is a worse answer than all 21 that can actually serve the door you are about to call - but the default page is 20, so `usable_for: 'audio'` alone still shows you 20 of those 21. Send `limit: 100` with a filter you expect to fit, and check `has_more` anyway. `usable_for` is the argument that does it: 'audio' for `generate_audio`, 'fake_text' for `generate_fake_text_video`, 'image_story' for `generate_image_story`. Every voice it returns is one that tool will accept. It works with or without `provider`, so 'which voices can I use for an image story' is a single call - though the answer is now the whole catalogue, because that door takes all three providers. ONE PLACE THE DOOR FILTER DOES NOT SHRINK ANYTHING, and it is worth knowing before you ask: `provider: 'elevenlabs'` with `usable_for: 'fake_text'` OR `'image_story'` matches the WHOLE library, because both create doors really do reach every voice on the account. `usable_for: 'audio'` is the one that narrows ElevenLabs, to its 21 platform STOCK voices - and those 21 work on every door. So for a narration or a chat side where the user has expressed no particular preference, ask for `usable_for: 'audio'` and choose from those; only widen to the whole library when they have asked for something the stock voices do not cover (a cloned voice, a specific accent), and expect to page when you do. `providers` RIDES ON EVERY ANSWER - one row per provider with its `voice_count`, the `usable_for` doors it serves and `language_bound`. It is how you see, from a page of Polly voices, that OpenAI holds eleven unrestricted ones. A `voice_count` of null means that provider's list is temporarily unreadable; its voices are simply absent from the paged stream until it recovers. EACH ENTRY has the SAME shape whatever provider it came from: `id` (the string you send as the voice), `provider`, `name`, `description` (prose, ElevenLabs only), `category`, `labels` (gender, age, accent, use_case, descriptive), `language`, `preview_url` and `usable_for`. Match the user's brief against `labels` and `description`, not against the name. `preview_url` is an mp3 sample - you cannot listen to it, so GIVE IT TO THE USER as a link beside the two or three voices you are proposing and let them decide; it is null for OpenAI and Polly, which synthesise per request and publish no sample. `category` is ElevenLabs' own bucket and is how you find the voice a user calls THEIRS: `premade` is a platform stock voice, `generated` is one CLONED inside this aicut workspace, and `professional` is a public Voice-Library voice added to it. It is null for OpenAI and Polly, which have no such buckets. `usable_for` DECIDES WHICH TOOL CAN USE IT, and getting it wrong costs a paid failure. THE ONLY DOOR THAT REFUSES ANYTHING IS `generate_audio`: it takes ElevenLabs voices and only its PLATFORM STOCK ones, because it reaches ElevenLabs through a reseller whose own key cannot see this account's library - so a voice from that library (cloned, custom, or added from the ElevenLabs Voice Library) reads 'fake_text' and 'image_story' and NOT 'audio'. Every OpenAI and Polly voice reads 'fake_text' and 'image_story' too: both video doors take all three providers. Offer only voices whose `usable_for` includes the tool you are about to call; if the user wants one of the account's own voices for a plain voice-over, say it is available on the two VIDEO tools and offer the closest stock voice for the audio one instead. POLLY IS LOCKED TO A LANGUAGE and nothing will error if you ignore that - you will just pay for a video where a US-English voice reads a German script. A Polly entry's `language` is its own ('US English', 'German'); every other provider's is null, meaning it reads any script. When you want a Polly voice, pass `provider: 'polly'` with `language` set to the language the chat will be in (`language: 'German'`) - the filter is the same check the create door runs, so every voice it returns is one the create will accept for that language. `language` is refused without `provider: 'polly'`, because the other two are not language-bound and a filter that silently did nothing would be worse than a 400. PRESENTING: name at most 3 that fit what the user asked for, one line each (name, what it sounds like, and its `preview_url` so they can hear it). NEVER dump the list, and never present a page as if it were the catalogue - if `has_more` is true and none of the entries fit, say you are looking at the first N of `total_matching` and either page on or narrow. 503 `voices_unavailable` = the provider you asked for is temporarily unreachable (only ElevenLabs is fetched live; the other two cannot go down). Say so and either use another provider or carry on with a default voice; speech still works. OUTPUT: this returns JSON for you to read. When you report back to the user, give them the media URL plus a one-line summary. Do not paste the raw JSON, job ids, or internal field names into the conversation.