{"name":"speech-to-text","url":"https://github.com/elevenlabs/skills/tree/main/speech-to-text","install":"npx skills add elevenlabs/skills --skill speech-to-text","sdk":"elevenlabs","key":"elevenlabs/speech-to-text","description":"Transcribe audio to text using ElevenLabs Scribe v2. Use when converting audio/video to text, generating subtitles, transcribing meetings, or processing spoken content.","hasContent":true,"content":"---\nname: speech-to-text\ndescription: Transcribe audio to text using ElevenLabs Scribe v2. Use when converting audio/video to text, generating subtitles, transcribing meetings, or processing spoken content.\nlicense: MIT\ncompatibility: Requires internet access and an ElevenLabs API key (ELEVENLABS_API_KEY).\nmetadata: {\"openclaw\": {\"requires\": {\"env\": [\"ELEVENLABS_API_KEY\"]}, \"primaryEnv\": \"ELEVENLABS_API_KEY\"}}\n---\n\n# ElevenLabs Speech-to-Text\n\nTranscribe audio to text with Scribe v2 - supports 90+ languages, speaker diarization, and word-level timestamps.\n\n> **Setup:** See [Installation Guide](references/installation.md). For JavaScript, use `@elevenlabs/*` packages only.\n\n## Quick Start\n\n### Python\n\n```python\nfrom elevenlabs import ElevenLabs\n\nclient = ElevenLabs()\n\nwith open(\"audio.mp3\", \"rb\") as audio_file:\n    result = client.speech_to_text.convert(file=audio_file, model_id=\"scribe_v2\")\n\nprint(result.text)\n```\n\n### JavaScript\n\n```javascript\nimport { ElevenLabsClient } from \"@elevenlabs/elevenlabs-js\";\nimport { createReadStream } from \"fs\";\n\nconst client = new ElevenLabsClient();\nconst result = await client.speechToText.convert({\n  file: createReadStream(\"audio.mp3\"),\n  modelId: \"scribe_v2\",\n});\nconsole.log(result.text);\n```\n\n### cURL\n\n```bash\ncurl -X POST \"https://api.elevenlabs.io/v1/speech-to-text\" \\\n  -H \"xi-api-key: $ELEVENLABS_API_KEY\" -F \"file=@audio.mp3\" -F \"model_id=scribe_v2\"\n```\n\n## Models\n\n| Model ID | Description | Best For |\n|----------|-------------|----------|\n| `scribe_v2` | State-of-the-art accuracy, 90+ languages | Batch transcription, subtitles, long-form audio |\n| `scribe_v2_realtime` | Low latency (~150ms) | Live transcription, voice agents |\n| `scribe_v2_realtime_turbo` | Realtime transcription variant | Live transcription |\n| `scribe_v2_realtime_lite` | Realtime transcription variant | Live transcription |\n\n## Transcription with Timestamps\n\nWord-level timestamps include type classification and speaker identification:\n\n```python\nresult = client.speech_to_text.convert(\n    file=audio_file, model_id=\"scribe_v2\", timestamps_granularity=\"word\"\n)\n\nfor word in result.words:\n    print(f\"{word.text}: {word.start}s - {word.end}s (type: {word.type})\")\n\n```\n\n## Speaker Diarization\n\nIdentify WHO said WHAT - the model labels each word with a speaker ID, useful for meetings, interviews, or any multi-speaker audio:\n\n```python\nresult = client.speech_to_text.convert(\n    file=audio_file,\n    model_id=\"scribe_v2\",\n    diarize=True\n)\n\nfor word in result.words:\n    print(f\"[{word.speaker_id}] {word.text}\")\n```\n\nFor call recordings, the batch API can label diarized speakers as `agent` and `customer` by setting `detect_speaker_roles=true` alongside `diarize=true`. This option is not compatible with `use_multi_channel=true`.\n\nIf your workspace has registered speaker profiles, set `use_speaker_library=true` with `diarize=true` to match detected speakers against the speaker library.\n\n```bash\ncurl -X POST \"https://api.elevenlabs.io/v1/speech-to-text\" \\\n  -H \"xi-api-key: $ELEVENLABS_API_KEY\" \\\n  -F \"file=@call.mp3\" \\\n  -F \"model_id=scribe_v2\" \\\n  -F \"diarize=true\" \\\n  -F \"detect_speaker_roles=true\" \\\n  -F \"use_speaker_library=true\"\n```\n\n## Multichannel Audio\n\nUse `use_multi_channel=true` when each speaker is isolated on a separate audio channel. By default, the API returns one transcript per channel under `transcripts`; set `multichannel_output_style=\"combined\"` to receive one transcript merged by timestamp, with `channel_index` on each word.\n\n```python\nresult = client.speech_to_text.convert(\n    file=audio_file,\n    model_id=\"scribe_v2\",\n    use_multi_channel=True,\n    multichannel_output_style=\"combined\",\n)\n```\n\n## Keyterm Prompting\n\nHelp the model recognize specific words it might otherwise mishear - product names, technical jargon, or unusual spellings (up to 100 terms):\n\n```python\nresult = client.speech_to_text.convert(\n    file=audio_file,\n    model_id=\"scribe_v2\",\n    keyterms=[\"ElevenLabs\", \"Scribe\", \"API\"]\n)\n```\n\n## Language Detection\n\nAutomatic detection with optional language hint:\n\n```python\nresult = client.speech_to_text.convert(\n    file=audio_file,\n    model_id=\"scribe_v2\",\n    language_code=\"eng\"  # ISO 639-1 or ISO 639-3 code\n)\n\nprint(f\"Detected: {result.language_code} ({result.language_probability:.0%})\")\n```\n\n## Supported Formats\n\n**Audio:** MP3, WAV, M4A, FLAC, OGG, WebM, AAC, AIFF, Opus\n**Video:** MP4, AVI, MKV, MOV, WMV, FLV, WebM, MPEG, 3GPP\n\n**Limits:** Up to 5.0GB file size, 10 hours duration\n\n## Response Format\n\n```json\n{\n  \"text\": \"The full transcription text\",\n  \"language_code\": \"eng\",\n  \"language_probability\": 0.98,\n  \"words\": [\n    {\"text\": \"The\", \"start\": 0.0, \"end\": 0.15, \"type\": \"word\", \"speaker_id\": \"speaker_0\"},\n    {\"text\": \" \", \"start\": 0.15, \"end\": 0.16, \"type\": \"spacing\", \"speaker_id\": \"speaker_0\"}\n  ]\n}\n```\n\n**Word types:**\n- `word` - An actual spoken word\n- `spacing` - Whitespace between words (useful for precise timing)\n- `audio_event` - Non-speech sounds the model detected (laughter, applause, music, etc.)\n\n## Error Handling\n\n```python\ntry:\n    result = client.speech_to_text.convert(file=audio_file, model_id=\"scribe_v2\")\nexcept Exception as e:\n    print(f\"Transcription failed: {e}\")\n```\n\nCommon errors:\n- **401**: Invalid API key\n- **422**: Invalid parameters\n- **429**: Rate limit exceeded\n\n## Tracking Costs\n\nMonitor usage via `request-id` response header:\n\n```python\nresponse = client.speech_to_text.convert.with_raw_response(file=audio_file, model_id=\"scribe_v2\")\nresult = response.parse()\nprint(f\"Request ID: {response.headers.get('request-id')}\")\n```\n\n## Real-Time Streaming\n\nFor live transcription with ultra-low latency (~150ms), use the real-time API. The real-time API produces two types of transcripts:\n\n- **Partial transcripts**: Interim results that update frequently as audio is processed - use these for live feedback (e.g., showing text as the user speaks)\n- **Committed transcripts**: Final, stable results after you \"commit\" - use these as the source of truth for your application\n\nA \"commit\" tells the model to finalize the current segment. You can commit manually (e.g., when the user pauses) or use Voice Activity Detection (VAD) to auto-commit on silence.\n\n### Python (Server-Side)\n\n```python\nimport asyncio\nfrom elevenlabs import ElevenLabs\n\nclient = ElevenLabs()\n\nasync def transcribe_realtime():\n    async with client.speech_to_text.realtime.connect(\n        model_id=\"scribe_v2_realtime\",\n        include_timestamps=True,\n        keyterms=[\"ElevenLabs\", \"Scribe\"],\n        no_verbatim=True,\n    ) as connection:\n        await connection.stream_url(\"https://example.com/audio.mp3\")\n\n        async for event in connection:\n            if event.type == \"partial_transcript\":\n                print(f\"Partial: {event.text}\")\n            elif event.type == \"committed_transcript\":\n                print(f\"Final: {event.text}\")\n\nasyncio.run(transcribe_realtime())\n```\n\n### JavaScript (Client-Side with React)\n\n```typescript\nimport { useScribe, CommitStrategy } from \"@elevenlabs/react\";\n\nfunction TranscriptionComponent() {\n  const [transcript, setTranscript] = useState(\"\");\n\n  const scribe = useScribe({\n    modelId: \"scribe_v2_realtime\",\n    commitStrategy: CommitStrategy.VAD, // Auto-commit on silence for mic input\n    keyterms: [\"ElevenLabs\", \"Scribe\"],\n    noVerbatim: true,\n    includeLanguageDetection: true,\n    onPartialTranscript: (data) => console.log(\"Partial:\", data.text),\n    onCommittedTranscript: (data) => setTranscript((prev) => prev + data.text),\n  });\n\n  const start = async () => {\n    // Get token from your backend (never expose API key to client)\n    const { token } = await fetch(\"/scribe-token\").then((r) => r.json());\n\n    await scribe.connect({\n      token,\n      microphone: { echoCancellation: true, noiseSuppression: true },\n    });\n  };\n\n  return <button onClick={start}>Start Recording</button>;\n}\n```\n\n### Commit Strategies\n\n| Strategy | Description |\n|----------|-------------|\n| **Manual** | You call `commit()` when ready - use for file processing or when you control the audio segments |\n| **VAD** | Voice Activity Detection auto-commits when silence is detected - use for live microphone input |\n\nSet `includeLanguageDetection: true` to receive the detected language code on committed transcript\nevents that include timestamps.\n\n```typescript\n// React: set commitStrategy on the hook (recommended for mic input)\nimport { useScribe, CommitStrategy } from \"@elevenlabs/react\";\n\nconst scribe = useScribe({\n  modelId: \"scribe_v2_realtime\",\n  commitStrategy: CommitStrategy.VAD,\n  keyterms: [\"ElevenLabs\", \"Scribe\"],\n  noVerbatim: true,\n  // Optional VAD tuning:\n  vadSilenceThresholdSecs: 1.5,\n  vadThreshold: 0.4,\n});\n```\n\n```javascript\n// JavaScript client: pass vad config on connect\nconst connection = await client.speechToText.realtime.connect({\n  modelId: \"scribe_v2_realtime\",\n  keyterms: [\"ElevenLabs\", \"Scribe\"],\n  noVerbatim: true,\n  vad: {\n    silenceThresholdSecs: 1.5,\n    threshold: 0.4,\n  },\n});\n```\n\n### Event Types\n\n| Event | Description |\n|-------|-------------|\n| `partial_transcript` | Live interim results |\n| `committed_transcript` | Final results after commit |\n| `committed_transcript_with_timestamps` | Final with word timing |\n| `error` | Error occurred |\n\nSee real-time references for complete documentation.\n\n## References\n\n- [Installation Guide](references/installation.md)\n- [Transcription Options](references/transcription-options.md)\n- [Real-Time Client-Side Streaming](references/realtime-client-side.md)\n- [Real-Time Server-Side Streaming](references/realtime-server-side.md)\n- [Commit Strategies](references/realtime-commit-strategies.md)\n- [Real-Time Event Reference](references/realtime-events.md)\n","contentSource":"https://raw.githubusercontent.com/elevenlabs/skills/main/speech-to-text/SKILL.md","contentFetchedAt":"2026-07-28T23:15:41.498Z"}