deepgram-python-management-api

使用 Deepgram Management API（Python SDK）

api.deepgram.com/v1/projects、/v1/models 中的管理 REST 端点，以及可重复使用的 Agent 配置存储。项目范围的资源位于 client.manage.v1.projects.* 下（keys、members、members.invites、usage、billing、models、requests）。全局模型位于 client.manage.v1.models。思考模型发现位于 client.agent.v1.settings.think.models。可重复使用的 Agent 配置位于 client.voice_agent.configurations.*。

何时使用此产品

• 发现 / 固定模型：client.manage.v1.models.list() 会返回当前启用的 STT/TTS 集合。
• 项目管理：列出 / 获取 / 更新 / 删除 / 离开项目。
• API 密钥生命周期管理：列出 / 创建 / 删除项目密钥。
• 成员 + 邀请管理：添加 / 移除成员、管理角色、发送 / 撤销邀请。
• 用量 + 账单：查询请求量、余额。
• 可重复使用的 Voice Agent 配置：将 Settings 消息中的 agent 块保存到服务端，并通过 agent_id 引用。存储的数据块仅包含 agent 对象（listen / think / speak 提供方 + 提示词），不包含完整的 AgentV1Settings。

以下情况请使用其他技能：

• 想要实际与 Agent 对话 → deepgram-python-voice-agent。
• 想要转录或合成 → STT/TTS 技能。

身份验证

from dotenv import load_dotenv
load_dotenv()

from deepgram import DeepgramClient
client = DeepgramClient()

请求头：Authorization: Token <api_key>。所有方法均为 REST。

快速开始 — 项目 + 模型

# Projects
projects = client.manage.v1.projects.list()
for p in projects.projects:
    print(p.project_id, p.name)

project = client.manage.v1.projects.get(project_id=projects.projects[0].project_id)
client.manage.v1.projects.update(project_id=project.project_id, name="New name")
# client.manage.v1.projects.delete(project_id=...)   # irreversible
# client.manage.v1.projects.leave(project_id=...)

# Models
models = client.manage.v1.models.list()
print("STT:", [m.canonical_name for m in models.stt])
print("TTS:", [m.canonical_name for m in models.tts])

# Include deprecated/outdated models
older = client.manage.v1.models.list(include_outdated=True)

# Per-project model access
project_models = client.manage.v1.projects.models.list(project_id=project.project_id)

快速开始 — 密钥 / 成员 / 邀请 / 用量 / 账单

所有项目范围的资源都位于 client.manage.v1.projects.* 下：

# Keys — `create` takes a single `request=` payload, not top-level kwargs
keys = client.manage.v1.projects.keys.list(project_id=pid)
client.manage.v1.projects.keys.create(
    project_id=pid,
    request={"comment": "CI key", "scopes": ["usage:write"]},
)
client.manage.v1.projects.keys.delete(project_id=pid, key_id=kid)

# Members + invites (invites are nested under members; method is `create`, not `send`)
members = client.manage.v1.projects.members.list(project_id=pid)
invites = client.manage.v1.projects.members.invites.list(project_id=pid)
client.manage.v1.projects.members.invites.create(project_id=pid, email="[email protected]", scope="member")

# Usage (get, not list) + billing balances (nested)
usage = client.manage.v1.projects.usage.get(project_id=pid)
usage_breakdown = client.manage.v1.projects.usage.breakdown.list(project_id=pid)
balance = client.manage.v1.projects.billing.balances.get(project_id=pid)

各子模块的示例请参见 examples/51-55。

快速开始 — Voice Agent 配置

# List reusable configs
configs = client.voice_agent.configurations.list(project_id=pid)

# Create: `config` is a JSON string of the `agent` BLOCK ONLY — not the full
# Settings message. Do NOT include top-level Settings fields like `audio`;
# those are sent at connect-time in the live Settings message. The stored
# `agent_id` later replaces the inline `agent` object in a Settings message.
import json
config_json = json.dumps({
    "listen": {"provider": {"type": "deepgram", "model": "nova-3"}},
    "think":  {"provider": {"type": "open_ai", "model": "gpt-4o-mini"}, "prompt": "..."},
    "speak":  {"provider": {"type": "deepgram", "model": "aura-2-asteria-en"}},
})
created = client.voice_agent.configurations.create(
    project_id=pid,
    config=config_json,
    metadata={"label": "support-en"},
)
print(created.agent_id)

# Update metadata (immutable config body — create a new one to change behavior)
client.voice_agent.configurations.update(project_id=pid, agent_id=created.agent_id, metadata={"label": "v2"})

# Get / delete
one = client.voice_agent.configurations.get(project_id=pid, agent_id=created.agent_id)
# client.voice_agent.configurations.delete(project_id=pid, agent_id=...)

思考提供方模型发现（Agent 支持哪些大模型）：

think_models = client.agent.v1.settings.think.models.list()

异步版本

from deepgram import AsyncDeepgramClient
client = AsyncDeepgramClient()
projects = await client.manage.v1.projects.list()

API 参考（分层）

1. 仓库内参考：reference.md —“Manage V1 Projects/Keys/Members/Invites/Usage/Billing/Models”“Voice Agent Configurations”。
2. OpenAPI（REST）：https://developers.deepgram.com/openapi.yaml
3. Context7：库 ID /llmstxt/developers_deepgram_llms_txt。
4. 产品文档：
   • https://developers.deepgram.com/reference/manage/projects/list
   • https://developers.deepgram.com/reference/manage/models/list
   • https://developers.deepgram.com/reference/voice-agent/agent-configurations/list-agent-configurations
   • https://developers.deepgram.com/reference/voice-agent/agent-configurations/create-agent-configuration
   • https://developers.deepgram.com/reference/voice-agent/think-models

注意事项

1. 使用 Token 身份验证，而不是 Bearer。
2. 项目范围的资源嵌套在 .projects.* 下。 不存在顶层的 client.manage.v1.keys / .members / .invites / .usage / .billing。请使用 client.manage.v1.projects.keys、...projects.members、...projects.members.invites、...projects.usage、...projects.billing.balances，以及用于请求日志的 ...projects.requests。顶层 client.manage.v1.* 命名空间仅有 projects 和 models。
3. 思考模型发现位于 Agent 客户端，而非 Manage： client.agent.v1.settings.think.models.list()。不存在 client.manage.v1.agent.*。
4. 创建时，Agent 配置正文必须是 JSON 字符串，而不是嵌套对象。请传入 config=json.dumps(...)。
5. Agent 配置仅包含 agent 块，不包含完整的 Settings 消息。不要包含 audio 等顶层字段——这些字段应在连接时放入实时 Settings 消息。
6. Agent 配置不可变——无法编辑配置正文。要更改行为，请创建新配置。只有元数据可变。
7. 固定较旧模型时，请在 models.list() 中使用 include_outdated=True。
8. 删除操作不可逆。 实际测试通常会注释掉破坏性调用。
9. 项目范围模型与全局模型：client.manage.v1.models.list() 会返回全部模型；client.manage.v1.projects.models.list(project_id=...) 会返回该项目可访问的模型。
10. 返回的 Agent 配置未经插值——它是原始存储的 JSON 字符串。使用前请先解析。

此仓库中的示例文件

• examples/50-management-projects.py
• examples/51-management-keys.py
• examples/52-management-members.py
• examples/53-management-invites.py
• examples/54-management-usage.py
• examples/55-management-billing.py
• examples/56-management-models.py
• tests/wire/test_manage_v1_projects.py
• tests/wire/test_manage_v1_models.py
• tests/wire/test_voiceAgent_configurations.py

相关技能

• deepgram-python-voice-agent — 运行 Agent（使用此处创建的配置）

核心产品技能

如需跨语言的 Deepgram 产品知识——整合后的 API 参考、文档查找器、专注且可运行的示例、第三方集成示例和 MCP 设置，请安装核心技能：

npx skills add deepgram/skills

此 SDK 提供符合语言习惯的代码技能；deepgram/skills 提供跨语言产品知识（请参阅 api、docs、recipes、examples、starters、setup-mcp）。