list_voices

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 a set narrowed to the door you are about to call - but no ElevenLabs filter narrows much (usable_for: 'audio' still matches 222 of 230), so page it properly: send limit: 100 and check has_more. 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 BARELY SHRINKS 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 reach every voice on the account. usable_for: 'audio' narrows it only a little - to the 222 of 230 whose id also resolves on the reseller's own ElevenLabs account, which is everything except the handful of voices CLONED inside this workspace. Send limit: 100 and page it like any other filter. 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 reaches ElevenLabs through a reseller, on the RESELLER'S key, so it can speak any voice whose id resolves for every account - platform stock, and any voice added to this workspace from the ElevenLabs Voice Library, which keeps its public id. What it cannot speak is a voice CLONED inside this workspace: ElevenLabs minted that id for us alone. Read the field, do not infer it from category. 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.