Tools

Using SDKs with Self-Hosted

Learn about how to use Deepgram SDKs with Deepgram self-hosted deployments.

By default, Deepgram’s SDKs hit the hosted endpoint api.deepgram.com. To use one of our SDKs with your self-hosted deployment, you will need to specify your own self-hosted endpoint instead.

Determining your host URL

If running your requests locally on your server, your URL may be as simple as http://localhost:8080 (pre-recorded) or ws://localhost:8080 (streaming).

If running your requests on other servers, you may be using a static IP, such as http://172.23.0.1:8080.

If you use a multi-server or auto-scaled environment, you may configure a URL that is served by a load balancer that routes your requests across several instances.

Note that for a host that does not have TLS enabled, you will use http rather than https, and ws rather than wss.

Python SDK

To configure the Python SDK for self-hosted deployments, create a custom DeepgramClientEnvironment with your self-hosted URLs and pass it to the DeepgramClient. This approach configures all endpoint types (REST APIs, WebSocket streaming, Agent WebSocket, and Agent REST).

The agent_rest field shown below requires Python SDK v7.2.0 or newer. On v7.0.0–v7.1.1, DeepgramClientEnvironment accepted only base, production, and agent — omit agent_rest on those versions.

Below is an example of how to make your first API request to your self-hosted deployment using the Python SDK. Substitute your own host address in place of localhost if needed.

Note that the api_key field cannot be a blank string as it is a required parameter for the Python SDK, but it does not need to be a valid Deepgram API key, as authorization with Deepgram for self-hosted deployments is configured through the container, not at the individual request level.

Python
1# For more Python SDK migration guides, visit:
2# https://github.com/deepgram/deepgram-python-sdk/tree/main/docs
3
4from deepgram import DeepgramClient
5from deepgram.environment import DeepgramClientEnvironment
6
7# Create a custom environment for your self-hosted deployment
8self_hosted_env = DeepgramClientEnvironment(
9    base="http://localhost:8080",           # HTTP endpoint for REST APIs
10    production="ws://localhost:8080",       # WebSocket endpoint for streaming
11    agent="ws://localhost:8080",            # WebSocket endpoint for agent
12    agent_rest="http://localhost:8080"      # HTTP endpoint for agent REST
13)
14
15# Initialize the client with your custom environment
16deepgram = DeepgramClient(
17    api_key="a",  # placeholder for self-hosted
18    environment=self_hosted_env
19)
20
21response = deepgram.listen.v1.media.transcribe_url(
22    url="https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav",
23    model="nova-3",
24    smart_format=True
25)
26print(response)
27
28# Alternative: Use environment variables for URLs
29import os
30
31self_hosted_env = DeepgramClientEnvironment(
32    base=os.getenv("DEEPGRAM_BASE_URL", "http://localhost:8080"),
33    production=os.getenv("DEEPGRAM_WS_URL", "ws://localhost:8080"),
34    agent=os.getenv("DEEPGRAM_AGENT_URL", "ws://localhost:8080"),
35    agent_rest=os.getenv("DEEPGRAM_AGENT_REST_URL", "http://localhost:8080")
36)

.NET SDK

The .NET SDK provides DeepgramHttpClientOptions (pre-recorded) and DeepgramWsClientOptions (streaming) classes, through which you can pass your host address. Below is a streaming example. Note that you should provide the /v1 suffix to the base address.

C#
1var apiKey = "<your API key>";
2var options = new DeepgramWsClientOptions(){
3  BaseAddress = "ws://localhost:8080/v1"
4};
5var liveClient = new LiveClient(apiKey, options);

If you encounter the following error message, note that you are receiving a 400 (bad request) when a 101 (successful stream) is expected.

Text
Error: "The server returned status code \u0027400\u0027 when status code \u0027101\u0027 was expected."

Ensure that your request parameters are specifying a model that you have available on your self-hosted instance. For example, when you intend to serve requests through a Nova-3 model, specify the following params:

C#
1var liveSchema = new LiveSchema()
2{
3  Model = "nova-3",
4  SmartFormat = true,
5};

If that model is not present in your models/ directory, the above error will occur.

Go SDK

To modify the Host option in type-client.go:

Go
1// ClientOptions defines any options for the client
2type ClientOptions struct {
3	...
4	Host       string // override for the host endpoint
5	...
6	SelfHosted bool   // set to true if using self-hosted
7  ...
8}

You can create an object of type ClientOptions and then set the Host value.

Go
1	// create a Deepgram client
2	c := client.New("", interfaces.ClientOptions{
3		Host: "http://localhost:8080",
4    SelfHosted: true,
5	})

JavaScript SDK

To modify the URL, you can pass the url property within the global object to a new client.

JavaScript
1const { DeepgramClient } = require("@deepgram/sdk");
2
3const client = new DeepgramClient({
4  apiKey: "DEEPGRAM_API_KEY",
5  baseUrl: "http://localhost:8080", // Set the desired URL here
6});

Java SDK

Use Environment.custom() to point all API traffic (REST and WebSocket) to your self-hosted endpoint.

Java
1import com.deepgram.DeepgramClient;
2import com.deepgram.core.Environment;
3
4Environment selfHostedEnv = Environment.custom()
5    .base("http://localhost:8080")    // REST endpoint
6    .agent("ws://localhost:8080")     // Agent WebSocket endpoint
7    .production("ws://localhost:8080") // STT/TTS WebSocket endpoint
8    .build();
9
10// The api_key value is required by the SDK but is not validated
11// by self-hosted deployments — use any non-empty string.
12DeepgramClient client = DeepgramClient.builder()
13    .apiKey("self-hosted")
14    .environment(selfHostedEnv)
15    .build();

What’s Next