Gladia Integration¶

Official Gladia API Documentation · OpenAPI schema

Gladia provides audio upload, pre-recorded transcription, and live-session APIs. Use KeyPool for the authenticated control-plane requests. For Live, KeyPool creates the session with a pooled key, then your client connects to the temporary WebSocket URL returned by Gladia; the audio stream itself is not relayed through KeyPool.

Endpoint¶

{YOUR_KEYPOOL_BASE_URL}/v1/gladia

Authentication¶

Send your KeyPool team token as a bearer token. Do not send a personal Gladia API key.

Authorization: Bearer {KEYPOOL_TOKEN}

Quick Start¶

Upload Audio¶

curl -X POST "${KEYPOOL_BASE_URL}/v1/gladia/v2/upload" \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}" \
  -F "audio=@./sample.wav"

The upload endpoint also accepts application/json with an audio_url when the audio is already hosted.

Start Pre-recorded Transcription¶

curl -X POST "${KEYPOOL_BASE_URL}/v1/gladia/v2/pre-recorded" \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/sample.wav",
    "diarization": false
  }'

Poll A Result¶

curl "${KEYPOOL_BASE_URL}/v1/gladia/v2/pre-recorded/${GLADIA_JOB_ID}" \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}"

GET /v2/pre-recorded/{id}/file returns the uploaded audio as binary application/octet-stream, not transcription metadata.

GET /v2/pre-recorded lists existing jobs with pagination and optional date filters. The interactive spec is generated from the provider schema for the supported pre-recorded surface.

Start a Live Session¶

curl -X POST "${KEYPOOL_BASE_URL}/v1/gladia/v2/live" \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "encoding": "wav/pcm",
    "sample_rate": 16000,
    "bit_depth": 16,
    "channels": 1,
    "model": "solaria-1"
  }'

Read the returned url and connect your WebSocket client to it. The URL contains a temporary session token; do not replace it with an API key. This backend-init/direct-WebSocket flow is the provider's documented design.

Current limits¶

Pre-recorded uploads accept files up to 1,000 MB and 135 minutes (Enterprise supports up to 4 hours 15 minutes).
Free plans allow three concurrent pre-recorded jobs; paid plans allow 25.
Live session initialization uses the pooled key; the audio WebSocket stream connects directly to the temporary Gladia URL.
See Gladia's concurrency limits and supported formats.

Notes¶

Use the same JSON request bodies documented by Gladia.
KeyPool injects the upstream x-gladia-key header for you.
Your token must be enabled for the gladia service.

Direct Handoff Smoke Check¶

Run the value-safe handoff check with a KeyPool team token that is enabled for gladia:

KEYPOOL_BASE_URL=https://keypool.example.com \
KEYPOOL_TEAM_TOKEN="$KEYPOOL_TOKEN" \
pnpm smoke:gladia:live

The check initializes a live session through KeyPool, validates that the response contains a temporary Gladia wss:// URL, and opens and closes that provider WebSocket directly. It does not relay audio packets through KeyPool.

Interactive API Reference¶

For in-browser testing, see API Reference -> Gladia.