sdk

README

Deepgram Go SDK

Community Go SDK for Deepgram. Start building with our powerful transcription & speech understanding API.

This SDK only supports hosted usage of api.deepgram.com.

• Deepgram Go SDK
• Getting an API Key
• Documentation
• Installation
• Requirements
• Configuration
• Testing
  • Using Example Projects to test new features
• Transcription
  • Remote Files
    • UrlSource
  • Local files
    • ReadStreamSource
    • PrerecordedTranscriptionOptions
• Generating Captions
  • Live Audio
    • LiveTranscriptionOptions
• Projects
  • Get Projects
  • Get Project
  • Update Project
  • Delete Project
• Keys
  • List Keys
  • Get Key
  • Create Key
  • Delete Key
• Members
  • Get Members
  • Remove Member
• Scopes
  • Get Member Scopes
  • Update Scope
• Invitations
  • List Invites
  • Send Invite
  • Delete Invite
  • Leave Project
• Usage
  • Get All Requests
    • UsageRequestListOptions
  • Get Request
  • Summarize Usage
    • UsageOptions
  • Get Fields
    • GetUsageFieldsOptions
  • Development and Contributing
  • Getting Help

Getting an API Key

🔑 To access the Deepgram API you will need a free Deepgram API Key.

Documentation

You can learn more about the full Deepgram API at https://developers.deepgram.com.

Installation

go get github.com/deepgram/deepgram-go-sdk

Requirements

Go (version ^1.18)

Configuration

dg := deepgram.NewClient(DEEPGRAM_API_KEY)

Testing

Using Example Projects to test new features

Contributors to the SDK can test their changes locally by running the projects in the examples folder. This can be done when making changes without adding a unit test, but of course it is recommended that you add unit tests for any feature additions made to the SDK.

Go to the folder examples and look for these two projects, which can be used to test out features in the Deepgram Go SDK:

• prerecorded
• streaming

These are standalone projects, so you will need to follow the instructions in the README.md files for each project to get it running.

Transcription

Remote Files

dg := prerecorded.NewClient("DEEPGRAM_API_KEY")
prClient := api.New(dg)

res, err := prClient.PreRecordedFromURL(deepgram.UrlSource{Url: "https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav"},
deepgram.PreRecordedTranscriptionOptions{Punctuate: true, Utterances: true})

See our Pre-Recorded Quickstart for more info.

UrlSource

Property	Value	Description
Url	string	Url of the file to transcribe

Local files

dg := prerecorded.NewClient("DEEPGRAM_API_KEY")
prClient := api.New(dg)

file, err := os.Open("PATH_TO_LOCAL_FILE")

if err != nil {
  log.Printf("error opening file %s\n", file.Name())
  }

source := api.ReadStreamSource{Stream: file, Mimetype: "MIMETYPE_OF_YOUR_FILE"}
res, err := prClient.PreRecordedFromStream(source, deepgram.PreRecordedTranscriptionOptions{Punctuate: true})
if err != nil {
  log.Printf("ERROR", err)
  return
  }

See our Pre-Recorded Quickstart for more info.

ReadStreamSource

Property	Value Type	reason for
Stream	io.Reader	stream to transcribe
MimeType	string	MIMETYPE of stream

PrerecordedTranscriptionOptions

Property	Value Type	Example
Model	string	Model: "phonecall"
Tier	string	Tier: "nova"
Version	string	Version: "latest"
Language	string	Language: "es"
DetectLanguage	bool	DetectLanguage: true
Punctuate	bool	Punctuate: true
Profanity_filter	bool	Profanity_filter: true
Redact	bool	Redact: true
Diarize	bool	Diarize: true
SmartFormat	bool	SmartFormat: true
Multichannel	bool	Multichannel: true
Alternatives	int	Alternatives: 2
Numerals	bool	Numerals: true
Search	[]string	Search: []string{"apple"}
Replace	[]string	Replace:[]string{"apple:orange"}
Callback	string	Callback: "https://example.com"
Keywords	[]string	Keywords: []string{"Hannah"}
Paragraphs	bool	Paragraphs: true
Summarize	bool	Summarize: true
DetectTopics	bool	DetectTopics: true
Utterances	bool	Utterances: true
Utt_split	int	Utt_split: 9

Generating Captions

// The request can be from a local file stream or a URL
// Turn on utterances with {Utterances: true} for captions to work
res, err := prClient.PreRecordedFromStream(source, deepgram.PreRecordedTranscriptionOptions{Punctuate: true, Utterances:true})

// Convert the results to WebVTT format
vtt, err := res.ToWebVTT()

// Convert the results to SRT format
stt, err := res.ToSRT()

Live Audio

options := deepgram.LiveTranscriptionOptions{
		Language:  "en-US",
		Punctuate: true,
	}
dg, _, err := live.New(options, "DEEPGRAM_API_KEY")

LiveTranscriptionOptions

See API Reference

Projects

projectId and memberId are of typestring

Get Projects

Returns all projects accessible by the API key.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)
res, err := mgClient.ListProjects()

See our API reference for more info.

Get Project

Retrieves a specific project based on the provided projectId.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)
res, err := mgClient.GetProject(projectId)

See our API reference for more info.

Update Project

Update a project.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
options := deepgram.ProjectUpdateOptions{
	Name: "NAME_OF_PROJECT",
	Company:"COMPANY",
}

res, err := mgClient.UpdateProject(projectID, options)

Project Type

Property Name	Type	Description
ProjectId	string	Unique identifier of the Deepgram project
Name	string	Name of the project
Company	string	Name of the company associated with the Deepgram project

See our API reference for more info.

Delete Project

Delete a project.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"

res, err := mgClient.DeleteProject(projectID)

See our API reference for more info.

Keys

projectId,keyId and comment are of typestring

List Keys

Retrieves all keys associated with the provided project_id.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"

res, err := mgClient.ListKeys(projectID)

See our API reference for more info.

Get Key

Retrieves a specific key associated with the provided project_id.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
keyID := "YOUR_KEY_ID"

res, err := mgClient.GetKey(projectID, keyID)

See our API reference for more info.

Create Key

Creates an API key with the provided scopes.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
comment := "A comment"
scopes := []string{"admin", "member"}
options := deepgram.CreateKeyOptions{
    ExpirationDate: time.Now().AddDate(1, 0, 0),
		TimeToLive:     3600,
		Tags:           []string{"tag1", "tag2"},
}

res, err := mgClient.CreateKey(projectID, comment, scopes, options)

See our API reference for more info.

Delete Key

Deletes a specific key associated with the provided project_id.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
keyID := "YOUR_KEY_ID"

res, err := mgClient.DeleteKey(projectID, keyID)

See our API reference for more info.

Members

projectId and memberId are of typestring

Get Members

Retrieves account objects for all of the accounts in the specified project_id.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"

res, err := mgClient.ListMembers(projectID)

See our API reference for more info.

Remove Member

Removes member account for specified member_id.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
memberID := "YOUR_MEMBER_ID"

res, err := mgClient.RemoveMember(projectID, memberID)

See our API reference for more info.

Scopes

projectId and memberId are of typestring

Get Member Scopes

Retrieves scopes of the specified member in the specified project.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
memberID := "YOUR_MEMBER_ID"

res, err := mgClient.GetMemberScopes(projectID, memberID)

See our API reference for more info.

Update Scope

Updates the scope for the specified member in the specified project.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
memberID := "THEIR_MEMBER_ID"
scope := "SCOPE_TO_ASSIGN"

res, err := mgClient.UpdateMemberScopes(projectID, memberID, scope)

See our API reference for more info.

Invitations

List Invites

Retrieves all invitations associated with the provided project_id.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"

res, err := mgClient.ListInvitations(projectID)

See our API reference for more info.

Send Invite

Sends an invitation to the provided email address.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
invitationOptions := deepgram.InvitationOptions{
    Email: "",
		Scope: "",
}

res, err := mgClient.SendInvitation(projectID, invitationOptions)

See our API reference for more info.

Delete Invite

Removes the specified invitation from the project.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
email := ""

res, err := mgClient.DeleteInvitation(projectID, email)

See our API reference for more info.

Leave Project

Removes the authenticated user from the project.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"

res, err := mgClient.LeaveProject(projectID)

See our API reference for more info.

Usage

projectId and requestId typestring

Get All Requests

Retrieves all requests associated with the provided projectId based on the provided options.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
options := deepgram.UsageRequestListOptions{
    Start: "2009-11-10",
		End: "2029-11-10",
		Page: 0,
		Limit:0,
		Status: "failed",
}

res, err := mgClient.ListRequests(projectID, options)

UsageRequestListOptions

Property	Type	Description
Start	string	Start date of the requested date range, YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or YYYY-MM-DDTHH:MM:SS+HH:MM
End	string	End date of the requested date range, YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or YYYY-MM-DDTHH:MM:SS+HH:MM
Page	int	Pages to include
Limit	int	number of results per page
Status	string	Status of requests to return

See our API reference for more info.

Get Request

Retrieves a specific request associated with the provided projectId.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
requestID := "REQUEST_ID"
res, err := mgClient.GetRequest(projectID, requestID)

See our API reference for more info.

Summarize Usage

Retrieves usage associated with the provided project_id based on the provided options.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
options := deepgram.UsageOptions{
	  Start: "2009-11-10",
		End: "2029-11-10",
}

res, err := mgClient.GetUsage(projectID, options)

UsageOptions

Property	Value	Description
Start	string	Start date of the requested date range, YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or YYYY-MM-DDTHH:MM:SS+HH:MM
End	string	End date of the requested date range, YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or YYYY-MM-DDTHH:MM:SS+HH:MM

See our API reference for more info.

Get Fields

Lists the features, models, tags, languages, and processing method used for requests in the specified project.

dg := manage.New("YOUR_API_KEY")
mgClient := api.New(dg)

projectID := "YOUR_PROJECT_ID"
options := deepgram.UsageRequestListOptions{
    Start: "2009-11-10",
		End: "2029-11-10",
}
res, err := mgClient.GetFields(projectID, options)

GetUsageFieldsOptions

Property	Value	Description
StartDateTime	DateTime	Start date of the requested date range, YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or YYYY-MM-DDTHH:MM:SS+HH:MM
EndDateTime	DateTime	End date of the requested date range, YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or YYYY-MM-DDTHH:MM:SS+HH:MM

See our API reference for more info.

Development and Contributing

Interested in contributing? We ❤️ pull requests!

To make sure our community is safe for all, be sure to review and agree to our Code of Conduct. Then see the Contribution guidelines for more information.

Getting Help

We love to hear from you so if you have questions, comments or find a bug in the project, let us know! You can either:

• Open an issue in this repository
• Join the Deepgram Github Discussions Community
• Join the Deepgram Discord Community