Deepgram

Deepgram

This connector works with Deepgram (speech AI) through its REST API at https://api.deepgram.com/v1 with the user's own API key: transcription of pre-recorded audio and video from a URL (speech to text with speaker labels, summaries, topics, intents, sentiment and redaction), text intelligence on plain text, text to speech with the Aura voices, the model and voice list, and the account side of a project: API keys (read only), members, the request log, usage, balances, spend and purchases. Live streaming, the voice agent API and key or member management are not part of this connector.

Spending: deepgram_transcribe_url (per audio minute, more with summaries and other intelligence features), deepgram_analyze_text (per token) and deepgram_text_to_speech (per character) are billed to the project of the key; new accounts start with free credit. Everything else is free. For a long recording or a large batch, say roughly what it will cost before running it; deepgram_list_balances shows the credit left.

Setup (about 3 minutes)

1. Sign in at https://console.deepgram.com (a new account gets free credit) and open the project you want to use.
2. Open API Keys, click Create a New API Key, give it a name, and pick the role: Member is enough for transcription, text to speech, text intelligence, keys and usage; Admin or Owner is needed for members, balances, spend and purchases (billing:read). Leave the expiration empty or set one you will remember.
3. Copy the key (it is shown only once) into DEEPGRAM_API_KEY. Paste the key itself: the connector sends it as Authorization: Token <key>.
4. Run deepgram_list_projects to check it.

Workflow

• Transcribe a recording: deepgram_transcribe_url with a public url (a presigned S3, GCS or Drive link works; a page that needs a sign-in does not). Good defaults: model: nova-3, smart_format: true. Add diarize and utterances or paragraphs for who said what, detect_language when the language is unknown (or language: multi on nova-3 for mixed languages), keyterm for names and jargon, summarize: v2, topics, intents, sentiment for call analysis (English only), and redact to hide card numbers or personal data.
• Analyze text you already have (a transcript, an email, notes): deepgram_analyze_text with summarize, topics, intents or sentiment (English).
• Make audio: deepgram_text_to_speech with the text and an Aura voice in model; find voices with deepgram_list_models (the tts list, with language, accent and a sample link).
• Models: deepgram_list_models and deepgram_get_model for the public models; deepgram_list_project_models for what one project can use, including custom models.
• Account: deepgram_list_projects for the project_id, then deepgram_get_project, deepgram_list_keys, deepgram_list_members.
• Usage and cost: deepgram_get_usage_breakdown for hours, requests, tokens and characters (totals per period, or grouped by endpoint, model, key or tag), deepgram_list_usage_fields for the values that can be filtered on, deepgram_list_requests and deepgram_get_request for single calls with their cost, deepgram_get_billing_breakdown for spend in USD, deepgram_list_balances, deepgram_get_balance and deepgram_list_purchases for credit.

Reading the answers

• Transcription: the text is in results.channels[0].alternatives[0].transcript (one channel per audio channel with multichannel), with a confidence from 0 to 1. With paragraphs the formatted text with speaker labels is in alternatives[0].paragraphs.transcript. results.utterances lists turns with start and end in seconds and speaker (0, 1, ...). Summaries are in results.summary.short; topics, intents and sentiments in results.topics, results.intents, results.sentiments as segments. Per-word timings are removed from the answer to keep it small: use utterances or paragraphs for timing. metadata.duration is the audio length in seconds and metadata.request_id identifies the call in the request log.
• Text intelligence: results.summary.text, and segments with start_word and end_word indexes into the text.
• Text to speech: the audio is attached to the result as a file (audio/mpeg for MP3); the text of the result gives its type and size. It is not saved anywhere at Deepgram, so keep the file if it is needed later.
• Usage figures are hours of audio as decimal strings, tokens and characters as numbers; billing amounts and balances are in units (usually usd). Dates are YYYY-MM-DD in UTC; request times are ISO 8601.

Paging: deepgram_list_requests pages with page (from 0) and limit (up to 1000); keep going while a page comes back full. The other lists return everything at once.

Limits: text to speech takes at most 2,000 characters per call (413 above); split longer text at sentence boundaries. Transcription answers in one call, which the connector waits for up to 30 seconds: nova-3 usually transcribes an hour of audio well within that, but very long files with many intelligence features can take longer; transcribe them in parts. Pay-as-you-go and Growth projects run up to 50 concurrent transcriptions, 15 text-to-speech and about 10 text intelligence requests at once; more return 429. Text intelligence takes up to 150K tokens of input (400 TOKEN_LIMIT_EXCEEDED above).

Errors: 400 with err_code and err_msg for an option the model does not support (for example keyterm on nova-2, or intelligence features on non-English audio) or a URL Deepgram cannot download; 401 for a wrong or expired key; 402 when the project has no credit left; 403 when the key's role lacks the scope (members and billing need Admin or Owner); 404 for an unknown project, request or balance id; 413 for text over 2,000 characters; 429 for too many requests at once.