Deepgram Integration¶

Official Deepgram API Documentation

Deepgram provides speech-to-text, text-to-speech, text analysis, and voice-agent APIs. Use your KeyPool team token with the Deepgram SDKs and point the SDK base URL at your KeyPool Deepgram endpoint.

Endpoint¶

{YOUR_KEYPOOL_BASE_URL}/v1/deepgram

Authentication¶

Send your KeyPool team token as a bearer token. Your token must be enabled for the deepgram service.

Authorization: Bearer {KEYPOOL_TOKEN}

Do not pass a personal Deepgram API key when using KeyPool.

Supported developer workflows¶

The current SDK samples validate these Deepgram surfaces through KeyPool:

Model discovery: GET /v1/models
Speech-to-text (Listen): POST /v1/listen
Text-to-speech (Speak): POST /v1/speak
Text analysis (Read): POST /v1/read
Voice Agent settings/model discovery: GET /v1/agent/settings/think/models

For the full endpoint list, use the API Reference → Deepgram.

Python SDK¶

Install the official SDK:

pip install deepgram-sdk httpx

Configure the SDK with a Deepgram environment that points at your KeyPool base URL and use access_token so the SDK sends a bearer token.

import os
import httpx
from deepgram import DeepgramClient, DeepgramClientEnvironment

KEYPOOL_BASE_URL = os.environ["KEYPOOL_BASE_URL"]
KEYPOOL_TOKEN = os.environ["KEYPOOL_TOKEN"]
DEEPGRAM_BASE_URL = f"{KEYPOOL_BASE_URL}/v1/deepgram"

client = DeepgramClient(
    access_token=KEYPOOL_TOKEN,
    environment=DeepgramClientEnvironment(
        base=DEEPGRAM_BASE_URL,
        agent=DEEPGRAM_BASE_URL.replace("https://", "wss://"),
        production=DEEPGRAM_BASE_URL.replace("https://", "wss://"),
    ),
    httpx_client=httpx.Client(timeout=60.0, follow_redirects=True),
)

# Model discovery
models = client.manage.v1.models.list()
print(models)

# Speech-to-text from a URL
transcript = client.listen.v1.media.transcribe_url(
    url="https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav",
    model="nova-3",
    smart_format=True,
)
print(transcript.results.channels[0].alternatives[0].transcript)

# Text-to-speech
chunks = client.speak.v1.audio.generate(
    text="Hello from Deepgram through KeyPool.",
    model="aura-2-thalia-en",
    encoding="linear16",
    container="wav",
)
audio_bytes = b"".join(chunks)

# Text analysis
analysis = client.read.v1.text.analyze(
    request={"text": "Deepgram SDK request through KeyPool."},
    language="en",
    summarize="v2",
    topics=True,
    intents=True,
    sentiment=True,
)
print(analysis)

# Voice Agent settings/model discovery
agent_models = client.agent.v1.settings.think.models.list()
print(agent_models)

TypeScript SDK¶

Install the official SDK:

bun add @deepgram/sdk

The TypeScript SDK accepts a custom fetch implementation. Use it to prepend the KeyPool service path and attach your KeyPool bearer token.

import { DeepgramClient } from "@deepgram/sdk";

const KEYPOOL_BASE_URL = process.env.KEYPOOL_BASE_URL!;
const KEYPOOL_TOKEN = process.env.KEYPOOL_TOKEN!;

function makeKeypoolDeepgramClient(baseUrl: string, token: string): DeepgramClient {
  return new DeepgramClient({
    apiKey: token,
    baseUrl,
    fetch: (input: RequestInfo | URL, init?: RequestInit) => {
      const rawUrl = typeof input === "string"
        ? input
        : input instanceof URL
          ? input.toString()
          : input.url;

      const sdkUrl = new URL(rawUrl);
      const proxyUrl = new URL(baseUrl);
      proxyUrl.pathname = `/v1/deepgram${sdkUrl.pathname}`;
      proxyUrl.search = sdkUrl.search;

      const headers = new Headers(init?.headers);
      headers.set("Authorization", `Bearer ${token}`);

      return fetch(proxyUrl.toString(), { ...init, headers });
    },
  });
}

const client = makeKeypoolDeepgramClient(KEYPOOL_BASE_URL, KEYPOOL_TOKEN);

// Model discovery
const models = await client.manage.v1.models.list();
console.log(models);

// Speech-to-text from a URL
const transcript = await client.listen.v1.media.transcribeUrl({
  url: "https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav",
  model: "nova-3",
  smart_format: true,
});
console.log(transcript.results.channels[0].alternatives[0].transcript);

// Text-to-speech
const tts = await client.speak.v1.audio.generate({
  text: "Hello from Deepgram through KeyPool.",
  model: "aura-2-thalia-en",
  encoding: "linear16",
  container: "wav",
});
const audio = await tts.arrayBuffer();

// Text analysis
const analysis = await client.read.v1.text.analyze({
  body: { text: "Deepgram SDK request through KeyPool." },
  language: "en",
  summarize: "v2",
  topics: true,
  intents: true,
  sentiment: true,
});
console.log(analysis);

// Voice Agent settings/model discovery
const agentModels = await client.agent.v1.settings.think.models.list();
console.log(agentModels);

Error handling¶

Common responses:

401 Unauthorized: missing or invalid KeyPool token.
403 Forbidden: your token is not enabled for deepgram.
429 Too Many Requests: your team token has reached its configured rate limit.
502 Bad Gateway: Deepgram returned an error or the request could not be completed.

SDK sample tests¶

The repository includes Deepgram SDK tests for both Python and TypeScript:

pnpm sdk:py:deepgram
pnpm sdk:ts:deepgram