Generate music — a theme, background track, song, or instrumental bed.

Returns immediately with a job_id; the audio is produced in the background. Poll it with check_jobs([job_id]) to get the file path when it's ready. Fire several calls to mass-produce variants without waiting.

Args: prompt: What to make, in plain language ("uplifting orchestral intro, soaring strings" / "warm lo-fi study loop"). For a sung song, this is the theme/style and Mureka writes the lyrics; pass lyrics to supply your own. Give either this OR composition_plan (Eleven Music), not both. duration: Target length in seconds, if you care (else the model decides). instrumental: True for no vocals (BGM/underscore); False allows sung vocals. reference: Optional path (local audio file) or URL to a reference track to steer style (Mureka only — we upload it and match its vibe; Eleven Music has no such input). lyrics: Mureka song only — supply exact lyrics (incl. [Verse]/[Chorus] tags) instead of letting Mureka write them from the prompt. When set, prompt is treated as an optional style descriptor ("r&b, slow, male vocal"). engine: Provider override. Soft-defaults to Mureka; pass "elevenlabs" to use Eleven Music instead (honours prompt, duration, instrumental; ignores reference/count). format: Output format. Mureka defaults to flac (lossless, highest quality, ~half the size of wav) and also offers "wav" (lossless, uncompressed) and "mp3" (smaller) — all free from the same generation. ElevenLabs: "mp3"/"wav". count: How many tracks to generate this call, 1–3 (Mureka only). composition_plan: Eleven Music only — a structured multi-section plan (intro/verse/ chorus with per-section prompts and durations) instead of a free-text prompt. Mutually exclusive with prompt; auto-routes the job to ElevenLabs. store_for_inpainting: Eleven Music only — persist the generated song so later calls can condition on / inpaint sections of it. Surfaces a song_id in the job result (via check_jobs) to reference it later. respect_sections_durations: Eleven Music + composition_plan only — enforce each section's requested duration strictly.

Returns: {"job_id": ..., "status": "queued", "engine": ...} or {"error": ...}. When a job finishes, check_jobs also returns song_id if store_for_inpainting was set.

Write song lyrics from a theme/description (Mureka) — returns text, not audio.

Synchronous: returns immediately with the lyrics so an agent can read/review or edit them before spending song credits, then pass them to generate_music(lyrics=...). Great for getting the words right first, or generating lyrics on their own.

Args: prompt: The theme/brief ("a hopeful song about starting over in a new city").

Returns: {"title": ..., "lyrics": ...} or {"error": ...}.

Generate a sound effect — a one-shot, ambience, or seamless loop.

Returns a job_id immediately; poll with check_jobs([job_id]) for the file path.

Args: prompt: The sound to make ("heavy wooden door creak", "sci-fi UI blip", "rain on a tin roof, distant thunder"). duration_seconds: Length 0.5–30, or None to let the model choose. loop: True to produce a seamlessly loopable clip (great for ambience/BGM beds). prompt_influence: 0–1 (default ~0.3) — higher sticks closer to the prompt, lower gives the model more creative latitude. model: SFX model id override (default the current text-to-sound model). engine: Provider override. Defaults to ElevenLabs for SFX. format: Output format ("mp3" default, "wav" where supported).

Returns: {"job_id": ..., "status": "queued", "engine": ...} or {"error": ...}.

Generate spoken dialogue / character voice acting.

Returns a job_id immediately; poll with check_jobs([job_id]) for the file path. Fire several calls to voice a whole scene without waiting.

Two ways to shape delivery, and they combine:

• A profile — a saved persona/mood preset. Built-ins: neutral, narrator, calm, whisper, sad, angry, excited, shout (see list_profiles). Save your own with save_profile. A profile just presets the knobs below.

• The precision knobs — any of these override the profile for this one line. Emotion can also be written inline as Eleven v3 audio tags, e.g. "[whispers] they're coming... [shouts] run!".

Args: text: The line(s) to speak, optionally with inline v3 audio tags. voice: An ElevenLabs voice name (see list_voices) or a voice id. Overrides any voice pinned by the profile. Omit for the default voice. profile: A saved/built-in profile name to preset delivery. model: Model id (default eleven_v3 for expressive character acting). stability: v3 delivery mode — "creative" (most expressive/tag-responsive), "natural" (balanced), or "robust" (locked-in) — or a 0-1 float. style: 0-1, amplifies the speaker's stylistic character (default 0). speed: Playback speed, 1.0 = normal (roughly 0.7-1.2 is usable). similarity_boost: 0-1, adherence to the reference voice (default 0.75). use_speaker_boost: Boost speaker similarity (slightly higher latency). seed: Fix sampling (0-4294967295) for more reproducible takes. Best-effort, NOT bit-exact (especially on v3) — a character's identity comes from its voice and settings, not the seed. previous_text / next_text: Surrounding lines, for prosody continuity in a scene. language_code: ISO 639-1 code to pin the language (not for multilingual_v2). with_timestamps: Also return per-character alignment (word/char timings) as a sidecar JSON next to the audio — for lip-sync, captions, and cut timing. variants: Generate N takes of this line in parallel (2-8) so a human can pick the best — v3 varies run-to-run. Returns {"job_ids": [...]} instead of one job_id. pronunciation: One or more pronunciation-dictionary names (or ids) to apply so lore names/terms are said a fixed way — up to 3. Create one with create_pronunciation_dictionary. engine: Provider override. Defaults to ElevenLabs for speech. format: Output format ("mp3" default, "wav"/PCM where the tier supports it).

Returns: {"job_id": ..., "status": "queued", "engine": ...} or {"error": ...}.

Generate a multi-speaker dialogue scene in a single call (ElevenLabs Text-to-Dialogue).

One request renders all turns with natural back-and-forth timing — better than stitching N separate generate_speech calls. Up to 10 distinct voices, ~2000 characters total.

Args: lines: Ordered turns, each {"voice": , "text": }. An optional "speaker" label is allowed for your own clarity. v3 audio tags work in the text (e.g. "[laughs] no way!"). model: Dialogue model id (default eleven_v3). seed: Best-effort determinism for the whole scene. language_code: ISO 639-1 language pin. apply_text_normalization: "auto" | "on" | "off". engine: Provider override (defaults to ElevenLabs). format: Output format ("mp3" default).

Returns: {"job_id": ..., "status": "queued", "engine": ...} or {"error": ...}. check_jobs returns the mixed dialogue audio path.

Save a reusable speech profile (a persona/mood preset) under name.

A profile bundles delivery settings so generate_speech(profile="") reproduces it. Pin voice + a seed to lock a character's exact sound line-to-line, or leave voice out for a voice-agnostic mood you can lay over any voice. Saving a name that matches a built-in shadows it. Everything here maps to the same knobs generate_speech accepts.

Args: name: Handle to save under (e.g. "kael", "villain-calm"). voice: ElevenLabs voice name or id to pin (optional). model: Model id to pin (optional). stability: "creative"/"natural"/"robust" or a 0-1 float. style: 0-1. speed: Playback speed (1.0 = normal). similarity_boost: 0-1. use_speaker_boost: Boost speaker similarity. tag: An audio tag prepended to every line, e.g. "angry" → "[angry] ...". seed: Fix sampling for consistency (0-4294967295). description: Human note shown in list_profiles.

List speech profiles — built-in delivery presets plus any saved via save_profile.

Each entry shows its name, whether it's built-in, and the delivery settings it presets. Use a name as generate_speech(profile="").

Save a reusable SPEAKER — a pinned voice + its base delivery — under a workspace.

A speaker is the identity ("narrator"); a profile is a mood ("angry"). Speak one with speak(speaker, text, mood?) and the mood layers on top. Group speakers by workspace so casts for different projects don't collide.

Args: name: Speaker handle (e.g. "narrator"). voice: The voice to pin — an ElevenLabs voice name/id, or a saved voice/clone name. workspace: Workspace namespace (default "default"). model / stability / style / speed / similarity_boost / use_speaker_boost / seed: The speaker's BASE delivery (all optional; each overridable per line). pronunciation: A pronunciation-dictionary name/id (or list) to apply automatically whenever this speaker talks — so it always says lore names the same way. description: Human note.

Speak a line as a saved SPEAKER, optionally in a MOOD.

Resolves the speaker (voice + base delivery), layers a mood profile if given, then applies any per-line overrides. Returns a job_id like generate_speech (or job_ids if variants > 1).

Args: speaker: A saved speaker name (see list_speakers). text: The line (v3 audio tags work). mood: Optional profile name (built-in like "angry"/"whisper", or a saved one) to layer over the speaker's base delivery for this one line. workspace: Which workspace's speaker (default "default"). stability / style / speed / seed: Per-line overrides (win over speaker + mood). with_timestamps: Also emit an alignment sidecar (lip-sync/captions). variants: Generate N takes (2-8) to preview and pick the best. engine / format: as generate_speech.

List saved speakers (voice + base delivery), optionally within one workspace.

List workspace namespaces that currently hold speakers.

Preview voices for a role — search the Voice Library and return top candidates, each with a ready-made preview_url to listen to. No generation, no voice slots consumed.

Pick one, then add_speaker_from_library(name, public_owner_id, voice_id) to add + save it as a speaker. (Library voices sound better than designed ones — search here first.)

Args: query: Short role term ("narrator", "villain", "host") — one or two words. gender / age / accent / use_case: Optional label filters. n: How many candidates to return (default 5).

Add a Voice Library voice to the account AND save it as a speaker, in one step.

Combines add_library_voice + save_speaker. Consumes a voice slot. After this, speak('', text, workspace=...) uses it.

Args: name: Speaker/voice handle to save under. public_owner_id, voice_id: From a preview_voices candidate. workspace: Workspace namespace (default "default"). seed: Optional base seed for the speaker. description: Human note.

Search ElevenLabs' shared Voice Library — thousands of ready-made voices.

This is how you pick a voice instead of dialing one out of parameters: search for "warm narrator", "raspy villain", "friendly host", filter by age/gender/accent, then add the one you like with add_library_voice(...) and use it by name in generate_speech.

Keep query SHORT — one or two words ("narrator", "villain", "host"). Long sentences over-match and return almost nothing; lean on the label filters to narrow instead.

Args: query: Short free-text term ("narrator", "host", "villain"). One or two words. gender / age / accent: Label filters (e.g. age="old", gender="male"). use_case: e.g. "characters_animation", "narrative_story", "video_games". category: "professional", "famous", or "high_quality". descriptives: Extra descriptive terms (e.g. ["raspy", "gruff"]). page_size: Max results (1-100, default 20).

Returns: {"voices": [{public_owner_id, voice_id, name, description, gender, age, accent, preview_url, ...}], "count": N}. Pass public_owner_id + voice_id to add_library_voice.

Add a shared Voice Library voice to the account and save it under name.

Take public_owner_id + voice_id from search_voice_library. After this, generate_speech(voice="") uses that character. NOTE: consumes one custom-voice slot on the ElevenLabs account (tiers cap how many you can hold).

Returns: {"voice_id": , "name": ...} or {"error": ...}.

Design a brand-new custom voice from a text description (ElevenLabs Voice Design).

Describe the character ("elderly gruff grandfather, warm but gravelly, slight wheeze") and get back a few preview clips saved to the output dir. Audition them, then keep one with save_voice(name, generated_voice_id) — or pass save_as to auto-keep the first.

Args: description: The voice to synthesize, in plain language. save_as: If set, immediately save the first preview as a permanent voice under this name (consumes one custom-voice slot). text: Optional preview line (100-1000 chars); omit to auto-generate suitable text. model: Voice-design model ("eleven_multilingual_ttv_v2" default, or "eleven_ttv_v3"). guidance_scale: 0-100ish; higher sticks closer to the prompt (default ~5). loudness: -1 (quiet) to 1 (loud), default 0.5. seed: Fix generation for reproducible previews.

Returns: {"previews": [{generated_voice_id, path, duration}], "preview_text": ..., optionally "saved": {name, voice_id}} or {"error": ...}.

Save a designed voice preview (from design_voice) as a permanent, reusable voice.

Consumes one custom-voice slot on the account. After this, generate_speech(voice="") uses it.

Args: name: Handle to save under. generated_voice_id: The preview id from design_voice. description: Optional description stored on the voice.

Delete a custom voice from the ElevenLabs account, freeing a voice slot.

DESTRUCTIVE and irreversible — you must pass confirm=True. Resolves a name to its id first and refuses if the name is ambiguous (pass the exact voice_id then). Premade voices can't be deleted. Also removes local nickname aliases and warns if a saved profile still pins the voice.

Args: voice: The voice name or id to delete. confirm: Must be True to actually delete.

Clone a voice from audio sample(s) — ElevenLabs Instant Voice Cloning.

A human provides the audio FILES on the machine ofaudio runs on; pass their paths. ~1-2 minutes of clean, single-speaker audio clones best. The result is saved under name and usable immediately as generate_speech(voice=""). Consumes one voice slot, and needs a tier that allows instant cloning (see account_status).

IMPORTANT: only clone a voice you have the rights/consent to use.

Args: name: Handle to save the cloned voice under. audio_paths: Path(s) to audio files (mp3/wav/…) readable on this machine. description: Optional description stored on the voice. remove_background_noise: Run ElevenLabs' denoiser on the samples first.

List the ElevenLabs voices available on the account, plus saved speech profiles.

Returns {"account": [ {voice_id, name, category, labels, description}, ... ], "profiles": [ ... ]}. Use a voice name (or id) as generate_speech(voice=...), or a profile name as generate_speech(profile=...).

Credits + quotas for ALL configured providers in one call — check before fan-out.

Returns a section per available provider (only those with a configured key):

• "elevenlabs": tier, characters used/limit/remaining, voice slots, cloning entitlements, next quota reset, and "quality" (which audio formats this tier can request — lossless wav/pcm need Pro+, mp3_192 needs Creator+).

• "mureka": prepaid credit balance, total recharge/spending, and concurrent_request_limit (=1 on the $30 tier — drives how many music jobs run at once).

Use it to avoid mid-batch failures (out of credits / voice slots) and to pick a supported audio format for the account's tier. A provider that errors is reported under its own key rather than failing the whole call.

List ElevenLabs models available on the account, with capability flags.

Each: {model_id, name, can_do_tts, can_do_voice_conversion, max_characters, languages}. Use to pick or confirm a model id before pinning it via model=.

Transcribe speech to text (ElevenLabs Scribe) — for podcasts, meetings, captions, dubbing prep.

Args: audio: A local audio/video file path, OR a URL (hosted file, YouTube, TikTok). language: ISO code (639-1 or -3) to force; omit to auto-detect. diarize: True to label speakers (who said what). captions: "srt" or "vtt" to also write a subtitle file (from word timings) and return its path.

Returns: {"text", "language_code", "words": , "captions_path"?} or {"error"}.

Align a KNOWN script to existing audio → exact per-word timings (ElevenLabs).

Use when you already have the exact transcript (a recorded VO + its script) and want precise timings for captions/lip-sync/cut timing. (Unlike transcribe, which discovers the words — this snaps your given text to the audio.)

Args: audio: Local audio file path. text: The exact transcript/script spoken in the audio. captions: "srt" or "vtt" to also write a subtitle file from the aligned words.

Returns: {"words": , "characters": , "loss", "captions_path"?} or {"error"}.

Remove background noise / isolate the voice from an audio file (ElevenLabs).

For cleaning up field recordings, podcast takes, or noisy clips before further use.

Args: audio: Local path to the audio file to clean.

Returns: {"path": } or {"error"}.

Re-voice a recorded performance onto another voice (ElevenLabs speech-to-speech).

Keeps the delivery/timing of the input recording but swaps the voice — for dubbing, ADR, or turning your own take into a character's voice.

Args: audio: Local path to the source audio (the performance to convert). voice: Target voice — a saved name or an ElevenLabs voice id. remove_background_noise: Clean the input before converting. format: Output format ("mp3"/"wav"; wav auto-downgrades to mp3 on sub-Pro tiers). seed: Optional determinism hint.

Returns: {"path": } or {"error"}.

Create a pronunciation dictionary so specific words/names are ALWAYS said a fixed way.

Great for a game/story cast: lock how lore names, places, and invented terms are pronounced, then apply it to any speech so every character says them consistently. Save it once (by name), then pass pronunciation=<name> to generate_speech/speak, or pin it to a speaker (save_speaker(pronunciation=)).

Args: name: A name to save this dictionary under (reuse it later by name). rules: The easy form is a {word: say-it-like-this} map, e.g. {"Kaelthas": "kal-thass", "Y'ffre": "iffray"} (alias rules). For precise IPA control, pass a list of ElevenLabs rule objects ({"type":"phoneme","string_to_replace":"...","phoneme":"...","alphabet":"ipa"}). description: Optional note.

Returns: {"name", "id", "version_id", "rules": } or {"error"}.

Add rules to an existing pronunciation dictionary (by saved name or id).

Args: dictionary: A saved dictionary name (or an ElevenLabs dictionary id). rules: {word: say_as} map or a list of EL rule objects (see create_pronunciation_dictionary).

Returns: {"id", "version_id", "added": } or {"error"}.

Details for one voice (by name or id): category, labels, description, preview_url.

List saved pronunciation dictionaries (name → id/version). Apply one via generate_speech/speak pronunciation= or save_speaker pronunciation=.

List everything saved in the presets registry: speaker voices and music identities.

Batch-poll jobs by id. This is the companion to fan-out generation.

Returns one status record per id: {job_id, kind, status, provider, and — when done — path, duration, format, seed}. status is one of queued/running/succeeded/failed; failed records include an "error". Unknown ids come back with status "unknown".

List recent jobs (newest first), optionally filtered by status.

Args: status: Filter to one of queued/running/succeeded/failed, or omit for all. limit: Max records to return (default 50).