Speech transcription

Direct Deepgram transcription and speaker diarization using short-lived tokens and your shared credit.

AI/LLM: this page is available in plain markdown at /docs/resources/deepgram.md

npx extraorbital add deepgram

This provisions a stable refresh credential. Your audio goes directly to Deepgram. Transcription and speaker diarization use your existing shared credit, including the $5 machine allowance. There is no separate Deepgram free allocation.

Credentials

Variable	Purpose
`DEEPGRAM_BASE_URL`	Deepgram's API origin
`DEEPGRAM_TOKEN_URL`	Exchange your refresh credential for a temporary token
`DEEPGRAM_REFRESH_TOKEN`	Stable credential; keep it in your backend

Transcribe with speaker labels

Get a token immediately before making the request:

const grant = await fetch(process.env.DEEPGRAM_TOKEN_URL, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.DEEPGRAM_REFRESH_TOKEN}` },
});
if (!grant.ok) throw new Error(`Token refused: ${grant.status}`);
const { access_token } = await grant.json();

const response = await fetch(
  `${process.env.DEEPGRAM_BASE_URL}/v1/listen?model=nova-3&diarize=true&utterances=true&smart_format=true`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${access_token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url: "https://example.com/meeting.wav" }),
  },
);
if (!response.ok) throw new Error(`Transcription failed: ${response.status}`);
console.log(await response.json());

The token lasts 30 seconds and uses Authorization: Bearer. It is not a permanent Deepgram API key. Binary audio and WebSocket connections also go directly to Deepgram. Fetch a new token before each new request or connection; grants are limited to one per resource per five seconds. An expired token requires a new grant.

Credit and resuming access

Usage is polled every minute, subject to Deepgram's reporting delay. Actual provider cost, including any selected features, is deducted from the same balance as other resources. If credit runs out, token issuance returns 402. Add credit or increase the exhausted budget cap and request a token again: the refresh credential stays unchanged. A manually suspended resource must also be resumed by its operator.

If billing or usage reconciliation is unavailable, token issuance pauses until it recovers. It does not fall back to free access.

Token expiry prevents new connections; it does not disconnect an existing WebSocket. In-flight work and provider reporting delays may exceed the remaining credit. This integration does not promise an immediate cutoff of active streams or a strict provider-side spending cap.

Removing the resource permanently revokes its parent key. Removal is separate from the reversible pause that happens when credit runs out.

← Previous

Auth

Git