Implementation:Elevenlabs Elevenlabs python ForcedAlignmentClient

Field	Value
Sources	src/elevenlabs/forced_alignment/client.py, src/elevenlabs/forced_alignment/raw_client.py
Domains	Forced Alignment, Audio Processing
Last Updated	2026-02-15

Overview

The ForcedAlignmentClient provides a method for aligning audio files to text transcripts using the ElevenLabs Forced Alignment API. Forced alignment is the process of determining the precise timing of each character and word in an audio file given a known text transcript. This is useful for generating subtitles, creating synchronized animations, or performing phonetic analysis.

The client exposes a single create() method that accepts an audio file and a text transcript, and returns timing information at both the character and word level. The audio file is uploaded as a multipart form data request to the v1/forced-alignment endpoint.

The client is accessible via client.forced_alignment on an ElevenLabs instance. Both synchronous (ForcedAlignmentClient) and asynchronous (AsyncForcedAlignmentClient) variants are provided. A raw response variant is available via the with_raw_response property.

API Endpoints

Method	HTTP	Endpoint
create()	POST	v1/forced-alignment

Code Reference

Source Location

• High-level client: src/elevenlabs/forced_alignment/client.py
• Raw client: src/elevenlabs/forced_alignment/raw_client.py

Class Signatures

class ForcedAlignmentClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper): ...

class AsyncForcedAlignmentClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper): ...

Import

The client is not typically imported directly. Instead, it is accessed through the main ElevenLabs client:

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
client.forced_alignment  # ForcedAlignmentClient instance

I/O Contract

create()

Force align an audio file to text. Returns timing information for each character and word in the audio based on the provided text transcript.

Input Parameters:

Parameter	Type	Required	Description
file	core.File	Yes	The audio file to align. Accepts a file path, file-like object, or tuple of (filename, contents, content_type).
text	str	Yes	The text to align with the audio. Can be in any format; diarization is not supported.
enabled_spooled_file	typing.Optional[bool]	No	If true, the file will be streamed to the server and processed in chunks. Useful for large files that cannot be loaded into memory. Defaults to false.
request_options	typing.Optional[RequestOptions]	No	Request-specific configuration.

Output:

Type	Description
ForcedAlignmentResponseModel	Alignment results containing character-level and word-level timing information.

Error Handling

All methods may raise:

• UnprocessableEntityError (HTTP 422) -- contains an HttpValidationError body with validation details.
• ApiError -- for all other non-2xx HTTP status codes.

Usage Examples

Basic Forced Alignment

from elevenlabs import ElevenLabs

client = ElevenLabs(
    api_key="YOUR_API_KEY",
)
result = client.forced_alignment.create(
    file=open("audio.mp3", "rb"),
    text="Hello, this is a sample transcript to align.",
)

Alignment with Spooled File for Large Audio

from elevenlabs import ElevenLabs

client = ElevenLabs(
    api_key="YOUR_API_KEY",
)
result = client.forced_alignment.create(
    file=open("large_audio.wav", "rb"),
    text="This is a long transcript for a large audio file...",
    enabled_spooled_file=True,
)

Async Usage

import asyncio
from elevenlabs import AsyncElevenLabs

client = AsyncElevenLabs(
    api_key="YOUR_API_KEY",
)

async def main() -> None:
    result = await client.forced_alignment.create(
        file=open("audio.mp3", "rb"),
        text="Hello, this is a sample transcript to align.",
    )

asyncio.run(main())

Raw Response Access

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

raw_response = client.forced_alignment.with_raw_response.create(
    file=open("audio.mp3", "rb"),
    text="text",
)
print(raw_response.response.status_code)
print(raw_response.data)

Related Pages

• Elevenlabs_Elevenlabs_python_SamplesClient -- Voice sample management client
• Elevenlabs_Elevenlabs_python_Environment -- Environment and base URL configuration