Deepgram CI Integration

Examples

Run unit/schema tests on every pull request with mocked Deepgram responses. Execute one trusted protected-branch integration test against a development project using a short licensed fixture and a scoped secret; retain redacted status/metrics on failure and never inject the key into forked or untrusted CI workflows.

Overview

Set up CI/CD pipelines for Deepgram integrations with GitHub Actions. Includes unit tests with mocked SDK, integration tests against the real API, smoke tests, automated key rotation, and deployment gates.

Prerequisites

• GitHub repository with Actions enabled
• DEEPGRAM_API_KEY stored as repository secret
• @deepgram/sdk and vitest installed
• Test fixtures committed (or downloaded in CI)

Instructions

Step 1: GitHub Actions Workflow

# .github/workflows/deepgram-ci.yml
name: Deepgram CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  NODE_VERSION: '20'

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --reporter=verbose
        # Unit tests use mocked SDK — no API key needed

  integration-tests:
    runs-on: ubuntu-latest
    needs: unit-tests
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
      - run: npm ci
      - run: npm run test:integration
        env:
          DEEPGRAM_API_KEY: ${{ secrets.DEEPGRAM_API_KEY }}
        timeout-minutes: 5

  smoke-test:
    runs-on: ubuntu-latest
    needs: integration-tests
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
      - run: npm ci && npm run build
      - name: Smoke test
        run: npx tsx scripts/smoke-test.ts
        env:
          DEEPGRAM_API_KEY: ${{ secrets.DEEPGRAM_API_KEY }}
        timeout-minutes: 2

Step 2: Integration Test Suite

// tests/integration/deepgram.test.ts
import { describe, it, expect, beforeAll } from 'vitest';
import { createClient, DeepgramClient } from '@deepgram/sdk';

const SAMPLE_URL = 'https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav';

describe('Deepgram Integration', () => {
  let client: DeepgramClient;

  beforeAll(() => {
    const key = process.env.DEEPGRAM_A…

Deepgram Common Errors

Examples

For a failed transcription request, record its opaque correlation ID, environment, model, status class, and redacted timing. Check media format, credentials, timeout, and rate-limit state with a non-sensitive fixture; if the condition remains, escalate with the minimal redacted bundle rather than attaching customer audio or transcript text.

Overview

Comprehensive error reference for Deepgram API integration. Covers HTTP error codes, WebSocket errors, transcription quality issues, SDK-specific problems, and audio format debugging with real diagnostic commands.

Prerequisites

• Deepgram API key configured
• curl available for API testing
• Access to application logs

Instructions

Step 1: Quick Diagnostic

# Test API key validity
curl -s -w "\nHTTP %{http_code}\n" \
  'https://api.deepgram.com/v1/projects' \
  -H "Authorization: Token $DEEPGRAM_API_KEY"

# Test transcription endpoint
curl -s -w "\nHTTP %{http_code}\n" \
  -X POST 'https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true' \
  -H "Authorization: Token $DEEPGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav"}'

Step 2: HTTP Error Reference

Step 3: WebSocket Errors

import …

Deepgram Core Workflow A: Pre-recorded Transcription

Examples

Upload a short synthetic or licensed audio fixture to the development workflow, validate transcript format, timestamps, language/model choice, and error handling, then remove the artifact according to retention policy. Do not use customer recordings for a tutorial or log raw transcript text when a correlation ID and aggregate result suffice.

Overview

Production pre-recorded transcription service using Deepgram's REST API. Covers transcribeUrl and transcribeFile, speaker diarization, audio intelligence (summarization, topic detection, sentiment, intent), batch processing with concurrency control, and callback-based async transcription for large files.

Prerequisites

• @deepgram/sdk installed, DEEPGRAM_API_KEY configured
• Audio files: WAV, MP3, FLAC, OGG, M4A, or WebM
• For batch: p-limit package (npm install p-limit)

Instructions

Step 1: Transcription Service Class

import { createClient, DeepgramClient } from '@deepgram/sdk';
import { readFileSync } from 'fs';

interface TranscribeOptions {
  model?: 'nova-3' | 'nova-2' | 'nova-2-meeting' | 'nova-2-phonecall' | 'base';
  language?: string;
  diarize?: boolean;
  utterances?: boolean;
  paragraphs?: boolean;
  smart_format?: boolean;
  summarize?: boolean;      // Audio intelligence
  detect_topics?: boolean;  // Topic detection
  sentiment?: boolean;      // Sentiment analysis
  intents?: boolean;        // Intent recognition
  keywords?: string[];      // Keyword boosting: ["term:weight"]
  callback?: string;        // Async callback URL
}

class DeepgramTranscriber {
  private client: DeepgramClient;

  constructor(apiKey: string) {
    this.client = createClient(apiKey);
  }

  async transcribeUrl(url: string, opts: TranscribeOptions = {}) {
    const { result, error } = await this.client.listen.prerecorded.transcribeUrl(
      { url },
      {
        model: opts.model ?? 'nova-3',
        language: opts.language ?? 'en',
        smart_format: opts.smart_format ?? true,
        diarize: opts.diarize ?? false,
        utterances: opts.utterances ?? false,
        paragraphs: opts.paragraphs ?? false,
        summarize: opts.summarize ? 'v2' : undefined,
        detect_topics: opts.detect_topics ?? false,
        sentiment: opts.sentiment ?? false,
        intents: opts.intents ?? false,
        keywords: opts.keywords,
        callback: opts.callback,
      }
    );
    if (error) throw new Error(`Transcription failed: ${error.message}`);
    return result;
  }

  async transcribeFile(filePath: string, opts: TranscribeOptions = {}) {
    const audio = readFileSync(filePath);
    const mimetype = this.detectMimetype(fil…

Deepgram Core Workflow B: Live Streaming Transcription

Examples

Open a development streaming session with a non-sensitive test utterance, verify connection/authentication, partial/final transcript state, timeout, and close behavior. Enforce the session's data/consent policy and log a correlation ID plus state transitions—not audio bytes, API keys, or full participant speech.

Overview

Real-time streaming transcription using Deepgram's WebSocket API. The SDK manages the WebSocket connection via listen.live(). Covers microphone capture, interim/final result handling, speaker diarization, UtteranceEnd detection, auto-reconnect, and building an SSE endpoint for browser clients.

Prerequisites

• @deepgram/sdk installed, DEEPGRAM_API_KEY configured
• Audio source: microphone (via Sox/rec), file stream, or WebSocket audio from browser
• For mic capture: sox installed (apt install sox / brew install sox)

Instructions

Step 1: Basic Live Transcription

import { createClient, LiveTranscriptionEvents } from '@deepgram/sdk';

const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

const connection = deepgram.listen.live({
  model: 'nova-3',
  language: 'en',
  smart_format: true,
  punctuate: true,
  interim_results: true,      // Show in-progress results
  utterance_end_ms: 1000,     // Silence threshold for utterance end
  vad_events: true,           // Voice activity detection events
  encoding: 'linear16',       // 16-bit PCM
  sample_rate: 16000,         // 16 kHz
  channels: 1,                // Mono
});

// Connection lifecycle events
connection.on(LiveTranscriptionEvents.Open, () => {
  console.log('WebSocket connected to Deepgram');
});

connection.on(LiveTranscriptionEvents.Close, () => {
  console.log('WebSocket closed');
});

connection.on(LiveTranscriptionEvents.Error, (err) => {
  console.error('Deepgram error:', err);
});

// Transcript events
connection.on(LiveTranscriptionEvents.Transcript, (data) => {
  const transcript = data.channel.alternatives[0]?.transcript;
  if (!transcript) return;

  if (data.is_final) {
    console.log(`[FINAL] ${transcript}`);
  } else {
    process.stdout.write(`\r[interim] ${transcript}`);
  }
});

// UtteranceEnd — fires when speaker pauses
connection.on(LiveTranscriptionEvents.UtteranceEnd, () => {
  console.log('\n--- utterance end ---');
});

Step 2: Microphone Capture with Sox

import { spawn } from 'child_process';

function startMicrophone(connection: any) {
  // Sox captures from default mic: 16kHz, 16-bit signed LE, mono
  const mic = spawn('rec', [
    '-q',              // Quiet (no progress)
    …

Deepgram Cost Tuning

Prerequisites

• An aggregate usage/cost baseline, approved budget owner, delivery/quality SLO, and data/retention policy.
• Synthetic fixtures and a reversible optimization/change record.

Examples

Compare aggregate duration, model, concurrency, and error data in a development/staging workload, change one approved model or batching parameter, and observe the quality/latency/cost tradeoff. Revert if quality or reliability drops; do not reduce retention, privacy, or consent safeguards merely to lower spend.

Overview

Optimize Deepgram API costs through smart model selection, audio preprocessing to reduce billable minutes, usage monitoring via the Deepgram API, budget guardrails, and feature-aware cost estimation. Deepgram bills per audio minute processed.

Deepgram Pricing (2026)

Add-on costs:

• Diarization: +$0.0044/min
• Multichannel: billed per channel

Instructions

Step 1: Budget-Aware Transcription Service

import { createClient } from '@deepgram/sdk';

interface BudgetConfig {
  monthlyLimitUsd: number;
  warningThreshold: number;  // 0.0-1.0 (e.g., 0.8 = warn at 80%)
  costPerMinute: number;     // Base STT cost
}

class BudgetAwareTranscriber {
  private client: ReturnType<typeof createClient>;
  private config: BudgetConfig;
  private monthlySpendUsd = 0;
  private monthlyMinutes = 0;

  constructor(apiKey: string, config: BudgetConfig) {
    this.client = createClient(apiKey);
    this.config = config;
  }

  async transcribe(source: any, options: any) {
    // Estimate cost before transcription
    const estimatedCost = this.estimateCost(options);
    const projected = this.monthlySpendUsd + estimatedCost;

    if (projected > this.config.monthlyLimitUsd) {
      throw new Error(
        `Budget exceeded: $${this.monthlySpendUsd.toFixed(2)} spent, ` +
        `$${this.config.monthlyLimitUsd} limit`
      );
    }

    if (projected > this.config.monthlyLimitUsd * th…

Deepgram Data Handling

Prerequisites

• Data classification, consent/legal basis, approved retention/deletion policy, storage boundary, and named data owner.
• A redaction/logging policy and an incident route for recording or transcript exposure.

Examples

Process a licensed development fixture through the approved region/storage route, verify its retention/deletion behavior, and record only a correlation ID and policy result. Do not put recordings, transcripts, participant identifiers, or storage URLs into test logs; on accidental exposure, restrict access and follow the data incident procedure.

Overview

Best practices for handling audio and transcript data with Deepgram. Covers Deepgram's built-in redact parameter for PII, secure audio upload with encryption, transcript storage patterns, data retention policies, and GDPR/HIPAA compliance workflows.

Data Privacy Quick Reference

Deepgram's data policy: Audio is processed in real-time and not stored. Transcripts are not retained unless you use Deepgram's optional storage features.

Instructions

Step 1: Deepgram Built-in PII Redaction

import { createClient } from '@deepgram/sdk';

const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

// Deepgram redacts PII directly during transcription
const { result } = await deepgram.listen.prerecorded.transcribeUrl(
  { url: audioUrl },
  {
    model: 'nova-3',
    smart_format: true,
    redact: ['pci', 'ssn'],  // Credit cards + SSNs -> [REDACTED]
  }
);

// Output: "My card is [REDACTED] and SSN is [REDACTED]"
console.log(result.results.channels[0].alternatives[0].transcript);

// For maximum privacy, redact all numbers:
// redact: ['pci', 'ssn', 'numbers']

Step 2: Application-Level PII Redaction

// Additional redaction patterns beyond Deepgram's built-in
const piiPatterns: Array<{ name: string; pattern: RegExp; replacement: string }> = [
  { name: 'email',    pattern: /\b[\w.-]+@[\w.-]+\.\w{2,}\b/g, replacement: '[EMAIL]' },
  { name: 'phone',    pattern: /\b(\+?\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d…

Deepgram Debug Bundle

Examples

For a streaming failure, collect the correlation ID, environment, client/SDK version, model, connection state transitions, redacted status, and timestamp. Review the bundle for keys, audio bytes, transcript text, participant identifiers, and storage URLs before sharing; reproduce with a licensed fixture and use the approved support/incident route.

Current State

!node --version 2>/dev/null || echo 'Node.js not installed' !npm list @deepgram/sdk 2>/dev/null | grep deepgram || echo '@deepgram/sdk not found' !python3 --version 2>/dev/null || echo 'Python not installed'

Overview

Collect comprehensive debug information for Deepgram support tickets. Generates a sanitized bundle with environment info, API connectivity tests, audio analysis, request/response logs, and a minimal reproduction script. All API keys are automatically redacted.

Prerequisites

• Deepgram API key configured
• ffprobe available for audio analysis (part of ffmpeg)
• Sample audio that reproduces the issue

Instructions

Step 1: Environment Collection Script

#!/bin/bash
set -euo pipefail
BUNDLE_DIR="deepgram-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

# System info
{
  echo "=== System ==="
  uname -a
  echo ""
  echo "=== Node.js ==="
  node --version 2>/dev/null || echo "Not installed"
  echo ""
  echo "=== @deepgram/sdk ==="
  npm list @deepgram/sdk 2>/dev/null || echo "Not installed"
  echo ""
  echo "=== Python ==="
  python3 --version 2>/dev/null || echo "Not installed"
  pip show deepgram-sdk 2>/dev/null || echo "Not installed"
} > "$BUNDLE_DIR/environment.txt"

Step 2: API Connectivity Tests

# Test REST API
{
  echo "=== REST API Test ==="
  echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
  echo ""
  echo "--- Project listing ---"
  curl -s -w "\nHTTP: %{http_code} | Time: %{time_total}s\n" \
    'https://api.deepgram.com/v1/projects' \
    -H "Authorization: Token $DEEPGRAM_API_KEY" 2>&1 | \
    sed "s/$DEEPGRAM_API_KEY/REDACTED/g"
  echo ""
  echo "--- Transcription test (Bueller sample) ---"
  curl -s -w "\nHTTP: %{http_code} | Time: %{time_total}s\n" \
    -X POST 'https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true' \
    -H "Authorization: Token $DEEPGRAM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url":"https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav"}' 2>&…

Deepgram Deploy Integration

Examples

Deploy a versioned integration to staging with a scoped secret reference and a short licensed fixture, then verify health, timeout/retry behavior, redacted metrics, and the rollback command. Promote through a controlled production canary only after data/consent and quality checks pass; do not deploy a key or audio fixture in the manifest.

Overview

Deploy Deepgram transcription services to Docker, Kubernetes, AWS Lambda, and Google Cloud Run. Includes production Dockerfile, K8s manifests with secret management, serverless handlers for event-driven transcription, and health check patterns.

Prerequisites

• Working Deepgram integration (tested locally)
• Production API key in secret manager
• Container registry access (Docker Hub, ECR, GCR)
• Target platform CLI installed

Instructions

Step 1: Production Dockerfile

# Multi-stage build for minimal production image
FROM node:20-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci --production=false
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

FROM node:20-alpine AS runtime

# Security: non-root user
RUN addgroup -g 1001 -S app && adduser -S app -u 1001
WORKDIR /app

# Production dependencies only
COPY package*.json ./
RUN npm ci --production && npm cache clean --force

# Copy built application
COPY --from=builder /app/dist ./dist

# Health check (tests Deepgram connectivity)
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD wget -q --spider http://localhost:3000/health || exit 1

USER app
EXPOSE 3000

CMD ["node", "dist/server.js"]

Step 2: Docker Compose

# docker-compose.yml
version: '3.8'

services:
  deepgram-service:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DEEPGRAM_API_KEY=${DEEPGRAM_API_KEY}
      - DEEPGRAM_MODEL=nova-3
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '1.0'

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data

volumes:
  redis-data:

Step 3: Kubernetes Deployment

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: deepgram-service
  labels:
    app: deepgram-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: deepgram-service
  template:
    metadata:
      labels:
        app: deepgram-service
    spec:
      containers:
        - name: deepgram-service
       …

Deepgram Enterprise RBAC

Prerequisites

• A verified identity source, named project/role owners, least-privilege role map, and access-review schedule.
• Authority to provision/revoke users and service credentials through approved identity/admin paths.

Examples

Grant a transcription service account only the development project scope it needs, validate its permitted action with a synthetic fixture, and record the owner and expiration/review date. Confirm that the same identity cannot access production; on role mismatch, revoke the broad assignment and correct the group mapping before further use.

Overview

Role-based access control for enterprise Deepgram deployments. Maps five application roles to Deepgram API key scopes, implements scoped key provisioning via the Deepgram Management API, Express permission middleware, team management with auto-provisioned keys, and automated key rotation.

Deepgram Scope Reference

Instructions

Step 1: Define Roles and Scope Mapping

interface Role {
  name: string;
  deepgramScopes: string[];
  keyExpiry: number;        // Days
  description: string;
}

const ROLES: Record<string, Role> = {
  admin: {
    name: 'Admin',
    deepgramScopes: ['member'],
    keyExpiry: 90,
    description: 'Full access — project and key management',
  },
  developer: {
    name: 'Developer',
    deepgramScopes: ['listen', 'speak'],
    keyExpiry: 90,
    description: 'STT and TTS — no management access',
  },
  analyst: {
    name: 'Analyst',
    deepgramScopes: ['usage:read'],
    keyExpiry: 365,
    description: 'Read-only usage metrics',
  },
  service: {
    name: 'Service Account',
    deepgramScopes: ['listen'],
    keyExpiry: 90,
    description: 'STT only — for automated systems',
  },
  auditor: {
    name: 'Auditor',
    deepgramScopes: ['usage:read', 'keys:read'],
    keyExpiry: 30,
    description: 'Read-only audit access',
  },
};

Step 2: Scoped Key Provisioning

Deepgram Hello World

Examples

Transcribe a short licensed fixture in the development project, verify the response shape and selected model/language, and remove the fixture according to the test policy. Keep only a correlation ID and aggregate result in logs; do not use a customer call or retain its transcript as a tutorial artifact.

Overview

Minimal working examples for Deepgram speech-to-text. Transcribe an audio URL in 5 lines with createClient + listen.prerecorded.transcribeUrl. Includes local file transcription, Python equivalent, and Nova-3 model selection.

Prerequisites

• npm install @deepgram/sdk completed
• DEEPGRAM_API_KEY environment variable set
• Audio source: URL or local file (WAV, MP3, FLAC, OGG, M4A)

Instructions

Step 1: Transcribe Audio from URL (TypeScript)

import { createClient } from '@deepgram/sdk';

const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

async function main() {
  const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
    { url: 'https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav' },
    {
      model: 'nova-3',        // Latest model — best accuracy
      smart_format: true,     // Auto-punctuation, paragraphs, numerals
      language: 'en',
    }
  );

  if (error) throw error;

  const transcript = result.results.channels[0].alternatives[0].transcript;
  console.log('Transcript:', transcript);
  console.log('Confidence:', result.results.channels[0].alternatives[0].confidence);
}

main();

Step 2: Transcribe a Local File

import { createClient } from '@deepgram/sdk';
import { readFileSync } from 'fs';

const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

async function transcribeFile(filePath: string) {
  const audio = readFileSync(filePath);

  const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
    audio,
    {
      model: 'nova-3',
      smart_format: true,
      // Deepgram auto-detects format, but you can specify:
      mimetype: 'audio/wav',
    }
  );

  if (error) throw error;

  console.log(result.results.channels[0].alternatives[0].transcript);
}

transcribeFile('./meeting-recording.wav');

Step 3: Python Equivalent

import os
from deepgram import DeepgramClient, PrerecordedOptions

client = DeepgramClient(os.environ["DEEPGRAM_API_KEY"])

# URL transcription
url = {"url": "https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav"}
options = PrerecordedOptions(model="nova-3", smart_format=True, language="en")

response = client.listen.rest.v("1").transcribe_…

Deepgram Incident Runbook

Prerequisites

• An incident ID, commander, affected service/environment, escalation route, and authorized redacted diagnostic access.
• A data/consent owner and documented safe mitigation or rollback action.

Examples

For elevated transcription errors, declare scope, capture aggregate health and redacted correlation IDs, stabilize with the documented circuit-breaker/rollback, and verify recovery against the SLO. Escalate provider or data-impact incidents through the approved path; do not attach customer audio, transcripts, or credentials to the incident channel.

Overview

Standardized incident response for Deepgram-related production issues. Includes automated triage script, severity classification (SEV1-SEV4), immediate mitigation actions, fallback activation, and post-incident review template.

Quick Reference

Severity Classification

Instructions

Step 1: Automated Triage (First 5 Minutes)

#!/bin/bash
set -euo pipefail
echo "=== Deepgram Incident Triage ==="
echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo ""

# 1. Check Deepgram status page
echo "--- Status Page ---"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://status.deepgram.com)
echo "Status page: HTTP $STATUS"

# 2. Test API connectivity
echo ""
echo "--- API Connectivity ---"
curl -s -w "\nHTTP: %{http_code} | Latency: %{time_total}s\n" \
  'https://api.deepgram.com/v1/projects' \
  -H "Authorization: Token $DEEPGRAM_API_KEY" | head -5

# 3. Test transcription
echo ""
echo "--- Transcription Test ---"
RESULT=$(curl -s -w "\n%{http_code}" \
  -X POST 'https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true' \
  -H "Authorization: Token $DEEPGRAM_API_KEY" …

Deepgram Install & Auth

Examples

Load a development API key from the approved secret manager and send a short, non-sensitive audio fixture to the intended Deepgram project. Record only the project/environment and result. If the key appears in a repository, log, or support ticket, revoke it immediately and issue a replacement before investigating further.

Current State

!npm list @deepgram/sdk 2>/dev/null || echo '@deepgram/sdk not installed' !pip show deepgram-sdk 2>/dev/null | grep Version || echo 'deepgram-sdk (Python) not installed'

Overview

Install the Deepgram SDK and configure API key authentication. Deepgram provides speech-to-text (Nova-3, Nova-2), text-to-speech (Aura-2), and audio intelligence APIs. The JS SDK uses createClient() (v3/v4) or new DeepgramClient() (v5+).

Prerequisites

• Node.js 18+ or Python 3.10+
• Deepgram account at console.deepgram.com
• API key from Console > Settings > API Keys

Instructions

Step 1: Install SDK

Node.js (v3/v4 — current stable):

npm install @deepgram/sdk
# or
pnpm add @deepgram/sdk

Python:

pip install deepgram-sdk

Step 2: Configure API Key

# Option A: Environment variable (recommended)
export DEEPGRAM_API_KEY="your-api-key-here"

# Option B: .env file (add .env to .gitignore)
echo 'DEEPGRAM_API_KEY=your-api-key-here' >> .env

Never hardcode keys. Use dotenv for local dev, secret managers in production.

Step 3: Initialize Client (TypeScript)

import { createClient } from '@deepgram/sdk';

// Reads DEEPGRAM_API_KEY from env automatically
const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

SDK v5+ uses a different constructor:

import { DeepgramClient } from '@deepgram/sdk';
const deepgram = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

Step 4: Initialize Client (Python)

from deepgram import DeepgramClient, PrerecordedOptions, LiveOptions
import os

client = DeepgramClient(os.environ["DEEPGRAM_API_KEY"])

Step 5: Verify Connection

// TypeScript — list projects to verify key is valid
async function verify() {
  const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);
  const { result, error } = await deepgram.manage.getProjects();
  if (error) {
    console.error('Auth failed:', error.message);
    process.exit(1);
  }
  console…

Deepgram Local Dev Loop

Examples

Use a local or development workspace with a short licensed fixture, make one SDK/config change, run the focused unit test and a bounded integration test, then inspect redacted metrics. Commit only the reviewed change; never copy production recordings, transcripts, or API keys into a local test loop.

Overview

Set up a fast local development workflow for Deepgram: test fixtures with sample audio, mock responses for offline unit tests, Vitest integration tests against the real API, and a watch-mode transcription dev server.

Prerequisites

• @deepgram/sdk installed, DEEPGRAM_API_KEY configured
• npm install -D vitest tsx dotenv for testing and dev server
• Optional: curl for downloading test fixtures

Instructions

Step 1: Project Structure

mkdir -p src tests/mocks fixtures
touch src/transcribe.ts tests/transcribe.test.ts tests/mocks/deepgram-responses.ts

Step 2: Download Test Fixtures

# Deepgram provides free sample audio files
curl -o fixtures/nasa-podcast.wav \
  https://static.deepgram.com/examples/nasa-podcast.wav

curl -o fixtures/bueller.wav \
  https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav

Step 3: Environment Config

# .env.development
DEEPGRAM_API_KEY=your-dev-key
DEEPGRAM_MODEL=nova-3

# .env.test (use a separate test key with low limits)
DEEPGRAM_API_KEY=your-test-key
DEEPGRAM_MODEL=base

{
  "scripts": {
    "dev": "tsx watch src/transcribe.ts",
    "test": "vitest",
    "test:watch": "vitest --watch",
    "test:integration": "vitest run tests/integration/"
  }
}

Step 4: Mock Deepgram Responses

// tests/mocks/deepgram-responses.ts
export const mockPrerecordedResult = {
  metadata: {
    request_id: 'mock-request-id-001',
    created: '2026-01-01T00:00:00.000Z',
    duration: 12.5,
    channels: 1,
    models: ['nova-3'],
    model_info: { 'nova-3': { name: 'nova-3', version: '2026-01-01' } },
  },
  results: {
    channels: [{
      alternatives: [{
        transcript: 'Life moves pretty fast. If you don\'t stop and look around once in a while, you could miss it.',
        confidence: 0.98,
        words: [
          { word: 'life', start: 0.08, end: 0.32, confidence: 0.99, punctuated_word: 'Life' },
          { word: 'moves', start: 0.32, end: 0.56, confidence: 0.98, punctuated_word: 'moves' },
          { word: 'pretty', start: 0.56, end: 0.88, confidence: 0.97, punctuated_word: 'pretty' },
        …

Deepgram Migration Deep Dive

Prerequisites

• An inventory of existing audio/transcript flows, data retention/consent obligations, evaluation fixtures, and rollback owner.
• A staging environment with separate credentials and a compatibility/quality acceptance threshold.

Examples

Run the old and new transcription flow against approved non-sensitive fixtures, compare aggregate accuracy/latency/error metrics, and route a small reversible staging canary only after acceptance passes. Roll back immediately on quality, consent, or operational regression; do not bulk-migrate or reprocess customer recordings before the observation window closes.

Current State

!npm list @deepgram/sdk 2>/dev/null | grep deepgram || echo 'Not installed' !npm list @aws-sdk/client-transcribe 2>/dev/null | grep transcribe || echo 'AWS Transcribe SDK not found' !pip show google-cloud-speech 2>/dev/null | grep Version || echo 'Google STT not found'

Overview

Migrate to Deepgram from AWS Transcribe, Google Cloud Speech-to-Text, Azure Cognitive Services, or OpenAI Whisper. Uses an adapter pattern with a unified interface, parallel running for quality validation, percentage-based traffic shifting, and automated rollback.

Feature Mapping

AWS Transcribe -> Deepgram

Google Cloud STT -> Deepgram

Deepgram Multi-Environment Setup

Prerequisites

• Separate Deepgram projects/credentials, storage/retention policies, and owners for development, staging, and production.
• Reviewed promotion/rollback controls plus sanitized fixtures for each pre-production environment.

Examples

Validate a configuration in development with a licensed fixture, promote the same version to staging with a separate key, and record its quality/latency/alert results. Promote production through an approved canary only; never reuse production keys or recordings in development to make an environment test pass.

Overview

Configure isolated Deepgram environments for development, staging, and production. Each environment uses a separate Deepgram project, scoped API keys, environment-specific model selection, and validated configuration. Includes typed config, client factory, Docker Compose profiles, and Kubernetes overlays.

Environment Strategy

Instructions

Step 1: Typed Environment Configuration

interface DeepgramEnvConfig {
  apiKey: string;
  projectId: string;
  model: 'base' | 'nova-2' | 'nova-3';
  maxConcurrency: number;
  features: {
    diarize: boolean;
    smart_format: boolean;
    redact: string[] | false;
    summarize: boolean;
  };
  callbackBaseUrl?: string;
  timeout: number;
}

function loadConfig(env: string): DeepgramEnvConfig {
  const configs: Record<string, DeepgramEnvConfig> = {
    development: {
      apiKey: process.env.DEEPGRAM_API_KEY_DEV!,
      projectId: process.env.DEEPGRAM_PROJECT_ID_DEV!,
      model: 'base',
      maxConcurrency: 5,
      features: {
        diarize: false,
        smart_format: true,
        redact: false,
        summarize: false,
      },
      callbackBaseUrl: 'http://localhost:3000',
      timeout: 60000,
    },
    staging: {
      apiKey: process.env.DEEPGRAM_API_KEY_STAGING!,
      projectId: process.env.DEEPGRAM_PROJECT_ID_STAGING!,
      model: 'nova-3',
      maxConcurrency: 20,
      features: {
        diarize: true,
        smart_format: true,
        redact: ['pci', 'ssn'],
        summarize: true,
      },
      callbackBaseUrl: 'https://…

Deepgram Observability

Prerequisites

• An approved metrics/tracing/logging backend, data-retention policy, and on-call owner.
• Redaction rules that exclude audio, transcript text, API keys, participant identifiers, and other sensitive metadata.

Examples

Emit aggregate metrics for request count, latency, model, status class, streaming duration, and rate-limit headroom. Trigger a non-sensitive staging failure to verify alert routing, then record the correlation ID and remediation time—never audio samples, transcripts, or credentials.

Overview

Full observability stack for Deepgram: Prometheus metrics (request counts, latency histograms, audio processed, cost tracking), OpenTelemetry distributed tracing, structured JSON logging with Pino, Grafana dashboard JSON, and AlertManager rules.

Four Pillars

Instructions

Step 1: Prometheus Metrics Definition

import { Counter, Histogram, Gauge, Registry, collectDefaultMetrics } from 'prom-client';

const registry = new Registry();
collectDefaultMetrics({ register: registry });

// Request metrics
const requestsTotal = new Counter({
  name: 'deepgram_requests_total',
  help: 'Total Deepgram API requests',
  labelNames: ['method', 'model', 'status'] as const,
  registers: [registry],
});

const latencyHistogram = new Histogram({
  name: 'deepgram_request_duration_seconds',
  help: 'Deepgram API request duration',
  labelNames: ['method', 'model'] as const,
  buckets: [0.1, 0.5, 1, 2, 5, 10, 30, 60],
  registers: [registry],
});

// Usage metrics
const audioProcessedSeconds = new Counter({
  name: 'deepgram_audio_processed_seconds_total',
  help: 'Total audio seconds processed',
  labelNames: ['model'] as const,
  registers: [registry],
});

const estimatedCostDollars = new Counter({
  name: 'deepgram_estimated_cost_dollars_total',
  help: 'Estimated cost in USD',
  labelNames: ['model', 'method'] as const,
  registers: [registry],
});

// Operational metrics
const activeConnections = new Gauge({
  name: 'deepgram_active_websocket_connections',
  help: 'Currently active WebSocket connections',
  registers: [registry],
});

const rateLimitHits = new Counter({
  name: 'deepgra…

Deepgram Performance Tuning

Prerequisites

• A baseline for latency, throughput, quality, error/throttle rate, and a named service owner.
• Licensed non-sensitive fixtures, approved load window, and a rollback threshold.

Examples

Measure the development/staging transcription baseline with short fixtures, change one concurrency, streaming, or model parameter, and compare aggregate quality/latency/error results. Keep the change only within the signed threshold; revert on regression and never use customer recordings as performance fixtures.

Overview

Optimize Deepgram transcription performance through audio preprocessing with ffmpeg, model selection for speed vs accuracy, streaming for large files, parallel processing, result caching, and connection reuse. Targets: <2s latency for short files, 100+ files/minute batch throughput.

Performance Levers

Instructions

Step 1: Audio Preprocessing with ffmpeg

# Optimal format for Deepgram: 16kHz, 16-bit, mono, WAV
ffmpeg -i input.mp3 \
  -ar 16000 \          # 16kHz sample rate (ideal for speech)
  -ac 1 \              # Mono channel
  -acodec pcm_s16le \  # 16-bit signed LE PCM
  -f wav \
  output.wav

# Remove silence (saves API cost + processing time)
ffmpeg -i input.wav \
  -af "silenceremove=stop_periods=-1:stop_duration=0.5:stop_threshold=-30dB" \
  -ar 16000 -ac 1 -acodec pcm_s16le \
  trimmed.wav

# Noise reduction + normalization
ffmpeg -i input.wav \
  -af "highpass=f=200,lowpass=f=3000,loudnorm=I=-16:TP=-1.5:LRA=11" \
  -ar 16000 -ac 1 -acodec pcm_s16le \
  clean.wav

import { execSync } from 'child_process';
import { statSync } from 'fs';

function preprocessAudio(inputPath: string, outputPath: string): {
  originalSize: number;
  optimizedSize: number;
  savings: string;
} {
  const originalSize = statSync(inputPath).size;

  execSync(`ffmpeg -y -i "${inputPath}" \
    -af "silenceremove=stop_periods=-1:stop_duration=0.5:stop_threshold=-30dB,\
    highpass=f=200,lowpass=f=3000" \
    -ar 16000 -ac 1 -acodec pcm_s16le \
    "${ou…

Deepgram Production Checklist

Prerequisites

• A named service/data owner, approved model/provider/data-routing decision, and production rollback plan.
• Passing staging evidence for credentials, audio retention/consent, observability, rate limits, quality, and incident escalation.

Examples

Run the final production gate with a non-sensitive canary, verify alert routing and the redacted request receipt, then observe against the stated quality/latency/error threshold. If any gate fails, halt rollout and restore the previous approved configuration rather than extending the canary or disabling controls.

Overview

Comprehensive go-live checklist for Deepgram integrations. Covers singleton client, health checks, Prometheus metrics, alert rules, error handling, and a phased go-live timeline.

Production Readiness Matrix

Deepgram Rate Limits

Prerequisites

• Current provider-limit knowledge, measured baseline, concurrency budget, and stable request/job identifiers.
• Synthetic audio fixtures and alerts for throttling, queue age, failures, and duplicate processing.

Examples

Run a development load test using short non-sensitive fixtures, increment concurrency gradually, and record aggregate latency, 429s, and completion rate. Apply exponential backoff with jitter and preserve the request ID; reduce load on throttling instead of immediate bulk retries or sending customer recordings as test traffic.

Overview

Implement rate limiting, exponential backoff, and circuit breaker patterns for Deepgram API. Deepgram limits by concurrent connections (not requests per second). Understanding this model is key to building reliable integrations.

Deepgram Rate Limit Model

Deepgram uses concurrency-based limits, not traditional requests-per-minute:

When you exceed your concurrency limit, Deepgram returns 429 Too Many Requests.

Key insight: You can send unlimited total requests — just not more than your concurrency limit simultaneously.

Instructions

Step 1: Concurrency-Aware Queue

import pLimit from 'p-limit';
import { createClient } from '@deepgram/sdk';

class DeepgramRateLimiter {
  private limit: ReturnType<typeof pLimit>;
  private client: ReturnType<typeof createClient>;
  private stats = { total: 0, active: 0, queued: 0, errors: 0 };

  constructor(apiKey: string, maxConcurrent = 50) {
    // Stay well under plan limit (e.g., 50 of 100 allowed)
    this.limit = pLimit(maxConcurrent);
    this.client = createClient(apiKey);
  }

  async transcribe(source: { url: string }, options: Record<string, any>) {
    this.stats.queued++;
    return this.limit(async () => {
      this.stats.queued--;
      this.stats.active++;
      this.stats.total++;
      try {
        const { result, error } = await this.client.listen.prerecorded.transcribeUrl(
          source, options
        );
        if (error) {
          this.stats.errors++;
          throw error;
        }
        return result;
      } catch (err) {
        this.stats.errors++;
        throw err;
      } finally {
        this.stats.active--;
      }
    });
  }

  getStats() { return { ...this.stats }; }
}

// Usage:
const limiter = new DeepgramRateLimiter(p…

Deepgram Reference Architecture

Prerequisites

• A documented audio/transcript data flow, consent/retention policy, approved environment boundaries, and service/data owners.
• Reviewed interfaces for auth, media ingestion, callbacks, observability, storage, and incident response.

Examples

Model a development producer that validates media metadata, sends a request using a scoped project key, receives a signed callback, and records only correlation/state metrics. Promote the same versioned contract through staging before a production canary, retaining a dead-letter/recovery owner and excluding audio/transcript content from telemetry.

Overview

Four reference architectures for Deepgram transcription at scale: synchronous REST for short files, async queue (BullMQ) for batch processing, WebSocket proxy for real-time streaming, and a hybrid router that auto-selects the best pattern based on audio duration.

Architecture Selection Guide

Instructions

Step 1: Synchronous REST Pattern

import express from 'express';
import { createClient } from '@deepgram/sdk';

const app = express();
app.use(express.json());

const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

// Direct API call — best for short files (<60s)
app.post('/api/transcribe', async (req, res) => {
  const { url, model = 'nova-3', diarize = false } = req.body;

  try {
    const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
      { url },
      { model, smart_format: true, diarize, utterances: diarize }
    );
    if (error) return res.status(502).json({ error: error.message });

    res.json({
      transcript: result.results.channels[0].alternatives[0].transcript,
      confidence: result.results.channels[0].alternatives[0].confidence,
      duration: result.metadata.duration,
      request_id: result.metadata.request_id,
      utterances: diarize ? result.results.utterances : undefined,
    });
  } catch (err: any) {
    res.status(500).json({ error: err.message });
  }
});

Step 2: Async Queue Pattern (BullMQ)

import { Queue, Worker, J…

Deepgram SDK Patterns

Examples

Wrap the SDK behind a client that receives a scoped secret reference, validates media metadata, applies timeout/retry limits, and emits only redacted request metrics. Unit-test the wrapper with a mocked response; use a development fixture for one integration test and verify that credentials, audio, and transcript content never enter logs.

Overview

Production patterns for @deepgram/sdk (TypeScript) and deepgram-sdk (Python). Covers singleton client, typed wrappers, text-to-speech with Aura, audio intelligence pipeline, error handling, and SDK v5 migration path.

Prerequisites

• npm install @deepgram/sdk or pip install deepgram-sdk
• DEEPGRAM_API_KEY environment variable configured

Instructions

Step 1: Singleton Client (TypeScript)

import { createClient, DeepgramClient } from '@deepgram/sdk';

class DeepgramService {
  private static instance: DeepgramService;
  private client: DeepgramClient;

  private constructor() {
    const apiKey = process.env.DEEPGRAM_API_KEY;
    if (!apiKey) throw new Error('DEEPGRAM_API_KEY is required');
    this.client = createClient(apiKey);
  }

  static getInstance(): DeepgramService {
    if (!this.instance) this.instance = new DeepgramService();
    return this.instance;
  }

  getClient(): DeepgramClient { return this.client; }
}

export const deepgram = DeepgramService.getInstance().getClient();

Step 2: Text-to-Speech with Aura

import { createClient } from '@deepgram/sdk';
import { writeFileSync } from 'fs';

const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

async function textToSpeech(text: string, outputPath: string) {
  const response = await deepgram.speak.request(
    { text },
    {
      model: 'aura-2-thalia-en',  // Female English voice
      encoding: 'linear16',
      container: 'wav',
      sample_rate: 24000,
    }
  );

  const stream = await response.getStream();
  if (!stream) throw new Error('No audio stream returned');

  // Collect stream into buffer
  const reader = stream.getReader();
  const chunks: Uint8Array[] = [];
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    chunks.push(value);
  }

  const buffer = Buffer.concat(chunks);
  writeFileSync(outputPath, buffer);
  console.log(`Audio saved: ${outputPath} (${buffer.length} bytes)`);
  return buffer;
}

// Aura-2 voice options:
// aura-2-thalia-en    — Female, warm
// aura-2-asteria-en   — Female, default
// aura-2-orion-en     — Male, deep
// aura-2-luna-en      — Female, soft
// aura-2-helios-en    — Male, authoritative
// aura-asteria-en     — Aura v1 fallback

Step 3: Audio Intelligence Pipeline

Deepgram Security Basics

Prerequisites

• A data classification and consent decision for the audio/transcript workload.
• Scoped project credentials in the approved secret manager, an owner, and an incident/revocation route.

Examples

Use a development credential and a licensed non-sensitive audio fixture to verify the integration, logging only an opaque request ID and outcome. If recordings, transcripts, or keys are exposed, restrict access, revoke credentials where applicable, and follow the organization’s incident process before continuing.

Overview

Security best practices for Deepgram integration: scoped API keys, key rotation, Deepgram's built-in PII redaction feature, client-side temporary keys, SSRF prevention for audio URLs, and audit logging.

Security Checklist

• [ ] API keys in environment variables or secret manager (never in code)
• [ ] Separate keys per environment (dev/staging/prod)
• [ ] Keys scoped to minimum required permissions
• [ ] Key rotation schedule (90 days recommended)
• [ ] Deepgram redact option enabled for PII-sensitive audio
• [ ] Audio URLs validated (HTTPS only, no private IPs)
• [ ] Audit logging on all transcription operations

Instructions

Step 1: Scoped API Keys

Create keys with minimal permissions in Console > Settings > API Keys:

// Production transcription service — only needs listen scope
const sttKey = process.env.DEEPGRAM_STT_KEY;  // Scope: listen

// TTS service — only needs speak scope
const ttsKey = process.env.DEEPGRAM_TTS_KEY;  // Scope: speak

// Monitoring dashboard — only needs usage read
const monitorKey = process.env.DEEPGRAM_MONITOR_KEY;  // Scope: usage:read

// Admin operations — separate key, restricted access
const adminKey = process.env.DEEPGRAM_ADMIN_KEY;  // Scope: manage, keys

Step 2: Deepgram Built-in PII Redaction

import { createClient } from '@deepgram/sdk';

const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

// Deepgram redacts PII directly in the transcript
const { result } = await deepgram.listen.prerecorded.transcribeUrl(
  { url: audioUrl },
  {
    model: 'nova-3',
    smart_format: true,
    // Built-in redaction — replaces sensitive data in transcript
    redact: ['pci', 'ssn', 'numbers'],
    // pci     — Credit card numbers → [REDACTED]
    // ssn     — Social Security numbers → [REDACTED]
    // numbers — All numeric sequences → [REDACTED]
  }
);

// Transcript will contain [REDACTED] in place of sensitive numbers
console.log(result.results.channels[0].alternatives[0].transcript);
// "My card number is [REDACTED] and my SSN is [REDACTED]"

Step 3: Temporary Keys for Client-Side

…

Deepgram Upgrade Migration

Prerequisites

• Current/target SDK or API versions, compatibility matrix, approved fixtures, quality/latency thresholds, and rollback owner.
• Separate staging credentials plus a data-retention and consent review for any migration/reprocessing action.

Examples

Upgrade the SDK in staging, run mock/unit tests and a small licensed-fixture comparison against the prior version, and compare aggregate output/latency/error metrics. Promote through an approved canary only after acceptance passes; revert to the prior lockfile/configuration on regression and do not reprocess production recordings to validate the upgrade.

Current State

!npm list @deepgram/sdk 2>/dev/null | grep deepgram || echo 'SDK not installed'

Overview

Guide for Deepgram SDK version upgrades (v3 -> v4 -> v5) and model migrations (Nova-2 -> Nova-3). Includes breaking change maps, side-by-side API comparison, A/B testing scripts, automated validation, and rollback procedures.

SDK Version History

Instructions

Step 1: Identify Current Version and Breaking Changes

# Check installed version
npm list @deepgram/sdk

# Check latest available
npm view @deepgram/sdk versions --json | tail -5

Step 2: v3/v4 to v5 Migration Map

// ============= CLIENT CREATION =============
// v3/v4:
import { createClient } from '@deepgram/sdk';
const dg = createClient(process.env.DEEPGRAM_API_KEY!);

// v5:
import { DeepgramClient } from '@deepgram/sdk';
const dg = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

// ============= PRE-RECORDED STT =============
// v3/v4:
const { result, error } = await dg.listen.prerecorded.transcribeUrl(
  { url: audioUrl },
  { model: 'nova-3', smart_format: true }
);

// v5:
const response = await dg.listen.v1.media.transcribeUrl(
  { url: audioUrl },
  { model: 'nova-3', smart_format: true }
);
// v5 throws on error instead of returning { error }

// ======…

Deepgram Webhooks & Callbacks

Prerequisites

• A verified callback endpoint, signature/authentication requirements, idempotency store, and redacted observability.
• A data-retention/consent decision and an owner for failed callback recovery.

Examples

Validate the callback signature before parsing its body, deduplicate by an opaque event ID, acknowledge promptly, and write only state/result metadata to logs. Test with a development event; retry transient failures with bounded backoff and quarantine terminal failures rather than replaying audio/transcripts blindly.

Overview

Implement async transcription with Deepgram's callback feature. When you pass a callback URL, Deepgram returns a request_id immediately, processes audio in the background, and POSTs results to your endpoint. Supports HTTP and WebSocket callbacks with automatic retry (10 attempts, 30s intervals).

Deepgram Callback Flow

1. Client -> POST /v1/listen?callback=https://you.com/webhook  (with audio)
2. Deepgram -> 200 { request_id: "..." }                       (immediate)
3. Deepgram processes audio asynchronously
4. Deepgram -> POST https://you.com/webhook                    (results)
   Retries up to 10 times (30s delay) on non-2xx response

Instructions

Step 1: Submit Async Transcription

import { createClient } from '@deepgram/sdk';

const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

async function submitAsync(audioUrl: string, callbackUrl: string) {
  // Deepgram sends transcription via callback URL instead of
  // holding the connection open.
  const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
    { url: audioUrl },
    {
      model: 'nova-3',
      smart_format: true,
      diarize: true,
      utterances: true,
      callback: callbackUrl,  // Your HTTPS endpoint
      // callback_method: 'put',  // Optional: use PUT instead of POST
    }
  );

  if (error) throw new Error(`Submit failed: ${error.message}`);

  // Deepgram returns immediately with request_id
  const requestId = result.metadata.request_id;
  console.log(`Submitted. Request ID: ${requestId}`);
  console.log(`Results will be POSTed to: ${callbackUrl}`);
  return requestId;
}

// Also works with direct curl:
// curl -X POST 'https://api.deepgram.com/v1/listen?model=nova-3&callback=https://you.com/webhook' \
//   -H "Authorization: Token $DEEPGRAM_API_KEY" \
//   -H "Content-Type: application/json" \
//   -d '{"url":"https://example.com/audio.wav"}'

Step 2: Callback Server

import express from 'express';
import crypto from 'crypto';

const app = express();

// IMPORTANT: Use raw body for HMAC signatur…