Deepgram Go SDK (spec-mock)

Go SDK for the Deepgram speech-to-text platform: prerecorded transcription, live streaming transcription, WebSocket, HTTP, and SageMaker transports, smart formatting, diarization, language detection, entity detection, intents, sentiment, summarization, topic detection. Runs on Go 1.24+. This is the prototype implementation generated by the Deepgram Smithy spec pipeline; see REGEN.md for the pipeline and maintainer guide.

Install

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

Quick start: prerecorded transcription

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	prerecorded "github.com/deepgram/spec-mock-go-sdk/pkg/client/listen/v1/prerecorded"
)

func main() {
	client := prerecorded.New(prerecorded.WithAPIKey(os.Getenv("DEEPGRAM_API_KEY")))
	resp, err := client.FromURL(context.Background(),
		"https://dpgr.am/spacewalk.wav",
		&prerecorded.PreRecordedTranscriptionOptions{
			Model:       "nova-3",
			Punctuate:   true,
			SmartFormat: true,
		})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp.RequestID)
}

Runnable examples for every public method:

• Client.FromURL — transcribe a remote URL.
• Client.FromFile — transcribe a local file.
• Client.FromStream — transcribe an io.Reader.
• PreRecordedTranscriptionOptions — typed options plus additional query parameters.
• WithSageMakerTransport — route prerecorded transcription through SageMaker.

Full godoc: pkg.go.dev/.../listen/v1/prerecorded

Quick start: live streaming transcription

package main

import (
	"context"
	"log"
	"os"

	live "github.com/deepgram/spec-mock-go-sdk/pkg/client/listen/v1/live"
)

func main() {
	client := live.New(live.WithAPIKey(os.Getenv("DEEPGRAM_API_KEY")))
	stream, err := client.Connect(context.Background(),
		&live.LiveTranscriptionOptions{
			Model:          "nova-3",
			Encoding:       "linear16",
			SampleRate:     16000,
			InterimResults: true,
			SmartFormat:    true,
		})
	if err != nil {
		log.Fatal(err)
	}
	defer stream.Close()

	go func() {
		audio := readAudioBytes()
		_ = stream.SendAudio(audio)
		_ = stream.CloseStream()
	}()

	for {
		event, err := stream.Recv()
		if err != nil {
			return
		}
		switch event.(type) {
		case *live.ResultsEvent:
		case *live.MetadataEvent:
			return
		case *live.ErrorEvent:
			return
		}
	}
}

func readAudioBytes() []byte { return nil }

Runnable examples for every public method:

• Client.Connect — open a streaming session.
• Stream.SendAudio — send raw audio bytes.
• Stream.Recv — receive the next event.
• Stream.Finalize — force a final result.
• Stream.KeepAlive — keep the session alive.
• Stream.CloseStream — graceful end-of-audio.
• LiveTranscriptionOptions — typed live options.
• WithSageMakerBidiTransport — route live streaming through SageMaker HTTP/2.

Full godoc: pkg.go.dev/.../listen/v1/live

Auth

Both clients pick up credentials from the environment by default:

export DEEPGRAM_API_KEY="your_api_key"
# or, for Bearer-token auth:
export DEEPGRAM_ACCESS_TOKEN="your_access_token"

prerecorded.New() and live.New() read these automatically. Pass prerecorded.WithAPIKey, prerecorded.WithAccessToken, live.WithAPIKey, or live.WithAccessToken to provide credentials explicitly. When both are set, the access token wins.

For custom configurations:

client := prerecorded.New(
	prerecorded.WithAPIKey("dg-key"),
	prerecorded.WithBaseURL("https://api.example.com"),
	prerecorded.WithHTTPClient(myHTTPClient),
)

Test the examples

Every Example_* function in pkg/.../example_test.go is runnable via go test:

go test ./pkg/...

Examples without an // Output: assertion are compile-checked. Examples with one are also output-asserted. If a method signature changes and an example stops compiling, the test suite fails.

Standalone programs live in examples/:

go build ./examples/...

What's in this SDK

Surface	Package
Prerecorded transcription (POST /v1/listen)	pkg/client/listen/v1/prerecorded
Live streaming transcription (WS /v1/listen)	pkg/client/listen/v1/live
SageMaker request/response and bidirectional streaming transports	api/transport/sagemaker

Other products (text-to-speech, voice agent, etc.) land per-product as the SDK grows.