{"id":13826514,"url":"https://github.com/deepgram/deepgram-python-sdk","last_synced_at":"2025-12-12T00:59:48.881Z","repository":{"id":37531755,"uuid":"366871642","full_name":"deepgram/deepgram-python-sdk","owner":"deepgram","description":"Official Python SDK for Deepgram.","archived":false,"fork":false,"pushed_at":"2025-05-09T21:01:21.000Z","size":16767,"stargazers_count":304,"open_issues_count":24,"forks_count":82,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-05-09T21:26:37.362Z","etag":null,"topics":["asr","automated-speech-recognition","deepgram","hacktoberfest","python","speech-recognition","speech-to-text","text-to-speech","voice-agent","voice-ai"],"latest_commit_sha":null,"homepage":"https://developers.deepgram.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deepgram.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-05-12T22:41:01.000Z","updated_at":"2025-05-09T20:57:56.000Z","dependencies_parsed_at":"2023-11-28T06:24:50.639Z","dependency_job_id":"a310fc1c-caf4-461e-a480-b550b41f6b19","html_url":"https://github.com/deepgram/deepgram-python-sdk","commit_stats":{"total_commits":356,"total_committers":37,"mean_commits":9.621621621621621,"dds":0.6601123595505618,"last_synced_commit":"7df7b270a530c00fac4ebd77e9581ddafebe2d9f"},"previous_names":[],"tags_count":117,"template":false,"template_full_name":"deepgram/oss-repo-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepgram%2Fdeepgram-python-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepgram%2Fdeepgram-python-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepgram%2Fdeepgram-python-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepgram%2Fdeepgram-python-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deepgram","download_url":"https://codeload.github.com/deepgram/deepgram-python-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254118647,"owners_count":22017942,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asr","automated-speech-recognition","deepgram","hacktoberfest","python","speech-recognition","speech-to-text","text-to-speech","voice-agent","voice-ai"],"created_at":"2024-08-04T09:01:39.441Z","updated_at":"2025-12-12T00:59:48.873Z","avatar_url":"https://github.com/deepgram.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Deepgram Python SDK\n\n![Built with Fern](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)\n[![PyPI version](https://img.shields.io/pypi/v/deepgram-sdk)](https://pypi.python.org/pypi/deepgram-sdk)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)\n\nThe official Python SDK for Deepgram's automated speech recognition, text-to-speech, and language understanding APIs. Power your applications with world-class speech and Language AI models.\n\n## Documentation\n\nComprehensive API documentation and guides are available at [developers.deepgram.com](https://developers.deepgram.com).\n\n### Migrating From Earlier Versions\n\n- [v2 to v3+](./docs/Migrating-v2-to-v3.md)\n- [v3+ to v5](./docs/Migrating-v3-to-v5.md) (current)\n\n## Installation\n\nInstall the Deepgram Python SDK using pip:\n\n```bash\npip install deepgram-sdk\n```\n\n## Reference\n\n- **[API Reference](./reference.md)** - Complete reference for all SDK methods and parameters\n- **[WebSocket Reference](./websockets-reference.md)** - Detailed documentation for real-time WebSocket connections\n\n## Usage\n\n### Quick Start\n\nThe Deepgram SDK provides both synchronous and asynchronous clients for all major use cases:\n\n#### Real-time Speech Recognition (Listen v2)\n\nOur newest and most advanced speech recognition model with contextual turn detection ([WebSocket Reference](./websockets-reference.md#listen-v2-connect)):\n\n```python\nfrom deepgram import DeepgramClient\nfrom deepgram.core.events import EventType\n\nclient = DeepgramClient()\n\nwith client.listen.v2.connect(\n    model=\"flux-general-en\",\n    encoding=\"linear16\",\n    sample_rate=\"16000\"\n) as connection:\n    def on_message(message):\n        print(f\"Received {message.type} event\")\n\n    connection.on(EventType.OPEN, lambda _: print(\"Connection opened\"))\n    connection.on(EventType.MESSAGE, on_message)\n    connection.on(EventType.CLOSE, lambda _: print(\"Connection closed\"))\n    connection.on(EventType.ERROR, lambda error: print(f\"Error: {error}\"))\n\n    # Start listening and send audio data\n    connection.start_listening()\n```\n\n#### File Transcription\n\nTranscribe pre-recorded audio files ([API Reference](./reference.md#listen-v1-media-transcribe-file)):\n\n```python\nfrom deepgram import DeepgramClient\n\nclient = DeepgramClient()\n\nwith open(\"audio.wav\", \"rb\") as audio_file:\n    response = client.listen.v1.media.transcribe_file(\n        request=audio_file.read(),\n        model=\"nova-3\"\n    )\n    print(response.results.channels[0].alternatives[0].transcript)\n```\n\n#### Text-to-Speech\n\nGenerate natural-sounding speech from text ([API Reference](./reference.md#speak-v1-audio-generate)):\n\n```python\nfrom deepgram import DeepgramClient\n\nclient = DeepgramClient()\n\nresponse = client.speak.v1.audio.generate(\n    text=\"Hello, this is a sample text to speech conversion.\"\n)\n\n# Save the audio file\nwith open(\"output.mp3\", \"wb\") as audio_file:\n    audio_file.write(response.stream.getvalue())\n```\n\n#### Text Analysis\n\nAnalyze text for sentiment, topics, and intents ([API Reference](./reference.md#read-v1-text-analyze)):\n\n```python\nfrom deepgram import DeepgramClient\n\nclient = DeepgramClient()\n\nresponse = client.read.v1.text.analyze(\n    request={\"text\": \"Hello, world!\"},\n    language=\"en\",\n    sentiment=True,\n    summarize=True,\n    topics=True,\n    intents=True\n)\n```\n\n#### Voice Agent (Conversational AI)\n\nBuild interactive voice agents ([WebSocket Reference](./websockets-reference.md#agent-v1-connect)):\n\n```python\nfrom deepgram import DeepgramClient\nfrom deepgram.extensions.types.sockets import (\n    AgentV1SettingsMessage, AgentV1Agent, AgentV1AudioConfig,\n    AgentV1AudioInput, AgentV1Listen, AgentV1ListenProvider,\n    AgentV1Think, AgentV1OpenAiThinkProvider, AgentV1SpeakProviderConfig,\n    AgentV1DeepgramSpeakProvider\n)\n\nclient = DeepgramClient()\n\nwith client.agent.v1.connect() as agent:\n    settings = AgentV1SettingsMessage(\n        audio=AgentV1AudioConfig(\n            input=AgentV1AudioInput(encoding=\"linear16\", sample_rate=44100)\n        ),\n        agent=AgentV1Agent(\n            listen=AgentV1Listen(\n                provider=AgentV1ListenProvider(type=\"deepgram\", model=\"nova-3\")\n            ),\n            think=AgentV1Think(\n                provider=AgentV1OpenAiThinkProvider(\n                    type=\"open_ai\", model=\"gpt-4o-mini\"\n                )\n            ),\n            speak=AgentV1SpeakProviderConfig(\n                provider=AgentV1DeepgramSpeakProvider(\n                    type=\"deepgram\", model=\"aura-2-asteria-en\"\n                )\n            )\n        )\n    )\n\n    agent.send_settings(settings)\n    agent.start_listening()\n```\n\n### Complete SDK Reference\n\nFor comprehensive documentation of all available methods, parameters, and options:\n\n- **[API Reference](./reference.md)** - Complete reference for REST API methods including:\n\n  - Listen (Speech-to-Text): File transcription, URL transcription, and media processing\n  - Speak (Text-to-Speech): Audio generation and voice synthesis\n  - Read (Text Intelligence): Text analysis, sentiment, summarization, and topic detection\n  - Manage: Project management, API keys, and usage analytics\n  - Auth: Token generation and authentication management\n\n- **[WebSocket Reference](./websockets-reference.md)** - Detailed documentation for real-time connections:\n  - Listen v1/v2: Real-time speech recognition with different model capabilities\n  - Speak v1: Real-time text-to-speech streaming\n  - Agent v1: Conversational voice agents with integrated STT, LLM, and TTS\n\n## Authentication\n\nThe Deepgram SDK supports two authentication methods:\n\n### Access Token Authentication\n\nUse access tokens for temporary or scoped access (recommended for client-side applications):\n\n```python\nfrom deepgram import DeepgramClient\n\n# Explicit access token\nclient = DeepgramClient(access_token=\"YOUR_ACCESS_TOKEN\")\n\n# Or via environment variable DEEPGRAM_TOKEN\nclient = DeepgramClient()\n\n# Generate access tokens using your API key\nauth_client = DeepgramClient(api_key=\"YOUR_API_KEY\")\ntoken_response = auth_client.auth.v1.tokens.grant()\ntoken_client = DeepgramClient(access_token=token_response.access_token)\n```\n\n### API Key Authentication\n\nUse your Deepgram API key for server-side applications:\n\n```python\nfrom deepgram import DeepgramClient\n\n# Explicit API key\nclient = DeepgramClient(api_key=\"YOUR_API_KEY\")\n\n# Or via environment variable DEEPGRAM_API_KEY\nclient = DeepgramClient()\n```\n\n### Environment Variables\n\nThe SDK automatically discovers credentials from these environment variables:\n\n- `DEEPGRAM_TOKEN` - Your access token (takes precedence)\n- `DEEPGRAM_API_KEY` - Your Deepgram API key\n\n**Precedence:** Explicit parameters \u003e Environment variables\n\n## Async Client\n\nThe SDK provides full async/await support for non-blocking operations:\n\n```python\nimport asyncio\nfrom deepgram import AsyncDeepgramClient\n\nasync def main():\n    client = AsyncDeepgramClient()\n\n    # Async file transcription\n    with open(\"audio.wav\", \"rb\") as audio_file:\n        response = await client.listen.v1.media.transcribe_file(\n            request=audio_file.read(),\n            model=\"nova-3\"\n        )\n\n    # Async WebSocket connection\n    async with client.listen.v2.connect(\n        model=\"flux-general-en\",\n        encoding=\"linear16\",\n        sample_rate=\"16000\"\n    ) as connection:\n        async def on_message(message):\n            print(f\"Received {message.type} event\")\n\n        connection.on(EventType.MESSAGE, on_message)\n        await connection.start_listening()\n\nasyncio.run(main())\n```\n\n## Exception Handling\n\nThe SDK provides detailed error information for debugging and error handling:\n\n```python\nfrom deepgram import DeepgramClient\nfrom deepgram.core.api_error import ApiError\n\nclient = DeepgramClient()\n\ntry:\n    response = client.listen.v1.media.transcribe_file(\n        request=audio_data,\n        model=\"nova-3\"\n    )\nexcept ApiError as e:\n    print(f\"Status Code: {e.status_code}\")\n    print(f\"Error Details: {e.body}\")\n    print(f\"Request ID: {e.headers.get('x-dg-request-id', 'N/A')}\")\nexcept Exception as e:\n    print(f\"Unexpected error: {e}\")\n```\n\n## Advanced Features\n\n### Raw Response Access\n\nAccess raw HTTP response data including headers:\n\n```python\nfrom deepgram import DeepgramClient\n\nclient = DeepgramClient()\n\nresponse = client.listen.v1.media.with_raw_response.transcribe_file(\n    request=audio_data,\n    model=\"nova-3\"\n)\n\nprint(response.headers)  # Access response headers\nprint(response.data)     # Access the response object\n```\n\n### Request Configuration\n\nConfigure timeouts, retries, and other request options:\n\n```python\nfrom deepgram import DeepgramClient\n\n# Global client configuration\nclient = DeepgramClient(timeout=30.0)\n\n# Per-request configuration\nresponse = client.listen.v1.media.transcribe_file(\n    request=audio_data,\n    model=\"nova-3\",\n    request_options={\n        \"timeout_in_seconds\": 60,\n        \"max_retries\": 3\n    }\n)\n```\n\n### Custom HTTP Client\n\nUse a custom httpx client for advanced networking features:\n\n```python\nimport httpx\nfrom deepgram import DeepgramClient\n\nclient = DeepgramClient(\n    httpx_client=httpx.Client(\n        proxies=\"http://proxy.example.com\",\n        timeout=httpx.Timeout(30.0)\n    )\n)\n```\n\n### Retry Configuration\n\nThe SDK automatically retries failed requests with exponential backoff:\n\n```python\n# Automatic retries for 408, 429, and 5xx status codes\nresponse = client.listen.v1.media.transcribe_file(\n    request=audio_data,\n    model=\"nova-3\",\n    request_options={\"max_retries\": 3}\n)\n```\n\n## Contributing\n\nWe welcome contributions to improve this SDK! However, please note that this library is primarily generated from our API specifications.\n\n### Development Setup\n\n1. **Install Poetry** (if not already installed):\n\n   ```bash\n   curl -sSL https://install.python-poetry.org | python - -y --version 1.5.1\n   ```\n\n2. **Install dependencies**:\n\n   ```bash\n   poetry install\n   ```\n\n3. **Install example dependencies**:\n\n   ```bash\n   poetry run pip install -r examples/requirements.txt\n   ```\n\n4. **Run tests**:\n\n   ```bash\n   poetry run pytest -rP .\n   ```\n\n5. **Run examples**:\n   ```bash\n   python -u examples/listen/v2/connect/main.py\n   ```\n\n### Contribution Guidelines\n\nSee our [CONTRIBUTING](./CONTRIBUTING.md) guide.\n\n### Requirements\n\n- Python 3.8+\n- See `pyproject.toml` for full dependency list\n\n## Community Code of Conduct\n\nPlease see our community [code of conduct](https://developers.deepgram.com/code-of-conduct) before contributing to this project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepgram%2Fdeepgram-python-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeepgram%2Fdeepgram-python-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepgram%2Fdeepgram-python-sdk/lists"}