Elevenlabs Forced Alignment API Documentation

Elevenlabs Forced Alignment API Documentation

Playground

ElevenLabs Forced Alignment aligns an existing transcript with an audio recording and returns character-level and word-level timestamps as structured JSON for subtitles, captions, dubbing, localization, and transcript synchronization workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

ElevenLabs Forced Alignment aligns an existing transcript with an audio recording. Provide an audio file and the transcript spoken in that audio, and the endpoint returns structured alignment data with character-level and word-level timestamps.

This endpoint does not generate a new audio file and does not create an automatic transcript. The prompt is the existing transcript to align.

Why Choose This?

• Transcript alignment
  Align existing text with spoken audio.

• Character-level timing
  Receive timestamp data for individual characters.

• Word-level timing
  Retrieve word entries with start time, end time, and alignment loss.

• Long audio support
  Supports audio inputs up to 10 hours, subject to validation.

• Structured JSON output
  Use the returned alignment object for captions, subtitles, transcript viewers, or audio-text synchronization workflows.

Parameters

How to Use

1. Upload audio — Provide the audio recording you want to align.
2. Enter the transcript — Add the existing transcript spoken in the audio.
3. Submit — Run the alignment request.
4. Read the alignment JSON — Retrieve the structured alignment object from json.

Pricing

Pricing is based on input audio duration.

Billing is calculated per started hour. Audio duration is rounded up to the next whole hour, with a minimum charge of 1 hour and a maximum billed duration of 10 hours.

Example Costs

Billing uses the measured duration of the input audio, not transcript length or the timestamp of the last aligned word.

Best Use Cases

• Subtitle timing — Align transcript text with audio for subtitle or caption workflows.
• Transcript viewers — Build word-level or character-level synchronized transcript interfaces.
• Audio-text synchronization — Match spoken audio with existing text for playback highlighting.
• Dataset preparation — Prepare timestamped transcript data for speech or media workflows.
• Long-form audio alignment — Align interviews, podcasts, recordings, or narrated content.

Pro Tips

• Use a transcript that closely matches the spoken audio.
• Keep the transcript clean and ordered for better alignment.
• Use the measured input audio duration to estimate billing.
• Read alignment data from data.outputs[0].
• Use word-level timestamps for subtitles and character-level timestamps for more precise highlighting.
• Split very long audio when your workflow needs smaller alignment segments.

Notes

• audio and prompt are required.
• prompt must contain the existing transcript, not an instruction to generate text.
• The endpoint returns structured alignment JSON only.
• No voice ID is required.
• The supported input limit is 10 hours.
• Billing is rounded up to the next started hour and capped at 10 billed hours.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "audio": "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
  "prompt": "A cinematic ocean wave at sunrise, highly detailed"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/elevenlabs/forced-alignment" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters