Forced Alignment quickstart

Learn how to use the Forced Alignment API to align text to audio.

This guide will show you how to use the Forced Alignment API to align text to audio.

Using the Forced Alignment API

Create an API key
Create an API key in the dashboard here, which you’ll use to securely access the API.
Store the key as a managed secret and pass it to the SDKs either as a environment variable via an .env file, or directly in your app’s configuration depending on your preference.
.env
JavaScript
```
ELEVENLABS_API_KEY=<your_api_key_here>
```
Install the SDK
- SDK
- CLI
We’ll also use the dotenv library to load our API key from an environment variable.
Python
TypeScript
Python
pip install elevenlabs pip install python-dotenv
Install the ElevenLabs CLI. Homebrew (macOS) and Scoop (Windows) are recommended.
Homebrew (macOS)
Homebrew (macOS)
brew install elevenlabs/tap/elevenlabs
Scoop (Windows)
Scoop (Windows)
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket scoop install elevenlabs
npm
npm
npm install -g @elevenlabs/cli
curl
curl
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
Working with an AI coding assistant? Run elevenlabs generate-skills in your project to write a SKILL.md for every command group into skills/, so your assistant knows the CLI's full surface without you pasting docs. Use --output-dir to put them elsewhere. This reads the CLI's own embedded API definition, so it needs no API key and works offline — and it stays in step with whichever CLI version you have installed.
Then authenticate — this opens your browser to authorize the CLI:
Bash
elevenlabs auth login

Make the API request

Create a new file named example.py or example.mts, depending on your language of choice and add the following code:

Python

# example.py
import os
from io import BytesIO
from elevenlabs.client import ElevenLabs
import requests
from dotenv import load_dotenv

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

# Perform the text-to-speech conversion
transcription = elevenlabs.forced_alignment.create(
    file=audio_data,
    text="With a soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditative guides, or adding an intimate feel to your narrative projects."
)

print(transcription)

Then run it:

Python

python example.py

You should see the transcript of the audio file with exact timestamps printed to the console.

Download the sample audio, then align it with the transcript:

Bash

curl -O https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3

elevenlabs forced-alignment create \
  --file nicole.mp3 \
  --text "With a soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditative guides, or adding an intimate feel to your narrative projects."

The alignment with per-word timestamps is printed to your terminal.

Next steps

Speech to Text

Transcribe audio to text without requiring an existing transcript

Text to Speech

Generate the audio from text to use with forced alignment

API reference

Explore all Forced Alignment parameters and response formats

Search documentation

Help Center

Forced Alignment quickstart

Using the Forced Alignment API

Next steps

Help Center