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#

ModelUse caseLanguagesCode switchingLive supportsolaria-3Highest accuracy on European audioen, fr, de, es, itNoNo (pre-recorded only)solaria-1Generalist, maximum coverage100+ languagesYesYes

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)#

FeatureParameterUse caseSpeaker diarizationdiarization: trueIdentify who spoke whenTranslationtranslation: trueTranslate to multiple languagesSummarizationsummarization: trueGenerate summaries or bullet pointsSentiment analysissentiment_analysis: trueExtract emotions and toneNamed entity recognitionnamed_entity_recognition: trueDetect people, organizations, datesPII redactionpii_redaction: trueAnonymize sensitive dataCustom vocabularycustom_vocabulary: trueBoost accuracy for domain termsSubtitlessubtitles: trueGenerate 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#

ScenarioUseUser uploads a file, you transcribe laterPre-recorded ( /v2/pre-recorded)Real-time call, meeting, or voice agentLive ( /v2/live + WebSocket)Batch processing many filesPre-recorded with polling or webhooksNeed results immediately as user speaksLive with receive_partial_transcripts: true

When to use polling vs. webhooks vs. callbacks#

ApproachBest forTrade-offPollingSmall jobs, quick feedbackKeeps connection open, higher latencyWebhooksProduction, many jobsConfigure once at https://app.gladia.io/webhooksCallbacksPer-job controlSet callback_config in request body

When to use solaria-1 vs. solaria-3#

ConditionChooseEuropean audio, high accuracy neededsolaria-3Multiple languages or code switchingsolaria-1Live transcription requiredsolaria-1 (only option)Unknown language or 100+ language supportsolaria-1

When to enable diarization#

ScenarioEnableMulti-speaker call or meetingYesSingle speaker or known channelsNo (use channel field instead)Want speaker labels in outputYes, set diarization: trueKnow exact speaker countSet diarization_config.number_of_speakersSpeaker count variesSet 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