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

pip install deepgram-sdk==3.*

Initialization

from deepgram import Deepgram

# Your Deepgram API Key
DEEPGRAM_API_KEY = 'YOUR_DEEPGRAM_API_KEY'

# Initialize the Deepgram SDK
deepgram = Deepgram(DEEPGRAM_API_KEY)
from deepgram import DeepgramClient

# Create a Deepgram client using the DEEPGRAM_API_KEY from environment variables
deepgram = DeepgramClient()

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.

FILE = 'interview_speech-analytics.wav'

# file is local
# Open the audio file
audio = open(FILE, 'rb')

# Set the source
source = {
	'buffer': audio,
}

# Send the audio to Deepgram and get the response
response = await asyncio.create_task(
  deepgram.transcription.prerecorded(
    source,
    {
      'smart_format': "true",
      'summarize': "v2",
    }
  )
)

# Write the response to the console
print(json.dumps(response, indent=4))
AUDIO_FILE = "preamble.wav"

# Call the transcribe_file method on the prerecorded class
  with open(AUDIO_FILE, "rb") as file:
  buffer_data = file.read()

payload: FileSource = {
	"buffer": buffer_data,
}

options = PrerecordedOptions(
  smart_format=True,
  summarize="v2",
)
file_response = deepgram.listen.rest.v("1").transcribe_file(payload, options)

json = file_response.to_json()
print(f"{json}")

URL File Transcription

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

URL = 'https://static.deepgram.com/examples/interview_speech-analytics.wav'

# Set the source
source = {
    'url': URL,
}

# Send the audio to Deepgram and get the response
response = await asyncio.create_task(
  deepgram.transcription.prerecorded(
    source,
    {
      'smart_format': "true",
      'summarize': "v2",
    }
  )
)

# Write the response to the console
print(json.dumps(response, indent=4))
AUDIO_URL = {
    "url": "https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav"
}

options = PrerecordedOptions(
    smart_format=True,
    summarize="v2",
)
url_response = deepgram.listen.rest.v("1").transcribe_url(AUDIO_URL, options)

json = url_response.to_json()
print(f"{json}")

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.

try:
  deepgramLive = await deepgram.transcription.live({
    'smart_format': True,
    'interim_results': False,
    'language': 'en-US',
    'model': 'nova-2',
  })
except Exception as e:
  print(f'Could not open socket: {e}')
  return

# Listen for the connection to close
deepgramLive.registerHandler(deepgramLive.event.CLOSE, lambda c: print(
                             f'Connection closed with code {c}.'))

# Listen for any transcripts received from Deepgram and write them to the console
deepgramLive.registerHandler(deepgramLive.event.TRANSCRIPT_RECEIVED, print)

# Listen for the connection to open and send streaming audio from the URL to Deepgram
# IMPORTANT: This is a blocking call with no way to exit except through a Cntl-C,
# IMPORTANT: disconnecting your internet, or killing the streaming (assuming you control that)
async with aiohttp.ClientSession() as session:
  async with session.get(URL) as audio:
  while True:
    data = await audio.content.readany()
    deepgramLive.send(data)

# If no data is being sent from the live stream, then break out of the loop.
if not data:
	break

# 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
await deepgramLive.finish()
try:
    deepgram: DeepgramClient = DeepgramClient()

    dg_connection = deepgram.listen.websocket.v("1")
  
		# define callbacks for transcription messages
    def on_message(self, result, **kwargs):
        sentence = result.channel.alternatives[0].transcript
        if len(sentence) == 0:
            return
        print(f"speaker: {sentence}")

    dg_connection.on(LiveTranscriptionEvents.Transcript, on_message)

    # connect to websocket
    options = LiveOptions(model="nova-2", interim_results=False, language="en-US")
    dg_connection.start(options)

    lock_exit = threading.Lock()
    exit = False

    # define a worker thread
    def myThread():
      with httpx.stream("GET", URL) as r:
        for data in r.iter_bytes():
          lock_exit.acquire()
          if exit:
            	break
          lock_exit.release()

          dg_connection.send(data)

    # start the worker thread
    myHttp = threading.Thread(target=myThread)
    myHttp.start()

    # signal finished
    input("Press Enter to stop recording...\n\n")
    lock_exit.acquire()
    exit = True
    lock_exit.release()

    # Wait for the HTTP thread to close and join
    myHttp.join()

    # Indicate that we've finished
    dg_connection.finish()

except Exception as e:
    print(f"Could not open socket: {e}")
    return

Management API

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

get all projects for a user

result = await deepgram.projects.list()
result = deepgram.manage.v("1").get_projects()

See our API reference for more info.

get a project

result = await deepgram.projects.get(PROJECT_ID)
result = deepgram.manage.v("1").get_project(projectId)

See our API reference for more info.

update a project

result = await deepgram.projects.update(object)
result = deepgram.manage.v("1").update_project(projectId, name="My TEST RENAME Example")

See our API reference for more info.

delete a project

result = await deepgram.projects.delete(PROJECT_ID)
result = deepgram.manage.v("1").delete_project(projectId)

See our API reference for more info.

get all project key details

result = await deepgram.keys.list(PROJECT_ID)
result = deepgram.manage.v("1").get_keys(projectId)

See our API reference for more info.

get a project key

result = await deepgram.keys.get(PROJECT_ID, KEY_ID)
result = deepgram.manage.v("1").get_key(projectId, myKeyId)

See our API reference for more info.

create a project key

result = await deepgram.keys.create(PROJECT_ID, COMMENT_FOR_KEY, SCOPES)
options = KeyOptions(
  comment="MyTestKey",
  scopes=["member"],
)

result = deepgram.manage.v("1").create_key(projectId, options)

See our API reference for more info.

delete a project key

result = await deepgram.keys.delete(PROJECT_ID, KEY_ID)
result = deepgram.manage.v("1").delete_key(projectId, keyId)

See our API reference for more info.

get all project members

result = await deepgram.members.list_members(PROJECT_ID);
result = deepgram.manage.v("1").get_members(projectId)

See our API reference for more info.

remove a project member

result = await deepgram.members.remove_member(PROJECT_ID, MEMBER_ID)
result = deepgram.manage.v("1").remove_member(projectId, memberId)

See our API reference for more info.

get all scopes for a project member

result = await deepgram.scopes.get_scope(PROJECT_ID, MEMBER_ID)
result = deepgram.manage.v("1").get_member_scopes(projectId, memberId)

See our API reference for more info.

update a scope for a project member

result = await deepgram.scopes.update_scope(PROJECT_ID, MEMBER_ID, 'member')
options = ScopeOptions
	scope="admin"
)
result = deepgram.manage.v("1").update_member_scope(projectId, memberId, options)

See our API reference for more info.

get all project invites

result = await deepgram.invitations.list_invitations(PROJECT_ID);
result = deepgram.manage.v("1").get_invites(projectId)

See our API reference for more info.

send a project invite

result = await deepgram.invitations.send_invitation(PROJECT_ID, {
  email: '[email protected]',
  scope: 'member',
})
options = InviteOptions(
  email="[email protected]",
  scope="member"
)

result = deepgram.manage.v("1").send_invite_options(projectId, options)

See our API reference for more info.

delete a project invite

result = await deepgram.invitations.remove_invitation(
  PROJECT_ID,
  '[email protected]'
)
result = deepgram.manage.v("1").delete_invite(projectId, "[email protected]")

See our API reference for more info.

leave a project

result = await deepgram.invitation.leave_project(PROJECT_ID);
result = deepgram.manage.v("1").leave_project(projectId)

See our API reference for more info.

get all usage requests for a project

result = await deepgram.usage.list_requests(PROJECT_ID, {
  'limit': 10,
  # other options are available
});
result = deepgram.manage.v("1").get_usage_requests(projectId, options)

See our API reference for more info.

get a usage request for a project

result = await deepgram.usage.get_request(PROJECT_ID, REQUEST_ID);
result = deepgram.manage.v("1").get_usage_request(projectId, requestId)

See our API reference for more info.

get the project usage summary

result = await deepgram.usage.get_usage(PROJECT_ID, {
  'start': '2020-01-01T00:00:00+00:00',
  # other options are available
});
result = deepgram.manage.v("1").get_usage_summary(projectId, options)

See our API reference for more info.

get project usage fields

result = await deepgram.usage.get_fields(PROJECT_ID, {
  'start': '2020-01-01T00:00:00+00:00',
  # other options are available
});
result = deepgram.manage.v("1").get_usage_fields(projectId, options)

See our API reference for more info.

get all project balances

result = await deepgram.billing.list_balance(PROJECT_ID);
result = deepgram.manage.v("1").get_balances(projectId)

See our API reference for more info.

get a project balance

result = await deepgram.billing.get_balance(PROJECT_ID, BALANCE_ID);
result = deepgram.manage.v("1").get_balance(projectId, balanceId)

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.