TTS Production with ElevenLabs

Generate, audition and mix narration using the ElevenLabs Text-to-Speech API. Model guidance was checked on 2026-10-07 against the official ElevenLabs TTS skill and models documentation; re-check the live endpoint, voice eligibility, quota and price before execution.

This skill uses the official HTTP API; inspect the actual schema if an optional connector is used. Use narration audition for spoken phrasing, delivery and the audition decision. Keep voice identifiers and account receipts in the private execution record.

API Pattern

Text-to-Speech with Timestamps (recommended)

curl --fail-with-body -sS -X POST "https://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}/with-timestamps" \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your text here",
    "model_id": "eleven_v4",
    "voice_settings": {
      "stability": 0.75,
      "similarity_boost": 0.80
    }
  }' \
  --output /tmp/tts-response.json

Decode Response

import json, base64
with open('/tmp/tts-response.json', 'r') as f:
    data = json.load(f)
audio_bytes = base64.b64decode(data['audio_base64'])
with open('output.mp3', 'wb') as f:
    f.write(audio_bytes)
ends = data.get('alignment', {}).get('character_end_times_seconds', [])
print(f'Duration: {ends[-1]:.2f}s' if ends else 'No timestamps')

Simple TTS (no timestamps)

curl --fail-with-body -sS -X POST "https://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}" \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Your text here", "model_id": "eleven_v4", "voice_settings": { "stability": 0.75, "similarity_boost": 0.80 } }' \
  --output output.mp3

Sound Effects Generation

curl --fail-with-body -sS -X POST "https://api.elevenlabs.io/v1/sound-generation" \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "text": "short sharp underwater splash blip", "duration_seconds": 1.0, "prompt_influence": 0.8 }' \
  --output sfx.mp3

Model Selection

Select for the actual voice, language and endpoint. Model language support does not prove that a chosen voice pronounces the script well. Preserve failed/refused requests; do not silently fall back after a paid attempt.

Voice Settings

For eleven_v4, use only stability and similarity_boost. Do not send style, speed, use_speaker_boost or SSML; these are not supported v4 controls. Supported audio tags, punctuation and spoken phrasing can direct delivery, but their result must be auditioned. The TTS stream-input WebSocket does not support v4.

Audition starting points for v4

Neutral narration (clean, informational):

{ "stability": 0.75, "similarity_boost": 0.80 }

Cinematic narration (authoritative, confident):

{ "stability": 0.55, "similarity_boost": 0.85 }

Warm/conversational:

{ "stability": 0.60, "similarity_boost": 0.75 }

Workflow

1. Check current voice/model access and output-format eligibility separately from available quota. A voice can return 402 / paid_plan_required even with remaining characters. Preserve the refusal; another eligible voice must fit the brief and budget. A plan upgrade needs separate authority.
2. Allocate audition, full narration and any one targeted repair within one cumulative production cap. Retain request/operation IDs and measured usage; reconcile unknown outcomes before another submission.
3. Generate a representative audition with difficult words, numbers and intended pauses. Listen to the actual saved audio before accepting the voice and delivery.
4. Generate full narration with timestamps when the selected endpoint supports them. Measure duration with ffprobe -i clip.mp3 -show_entries format=duration -v quiet -of csv="p=0"; listen through all clauses and any stitched boundaries.
5. Mix the accepted audio into the representative animatic and final video using FFmpeg Audio Recipes, then listen to both mixes.

QA and bounded repair

• Adjust v4 pacing by improving spoken phrasing, pauses and supported delivery directions, then audition; do not add a speed parameter.
• If existing audio is time-stretched with FFmpeg, listen for artifacts and recompute/rescale alignment. No universal tempo factor guarantees natural speech.
• Hard step ducking causes audible clicks — always use cosine-ease transitions
• Duration and expressive quality vary by voice/model; measure the actual output instead of assuming an ordering.
• Check the target language and audition pronunciation with the selected voice; language support alone is insufficient.

Check HTTP success before decoding, and confirm non-empty playable audio plus alignment before deriving timing. Listen for pronunciation, omissions, clicks and pauses. Changing tempo invalidates original timestamps; divide timing by the tempo multiplier or realign. Repair one observed defect at most once within the agreed budget. Probe/decode and transcription checks do not establish delivery quality; report any missing listening coverage.

Environment

References

• FFmpeg Audio Recipes — ducking, mixing, normalization, multi-element assembly
• Create speech with timing — request/response contract
• Gemini 3.8 Flash TTS — optional alternate provider; requires structured speech_metadata directions and returns WAV by default. This plugin does not implement that provider directly.