Elevenlabs Speech to Text API Reference

Version: v1.0.0 | Last Updated: 2026-07-15 | Models: scribe_v2, scribe_v2_realtime | Status: GA
This document is written from live requests/responses against the production environment (https://platform.dataeyes.ai). All field names, types, and values strictly match actual API behavior.

1. Overview

The Speech to Text API provides high-accuracy speech recognition powered by the Scribe v2 model family, covering two typical scenarios:

Scenario	Model	Protocol	Best for
File transcription	`scribe_v2`	HTTP (`multipart/form-data`)	Offline/batch transcription of complete audio files: meeting recordings, podcasts, call QA, etc.
Realtime streaming	`scribe_v2_realtime`	WebSocket	Low-latency transcribe-as-you-speak: live captions, voice input, meeting notes, etc.

Key capabilities:

Capability	Description
Multilingual	90+ languages with automatic language detection and confidence score
Word-level timestamps	Millisecond-precision `start` / `end` per word; the realtime model additionally returns character-level timestamps
Speaker diarization	Multi-speaker audio automatically labeled with `speaker_id`
Confidence scores	Each word carries `logprob` (log probability) usable for quality filtering
Incremental streaming output	WebSocket sessions continuously push `partial_transcript` (tentative) and `committed_transcript` (final) results

2. Authentication

All requests must carry an API Key:

Authorization: Bearer YOUR_API_KEY

Protocol	How to send
HTTP	Request header `Authorization: Bearer <API_KEY>`
WebSocket	Handshake request header `Authorization: Bearer <API_KEY>`

Security note: Your API Key is a sensitive credential. Never expose it in client-side code, public repositories, or logs. Inject it via environment variables or a secrets manager.

3. Available Models & Pricing

Model ID	Description	Protocol	Billing	Status
`scribe_v2`	File transcription model. High accuracy with speaker diarization and word-level timestamps.	HTTP	By audio duration	GA
`scribe_v2_realtime`	Realtime streaming transcription model. Low-latency incremental output with word- and character-level timestamps.	WebSocket	By audio duration	GA

Both models are billed by audio duration (pay-as-you-go), independent of request count — see 7. Billing for metering rules. Refer to the console model-pricing page for the authoritative live unit price.

4. File Transcription (HTTP)

4.1 Endpoint

POST https://platform.dataeyes.ai/v1/elevenlabs/speech-to-text

Request format: multipart/form-data.

4.2 Request Parameters

Parameter	Type	Required	Description
`model_id`	`string`	Yes	Model identifier. Currently available: `scribe_v2`. Missing value returns `400`.
`file`	`file`	One of two	Audio file (binary upload). At least one of `file` / `source_url` is required. Common formats supported: wav / mp3 / m4a / flac / ogg / webm, etc.
`source_url`	`string`	One of two	Public URL of the audio file. Must be directly reachable by the transcription servers (private/intranet URLs or some region-restricted CDNs may fail). Prefer `file` upload.
`language_code`	`string`	No	Audio language (ISO 639-1/639-3, e.g. `en`, `zh`). Auto-detected if omitted. Setting it explicitly skips detection and improves accuracy (measured: `language_probability` becomes `1.0`).
`diarize`	`boolean`	No	Enable speaker diarization, default `false`. When enabled, each item in `words[]` carries a `speaker_id` (e.g. `speaker_0`, `speaker_1`).
`num_speakers`	`integer`	No	Hint for the maximum number of speakers; use together with `diarize=true` to improve separation accuracy.
`timestamps_granularity`	`string`	No	Timestamp granularity: `word` (default) / `character` / `none`.
`tag_audio_events`	`boolean`	No	Tag non-speech audio events (laughter, applause, etc.), default `true`.

All other official ElevenLabs Speech-to-Text parameters (e.g. additional_formats, file_format) are passed through verbatim and behave as officially documented.

4.3 Response Body

Returns HTTP 200 on success. Top-level fields:

Field	Type	Description
`language_code`	`string`	Detected/specified language code (ISO 639-3), e.g. `"eng"`.
`language_probability`	`float`	Language-detection confidence, 0–1. Equals `1.0` when `language_code` was explicitly provided.
`text`	`string`	Full transcript text.
`words`	`array<object>`	Per-word details with timestamps and confidence — see 4.4 The words Array.
`transcription_id`	`string`	Unique identifier of this transcription, useful for troubleshooting and log tracing.
`audio_duration_secs`	`float`	Total duration of the audio file in seconds. The billed duration is based on the `end` time of the last transcribed word — see 7. Billing.

Sample Response

Sample response (9.06-second English test audio, words truncated):

{
  "language_code": "eng",
  "language_probability": 0.8746970891952515,
  "text": "Hello DataEyes, this is a speech-to-text API test. The quick brown fox jumps over the lazy dog",
  "words": [
    {
      "text": "Hello",
      "start": 0.219,
      "end": 0.5,
      "type": "word",
      "logprob": -0.0000160931
    },
    {
      "text": " ",
      "start": 0.5,
      "end": 0.599,
      "type": "spacing",
      "logprob": -0.0573769733
    },
    {
      "text": "DataEyes,",
      "start": 0.599,
      "end": 1.179,
      "type": "word",
      "logprob": -0.2447926141
    }
  ],
  "transcription_id": "wnnnNJ3sHGJrl8gXgXyS",
  "audio_duration_secs": 9.06
}

4.4 The words Array

Field	Type	Description
`text`	`string`	Word text (punctuation included). A space when `type=spacing`.
`start`	`float`	Start time in seconds.
`end`	`float`	End time in seconds.
`type`	`string`	Element type: `word` / `spacing` (inter-word gap) / `audio_event` (requires `tag_audio_events=true`).
`logprob`	`float`	Log probability of the word (≤ 0; closer to 0 means higher confidence).
`speaker_id`	`string`	Speaker label (e.g. `"speaker_0"`). Only present when `diarize=true`.

Parsing tip: Use the top-level text field for plain text; when processing words, filter by type — do not assume word and spacing strictly alternate.

5. Realtime Transcription (WebSocket)

5.1 Connection URL

wss://platform.dataeyes.ai/v1/elevenlabs/realtime

A successful handshake returns 101 Switching Protocols. Authentication failures are rejected at the handshake with HTTP 401 — no connection is established.

5.2 Query Parameters

Parameter	Type	Required	Description
`model_id`	`string`	No	Model identifier, default `scribe_v2_realtime` (currently the only available value; passing it explicitly is recommended).
`audio_format`	`string`	No	Audio encoding, default `pcm_16000`. Format is `pcm_<sample_rate>` and must match the audio you actually send — see 5.5.
`language_code`	`string`	No	Audio language. Auto-detected if omitted.
`commit_strategy`	`string`	No	Commit strategy. Set to `vad` to let server-side voice-activity detection segment and commit automatically; by default the client commits manually via the `commit` field.
Others	—	No	All other official ElevenLabs Realtime query parameters are passed through verbatim.

Note: include_timestamps is force-set to true by the platform so that sessions can be billed precisely from word-level timestamps at session end.

5.3 Client Messages

After the connection is established, the client sends audio chunks as JSON text frames:

{
  "message_type": "input_audio_chunk",
  "audio_base_64": "<Base64-encoded PCM audio data>",
  "sample_rate": 16000,
  "commit": true
}

Field	Type	Required	Description
`message_type`	`string`	Yes	Fixed value `"input_audio_chunk"`.
`audio_base_64`	`string`	Yes	Base64-encoded raw PCM audio (16-bit, mono, little-endian, no file header).
`sample_rate`	`integer`	No	Sample rate; must match `audio_format`, e.g. `16000`.
`commit`	`boolean`	No	When `true`, the server commits the audio accumulated so far and produces final transcript results. When streaming continuously, send chunks and set `true` on the last one.

5.4 Server Messages

The server pushes JSON text frames in the following order:

session_started → partial_transcript (0–N times) → committed_transcript → committed_transcript_with_timestamps

session_started — session established

{
  "message_type": "session_started",
  "session_id": "b4c1d85547624f98adecc5a4df82511a",
  "config": {
    "sample_rate": 16000,
    "audio_format": "pcm_16000",
    "language_code": null,
    "timestamps_granularity": "word",
    "vad_commit_strategy": false,
    "vad_silence_threshold_secs": 1.5,
    "vad_threshold": 0.4,
    "min_speech_duration_ms": 100,
    "min_silence_duration_ms": 100,
    "max_tokens_to_recompute": 5,
    "model_id": "scribe_v2_realtime",
    "include_timestamps": true,
    "include_language_detection": false,
    "filter_background_audio": false,
    "keyterms": [],
    "no_verbatim": false,
    "entity_detection": null
  }
}

Field	Description
`session_id`	Unique session identifier for troubleshooting and reconciliation.
`config`	The effective session configuration (query parameters merged with defaults). Validate it before sending audio.

partial_transcript — tentative transcript (incremental, optional)

Low-latency intermediate result; may be revised by subsequent audio. Suitable for live-caption previews:

{ "message_type": "partial_transcript", "text": "Hello, DataEyes. This is" }

committed_transcript — final transcript

Returned after a commit; the text will no longer change:

{
  "message_type": "committed_transcript",
  "text": "Hello, DataEyes. This is a speech-to-text API test. The quick brown fox jumps over the lazy dog."
}

committed_transcript_with_timestamps — final transcript with timestamps

Immediately follows committed_transcript, carrying full word- and character-level timestamps:

{
  "message_type": "committed_transcript_with_timestamps",
  "text": "Hello, DataEyes. This is a speech-to-text API test. The quick brown fox jumps over the lazy dog.",
  "language_code": null,
  "words": [
    {
      "text": "Hello,",
      "start": 0.219,
      "end": 0.479,
      "type": "word",
      "speaker_id": null,
      "logprob": -0.5185597737,
      "characters": [
        { "text": "H", "start": 0.219, "end": 0.239 },
        { "text": "e", "start": 0.239, "end": 0.319 },
        { "text": "l", "start": 0.319, "end": 0.34 },
        { "text": "l", "start": 0.34, "end": 0.36 },
        { "text": "o", "start": 0.36, "end": 0.479 },
        { "text": ",", "start": 0.479, "end": 0.479 }
      ],
      "channel_index": null
    }
  ]
}

The words[] structure matches the HTTP endpoint (see 4.4) with two additional fields:

Field	Type	Description
`characters`	`array<object>`	Character-level timestamps; each item has `text` / `start` / `end`.
`channel_index`	`integer \| null`	Audio channel index; `null` for mono audio.

Error events

Upstream service errors are relayed to the client as messages (such sessions incur no charge):

message_type	Meaning
`scribeAuthError`	Service authentication error
`scribeQuotaExceededError`	Service quota exceeded
`scribeThrottledError`	Service throttled
`scribeSessionTimeLimitExceededError`	Session exceeded the maximum duration limit

5.5 Audio Format Requirements

Item	Requirement
Encoding	Raw PCM (16-bit signed, little-endian), no WAV/RIFF header
Channels	Mono
Sample rate	Must match the `audio_format` parameter; `pcm_16000` (16 kHz) recommended

Extract PCM from a WAV file (ffmpeg):

6. Complete Examples

6.1 cURL — File Transcription

6.2 Python — File Transcription

6.3 Python — Realtime (WebSocket)

Dependency: pip install websockets

6.4 Node.js — Realtime (WebSocket)

Dependency: npm install ws

7. Billing

Both models are billed by actual audio duration, independent of request count or output text length. Refer to the console model-pricing page for the current unit price.

Metering rules:

The billed duration is the audio span covered by the transcript — the end time of the last word, rounded up to whole seconds (trailing silence is not charged).

Duration is metered in audio tokens: 1 minute of audio = 1,000 audio tokens (partial minutes prorated and rounded up), reported as prompt_tokens in the usage logs.

Example: 9.06 s audio with last word end = 8.319s → rounded to 9 s → 9 / 60 × 1000 = 150 audio tokens.

Realtime sessions are settled when the connection closes; sessions that produce no committed transcript (e.g. connect then disconnect immediately) cost 0.

Failed request validation (400) and failed authentication (401) are never charged; WebSocket sessions that receive an upstream error event are not charged.

Per-request audio-token usage and cost details are visible in the console logs.

8. Error Codes

HTTP status	Scenario	Error message example	Handling
`400`	Missing required parameter such as `model_id`	`model_id is required`	Complete the required fields per 4.2.
`401`	API Key missing, malformed, or revoked (applies to both HTTP and WebSocket handshake)	`无效的令牌` (invalid token)	Confirm the header is `Authorization: Bearer <key>` and the key is valid.
`403`	The key has no access to the requested model	—	Confirm the API Key has access to the requested model.
`429`	Rate limit exceeded or insufficient quota	—	Reduce request rate and retry with exponential backoff; upgrade the plan if needed.
`500`	Invalid request (e.g. neither `file` nor `source_url` provided) or internal server error	`either file or source_url is required`	Check request completeness first; for transient server errors, contact support with the `request id` from the error message.
`503`	Service temporarily unavailable or overloaded	—	Retry with exponential backoff.

All error responses share one JSON structure: {"error": {"code": "...", "message": "... (request id: ...)", "type": "..."}}. Include the request id from message when reporting issues.

9. Best Practices

9.1 Choosing a model

You already have a complete audio file → use scribe_v2 (HTTP): one request, accuracy first.

You need transcribe-as-you-speak → use scribe_v2_realtime (WebSocket): render partial_transcript for low-latency previews and treat committed_transcript_with_timestamps as the final result.

9.2 HTTP transcription

Prefer binary file upload. source_url requires the transcription servers to reach the URL directly — intranet or restricted-CDN URLs will fail to fetch.

Pass language_code explicitly when the language is known: it skips detection and improves accuracy.

Transcription time grows with audio length; scale client timeouts with duration (start at ≥ 300 s).

9.3 Realtime sessions

Audio must be raw header-less PCM (16-bit / mono) with a sample rate matching audio_format — mismatched formats produce empty or garbled transcripts.

In production, stream audio in 100–500 ms chunks and set commit: true at the end of an utterance (or use commit_strategy=vad for server-side segmentation).

Validate the config returned in session_started to confirm your parameters took effect.

Close the connection only after receiving committed_transcript_with_timestamps to get complete timestamps; settlement happens on close.

Record session_id (WebSocket) and transcription_id (HTTP) for troubleshooting and usage reconciliation.

9.4 Working with results

Use the top-level text for plain transcripts; when processing words, branch on the type field (word / spacing / audio_event).

logprob closer to 0 means higher confidence; flag low-confidence words (e.g. logprob < -1.0) for human review.

For diarized audio, group words by speaker_id to reconstruct the per-speaker dialogue.

10. Changelog

Date	Version	Changes
2026-07-15	v1.0.0	Initial release. Supports `scribe_v2` (HTTP file transcription) and `scribe_v2_realtime` (WebSocket realtime transcription).

Written from live production testing (platform.dataeyes.ai) on 2026-07-15. Test sample: 9.06-second 16 kHz mono English audio; HTTP transcription returned 33 words elements; the realtime session message flow session_started → committed_transcript → committed_transcript_with_timestamps was verified end to end.

Elevenlabs Speech to Text API Reference

Table of Contents#

1. Overview#

2. Authentication#

3. Available Models & Pricing#

4. File Transcription (HTTP)#

4.1 Endpoint#

4.2 Request Parameters#

4.3 Response Body#

Sample Response#

4.4 The words Array#

5. Realtime Transcription (WebSocket)#

5.1 Connection URL#

5.2 Query Parameters#

5.3 Client Messages#

5.4 Server Messages#

session_started — session established#

partial_transcript — tentative transcript (incremental, optional)#

committed_transcript — final transcript#

committed_transcript_with_timestamps — final transcript with timestamps#

Error events#

5.5 Audio Format Requirements#

6. Complete Examples#

6.1 cURL — File Transcription#

6.2 Python — File Transcription#

6.3 Python — Realtime (WebSocket)#

6.4 Node.js — Realtime (WebSocket)#

7. Billing#

8. Error Codes#

9. Best Practices#

9.1 Choosing a model#

9.2 HTTP transcription#

9.3 Realtime sessions#

9.4 Working with results#

10. Changelog#

Table of Contents