ElevenLabs Hello World

Overview

Generate speech from text using the ElevenLabs TTS API. This skill covers the

core POST /v1/text-to-speech/ 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 ELEVENLABSAPIKEY 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 elevenflashv2_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 mp344100128 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

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.