Python SDK V2 to V3 Migration Guide

Migrating from Deepgram Python SDK v2 to the Deepgram Python SDK v3

This guide is for users with experience using the Deepgram Python SDK v2 who want to migrate to the Deepgram Python SDK v3. This is not an end-to-end guide, but a reference for people using our existing Python SDK to migrate to our newest version.

Notable Changes

  • Significant Restructure of the Python SDK
  • Improved implementation for Live Client
  • Implements both Sync(/Threaded) and Async(/Await) Classes and Functions
  • Verbosity Logging Levels for Troubleshooting
  • WebVTT and SRT captions published as a standalone package
  • Custom Header and Query Parameters for API calls
  • Support for future products (APIs)
  • Better error handling

Migration Guide

This migration guide focuses primarily on the Sync/Threaded classes and methods in this SDK. The Async/Await classes and methods are very similar, where the class name will be prepended with “Async” and properties prepended with “async”.

For example, the Prerecorded Client for Sync/Threaded would be Prerecorded and the Async/Await would be AsyncPrerecorded.

If accessing the Pre-recorded Client from the deepgram.listen properties, the Sync/Threaded property would be deepgram.listen.prerecorded and the Async/Await would be deepgram.listen.asyncprerecorded.

Installation

Terminal
1pip install deepgram-sdk==3.*

Initialization

1from deepgram import Deepgram
2
3# Your Deepgram API Key
4DEEPGRAM_API_KEY = 'YOUR_DEEPGRAM_API_KEY'
5
6# Initialize the Deepgram SDK
7deepgram = Deepgram(DEEPGRAM_API_KEY)

Transcription: Pre-recorded

We have separated the callback feature into its own method. The functionality below is not valid with the callback feature.

Local File Transcription

Transcribe a local file on the same filesystem as the app is running.

1FILE = 'interview_speech-analytics.wav'
2
3# file is local
4# Open the audio file
5audio = open(FILE, 'rb')
6
7# Set the source
8source = {
9 'buffer': audio,
10}
11
12# Send the audio to Deepgram and get the response
13response = await asyncio.create_task(
14 deepgram.transcription.prerecorded(
15 source,
16 {
17 'smart_format': "true",
18 'summarize': "v2",
19 }
20 )
21)
22
23# Write the response to the console
24print(json.dumps(response, indent=4))

URL File Transcription

Transcribe a remote file by sending us a publicly accessible URL to it.

1URL = 'https://static.deepgram.com/examples/interview_speech-analytics.wav'
2
3# Set the source
4source = {
5 'url': URL,
6}
7
8# Send the audio to Deepgram and get the response
9response = await asyncio.create_task(
10 deepgram.transcription.prerecorded(
11 source,
12 {
13 'smart_format': "true",
14 'summarize': "v2",
15 }
16 )
17)
18
19# Write the response to the console
20print(json.dumps(response, indent=4))

Transcription: Live

The Live Client abstracts the underlying Websocket implementation from the user. This in turn only requires that you deal with higher level functions like start(), write(), finish() methods.

Live Transcription

Transcribe live audio streams. Previously only Async/Await class and methods were available. As of this release, both Sync/Threaded and Await/Await classes and methods are provided, but the prefered method of performing live transcription is Sync/Threaded.

1try:
2 deepgramLive = await deepgram.transcription.live({
3 'smart_format': True,
4 'interim_results': False,
5 'language': 'en-US',
6 'model': 'nova-3',
7 })
8except Exception as e:
9 print(f'Could not open socket: {e}')
10 return
11
12# Listen for the connection to close
13deepgramLive.registerHandler(deepgramLive.event.CLOSE, lambda c: print(
14 f'Connection closed with code {c}.'))
15
16# Listen for any transcripts received from Deepgram and write them to the console
17deepgramLive.registerHandler(deepgramLive.event.TRANSCRIPT_RECEIVED, print)
18
19# Listen for the connection to open and send streaming audio from the URL to Deepgram
20# IMPORTANT: This is a blocking call with no way to exit except through a Cntl-C,
21# IMPORTANT: disconnecting your internet, or killing the streaming (assuming you control that)
22async with aiohttp.ClientSession() as session:
23 async with session.get(URL) as audio:
24 while True:
25 data = await audio.content.readany()
26 deepgramLive.send(data)
27
28# If no data is being sent from the live stream, then break out of the loop.
29if not data:
30 break
31
32# Indicate that we've finished sending data by sending the customary zero-byte message to the Deepgram streaming endpoint, and wait until we get back the final summary metadata object
33await deepgramLive.finish()

Management API

This provides a transition guide from Async/Await to Sync/Threaded Manage APIs.

get all projects for a user

1result = await deepgram.projects.list()

See our API reference for more info.

get a project

1result = await deepgram.projects.get(PROJECT_ID)

See our API reference for more info.

update a project

1result = await deepgram.projects.update(object)

See our API reference for more info.

delete a project

1result = await deepgram.projects.delete(PROJECT_ID)

See our API reference for more info.

get all project key details

1result = await deepgram.keys.list(PROJECT_ID)

See our API reference for more info.

get a project key

1result = await deepgram.keys.get(PROJECT_ID, KEY_ID)

See our API reference for more info.

create a project key

1result = await deepgram.keys.create(PROJECT_ID, COMMENT_FOR_KEY, SCOPES)

See our API reference for more info.

delete a project key

1result = await deepgram.keys.delete(PROJECT_ID, KEY_ID)

See our API reference for more info.

get all project members

1result = await deepgram.members.list_members(PROJECT_ID);

See our API reference for more info.

remove a project member

1result = await deepgram.members.remove_member(PROJECT_ID, MEMBER_ID)

See our API reference for more info.

get all scopes for a project member

1result = await deepgram.scopes.get_scope(PROJECT_ID, MEMBER_ID)

See our API reference for more info.

update a scope for a project member

1result = await deepgram.scopes.update_scope(PROJECT_ID, MEMBER_ID, 'member')

See our API reference for more info.

get all project invites

1result = await deepgram.invitations.list_invitations(PROJECT_ID);

See our API reference for more info.

send a project invite

1result = await deepgram.invitations.send_invitation(PROJECT_ID, {
2 email: '[email protected]',
3 scope: 'member',
4})

See our API reference for more info.

delete a project invite

1result = await deepgram.invitations.remove_invitation(
2 PROJECT_ID,
3 '[email protected]'
4)

See our API reference for more info.

leave a project

1result = await deepgram.invitation.leave_project(PROJECT_ID);

See our API reference for more info.

get all usage requests for a project

1result = await deepgram.usage.list_requests(PROJECT_ID, {
2 'limit': 10,
3 # other options are available
4});

See our API reference for more info.

get a usage request for a project

1result = await deepgram.usage.get_request(PROJECT_ID, REQUEST_ID);

See our API reference for more info.

get the project usage summary

1result = await deepgram.usage.get_usage(PROJECT_ID, {
2 'start': '2020-01-01T00:00:00+00:00',
3 # other options are available
4});

See our API reference for more info.

get project usage fields

1result = await deepgram.usage.get_fields(PROJECT_ID, {
2 'start': '2020-01-01T00:00:00+00:00',
3 # other options are available
4});

See our API reference for more info.

get all project balances

1result = await deepgram.billing.list_balance(PROJECT_ID);

See our API reference for more info.

get a project balance

1result = await deepgram.billing.get_balance(PROJECT_ID, BALANCE_ID);

See our API reference for more info.

Self-Hosted API

[NOTICE] The self-hosted API has not changed since the last release, but in v4 these APIs will likely go through a breaking change. There was only so much we could do with this release and unfortunately, these APIs failed to make the cut off.

Built with