Deepgram voice

Deepgram serves speech-to-text (Nova-3, Whisper) and text-to-speech (Aura-2, Aura). @mayurajs/voice-deepgram plugs them into the voice registry, so your code and your agents use them with the same ids, prices, per-call bounds and voice:<id> permissions as every other voice provider. It talks to Deepgram's HTTP API with fetch: no Deepgram SDK, no other dependencies, and it runs on every runtime Mayura runs on.

#Install

npm install mayura @mayurajs/voice-deepgram

#Credentials

Create an API key in the Deepgram console under API Keys. The package calls only /v1/listen and /v1/speak, and sends the key as Authorization: Token <key>. The package reads nothing from the environment: pass the key in yourself, for example from DEEPGRAM_API_KEY.

#Use it

import { createVoices, transcriptionTool } from 'mayura/voice';
import { deepgramVoice } from '@mayurajs/voice-deepgram';

const voices = createVoices({
  providers: [deepgramVoice({ apiKey: process.env.DEEPGRAM_API_KEY ?? '' })],
  prices: 'catalog',
  maxCallCostMicros: 50_000,
});

// Speech ids name a model family; the voice completes it: aura-2 with thalia-en is Deepgram's aura-2-thalia-en.
const speech = await voices.speaker('deepgram/aura-2').speak({ text: 'Your order ships tomorrow.', voice: 'thalia-en', format: 'wav' });
// WAV is measured, so no duration is needed. Without a language, Deepgram detects it.
const transcript = await voices.transcriber('deepgram/nova-3').transcribe({ audio: speech.audio });
console.log(transcript.text, transcript.language, transcript.usage.costMicros);

// A tool for agents and workflows: grant tool:voice.transcribe and voice:deepgram/nova-3 to the run.
const transcribe = transcriptionTool(voices.transcriber('deepgram/nova-3'));

Ids are deepgram/<model>. Each voice tool requires voice:<id> besides tool:<tool id>, reserves the model's per-call bound from the run's budget and reports what the call cost. See Voice.

#Options

#Models and prices

The catalog has Deepgram's pay-as-you-go prices for pre-recorded audio as of 2026-09-30, used when you pass prices: 'catalog':

Nova-3 costs more when it transcribes several languages than one, under the same model id, so the catalog lists it at the multilingual rate: a catalog price may overcount, never undercount. Give your own price in prices if you know your audio is monolingual. Another Deepgram model works with a price you give.

#Cost bounds

Every call is priced before it is sent, and refused with BUDGET_EXCEEDED if it would cost more than the model's bound: speech from its text's characters (Unicode code points), and transcription from the audio's duration, measured from WAV or given as durationMs for compressed audio. With a 50,000-micro bound, deepgram/aura-2 speaks up to 1,666 characters a call and deepgram/nova-3 transcribes up to about 9 and a half minutes.

The cost a transcription reports is what Deepgram billed: the duration in its response's metadata, and otherwise the duration measured or given. Speech is charged for the characters of the text.

#Audio and formats

• Transcription sends the audio's bytes as the request body with its media type, with smart formatting on. A language is sent as given (pt-BR); without one, Deepgram is asked to detect it and the transcript reports what it found. Segments are words, with their timings and a speaker when Deepgram reports one. The registry accepts up to 25 MiB of audio by default.
• Speech comes in every Mayura format: mp3 (the default), opus (in Ogg, audio/ogg), aac, flac, wav (16-bit linear PCM in WAV) and pcm16 (raw 16-bit PCM at 24 kHz). Audio streams to onAudio as it arrives.
• The voice completes the model family: lowercase letters, optionally followed by a language such as -en, as in thalia-en. Anything else fails with configuration before a request is made.
• A speech response that is not audio, is empty, or is larger than maxAudioBytes fails with invalid_response, as does a transcription response larger than maxResponseBytes. Redirects are not followed.

#Errors

Failures reach you as a VoiceProviderError with a reason. Its message is fixed text: nothing Deepgram wrote reaches it.

A call cancelled through its signal fails with CANCELLED. Before anything is sent, the registry refuses a call over its bound (BUDGET_EXCEEDED), audio or text over its limits (LIMIT_EXCEEDED), and compressed audio without durationMs (INVALID_INPUT). A missing key, a non-https baseURL or a malformed model id fails with INVALID_CONFIG.

#How it is tested

• Unit tests run the package against a fake Deepgram API in Deepgram's own wire format. They check the URLs and query parameters, the Authorization header, that the raw audio is sent with its media type, language detection, the family-and-voice model name, catalog charges and refused voices, and that nothing is read from the environment.
• The voice adapter conformance suite passes against that fake: result shapes, costs, HTTP failures mapped without Deepgram's text, cancellation and timeouts.
• scripts/live/voice-deepgram.mjs passed against a real Deepgram account on October 6, 2026: aura-2 with thalia-en spoke a sentence, and nova-3 transcribed it back with its words, through the shared voice checks at catalog prices.

#Related

• Voice: the registry, prices, bounds and voice tools.
• AssemblyAI transcription: another transcription provider.
• ElevenLabs voice: another provider that speaks and transcribes.
• Costs and budgets: how a run's budget reserves each call's bound.