By default, Deepgram’s SDKs hit the hosted endpointapi.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 ashttp://localhost:8080 (pre-recorded) orws://localhost:8080 (streaming).

If running your requests on other servers, you may be using a static IP, such ashttp://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 usehttp rather thanhttps, andws rather thanwss.

Python SDK

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

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 oflocalhost if needed.

Note that theapi_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.

1
# For help migrating to the new Python SDK, check out our migration guide:
2
# https://github.com/deepgram/deepgram-python-sdk/blob/main/docs/Migrating-v3-to-v5.md
3
4
from deepgram import DeepgramClient
5
from deepgram.environment import DeepgramClientEnvironment
6
7
# Create a custom environment for your self-hosted deployment
8
self_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
    preview="ws://localhost:8080"           # WebSocket endpoint for preview
13
)
14
15
# Initialize the client with your custom environment
16
deepgram = DeepgramClient(
17
    api_key="a",  # placeholder for self-hosted
18
    environment=self_hosted_env
19
)
20
21
response = 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
)
26
print(response)
27
28
# Alternative: Use environment variables for URLs
29
import os
30
31
self_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
    preview=os.getenv("DEEPGRAM_PREVIEW_URL", "ws://localhost:8080")
36
)

.NET SDK

The .NET SDK providesDeepgramHttpClientOptions(pre-recorded) andDeepgramWsClientOptions (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.

1
var apiKey = "<your API key>";
2
var options = new DeepgramWsClientOptions(){
3
  BaseAddress = "ws://localhost:8080/v1"
4
};
5
var 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.

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:

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

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

Go SDK