Pre-Recorded Transcription

intent

transcribe pre-recorded audio and video files asynchronously using gladia's api. use this skill when you have existing audio/video files or urls (including social media links) and need batch transcription with features like speaker diarization, pii redaction, subtitles, translation, summarization, or audio intelligence. do not use this for live/real-time transcription of streams or microphone input; use the live-transcription skill instead.

inputs

gladia api credentials:

• GLADIA_API_KEY: your gladia api key (required). set as environment variable or pass to sdk client config.
• endpoint: https://api.gladia.io/v2 (default, included in sdk).

audio/video input source (one of):

• local file path (string): relative or absolute path to audio/video file on disk.
• http(s) url: publicly accessible audio/video url.
• social/video url: youtube, tiktok, instagram, facebook, twitter, twitch links (gladia auto-downloads).
• binary file object: file-like object or buffer (js/python sdk).

sdk and client setup:

• gladia javascript sdk: @gladia-io/gladia-node-sdk (npm).
• gladia python sdk: gladia-sdk (pip).
• see ../sdk-integration/SKILL.md for installation, auth setup, retry config, and timeout settings.

optional: webhook for async delivery:

• callback_url: https webhook endpoint to receive job completion events (instead of polling). requires public https endpoint.

procedure

step 1: initialize gladia client

input: gladia api key (env var or explicit config). output: authenticated client object ready for transcription.

use the official sdk (javascript or python). pass your api key via environment variable (GLADIA_API_KEY) or explicit config. see ../sdk-integration/SKILL.md for full setup.

import Gladia from "@gladia-io/gladia-node-sdk";
const client = new Gladia();

from gladia import Gladia
client = Gladia()

step 2: prepare transcription options

input: user requirements (language, diarization, subtitles, translation, etc.). output: options object (javascript or python dict).

build your transcription config. pass as the second argument to transcribe(). common options:

• language_config: object with languages array (e.g., ["en", "es"]) and optional code_switching: true if speaker switches languages.
• diarization: boolean, identifies speakers (pre-recorded only).
• translation: object with target_languages array to translate transcript.
• summarization: object with type ("bullet_points" or "paragraph").
• subtitles: object with format ("srt" or "vtt").
• pii_redaction: boolean, masks pii in transcript.
• audio_to_llm: object with model_name and prompt for custom llm processing.

for full option list and audio intelligence config, see ./references/transcription-options.md and ../audio-intelligence/SKILL.md.

step 3: call transcribe() with audio input and options

input: audio source (file path, url, or buffer) and transcription options. output: transcription result object with status, transcript, and any requested features (diarization, subtitles, etc.).

the sdk's transcribe() method handles upload, job creation, and polling in one call. pass the audio source and options:

const result = await client.preRecorded().transcribe("./audio.mp3", {
  language_config: { languages: ["en"] },
  diarization: true,
});

result = client.prerecorded().transcribe(
    "audio.mp3",
    {"language_config": {"languages": ["en"]}, "diarization": True},
)

the transcribe() method:

• uploads local files automatically to /v2/upload and gets an audio_url.
• creates a job at /v2/pre-recorded with your options.
• polls /v2/pre-recorded/:id until job completes (status: "done").
• returns the full result object.

polling behavior: sdk polls with configurable interval (default 3s) and timeout (default 600s). customize polling via optional third argument:

const result = await client.preRecorded().transcribe(audio, options, {
  interval: 5000,  // poll every 5 seconds
  timeout: 600000, // timeout after 10 minutes
});

step 4: extract and use results

input: result object from transcribe(). output: transcript text, speaker labels (if diarization), subtitles (if requested), translations, etc.

access results from result.result object:

• result.result.transcription.full_transcript: complete text transcript.
• result.result.diarization: array of speaker segments with speaker_id and text.
• result.result.subtitles: srt or vtt formatted subtitle string.
• result.result.translation: translated transcripts keyed by language code.
• result.result.summarization: summary text.
• result.result.metadata: job id, duration, language detected, etc.

decision points

if user has local audio file: pass file path (string) to transcribe(). sdk auto-uploads to /v2/upload and extracts audio_url internally.

if user has remote url (http/https or social link): pass url (string) directly to transcribe(). gladia downloads and processes.

if user needs real-time/live transcription: do not use this skill. route to live-transcription skill instead, which uses websocket streaming.

if user needs diarization, pii redaction, or subtitles: use pre-recorded api (this skill). these features are pre-recorded only and not available in live mode.

if user prefers async delivery over polling: provide callback_url in options. gladia posts job completion event to your https webhook instead of blocking on poll. requires public https endpoint. polling is default if callback_url is omitted.

if sdk cannot satisfy requirement (edge case): fall back to raw rest api only as last resort. see ../sdk-integration/SKILL.md for fallback criteria. raw workflow: upload (if local), create job at /v2/pre-recorded, poll /v2/pre-recorded/:id, extract results.

if code switching enabled but no language list provided: gladia evaluates 100+ languages, causing slow processing and potential billing impact. always provide 3-5 expected languages when code_switching: true.

if job fails or times out: check error response. common causes: invalid audio url (404), unsupported format, file exceeds 1000 mb, duration exceeds limits. see ../troubleshooting/SKILL.md for diagnostics.

output contract

success response: result object with structure:

{
  "request_id": "job-uuid",
  "status": "done",
  "result": {
    "id": "job-uuid",
    "transcription": {
      "language": "en",
      "full_transcript": "the complete text here..."
    },
    "diarization": [
      {
        "speaker_id": 1,
        "start_time": 0.5,
        "end_time": 5.2,
        "transcript": "speaker 1 text..."
      }
    ],
    "subtitles": "1\n00:00:00,000 --> 00:00:05,000\nsubtitle text\n\n2\n00:00:05,000 --> 00:00:10,000\nnext subtitle\n",
    "translation": {
      "es": "transcripción completa aquí...",
      "fr": "transcription complète ici..."
    },
    "summarization": {
      "type": "bullet_points",
      "summary": "- key point 1\n- key point 2\n"
    },
    "metadata": {
      "duration_ms": 120500,
      "audio_url": "https://...",
      "created_at": "2024-01-15T10:30:00Z"
    }
  }
}

file outputs (if requested):

• subtitles saved as .srt or .vtt file if subtitles option enabled.
• transcript can be written to .txt file.
• full result can be serialized to .json.

rate limits:

• paid tier: 25 concurrent jobs.
• free tier: 3 concurrent jobs.
• queue queued jobs and poll status to respect concurrency.

file size and duration limits:

• max file size: 1000 mb.
• max duration: 135 minutes (120 min for youtube links).
• enterprise tier: up to 4h15m duration.

outcome signal

the skill worked if:

• result.status === "done" and result.result.transcription.full_transcript contains non-empty text.
• transcript text matches expected content from the audio (spot check).
• if diarization enabled: result.result.diarization array contains speaker segments with speaker_id, timestamps, and text.
• if subtitles enabled: result.result.subtitles contains valid srt or vtt formatted string.
• if translation enabled: result.result.translation object contains target language keys with translated text.
• if pii redaction enabled: sensitive data (phone, ssn, email) is masked or removed from transcript.
• if callback_url provided: webhook post received at callback endpoint with job completion event within 1-2 seconds of job completion.
• if any feature fails: error response includes error.type and error.message describing the issue (see ../troubleshooting/SKILL.md).