deepgram-python-management-api

Deepgram Management API の使用方法（Python SDK）

api.deepgram.com/v1/projects、/v1/models の管理用 REST エンドポイントと、再利用可能なエージェント設定ストレージです。プロジェクトスコープのリソースは client.manage.v1.projects.*（keys、members、members.invites、usage、billing、models、requests）にあります。グローバルモデルは client.manage.v1.models にあります。Think モデルの検出は client.agent.v1.settings.think.models で行います。再利用可能なエージェント設定は client.voice_agent.configurations.* にあります。

この製品を使用する場面

• モデルの検出／固定：client.manage.v1.models.list() は有効な STT/TTS セットを返します。
• プロジェクト管理：プロジェクトの一覧表示、取得、更新、削除、退出。
• API キーのライフサイクル管理：プロジェクトキーの一覧表示、作成、削除。
• メンバーと招待の管理：メンバーの追加／削除、ロールの管理、招待の送信／取り消し。
• 使用状況と請求：リクエスト数、残高の照会。
• 再利用可能な Voice Agent 設定：Settings メッセージの agent ブロックをサーバーに保存し、agent_id で参照します。保存されるデータは agent オブジェクトのみ（listen／think／speak プロバイダーとプロンプト）であり、AgentV1Settings 全体ではありません。

次の場合は別のスキルを使用してください：

• エージェントと実際に会話したい場合 → 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=...)

Think プロバイダーのモデル検出（Agent がサポートする LLM）：

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. 認証には Bearer ではなく Token を使用します。
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. Think モデルの検出は Manage ではなく Agent クライアントで行います：client.agent.v1.settings.think.models.list()。client.manage.v1.agent.* はありません。
4. エージェント設定の本文は作成時に JSON 文字列で指定します。ネストされたオブジェクトではありません。config=json.dumps(...) を渡してください。
5. エージェント設定は agent ブロックのみです。Settings メッセージ全体ではありません。audio などの最上位フィールドは含めないでください。これらは接続時のライブ Settings メッセージに指定します。
6. エージェント設定は不変です — 設定本文は編集できません。動作を変更するには新しい設定を作成してください。変更できるのはメタデータのみです。
7. 古いモデルを固定する場合は、models.list() で include_outdated=True を使用してください。
8. 削除は取り消せません。 ワイヤーテストでは通常、破壊的な呼び出しをコメントアウトします。
9. プロジェクトスコープのモデルとグローバルモデル：client.manage.v1.models.list() はすべてのモデルを返します。client.manage.v1.projects.models.list(project_id=...) はプロジェクトがアクセスできるモデルを返します。
10. 返されるエージェント設定は補間されていません — 保存された生の 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 — エージェントを実行します（ここで作成した設定を使用します）

中核製品スキル

言語を問わず Deepgram 製品の知識（統合された API リファレンス、ドキュメント検索、目的に特化した実行可能なレシピ、サードパーティ統合の例、MCP のセットアップ）を活用するには、中核スキルをインストールしてください。

npx skills add deepgram/skills

この SDK には言語に適したコードスキルが含まれています。deepgram/skills には言語を問わない製品知識が含まれています（api、docs、recipes、examples、starters、setup-mcp を参照）。