Deepgram

The Deepgram provider contains language model support for the Deepgram transcription and speech generation APIs. Deepgram models are not currently available through AI Gateway, so the opening example uses @ai-sdk/deepgram directly. See Using AI Gateway below for supported alternatives.

import { generateSpeech } from 'ai';
import { deepgram } from '@ai-sdk/deepgram';
import { writeFile } from 'node:fs/promises';

const { audio } = await generateSpeech({
  model: deepgram.speech('aura-2'),
  text: 'Hello, world!',
  outputFormat: 'mp3',
  voice: 'thalia',
  language: 'en',
});

await writeFile('speech.mp3', audio.uint8Array);

Using AI Gateway

The current AI Gateway model catalog does not list Deepgram models. Use @ai-sdk/deepgram for the APIs on this page. To use other speech models through Gateway, install ai and configure a Gateway API key:

pnpm add ai

npm install ai

yarn add ai

bun add ai

Set an AI Gateway API key in your environment:

export AI_GATEWAY_API_KEY=your_api_key_here

Vercel deployments can also use OIDC authentication. See the Gateway documentation for supported models and APIs.

Using @ai-sdk/deepgram

For direct access to Deepgram, install ai and @ai-sdk/deepgram:

pnpm add ai @ai-sdk/deepgram

npm install ai @ai-sdk/deepgram

yarn add ai @ai-sdk/deepgram

bun add ai @ai-sdk/deepgram

Set your Deepgram API credential in the DEEPGRAM_API_KEY environment variable:

export DEEPGRAM_API_KEY=your_api_key_here

Provider Instance

You can import the default provider instance deepgram from @ai-sdk/deepgram:

import { deepgram } from '@ai-sdk/deepgram';

If you need a customized setup, you can import createDeepgram from @ai-sdk/deepgram and create a provider instance with your settings:

import { createDeepgram } from '@ai-sdk/deepgram';

const deepgram = createDeepgram({
  // custom settings, e.g.
  fetch: customFetch,
});

You can use the following optional settings to customize the Deepgram provider instance:

• apiKey string

  API key that is being sent using the Authorization header. It defaults to the DEEPGRAM_API_KEY environment variable.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation. Defaults to the global fetch function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

Speech Models

You can create models that call the Deepgram text-to-speech API using the .speech() factory method.

The first argument is the voice family ID: aura-2 (current generation) or aura (Aura-1). The voice and language are selected with the generateSpeech voice and language options — the provider composes the upstream Deepgram model ID as <family>-<voice>-<language> (language defaults to en):

import { generateSpeech } from 'ai';
import { deepgram } from '@ai-sdk/deepgram';

const result = await generateSpeech({
  model: deepgram.speech('aura-2'),
  voice: 'thalia',
  language: 'en',
  text: 'Hello, world!',
});

You can also pass additional provider-specific options using the providerOptions argument:

import { generateSpeech } from 'ai';
import { deepgram, type DeepgramSpeechModelOptions } from '@ai-sdk/deepgram';

const result = await generateSpeech({
  model: deepgram.speech('aura-2'),
  voice: 'helena',
  text: 'Hello, world!',
  providerOptions: {
    deepgram: {
      encoding: 'linear16',
      sampleRate: 24000,
    } satisfies DeepgramSpeechModelOptions,
  },
});

The following provider options are available:

• encoding string

  Encoding type for the audio output. Supported values: 'linear16', 'mulaw', 'alaw', 'mp3', 'opus', 'flac', 'aac'. Optional.

• container string

  Container format for the output audio. Supported values: 'wav', 'ogg', 'none'. Optional.

• sampleRate number

  Sample rate for the output audio in Hz. Supported values depend on the encoding: 8000, 16000, 24000, 32000, 48000. Optional.

• bitRate number | string

  Bitrate of the audio in bits per second. For mp3: 32000 or 48000. For opus: 4000 to 650000. For aac: 4000 to 192000. Optional.

• callback string

  URL to which Deepgram will make a callback request with the audio. Optional.

• callbackMethod enum

  HTTP method for the callback request. Allowed values: 'POST', 'PUT'. Optional.

• mipOptOut boolean

  Opts out requests from the Deepgram Model Improvement Program. Optional.

• tag string | array of strings

  Label your requests for identification during usage reporting. Optional.

Speech results include Deepgram response details in providerMetadata.deepgram: modelName (the resolved upstream model), modelUuid, additionalModelUuids, charCount (the billed character count), breaksApplied, pronunciationsApplied, pronunciationWarnings (when present), and requestId.

The generateSpeech speed option is passed through to Deepgram's speed parameter. Deepgram accepts speeds in the 0.7–1.5 range and rejects out-of-range values with a 400 error; speed is not supported for all languages. instructions is not supported and is ignored with a warning.

Model Capabilities

See the full voice list for all voice names and accents.

Transcription Models

You can create models that call the Deepgram transcription API using the .transcription() factory method.

The first argument is the model id e.g. nova-3.

const model = deepgram.transcription('nova-3');

You can also pass additional provider-specific options using the providerOptions argument. For example, supplying the summarize option will enable summaries for sections of content.

import { transcribe } from 'ai';
import {
  deepgram,
  type DeepgramTranscriptionModelOptions,
} from '@ai-sdk/deepgram';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: deepgram.transcription('nova-3'),
  audio: await readFile('audio.mp3'),
  providerOptions: {
    deepgram: {
      summarize: 'v2',
    } satisfies DeepgramTranscriptionModelOptions,
  },
});

The following provider options are available:

• language string

  Language code for the audio. Supports numerous ISO-639-1 and ISO-639-3 language codes. Optional.

• detectLanguage boolean

  Whether to enable automatic language detection. When true, Deepgram will detect the language of the audio. Optional.

• smartFormat boolean

  Whether to apply smart formatting to the transcription. Optional.

• punctuate boolean

  Whether to add punctuation to the transcription. Optional.

• summarize enum | boolean

  Whether to generate a summary of the transcription. Allowed values: 'v2', false. Optional.

• topics boolean

  Whether to detect topics in the transcription. Optional.

• detectEntities boolean

  Whether to detect entities in the transcription. Optional.

• redact string | array of strings

  Specifies what content to redact from the transcription. Optional.

• search string

  Search term to find in the transcription. Optional.

• diarize boolean

  Whether to identify different speakers in the transcription. Defaults to false. Note that Deepgram bills speaker diarization as a per-minute add-on. Optional.

• utterances boolean

  Whether to segment the transcription into utterances. Optional.

• uttSplit number

  Threshold for splitting utterances. Optional.

• fillerWords boolean

  Whether to include filler words (um, uh, etc.) in the transcription. Optional.

• paragraphs boolean

  Whether to format the transcription into paragraphs. Optional.

• intents boolean

  Whether to detect intents in the transcription. Optional.

• sentiment boolean

  Whether to analyze sentiment in the transcription. Optional.

• keyterm string

  Key term to improve recognition accuracy for. Optional.

• replace string

  String to replace redacted content with. Optional.

Model Capabilities