tessl/pypi-deepgram-sdk

The official Python SDK for the Deepgram automated speech recognition platform.

—

Pending

Overview

Eval results

Files

Project Management

Name: tessl/pypi-deepgram-sdk
Author: tessl

Complete account and project management functionality including API key management, usage tracking, team member management, and billing information access. The Manage module provides comprehensive administrative capabilities for Deepgram accounts and projects.

Capabilities

Manage Client

Synchronous and asynchronous clients for account and project management operations.

class ManageClient:
    # Project Management
    def get_projects(self) -> ProjectsResponse: ...
    def get_project(self, project_id: str) -> Project: ...
    def update_project(self, project_id: str, options: ProjectOptions) -> Message: ...
    def delete_project(self, project_id: str) -> Message: ...
    
    # API Key Management
    def get_keys(self, project_id: str) -> KeysResponse: ...
    def get_key(self, project_id: str, key_id: str) -> KeyResponse: ...
    def create_key(self, project_id: str, options: KeyOptions) -> KeyResponse: ...
    def delete_key(self, project_id: str, key_id: str) -> Message: ...
    
    # Team Member Management
    def get_members(self, project_id: str) -> MembersResponse: ...
    def remove_member(self, project_id: str, member_id: str) -> Message: ...
    def get_member_scopes(self, project_id: str, member_id: str) -> ScopesResponse: ...
    def update_member_scope(self, project_id: str, member_id: str, options: ScopeOptions) -> Message: ...
    
    # Invitation Management
    def get_invites(self, project_id: str) -> InvitesResponse: ...
    def send_invite(self, project_id: str, options: InviteOptions) -> Message: ...
    def delete_invite(self, project_id: str, email: str) -> Message: ...
    
    # Usage and Billing
    def get_usage(self, project_id: str, options: UsageRequestOptions) -> UsageResponse: ...
    def get_usage_request(self, project_id: str, request_id: str) -> UsageRequest: ...
    def get_usage_requests(self, project_id: str, options: UsageRequestOptions) -> UsageRequestsResponse: ...
    def get_usage_summary(self, project_id: str, options: UsageSummaryOptions) -> UsageSummaryResponse: ...
    def get_usage_fields(self, project_id: str, options: UsageFieldsOptions) -> UsageFieldsResponse: ...
    def get_balances(self, project_id: str) -> BalancesResponse: ...
    
    # Model Information
    def get_models(self, project_id: str) -> ModelsResponse: ...
    def get_model(self, project_id: str, model_id: str) -> ModelResponse: ...

class AsyncManageClient:
    # All methods are async versions of ManageClient methods
    async def get_projects(self) -> ProjectsResponse: ...
    async def get_project(self, project_id: str) -> Project: ...
    # ... (all other methods with async keyword)

Options Classes

Configuration options for various management operations.

class ProjectOptions:
    def __init__(self, **kwargs): ...
    name: str = None  # Project name
    company: str = None  # Company name

class KeyOptions:
    def __init__(self, **kwargs): ...
    comment: str = None  # Key description/comment
    scopes: list = None  # Key permissions/scopes
    tags: list = None  # Key tags for organization
    time_to_live_in_seconds: int = None  # Key expiration time

class ScopeOptions:
    def __init__(self, **kwargs): ...
    scope: str  # Permission scope to assign/modify

class InviteOptions:
    def __init__(self, **kwargs): ...
    email: str  # Email address to invite
    scope: str  # Permission scope for invitee

class UsageRequestOptions:
    def __init__(self, **kwargs): ...
    start: str = None  # Start date (ISO format)
    end: str = None  # End date (ISO format)
    limit: int = None  # Number of results to return
    status: str = None  # Filter by request status

class UsageSummaryOptions:
    def __init__(self, **kwargs): ...
    start: str = None  # Start date (ISO format)
    end: str = None  # End date (ISO format)
    accessor: str = None  # Filter by accessor
    tag: str = None  # Filter by tag
    method: str = None  # Filter by HTTP method
    model: str = None  # Filter by model
    multichannel: bool = None  # Filter by multichannel usage
    interim_results: bool = None  # Filter by interim results usage
    punctuate: bool = None  # Filter by punctuation usage
    ner: bool = None  # Filter by NER usage
    diarize: bool = None  # Filter by diarization usage
    search: bool = None  # Filter by search usage
    redact: bool = None  # Filter by redaction usage
    alternatives: bool = None  # Filter by alternatives usage
    numerals: bool = None  # Filter by numerals usage
    smart_format: bool = None  # Filter by smart formatting usage

class UsageFieldsOptions:
    def __init__(self, **kwargs): ...
    start: str = None  # Start date (ISO format)
    end: str = None  # End date (ISO format)

Response Types

Project Management Responses

class ProjectsResponse:
    """List of projects response"""
    projects: list[Project]

class Project:
    """Project information"""
    project_id: str
    name: str
    company: str = None
    created: str
    updated: str = None

class Message:
    """Generic success/status message"""
    message: str

API Key Management Responses

class KeysResponse:
    """List of API keys response"""
    api_keys: list[Key]

class KeyResponse:
    """Single API key response"""
    api_key: Key

class Key:
    """API key information"""
    api_key_id: str
    key: str = None  # Actual key value (only shown on creation)
    comment: str = None
    created: str
    scopes: list[str]
    tags: list[str] = None

Team Management Responses

class MembersResponse:
    """Team members list response"""
    members: list[Member]

class Member:
    """Team member information"""
    member_id: str
    email: str
    first_name: str = None
    last_name: str = None
    scopes: list[str]

class ScopesResponse:
    """Member scopes response"""
    scopes: list[str]

class InvitesResponse:
    """Pending invitations response"""
    invites: list[Invite]

class Invite:
    """Invitation information"""
    email: str
    scope: str
    sent: str

Usage and Billing Responses

class UsageResponse:
    """Usage data response"""
    start: str
    end: str
    resolution: Resolution
    results: list[UsageRequest]

class UsageRequestsResponse:
    """Usage requests list response"""
    page: int
    limit: int
    requests: list[UsageRequest]

class UsageRequest:
    """Individual usage request"""
    request_id: str
    created: str
    path: str
    accessor: str = None
    response: dict = None
    callback: Callback = None

class UsageSummaryResponse:
    """Usage summary response"""
    start: str
    end: str
    resolution: Resolution
    results: list[UsageSummaryResults]

class UsageFieldsResponse:
    """Available usage fields response"""
    stt: STTDetails
    tts: TTSDetails

class BalancesResponse:
    """Account balances response"""
    balances: list[Balance]

class Balance:
    """Account balance information"""
    balance_id: str
    amount: float
    units: str
    purchase: str = None

Usage Detail Types

class UsageSummaryResults:
    """Usage summary data"""
    start: str
    end: str
    hours: float
    total_hours: float
    requests: int
    tokens: int

class Resolution:
    """Usage data resolution"""
    units: str
    amount: int

class STTDetails:
    """Speech-to-text usage details"""
    requests: int
    hours: float
    tokens: STTTokens

class TTSDetails:
    """Text-to-speech usage details"""
    requests: int
    characters: int
    tokens: TTSTokens

class TTSMetadata:
    """TTS metadata information"""
    model: str
    characters: int
    duration: float

class STTUsageDetails:
    """Detailed STT usage breakdown"""
    model: str
    language: str
    version: str
    uuid: str
    batch: bool
    streaming: bool
    method: str
    multichannel: bool
    alternatives: int
    numerals: bool
    punctuate: bool
    profanity_filter: bool
    redaction: bool
    diarization: bool
    ner: bool
    search: bool
    keywords: bool
    sentiment: bool
    topics: bool
    intents: bool
    custom_topics: bool
    custom_intents: bool

class TTSUsageDetails:
    """Detailed TTS usage breakdown"""
    model: str
    method: str

class STTTokens:
    """STT token usage"""
    tokens: int

class TTSTokens:
    """TTS token usage"""
    tokens: int

class UsageModel:
    """Usage model information"""
    name: str
    canonical_name: str
    architecture: str
    language: str = None
    version: str
    uuid: str
    batch: bool
    streaming: bool

Supporting Types

class Callback:
    """Callback configuration"""
    url: str
    method: str = "POST"

class TokenDetail:
    """Token usage details"""
    feature: str
    input: int
    output: int
    model: str

class SpeechSegment:
    """Speech processing segment"""
    start: float
    end: float
    confidence: float
    text: str

class Config:
    """Configuration settings"""
    key: str
    value: str

Model Information Responses

class ModelsResponse:
    """Available models list response"""
    stt_models: list[ModelInfo]
    tts_models: list[ModelInfo]

class ModelResponse:
    """Single model information response"""
    name: str
    canonical_name: str
    architecture: str
    languages: list[str] = None
    version: str
    uuid: str
    batch: bool
    streaming: bool

class ModelInfo:
    """Model information"""
    name: str
    canonical_name: str
    architecture: str
    language: str = None
    version: str
    uuid: str
    batch: bool
    streaming: bool

Usage Examples

Project Management

from deepgram import DeepgramClient

client = DeepgramClient(api_key="your-api-key")

# List all projects
projects_response = client.manage.get_projects()
print(f"Found {len(projects_response.projects)} projects:")

for project in projects_response.projects:
    print(f"- {project.name} (ID: {project.project_id})")
    
    # Get detailed project info
    project_details = client.manage.get_project(project.project_id)
    print(f"  Company: {project_details.company}")
    print(f"  Created: {project_details.created}")

API Key Management

from deepgram import DeepgramClient, KeyOptions

client = DeepgramClient(api_key="your-api-key")
project_id = "your-project-id"

# List existing keys
keys_response = client.manage.get_keys(project_id)
print(f"Existing keys: {len(keys_response.api_keys)}")

# Create a new API key
key_options = KeyOptions(
    comment="Development key for testing",
    scopes=["usage:read", "keys:read"],
    tags=["development", "testing"],
    time_to_live_in_seconds=86400  # 24 hours
)

new_key_response = client.manage.create_key(project_id, key_options)
print(f"Created new key: {new_key_response.api_key.api_key_id}")
print(f"Key value: {new_key_response.api_key.key}")  # Only shown on creation

# Get key details
key_details = client.manage.get_key(project_id, new_key_response.api_key.api_key_id)
print(f"Key scopes: {key_details.api_key.scopes}")
print(f"Key tags: {key_details.api_key.tags}")

Team Member Management

from deepgram import DeepgramClient, InviteOptions, ScopeOptions

client = DeepgramClient(api_key="your-api-key")
project_id = "your-project-id"

# List team members
members_response = client.manage.get_members(project_id)
print(f"Team members: {len(members_response.members)}")

for member in members_response.members:
    print(f"- {member.email} ({member.first_name} {member.last_name})")
    print(f"  Scopes: {member.scopes}")

# Send an invitation
invite_options = InviteOptions(
    email="new.member@company.com",
    scope="usage:read"
)

invite_response = client.manage.send_invite(project_id, invite_options)
print(f"Invitation sent: {invite_response.message}")

# List pending invitations
invites_response = client.manage.get_invites(project_id)
for invite in invites_response.invites:
    print(f"Pending invite: {invite.email} ({invite.scope}) - sent {invite.sent}")

# Update member scope
member_id = "member-id"
scope_options = ScopeOptions(scope="admin")
scope_response = client.manage.update_member_scope(project_id, member_id, scope_options)
print(f"Scope updated: {scope_response.message}")

Usage Tracking

from deepgram import DeepgramClient, UsageRequestOptions, UsageSummaryOptions
from datetime import datetime, timedelta

client = DeepgramClient(api_key="your-api-key")
project_id = "your-project-id"

# Get usage for the last 30 days
end_date = datetime.now()
start_date = end_date - timedelta(days=30)

usage_options = UsageRequestOptions(
    start=start_date.isoformat(),
    end=end_date.isoformat(),
    limit=100
)

usage_response = client.manage.get_usage(project_id, usage_options)
print(f"Usage period: {usage_response.start} to {usage_response.end}")
print(f"Found {len(usage_response.results)} usage records")

# Get usage summary
summary_options = UsageSummaryOptions(
    start=start_date.isoformat(),
    end=end_date.isoformat()
)

summary_response = client.manage.get_usage_summary(project_id, summary_options)
for result in summary_response.results:
    print(f"Period: {result.start} to {result.end}")
    print(f"  Hours: {result.hours:.2f}")
    print(f"  Requests: {result.requests}")
    print(f"  Tokens: {result.tokens}")

# Get available usage fields
fields_response = client.manage.get_usage_fields(project_id, usage_options)
print(f"STT requests this period: {fields_response.stt.requests}")
print(f"STT hours this period: {fields_response.stt.hours}")
print(f"TTS requests this period: {fields_response.tts.requests}")
print(f"TTS characters this period: {fields_response.tts.characters}")

Account Balances

from deepgram import DeepgramClient

client = DeepgramClient(api_key="your-api-key")
project_id = "your-project-id"

# Get account balances
balances_response = client.manage.get_balances(project_id)

print("Account Balances:")
for balance in balances_response.balances:
    print(f"- Balance ID: {balance.balance_id}")
    print(f"  Amount: {balance.amount} {balance.units}")
    if balance.purchase:
        print(f"  Purchase: {balance.purchase}")

Model Information

from deepgram import DeepgramClient

client = DeepgramClient(api_key="your-api-key")
project_id = "your-project-id"

# Get available models
models_response = client.manage.get_models(project_id)

print("Speech-to-Text Models:")
for model in models_response.stt_models:
    print(f"- {model.name} ({model.canonical_name})")
    print(f"  Architecture: {model.architecture}")
    print(f"  Version: {model.version}")
    print(f"  Batch: {model.batch}, Streaming: {model.streaming}")
    if model.language:
        print(f"  Language: {model.language}")

print("\nText-to-Speech Models:")
for model in models_response.tts_models:
    print(f"- {model.name} ({model.canonical_name})")
    print(f"  Architecture: {model.architecture}")
    print(f"  Version: {model.version}")

Async Management Operations

import asyncio
from deepgram import DeepgramClient

async def async_management_example():
    client = DeepgramClient(api_key="your-api-key")
    project_id = "your-project-id"
    
    # Perform multiple operations concurrently
    tasks = [
        client.manage.asyncmanage.get_projects(),
        client.manage.asyncmanage.get_keys(project_id),
        client.manage.asyncmanage.get_members(project_id),
        client.manage.asyncmanage.get_balances(project_id)
    ]
    
    projects, keys, members, balances = await asyncio.gather(*tasks)
    
    print(f"Projects: {len(projects.projects)}")
    print(f"API Keys: {len(keys.api_keys)}")
    print(f"Team Members: {len(members.members)}")
    print(f"Account Balances: {len(balances.balances)}")

# Run async example
asyncio.run(async_management_example())

Error Handling

from deepgram import DeepgramClient, DeepgramApiError, KeyOptions

client = DeepgramClient(api_key="your-api-key")
project_id = "your-project-id"

try:
    # Attempt to create a key with invalid options
    key_options = KeyOptions(
        comment="Test key",
        scopes=["invalid:scope"]  # This may cause an error
    )
    
    response = client.manage.create_key(project_id, key_options)
    print(f"Key created: {response.api_key.api_key_id}")
    
except DeepgramApiError as e:
    print(f"API Error: {e}")
    print("Please check your project ID and key permissions")
except Exception as e:
    print(f"Unexpected error: {e}")

Install with Tessl CLI