{"id":2922,"library":"deepgram-sdk","title":"Deepgram Python SDK","description":"The official Python SDK for Deepgram's automated speech recognition, text-to-speech, and language understanding APIs. It enables developers to integrate world-class speech and Language AI models into their applications. The library is actively maintained with frequent releases, currently at version 6.1.1.","status":"active","version":"6.1.1","language":"en","source_language":"en","source_url":"https://github.com/deepgram/deepgram-python-sdk","tags":["AI","Speech-to-Text","Text-to-Speech","STT","TTS","Speech Recognition","NLP","Audio Processing"],"install":[{"cmd":"pip install deepgram-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for using Deepgram models on AWS SageMaker endpoints.","package":"deepgram-sagemaker","optional":true}],"imports":[{"note":"The `Deepgram` client was used in v5 and earlier; `DeepgramClient` is the current client in v6.","wrong":"from deepgram import Deepgram","symbol":"DeepgramClient","correct":"from deepgram import DeepgramClient"},{"note":"Used for handling WebSocket events.","symbol":"EventType","correct":"from deepgram.core.events import EventType"},{"note":"Types are now imported from their feature-specific namespaces in v6.","symbol":"ListenV2Options","correct":"from deepgram.listen.v2.options import ListenV2Options"}],"quickstart":{"code":"import os\nfrom deepgram import DeepgramClient, DeepgramClientOptions, LiveTranscriptionEvents\n\n# Ensure you have your Deepgram API key set as an environment variable (DEEPGRAM_API_KEY or DEEPGRAM_TOKEN)\nAPI_KEY = os.environ.get('DEEPGRAM_API_KEY') or os.environ.get('DEEPGRAM_TOKEN')\n\nif not API_KEY:\n    raise ValueError(\"DEEPGRAM_API_KEY or DEEPGRAM_TOKEN environment variable not set.\")\n\n# Configure the client options for best performance and compatibility\nconfig = DeepgramClientOptions(verbose=1)\ndeepgram = DeepgramClient(API_KEY, config=config)\n\n# For real-time streaming, connect to the Listen API\n# This example demonstrates a synchronous connection for simplicity, \n# but async methods are also available.\ndef main():\n    try:\n        # Connect to the real-time Listen API (v2)\n        connection = deepgram.listen.v2.live.connect()\n\n        # Define event handlers\n        def on_message(self, result, **kwargs):\n            if result.speech_final: # Only print final transcripts\n                print(f\"Speaker: {result.speaker}\") # Assuming speaker diarization is enabled\n                print(f\"Transcript: {result.channel.alternatives[0].transcript}\")\n\n        def on_open(self, open, **kwargs):\n            print(\"Connection opened.\")\n\n        def on_close(self, close, **kwargs):\n            print(\"Connection closed.\")\n\n        def on_error(self, error, **kwargs):\n            print(f\"Error: {error}\")\n\n        # Register event handlers\n        connection.on(LiveTranscriptionEvents.Open, on_open)\n        connection.on(LiveTranscriptionEvents.Transcript, on_message)\n        connection.on(LiveTranscriptionEvents.Close, on_close)\n        connection.on(LiveTranscriptionEvents.Error, on_error)\n\n        # Start sending audio data (in a real app, this would be from a microphone or audio file)\n        # For this example, we'll just send a dummy message and close.\n        print(\"Sending dummy data... (in a real app, send actual audio bytes)\")\n        # In a real application, you would continuously send bytes from an audio source:\n        # connection.send_data(audio_chunk_bytes)\n        # For now, simulate sending options\n        connection.send_options({\n            \"model\": \"nova-2\",\n            \"language\": \"en-US\",\n            \"punctuate\": True,\n            \"diarize\": True,\n            \"smart_format\": True\n        })\n\n        import time\n        time.sleep(5) # Keep connection open for a bit to simulate processing\n\n        # Don't forget to close the connection when done\n        connection.finish()\n\n    except Exception as e:\n        print(f\"Could not open connection: {e}\")\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"This quickstart demonstrates how to initialize the DeepgramClient, configure it with an API key from environment variables, and establish a real-time WebSocket connection to the Deepgram Listen API (v2) for transcribing audio. It includes basic event handlers for connection status and incoming transcripts."},"warnings":[{"fix":"Review the official migration guide from v5 to v6. Update all WebSocket client instantiations and interaction patterns.","message":"Version 6.0.0 introduced significant breaking changes, including a complete overhaul of WebSocket clients. Hand-rolled WebSocket code from v5 has been replaced by fully generated clients for Listen v1/v2, Speak v1, and Agent v1.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure audio data is converted to `bytes` before sending via `send_media()`. Replace calls to `send_control()` with the new specific control methods.","message":"The `send_media()` method for WebSocket clients now exclusively accepts raw `bytes` for audio data. Control messages (like keep-alive, finalize, flush) have been replaced by dedicated methods (`send_keep_alive()`, `send_finalize()`, `send_flush()`) instead of the generic `send_control({'type': '...'})` pattern.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Update all type import statements to reflect the new module structure (e.g., `from deepgram.listen.v1.options import ListenV1Options`).","message":"The type system in v6 has shifted to domain-specific imports. Types are now imported from their respective feature namespaces (e.g., `deepgram.listen.v1.types`, `deepgram.agent.v1.types`) instead of a shared 'barrel' module.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"If using SageMaker transport, install the `deepgram-sagemaker` package separately (`pip install deepgram-sagemaker`).","message":"The SageMaker transport functionality has been extracted into a separate package, `deepgram-sagemaker`. It is no longer part of the core `deepgram-sdk`.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Be aware of the authentication priority: explicit parameter > `DEEPGRAM_TOKEN` env var > `DEEPGRAM_API_KEY` env var. Always ensure the correct API key or token is being used based on your configuration.","message":"When providing authentication credentials, the SDK prioritizes environment variables. Specifically, `DEEPGRAM_TOKEN` takes precedence over `DEEPGRAM_API_KEY`. Explicit `access_token` or `api_key` parameters during `DeepgramClient` initialization take the highest precedence.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}