Write, direct, and generate audio with ak:elevenlabs

Use ak:elevenlabs for end-to-end voice production: the agent writes and directs, and ElevenLabs performs. The Skill turns an idea or rough copy into a performance-ready script, adds delivery directions to finished copy, directs multi-speaker dialogue, and generates speech, an authorized instant voice clone, or a sound effect. Writing actions produce text only. Synthesis uses the ElevenLabs API and bundled Python helpers, so it can create local audio, consume provider quota, and, for cloning, add a persistent voice to the connected ElevenLabs account.

Choose the action

Use ak:elevenlabs when

• You have an idea, outline, article, or rough copy and need a script written for the ear, with directions the target model understands.
• You have final copy and want delivery directions added without changing a single spoken word.
• You need a multi-speaker dialogue with per-turn direction, optionally synthesized.
• You need text-to-speech from a finished script or a local text file.
• You have explicit authority to create an instant voice clone from clean audio samples.
• You need a described sound effect of up to 30 seconds.
• You can review pronunciation, identity, audio quality, rights, provider cost, and the intended distribution before using the result.

Choose another workflow when

• You need a complete video production with storyboards, mixing, and exports. Use ak:video.
• You need audio editing, normalization, transcoding, or mixing without an ElevenLabs generation request. Use an approved media-processing workflow.
• You want to clone a person without their informed consent or authorization.
• You need a live conversational agent. The packaged guide covers voice agents, but no action creates or deploys one.

Prepare the provider and source material

Writing actions (script, enhance, and the writing half of dialogue) need no API key. Before any synthesis:

• Complete Onboarding, and confirm Marketing Kit is installed for the current runtime and scope.
• Install Python and the packaged requirement elevenlabs>=1.0.0 in the approved environment.
• Make ELEVENLABS_API_KEY available through the approved secret mechanism and allow outbound requests to ElevenLabs.
• Confirm the account has the required feature access, quota, billing, and licensing for the selected operation, and confirm that the chosen model and voices are available on it.
• For cloning, supply a voice name and one or more authorized audio files. The helper accepts MP3, WAV, M4A, OGG, FLAC, and WebM paths and recommends one to two minutes of clear source audio.
• For sound effects, provide a descriptive prompt and an optional duration no greater than 30 seconds.

See Runtime adapters for broader delivery differences.

Run the Skill

Name the action and state the output boundary. This example asks for a script only, with no synthesis.

/ak:elevenlabs script "A 30-second warm, confident intro for our privacy feature: your data stays under your control." Target eleven_v4, English. Return the performance script and production notes; do not synthesize

/ak:elevenlabs script "A 30-second warm, confident intro for our privacy feature: your data stays under your control." Target eleven_v4, English. Return the performance script and production notes; do not synthesize

$ak:elevenlabs script "A 30-second warm, confident intro for our privacy feature: your data stays under your control." Target eleven_v4, English. Return the performance script and production notes; do not synthesize

The argument hint is [action: script|enhance|speak|dialogue|clone|sfx] [text-or-file]. When you omit the action, the Skill infers it: an idea or outline becomes script, final copy with "don't change the words" becomes enhance, several speakers become dialogue, and a ready script with a request for audio becomes speak.

Understand the actions

Production notes cover the model, voice, risky tags, pronunciation, chunking, and lines worth auditioning. Directions must be auditory; visual stage directions stay in the production notes, never in the spoken text.

enhance preserves every spoken word: strip the added tags and the text must match your input apart from punctuation and capitalization. Synthesis never rewrites the wording either. If a line needs to change, fix the script first.

Pick a model by use case

The Skill chooses by use case and confirms live availability on your account before any call. Model IDs, settings, prices, and limits change, so this page does not list prices or quotas.

Direction syntax follows the model. Eleven v4 and v3 take pacing and emotion from audio tags, punctuation, and text structure, and do not support SSML <break> tags. Multilingual v2 and Flash may use <break> where supported. Eleven v4 accepts only the stability and similarity voice settings.

Understand the speech helper

The bundled text-to-speech helper defaults to model eleven_v4, voice Rachel, and output output.mp3. It sends only the voice settings you pass. For a model in its capability table, it refuses a setting, flag, or <break> tag that model does not support instead of sending it; for any other model, it warns and sends only what you passed.

The helper is single-voice. It does not call Text to Dialogue, so synthesized multi-speaker files on v4 or v3 go through that API separately. Treat the defaults as bundled values, not a promise that the voice or model remains available on the connected account.

The cloning helper accepts -d/--description and --labels with JSON. The sound-effect helper accepts -o/--output (default sound_effect.mp3), -d/--duration, --loop, and --influence.

Follow the audio stages

1. Resolve the action. The Skill picks the action, target language, model, input and output paths, provider authority, consent, and publication boundary.
2. Write and direct. For script, enhance, and dialogue, it writes for the ear, plans performance beats, adds directions the target model supports, and runs a voice-readability pass. Synthesis follows only when you want audio.
3. Validate local input. It checks text or files before sending data. A missing or unsupported sample stops cloning.
4. Call the provider. The helper authenticates with ELEVENLABS_API_KEY, sends the request, and reports provider errors rather than fabricating audio. Long scripts are split at natural boundaries, with previous and next context where the model supports it.
5. Write or report the result. Speech and sound-effect audio is written to the chosen output. Cloning reports the created name and voice ID.
6. Review before use. The Skill inspects the saved audio: spoken words, language, duration, format, seams, and artifacts.

Keep consent, account mutation, and spend explicit

Never expose the API key in a prompt, generated file, log excerpt, or commit. Do not use generated or cloned audio for impersonation, deception, unauthorized endorsement, evasion of disclosure rules, or misleading testimony.

Review outputs and evidence

A complete run should report:

• The action, source text or sample paths, model, provider settings, and exact output path or returned voice ID.
• For writing actions, the performance script and, when useful, production notes.
• The provider response or a clear failure without a fabricated artifact.
• A listening review covering pronunciation, pacing, identity, artifacts, duration, and suitability for the approved context.
• Consent and rights status for source voices, scripts, music, and sound design.
• Quota or charge-relevant requests and any account or publication step still pending.

For cloning, retain the consent record and voice ID separately from public content. For speech, compare names, dates, prices, and legal or medical wording against the approved script after listening; correct text does not guarantee correct pronunciation.

Troubleshoot safely

Continue with the Marketing Kit overview or Projects, artifacts, and checkpoints.

Know the current limits

• The packaged list of available models is a historical excerpt, not a live inventory. Confirm models, voices, and settings on the account before a call.
• The speech helper is single-voice HTTP text-to-speech. It does not synthesize Text to Dialogue or stream eleven_v4_turbo.
• The current sound-effect helper accepts --loop and --influence, but its SDK request forwards only the prompt and optional duration. Do not claim the saved file is seamless or that prompt influence was applied without separate evidence.
• The cloning helper implements instant voice creation through voices.add; it does not perform the documented professional-cloning training workflow.
• Provider models, voices, language coverage, quotas, latency, prices, plan requirements, output formats, and licensing can change independently of the packaged Skill.
• Audio generation does not guarantee naturalness, identity fidelity, intelligibility, conversion, platform acceptance, or legal permission.