ElevenLabs Hello World

Overview

Generate speech from text using the ElevenLabs TTS API. This skill covers the core POST /v1/text-to-speech/<voice-id> endpoint with real voice IDs, model selection, and audio output. Start from the minimal SDK call below, then drill into the full implementation for the cURL, streaming, and multi-language paths.

Prerequisites

• Completed the elevenlabs-install-auth setup skill so the SDK is installed.
• A valid API key exported as ELEVENLABS_API_KEY in your shell environment.
• Node 20+ (for the TypeScript SDK path) or Python 3.9+ (for the Python path).

Instructions

The whole workflow is one API call: pick a voice ID, pick a model, send text, write the returned audio stream to a file. The minimal TypeScript path:

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createWriteStream } from "fs";
import { Readable } from "stream";
import { pipeline } from "stream/promises";

const client = new ElevenLabsClient();
const audio = await client.textToSpeech.convert("21m00Tcm4TlvDq8ikWAM", {
  text: "Hello! This is your first ElevenLabs text-to-speech generation.",
  model_id: "eleven_multilingual_v2",
});
await pipeline(Readable.fromWeb(audio as any), createWriteStream("output.mp3"));

The four generation paths, with full copy-paste code and inline commentary on every voice_settings field, live in references/implementation.md:

1. SDK (TypeScript / Python) — batch generation with tuned voice settings.
2. cURL — the raw REST call, no SDK, for shell scripts and testing.
3. Streaming — the eleven_flash_v2_5 low-latency path (~75 ms first chunk).
4. Model / voice / output-format tables — the exact IDs to plug in above.

Pick the path that matches your stack, swap the voice ID and text, and run it.

Output

A single audio file written to disk (default output.mp3), plus a console line confirming the write:

• output.mp3 — MP3 at mp3_44100_128 by default (~35–50 KB for a one-line greeting). Override the codec via output_format (see the output-format table in implementation.md).
• stdout: Audio saved to output.mp3 (or Streamed audio saved to streamed.mp3 on the streaming path).

A non-200 response returns a JSON error body instead of audio — see Error Handling below.

Error Handling

Error	HTTP	Cause	Solution
voice_not_found	404	Invalid voice ID	Use GET /v1/voices to list valid IDs
invalid_api_key	401	Bad or missing key	Check ELEVENLABS_API_KEY env var
model_not_found	400	Wrong model_id string	Use exact IDs from the models table
text_too_long	400	Exceeds 5,000 chars	Split into chunks; use streaming for long text
quota_exceeded	401	Monthly character limit hit	Check usage at elevenlabs.io/app/usage

With cURL, a failure writes the JSON error body to output.mp3; inspect it with cat output.mp3 before assuming the audio is corrupt.

Examples

Three end-to-end scenarios — first SDK MP3, one-shot cURL, and low-latency streaming — with the exact commands and the resulting on-disk artifacts are in references/examples.md. The quickest smoke test:

export ELEVENLABS_API_KEY="sk_..."
curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}" -H "Content-Type: application/json" \
  -d '{"text":"Hello from the ElevenLabs API!","model_id":"eleven_multilingual_v2"}' \
  --output output.mp3

Resources

• Full implementation walkthrough — SDK, cURL, streaming, and the model / voice / output-format tables.
• Worked examples — three runnable scenarios.
• TTS API Reference
• Stream API Reference
• Models Overview
• Voice Library

Next Steps

Once your first file plays back cleanly, proceed to elevenlabs-local-dev-loop for a development workflow with hot-reload and caching, or elevenlabs-core-workflow-a to move from pre-made voices into voice cloning.