wehub-resource-sync
112 lines
3.9 KiB
Markdown
112 lines
3.9 KiB
Markdown
---
|
|
summary: "Deepgram provider: API key setup, project discovery, and usage-breakdown metrics."
|
|
read_when:
|
|
- Debugging Deepgram API key or project selection
|
|
- Updating Deepgram usage parsing or menu display
|
|
- Explaining Deepgram setup to users
|
|
---
|
|
|
|
# Deepgram Provider
|
|
|
|
[Deepgram](https://deepgram.com) is a speech AI platform that provides APIs for speech-to-text, text-to-speech, audio intelligence, and related voice features.
|
|
|
|
## Authentication
|
|
|
|
Deepgram uses API key authentication. Get your API key from the [Deepgram Console](https://console.deepgram.com).
|
|
|
|
The API key must have access to the project you want to query. For usage data, the key also needs the `usage:read` scope for that project.
|
|
|
|
### Environment Variables
|
|
|
|
Set the `DEEPGRAM_API_KEY` environment variable:
|
|
|
|
```bash
|
|
export DEEPGRAM_API_KEY="dg_..."
|
|
```
|
|
|
|
Optionally set a Deepgram project ID:
|
|
|
|
```bash
|
|
export DEEPGRAM_PROJECT_ID="your-project-uuid"
|
|
```
|
|
|
|
If `DEEPGRAM_PROJECT_ID` is omitted, CodexBar calls Deepgram's project list endpoint and aggregates usage across all projects visible to the API key.
|
|
|
|
### Settings
|
|
|
|
You can also configure the API key and optional project ID in CodexBar Settings → Providers → Deepgram.
|
|
|
|
### CLI config
|
|
|
|
```bash
|
|
printf '%s' "$DEEPGRAM_API_KEY" | codexbar config set-api-key --provider deepgram --stdin
|
|
```
|
|
|
|
## Data Source
|
|
|
|
The Deepgram provider fetches summarized usage data from the Deepgram Management API.
|
|
|
|
1. **Projects API** (`/v1/projects`): Lists projects visible to the API key when no project ID is configured.
|
|
2. **Usage Breakdown API** (`/v1/projects/{PROJECT_ID}/usage/breakdown`): Returns summarized project usage over a date range. The response includes fields such as `start`, `end`, `resolution`, and `results`.
|
|
|
|
Each usage result may include:
|
|
|
|
* `start`
|
|
* `end`
|
|
* `hours`
|
|
* `total_hours`
|
|
* `agent_hours`
|
|
* `tokens_in`
|
|
* `tokens_out`
|
|
* `tts_characters`
|
|
* `requests`
|
|
|
|
Deepgram's usage breakdown endpoint supports querying with `start` and `end` date parameters. The response includes summarized usage results for the selected period.
|
|
|
|
## Display
|
|
|
|
The Deepgram menu card shows:
|
|
|
|
* **Usage notes**: Request count, total audio hours, total billable hours, agent hours, token totals, and TTS characters when returned by Deepgram
|
|
* **Identity**: Project name, project ID, or aggregated project count
|
|
|
|
Deepgram does not currently provide a credit balance through this provider. The provider displays usage, not remaining credits.
|
|
|
|
## CLI Usage
|
|
|
|
```bash
|
|
codexbar --provider deepgram
|
|
codexbar -p dg # alias
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
* **DEEPGRAM_API_KEY**: Your Deepgram API key. Required.
|
|
* **DEEPGRAM_PROJECT_ID**: Optional Deepgram project UUID. Leave unset to aggregate all visible projects.
|
|
* **DEEPGRAM_API_URL**: Override the base API URL. Optional, defaults to `https://api.deepgram.com/v1`.
|
|
Override values must be explicit HTTPS URLs or bare hosts/paths that CodexBar normalizes to HTTPS. Explicit
|
|
`http://` URLs fail closed before the Deepgram API key is attached to a request. For local proxy testing, use an
|
|
HTTPS listener or omit the scheme and let CodexBar normalize the override to HTTPS.
|
|
|
|
## Permissions
|
|
|
|
The API key must have permission to read usage data for the configured project.
|
|
|
|
If the key is valid but lacks the correct scope, Deepgram may return an error like:
|
|
|
|
```text
|
|
INSUFFICIENT_PERMISSIONS
|
|
Your account does not have the required scope to perform that action for this project.
|
|
Check that your account has the 'usage:read' scope for this project.
|
|
```
|
|
|
|
In that case, create or update a Deepgram API key with the `usage:read` scope for the target project.
|
|
|
|
## Notes
|
|
|
|
* Deepgram usage data is project-scoped.
|
|
* The project ID should be the project UUID, not just the project display name.
|
|
* The provider uses `Authorization: Token <API_KEY>` for requests.
|
|
* This provider currently reports usage metrics, not credit balance or per-request cost.
|
|
* Summarized usage data is not limited to 90 days, while console logs are limited to 90 days.
|