gladia-documentation-auto

Comprehensive Gladia speech-to-text reference auto-synced from docs.gladia.io. Use as a general-purpose fallback when other specialized skills don't match, or when the user needs a broad overview of Gladia capabilities, endpoints, decision guidance, or workflows. Always prefer the official SDK; fall back to raw REST/WebSocket only when SDK cannot satisfy the requirement.

SDK-first: always use the official SDK — see gladia-sdk-integration for policy, setup, and fallback criteria.

References

Consult these sibling skills as needed:

• ../gladia-sdk-integration/SKILL.md -- SDK setup, client initialization, error handling, and SDK vs raw API decision guide
• ../gladia-sdk-integration/references/sdk-versions.md -- Current SDK versions (auto-synced by CI)
• ../gladia-troubleshooting/SKILL.md -- Common errors, gotchas, and verification checklist
• ../gladia-live-transcription/SKILL.md -- Live streaming transcription
• ../gladia-pre-recorded-transcription/SKILL.md -- Pre-recorded file transcription

---

name: Gladia description: Use when building speech-to-text transcription features, processing audio or video files, implementing real-time transcription, extracting speaker information, translating transcripts, or adding audio intelligence features like summarization, sentiment analysis, and entity recognition. metadata: mintlify-proj: gladia version: "1.0"

Gladia Skill

Product summary

Gladia is a speech-to-text (STT) API that transcribes audio and video files asynchronously (pre-recorded) or in real-time (live). It supports 100+ languages, speaker diarization, translation, and audio intelligence features like summarization, sentiment analysis, and entity recognition. Use the JavaScript/Python SDKs (@gladiaio/sdk or gladiaio-sdk), REST API endpoints, or the CLI (gladia command) to transcribe. Authentication uses the x-gladia-key header. Primary docs: https://docs.gladia.io

Key endpoints:

• Pre-recorded: POST /v2/pre-recorded (create job), GET /v2/pre-recorded/{id} (get result), POST /v2/upload (upload file)
• Live: POST /v2/live (init session), WebSocket connection for streaming audio
• Authentication: x-gladia-key header on all requests

When to use

Reach for this skill when:

• A user asks to transcribe audio or video files (meetings, calls, podcasts, interviews)
• Building real-time transcription for live calls, meetings, or voice agents
• Extracting speaker information from multi-speaker audio (diarization)
• Translating transcripts to multiple languages
• Generating summaries, detecting sentiment, or extracting entities from audio
• Processing audio from URLs or local files
• Implementing webhooks or callbacks for async job completion
• Migrating from Deepgram or AssemblyAI to Gladia
• Using the CLI for quick terminal-based transcription

Quick reference

Models

Model	Use case	Languages	Code switching	Live support
solaria-3	Highest accuracy on European audio	en, fr, de, es, it	No	No (pre-recorded only)
solaria-1	Generalist, maximum coverage	100+ languages	Yes	Yes

Pre-recorded workflow

1. Upload (optional): POST /v2/upload with multipart form-data → get audio_url
2. Create job: POST /v2/pre-recorded with audio_url and options → get id
3. Get result: Poll GET /v2/pre-recorded/{id} until status: "done" or use webhooks/callbacks

Live workflow

1. Init session: POST /v2/live with audio config → get WebSocket url and id
2. Connect: Open WebSocket, send audio chunks as binary or base64
3. Read messages: Receive transcript, translation, sentiment, etc. via WebSocket
4. Stop: Send stop_recording message or close with code 1000

Audio Intelligence features (pre-recorded & live)

Feature	Parameter	Use case
Speaker diarization	diarization: true	Identify who spoke when
Translation	translation: true	Translate to multiple languages
Summarization	summarization: true	Generate summaries or bullet points
Sentiment analysis	sentiment_analysis: true	Extract emotions and tone
Named entity recognition	named_entity_recognition: true	Detect people, organizations, dates
PII redaction	pii_redaction: true	Anonymize sensitive data
Custom vocabulary	custom_vocabulary: true	Boost accuracy for domain terms
Subtitles	subtitles: true	Generate SRT or VTT files

SDK installation

bash

# JavaScript
npm install @gladiaio/sdk

# Python
pip install gladiaio-sdk
# or
uv add gladiaio-sdk

CLI installation

bash

# macOS & Linux
curl -fsSL https://github.com/gladiaio/gladia-cli/releases/latest/download/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://github.com/gladiaio/gladia-cli/releases/latest/download/install.ps1 | iex"

CLI quick commands

bash

gladia auth set YOUR_API_KEY
gladia transcribe audio.wav                    # plain text
gladia transcribe audio.wav -o json            # JSON output
gladia transcribe audio.wav --diarize          # with speaker labels
gladia transcribe audio.wav --language en,fr   # constrain languages
gladia transcribe audio.wav --model solaria-3  # use specific model

Decision guidance

When to use pre-recorded vs. live

Scenario	Use
User uploads a file, you transcribe later	Pre-recorded (/v2/pre-recorded)
Real-time call, meeting, or voice agent	Live (/v2/live + WebSocket)
Batch processing many files	Pre-recorded with polling or webhooks
Need results immediately as user speaks	Live with receive_partial_transcripts: true

When to use polling vs. webhooks vs. callbacks

Approach	Best for	Trade-off
Polling	Small jobs, quick feedback	Keeps connection open, higher latency
Webhooks	Production, many jobs	Configure once at https://app.gladia.io/webhooks
Callbacks	Per-job control	Set callback_config in request body

When to use solaria-1 vs. solaria-3

Condition	Choose
European audio, high accuracy needed	solaria-3
Multiple languages or code switching	solaria-1
Live transcription required	solaria-1 (only option)
Unknown language or 100+ language support	solaria-1

When to enable diarization

Scenario	Enable
Multi-speaker call or meeting	Yes
Single speaker or known channels	No (use channel field instead)
Want speaker labels in output	Yes, set diarization: true
Know exact speaker count	Set diarization_config.number_of_speakers
Speaker count varies	Set diarization_config.min_speakers and max_speakers

Workflow

Pre-recorded transcription (SDK)

1. Initialize client: Create GladiaClient with API key
2. Transcribe in one call: Use .transcribe(audioPath, options) for end-to-end flow
   • Pass local file path, URL, or binary data
   • SDK handles upload, job creation, polling automatically
3. Or use individual steps for fine control:
   • Upload: .uploadFile(path) → get audio_url
   • Create: .createUntyped({audio_url, ...options}) → get id
   • Poll: .get(id) until status: "done"
4. Access results: Extract result.transcription.full_transcript, utterances, translations, etc.

Pre-recorded transcription (API)

1. Upload audio (if local file): POST /v2/upload with multipart form-data
2. Create job: POST /v2/pre-recorded with JSON body containing audio_url and options
3. Poll for result: GET /v2/pre-recorded/{id} every 2–5 seconds until status: "done"
   • Or configure webhook at https://app.gladia.io/webhooks
   • Or set callback_config in request to receive POST when done
4. Parse result: Check result.transcription, result.translation, result.summarization, etc.

Live transcription (SDK)

1. Initialize session: Call .startSession(config) with audio format (encoding, sample_rate, bit_depth, channels)
2. Listen for events: Register handlers for message, started, ended, error
3. Send audio chunks: Call .sendAudio(chunk) as audio arrives
4. Read transcripts: On message event, check message.type === 'transcript' and is_final flag
5. Stop recording: Call .stopRecording() to finalize and trigger post-processing
6. Get final result: Call GET /v2/live/{id} after session ends

Live transcription (API)

1. Init session: POST /v2/live with audio config → get WebSocket url and id
2. Connect WebSocket: Open connection to returned url
3. Send audio: Send binary chunks or JSON with base64-encoded audio
4. Read messages: Parse incoming JSON messages; check type and is_final fields
5. Stop: Send {"type": "stop_recording"} or close with code 1000
6. Retrieve final result: GET /v2/live/{id} after WebSocket closes

CLI transcription

1. Set API key: gladia auth set YOUR_KEY (or export GLADIA_API_KEY)
2. Transcribe: gladia transcribe <file-or-url> [options]
3. Choose output: Use -o text|json|json-full|srt|vtt
4. Add features: Use --diarize, --language en,fr, --code-switching, --model solaria-3
5. Pipe output: Use in scripts: gladia transcribe audio.wav -o json | jq '.transcription'

Common gotchas

• solaria-3 with multiple languages: solaria-3 accepts only ONE language in language_config.languages — do not pass multiple or enable code switching. Use solaria-1 for multi-language.
• Live transcription model: Live only supports solaria-1. Attempting solaria-3 will fail.
• Audio format mismatch: Specify encoding, sample_rate, bit_depth, and channels correctly in live init — mismatches cause garbled output.
• 3-hour session limit: Live sessions terminate after 3 hours. Start a new session before hitting the limit.
• Pre-recorded duration limit: Max 135 minutes per request (4h15 for enterprise). Split longer files into ~60-minute chunks.
• File size limit: Max 1000 MB. Larger files are rejected.
• Polling without timeout: Always set a max retry count or timeout when polling — don't loop indefinitely.
• API key in client code: Never expose x-gladia-key in frontend code. Generate WebSocket URL on backend and pass only the URL to clients.
• Diarization hints are not hard constraints: number_of_speakers, min_speakers, max_speakers are hints; actual detection may differ.
• Custom vocabulary not a spell-checker: Custom vocabulary boosts recognition but doesn't force exact spelling — use custom_spelling for strict spelling control.
• Callback URL must be public: Webhook and callback endpoints must be reachable from Gladia's servers; localhost won't work.
• Multi-channel billing: Transcribing multi-channel audio is billed per channel — a 2-channel stream costs 2x the duration.
• Deprecated endpoints: Avoid /v2/transcription/* endpoints (deprecated); use /v2/pre-recorded/* instead.

Verification checklist

Before submitting transcription work:

• API key is set and valid (test with a simple request)
• Audio file or URL is accessible and in a supported format (mp3, wav, m4a, ogg, flac, etc.)
• For pre-recorded: audio duration ≤ 135 minutes (or split into chunks)
• For live: session will not exceed 3 hours
• Model choice matches use case (solaria-3 for European audio + single language; solaria-1 for multi-language or live)
• Language config is correct (solaria-3: exactly one language; solaria-1: one or more, or auto-detect)
• Audio Intelligence features are enabled only if needed (diarization, translation, etc.)
• Callback/webhook URL is public and reachable (if using async notifications)
• Result parsing handles all expected fields (transcription, translation, summarization, etc.)
• Error handling covers job failures, network timeouts, and rate limits
• For live: WebSocket reconnection logic handles network drops gracefully

Resources

Comprehensive page listing: https://docs.gladia.io/llms.txt

Critical documentation pages:

1. Pre-recorded STT Quickstart — Upload, create job, get result
2. Live STT Quickstart — WebSocket streaming, real-time transcription
3. API Reference — Full endpoint documentation, request/response schemas

---

For additional documentation and navigation, see: https://docs.gladia.io/llms.txt

---

This file is auto-synced from https://docs.gladia.io/.well-known/agent-skills/gladia/skill.md Do not edit manually — changes will be overwritten by CI. For additional documentation and navigation, see: https://docs.gladia.io/llms.txt