/speech-to-text

Transcription Options

Request Parameters

Single-Use Token Authentication

Generate a batch Scribe token on a trusted backend, then pass it as the token query parameter from the frontend. Do not expose the API key to the client.

TOKEN=$(elevenlabs tokens single-use create --token-type batch_scribe --query token --format raw)

elevenlabs speech-to-text convert \
  --file audio.mp3 \
  --model-id scribe_v2 \
  --token "$TOKEN"

Python Example

from elevenlabs import ElevenLabs

client = ElevenLabs()

with open("audio.mp3", "rb") as audio_file:
    result = client.speech_to_text.convert(
        file=audio_file,
        model_id="scribe_v2",
        language_code="eng",
        timestamps_granularity="word",
        diarize=True,
        keyterms=["ElevenLabs", "Scribe"]
    )

JavaScript Example

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createReadStream } from "fs";

const client = new ElevenLabsClient();

const result = await client.speechToText.convert({
  file: createReadStream("audio.mp3"),
  modelId: "scribe_v2",
  languageCode: "eng",
  timestampsGranularity: "word",
  diarize: true,
  keyterms: ["ElevenLabs", "Scribe"],
});

CLI Example

elevenlabs speech-to-text convert \
  --file audio.mp3 \
  --model-id scribe_v2 \
  --language-code eng \
  --timestamps-granularity word \
  --diarize true

Agent and Customer Role Detection

Use detect_speaker_roles with diarization when you want speaker labels tailored for contact center recordings:

Python

result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v2",
    diarize=True,
    detect_speaker_roles=True
)

for word in result.words:
    print(f"[{word.speaker_id}] {word.text}")

JavaScript

const result = await client.speechToText.convert({
  file: createReadStream("call.mp3"),
  modelId: "scribe_v2",
  diarize: true,
  detectSpeakerRoles: true,
});

for (const word of result.words ?? []) {
  console.log(`[${word.speakerId}] ${word.text}`);
}

CLI

elevenlabs speech-to-text convert \
  --file call.mp3 \
  --model-id scribe_v2 \
  --diarize true \
  --detect-speaker-roles true \
  --use-speaker-library true

Cloud Storage URL

If your media is already stored remotely and accessible over HTTPS, use cloud_storage_url instead of uploading a local file:

result = client.speech_to_text.convert(
    cloud_storage_url="https://storage.example.com/audio.mp3?signature=abc123",
    model_id="scribe_v2"
)

Transcribing from a URL

Use source_url when the media is already hosted online and you do not want to upload a file directly.

Python

result = client.speech_to_text.convert(
    model_id="scribe_v2",
    source_url="https://example.com/interview.mp4",
)

JavaScript

const result = await client.speechToText.convert({
  modelId: "scribe_v2",
  sourceUrl: "https://example.com/interview.mp4",
});

CLI

elevenlabs speech-to-text convert \
  --model-id scribe_v2 \
  --source-url "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Response Structure

{
  "text": "The complete transcribed text from the audio file.",
  "language_code": "eng",
  "language_probability": 0.98,
  "audio_duration_secs": 12.4,
  "words": [
    {
      "text": "The",
      "start": 0.0,
      "end": 0.15,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 0.15,
      "end": 0.16,
      "type": "spacing",
      "speaker_id": "speaker_0"
    }
  ]
}

Response Fields

Supported Languages (90+)

Common languages (ISO 639-3 codes):

Full list: Afrikaans, Amharic, Armenian, Azerbaijani, Belarusian, Bengali, Bosnian, Bulgarian, Burmese, Cantonese, Catalan, Cebuano, Croatian, Czech, Estonian, Filipino, Georgian, Greek, Gujarati, Hausa, Hebrew, Hungarian, Icelandic, Indonesian, Irish, Javanese, Kannada, Kazakh, Khmer, Kyrgyz, Lao, Latvian, Lithuanian, Luxembourgish, Macedonian, Malay, Malayalam, Maltese, Māori, Marathi, Mongolian, Nepali, Norwegian, Odia, Pashto, Persian, Punjabi, Romanian, Serbian, Shona, Sindhi, Slovak, Slovenian, Somali, Swahili, Tamil, Tajik, Telugu, Thai, Ukrainian, Urdu, Uzbek, Vietnamese, Welsh, Wolof, Xhosa, Yoruba, Zulu.

Format Requirements

Audio: MP3, WAV, M4A, FLAC, OGG, WebM, AAC, AIFF, Opus Video: MP4, AVI, MKV, MOV, WMV, FLV, WebM, MPEG, 3GPP

Limits:

• Maximum file size: 5.0GB (file upload) or 2GB (cloud storage URL)
• Maximum duration: 10 hours (standard) or 1 hour (multichannel mode)

Use Cases

Subtitle Generation with Speakers

result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v2",
    timestamps_granularity="word",
    diarize=True
)

# Generate SRT with speaker labels
for i, word in enumerate(result.words, 1):
    if word.type == "word":
        print(f"[{word.speaker_id}] {word.text} ({word.start:.2f}s)")

Meeting Transcription with Custom Terms

with open("meeting.mp3", "rb") as f:
    result = client.speech_to_text.convert(
        file=f,
        model_id="scribe_v2",
        diarize=True,
        keyterms=["Q4 forecast", "revenue target", "ACME Corp"]
    )

# Group by speaker
current_speaker = None
for word in result.words:
    if word.type == "word":
        if word.speaker_id != current_speaker:
            current_speaker = word.speaker_id
            print(f"\n[{current_speaker}]:", end=" ")
        print(word.text, end="")