Gladia Pre-Recorded Transcription

intent

transcribe audio and video files asynchronously using Gladia's pre-recorded API. use this skill when you have existing audio/video files or URLs (including social media and video links) and need batch transcription with features like speaker diarization, PII redaction, subtitles (SRT/VTT), translation, summarization, or other audio intelligence. do not use this for live transcription, real-time streams, or microphone input (use gladia-live-transcription instead). always prefer the official SDK; fall back to raw REST only when SDK cannot satisfy the requirement.

inputs

required:

• gladia API key (env var: GLADIA_API_KEY)
• audio input: local file path, HTTP(S) URL, social/video URL, or binary file object
  • max file size: 1000 MB
  • max duration: 135 minutes (120 min for YouTube; 4h15 for enterprise)

optional:

• gladia SDK (JavaScript or Python) installed per gladia-sdk-integration
• transcription options: language config, diarization, PII redaction, translation, summarization, subtitles, audio-to-LLM, callback URL
• polling config: interval (default 1000ms) and timeout (default 600000ms / 10 min)

external connections:

• gladia API v2 (https://api.gladia.io/v2/pre-recorded, https://api.gladia.io/v2/upload)
• webhooks (optional): callback URL for async job delivery to avoid polling

setup guidance:

• set GLADIA_API_KEY in environment or pass to client init
• for SDK use: follow gladia-sdk-integration setup
• for raw REST fallback: ensure curl/http client and Bearer auth headers

procedure

recommended workflow (SDK)

1. initialize client with API key (auto-loaded from GLADIA_API_KEY or passed explicitly)

   • input: API key
   • output: authenticated SDK client instance

2. call transcribe() with audio input and transcription options

   • input: audio (file path, URL, or file object), options object (language_config, diarization, translation, subtitles, pii_redaction, audio_to_llm, callback_url, etc.)
   • output: job created, SDK begins polling
   • note: SDK auto-uploads local files and handles job creation in one call

3. SDK polls job status with configurable interval and timeout

   • input: job ID, interval (ms), timeout (ms)
   • output: when status becomes "done", SDK returns full result object
   • edge case: if timeout exceeded before completion, SDK throws error with partial status

4. extract results from the response object

   • input: completed job result
   • output: result.result.transcription.full_transcript, result.result.diarization, result.result.subtitles, result.result.translation, result.result.summary, etc.
   • note: response shape varies by enabled features; see ./references/delivery-and-response.md

fallback workflow (raw REST, only when SDK not feasible)

1. upload local file (skip if audio is already a URL)

   • input: file bytes, POST /v2/upload with multipart form-data, Bearer token
   • output: audio_url string
   • edge case: if file exceeds 1000 MB or timeout on upload, API returns 413 or 408

2. create transcription job

   • input: audio_url, transcription options (language_config, diarization, etc.), POST /v2/pre-recorded with JSON body, Bearer token
   • output: job object with id and initial status
   • edge case: if API key invalid, returns 401; if concurrency limit hit (3 free, 25 paid), returns 429

3. poll job status until completion (or use webhook instead)

   • input: job ID, GET /v2/pre-recorded/:id, Bearer token, poll interval (3s start, max 30s exponential backoff)
   • output: updated job object with current status ("processing", "done", or "error")
   • edge case: if network timeout during poll, retry with backoff; if max retries exceeded, surface error to user

4. retrieve results when status is "done"

   • input: job ID, GET /v2/pre-recorded/:id, Bearer token
   • output: full job response with transcription, diarization, subtitles, translation, summary, etc.
   • note: do not request /v2/pre-recorded/:id/audio for transcript; use /v2/pre-recorded/:id for JSON

5. optional: download media files (subtitles, audio, etc.)

   • input: job ID, GET /v2/pre-recorded/:id/file with ?type=srt|vtt|text|json, Bearer token
   • output: file bytes (SRT, VTT, plaintext, or JSON)

post-processing (job management)

• get single job: SDK .get(id) or REST GET /v2/pre-recorded/:id
• list jobs: SDK .list(filters) or REST GET /v2/pre-recorded with query params
• delete job: SDK .delete(id) or REST DELETE /v2/pre-recorded/:id
• input: job ID or filters (status, limit, offset)
• output: job object(s) or 204 success

decision points

use SDK vs raw REST:

• if SDK is installed and available: use SDK transcribe() method (handles upload, job creation, polling automatically)
• else if SDK not installed or project constraints exist (e.g., frontend browser only): fall back to raw REST with manual upload, job creation, and polling

use polling vs webhooks:

• if callback_url is available: pass callback_url in options; skip polling, wait for async webhook delivery
• else: use SDK polling (default) or manual REST polling with exponential backoff (3s start, max 30s)

handle code-switching:

• if user enables code_switching: true without specifying languages: error; always require 3-5 expected languages in language_config.languages to avoid 100+ language auto-detection
• else: proceed with provided language list

handle pre-recorded-only features:

• if user requests diarization, PII redaction, or subtitles: confirm audio is pre-recorded (not live stream)
• else if live transcription required: redirect to gladia-live-transcription skill

handle audio input type:

• if input is local file path: SDK auto-uploads; for REST, manually upload first
• else if input is HTTP(S) URL or social URL: pass directly to job creation (no upload step)
• else if input is binary file object: SDK auto-uploads; for REST, post multipart form-data

handle job completion timeout:

• if polling timeout exceeded (default 10 min): surface error to user with current job status and ID for manual polling later
• else if status error: extract error details from response and surface to user

handle rate limits and concurrency:

• if API returns 429 (rate limit): implement exponential backoff, warn user of plan limits (3 free, 25 paid concurrent jobs)
• else if API returns 413 (file too large): surface error; file must be < 1000 MB

output contract

on success, skill delivers:

response object format (SDK):

{
  "result": {
    "id": "<job-id>",
    "status": "done",
    "transcription": {
      "full_transcript": "string",
      "paragraphs": [{ "transcript": "string", "start_time": 0, "end_time": 5000, ... }],
      ...
    },
    "diarization": {
      "speakers": [{ "speaker": 0, "transcript": "...", "start_time": 0, "end_time": 5000 }, ...],
      ...
    },
    "subtitles": {
      "srt": "1\n00:00:00,000 --> 00:00:05,000\ntext\n\n...",
      "vtt": "WEBVTT\n\n00:00:00.000 --> 00:00:05.000\ntext\n\n..."
    },
    "translation": {
      "<target-lang>": { "full_transcript": "string", ... }
    },
    "summary": {
      "bullets": ["point 1", "point 2", ...],
      "paragraph": "long summary..."
    },
    ...
  }
}

file locations (if requested):

• subtitles: via GET /v2/pre-recorded/:id/file?type=srt|vtt (SRT/VTT format)
• raw JSON: via GET /v2/pre-recorded/:id/file?type=json or in response body
• plaintext: via GET /v2/pre-recorded/:id/file?type=text

success signals:

• status: "done"
• result.transcription.full_transcript is non-empty string
• if diarization enabled: result.diarization.speakers array is present
• if subtitles enabled: result.subtitles.srt or result.subtitles.vtt is non-empty
• HTTP 200 and valid JSON response

common response fields (all optional depending on config):

• transcription: transcribed text, paragraphs, word timings, confidence scores
• diarization: speaker labels and their segments
• subtitles: SRT/VTT formatted subtitle data
• translation: translated transcripts in requested languages
• summary: bullet-point or paragraph summaries
• audio_to_llm: custom LLM-generated insights
• named_entities: extracted NER entities (if enabled)
• chapters: auto-detected topic chapters (if enabled)

outcome signal

user knows the skill worked when:

1. transcription appears: result.result.transcription.full_transcript contains non-empty transcribed text matching the audio content
2. diarization labels speakers (if enabled): result.result.diarization.speakers shows speaker 0, speaker 1, etc., with matching transcript segments
3. subtitles generated (if enabled): SRT/VTT files contain time-synced subtitle text
4. translation delivered (if enabled): result.result.translation[<target-lang>].full_transcript contains translated text
5. summary provided (if enabled): result.result.summary.bullets or .paragraph contains key takeaways
6. job status is done: response status field shows "done", not "processing" or "error"
7. no errors in response: response does not contain "error" field or HTTP error codes (4xx, 5xx)
8. callback received (if using webhooks): async POST to user's callback URL with complete result body

verify by inspecting response object in logs or console, or by checking that extracted transcript text matches the audio. if summary or subtitles are requested, confirm those fields are populated and match the transcription.

credits: original skill from clawhub. enriched per Implexa standards with explicit decision points, edge cases, rate limit handling, and comprehensive input/output contracts.