### Connect to Listen V2 WebSocket with v0.2.x

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/docs/Migrating-v0.2-to-v0.3.md

Example of connecting to the Listen V2 WebSocket API using a string for the model in v0.2.x.

```java
wsClient.connect(
    V2ConnectOptions.builder()
        .model("flux-general-en")
        .build());
```

--------------------------------

### Connect to Listen V2 WebSocket with v0.3.0

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/docs/Migrating-v0.2-to-v0.3.md

Example of connecting to the Listen V2 WebSocket API using the typed ListenV2Model enum in v0.3.0.

```java
import com.deepgram.types.ListenV2Model;

wsClient.connect(
    V2ConnectOptions.builder()
        .model(ListenV2Model.FLUX_GENERAL_EN)
        .build());
```

--------------------------------

### Deepgram Agent API - List Models and Real-time Agent

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Examples for interacting with the Agent API, including listing available agent models and initiating real-time agent communication via WebSocket.

```java
client.agent().v1().settings().think().models().list() // List available agent models
```

```java
client.agent().v1().v1WebSocket()                      // Real-time agent WebSocket
```

--------------------------------

### Async Transcription with Deepgram Java SDK

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Use the asynchronous client for non-blocking operations with CompletableFuture. This example shows how to transcribe audio from a URL and handle the response asynchronously.

```java
import com.deepgram.AsyncDeepgramClient;
import com.deepgram.resources.listen.v1.media.requests.ListenV1RequestUrl;
import com.deepgram.resources.listen.v1.media.types.MediaTranscribeResponse;
import java.util.concurrent.CompletableFuture;

AsyncDeepgramClient asyncClient = AsyncDeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .build();

// Async transcription
CompletableFuture<MediaTranscribeResponse> future = asyncClient.listen().v1().media()
    .transcribeUrl(ListenV1RequestUrl.builder()
        .url("https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav")
        .build());

// Non-blocking callback
future.thenAccept(result -> {
    System.out.println("Transcription complete!");
    result.visit(new MediaTranscribeResponse.Visitor<Void>() {
        @Override
        public Void visit(com.deepgram.types.ListenV1Response response) {
            response.getResults().getChannels().get(0)
                .getAlternatives().ifPresent(alts -> {
                    alts.get(0).getTranscript().ifPresent(System.out::println);
                });
            return null;
        }

        @Override
        public Void visit(com.deepgram.types.ListenV1AcceptedResponse accepted) {
            return null;
        }
    });
}).exceptionally(ex -> {
    System.err.println("Error: " + ex.getMessage());
    return null;
});

// Or block and wait for result
// MediaTranscribeResponse result = future.get();
```

--------------------------------

### Consolidate Agent Think/Speak Schemas in v0.3.0

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/docs/Migrating-v0.2-to-v0.3.md

In v0.3.0, agent think/speak schemas are consolidated into shared top-level types. This example shows how to use the new `ThinkSettingsV1` with an OpenAI provider.

```java
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentSpeak;
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentSpeakEndpoint;
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentThink;
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentThinkOneItem;

// Old agent-local generated types
AgentV1SettingsAgentSpeak speak = AgentV1SettingsAgentSpeak.of(/* agent-local speak type */);
AgentV1SettingsAgentThink think = AgentV1SettingsAgentThink.of(
    java.util.List.of(/* AgentV1SettingsAgentThinkOneItem */));
```

```java
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentSpeak;
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentThink;
import com.deepgram.types.OpenAiThinkProvider;
import com.deepgram.types.OpenAiThinkProviderModel;
import com.deepgram.types.ThinkSettingsV1;
import com.deepgram.types.ThinkSettingsV1Provider;

OpenAiThinkProvider provider = OpenAiThinkProvider.builder()
    .model(OpenAiThinkProviderModel.GPT4O_MINI)
    .build();

AgentV1SettingsAgentThink think = AgentV1SettingsAgentThink.of(
    ThinkSettingsV1.builder()
        .provider(ThinkSettingsV1Provider.openAi(provider))
        .prompt("You are a helpful assistant.")
        .build());
```

--------------------------------

### Deepgram Speak API - Generate Speech and Stream

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Examples for using the Speak API to generate speech from text and for real-time Text-to-Speech streaming via WebSocket.

```java
client.speak().v1().audio().generate(request)          // Generate speech from text
```

```java
client.speak().v1().v1WebSocket()                      // Real-time streaming TTS
```

--------------------------------

### Stream Text-to-Speech with WebSocket

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Use the Speak WebSocket API for real-time audio generation. Requires API key and output file setup. Handles connection, audio data, errors, and disconnection events.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.resources.speak.v1.types.SpeakV1Close;
import com.deepgram.resources.speak.v1.types.SpeakV1CloseType;
import com.deepgram.resources.speak.v1.types.SpeakV1Flush;
import com.deepgram.resources.speak.v1.types.SpeakV1FlushType;
import com.deepgram.resources.speak.v1.types.SpeakV1Text;
import com.deepgram.resources.speak.v1.websocket.V1WebSocketClient;
import java.io.FileOutputStream;
import java.io.OutputStream;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;

DeepgramClient client = DeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .build();

V1WebSocketClient wsClient = client.speak().v1().v1WebSocket();
CountDownLatch closeLatch = new CountDownLatch(1);
AtomicInteger audioChunks = new AtomicInteger(0);
OutputStream audioOutput = new FileOutputStream("output_streaming.wav");

// Register event handlers
wsClient.onConnected(() -> {
    System.out.println("Connected to Deepgram TTS WebSocket");
});

wsClient.onSpeakV1Audio(audioData -> {
    byte[] bytes = audioData.toByteArray();
    audioOutput.write(bytes);
    int count = audioChunks.incrementAndGet();
    System.out.printf("Received audio chunk #%d (%d bytes)%n", count, bytes.length);
});

wsClient.onFlushed(flushed -> {
    System.out.println("Audio flushed - all queued text converted");
});

wsClient.onError(error -> {
    System.err.println("Error: " + error.getMessage());
});

wsClient.onDisconnected(reason -> {
    audioOutput.close();
    System.out.println("Disconnected: " + reason.getCode());
    closeLatch.countDown();
});

// Connect
CompletableFuture<Void> connectFuture = wsClient.connect();
connectFuture.get(10, TimeUnit.SECONDS);

// Send text chunks for TTS conversion
String[] sentences = {
    "Hello, this is a streaming text-to-speech demo.",
    "Each sentence is sent as a separate message.",
    "The audio is generated and streamed back in real time."
};

for (String sentence : sentences) {
    System.out.println("Sending: \"" + sentence + "\"");
    wsClient.sendText(SpeakV1Text.builder().text(sentence).build());
}

// Flush to ensure all text is processed
wsClient.sendFlush(SpeakV1Flush.builder()
    .type(SpeakV1FlushType.FLUSH)
    .build());

Thread.sleep(5000);  // Wait for audio to arrive

// Close the connection
wsClient.sendClose(SpeakV1Close.builder()
    .type(SpeakV1CloseType.CLOSE)
    .build());

closeLatch.await(10, TimeUnit.SECONDS);
System.out.printf("Total audio chunks: %d%n", audioChunks.get());
```

--------------------------------

### Async Client Usage

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Utilize the asynchronous Deepgram client for non-blocking operations. This example demonstrates performing an asynchronous transcription from a URL.

```APIDOC
## Async Client

The SDK provides a fully asynchronous client for non-blocking operations:

```java
import com.deepgram.AsyncDeepgramClient;
import com.deepgram.resources.listen.v1.media.requests.ListenV1RequestUrl;
import com.deepgram.resources.listen.v1.media.types.MediaTranscribeResponse;
import java.util.concurrent.CompletableFuture;

AsyncDeepgramClient asyncClient = AsyncDeepgramClient.builder().build();

// Async transcription
CompletableFuture<MediaTranscribeResponse> future = asyncClient.listen().v1().media()
    .transcribeUrl(ListenV1RequestUrl.builder()
        .url("https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav")
        .build());

future.thenAccept(result -> {
    System.out.println("Transcription complete!");
});
```
```

--------------------------------

### Deepgram Read API - Analyze Text

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Example of using the Read API to analyze text content.

```java
client.read().v1().text().analyze(request)             // Analyze text content
```

--------------------------------

### Deepgram Listen API - Transcribe Audio

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Examples of using the Listen API to transcribe audio from a URL or file bytes, and initiate real-time streaming transcription via WebSocket.

```java
client.listen().v1().media().transcribeUrl(request)    // Transcribe audio from URL
```

```java
client.listen().v1().media().transcribeFile(body)      // Transcribe audio from file bytes
```

```java
client.listen().v1().v1WebSocket()                     // Real-time streaming transcription
```

--------------------------------

### Manage Self-Hosted Distribution Credentials

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Manage distribution credentials for on-premises Deepgram deployments. This includes listing, creating, getting, and deleting credentials.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.types.ListProjectDistributionCredentialsV1Response;
import com.deepgram.types.ListProjectsV1Response;
import java.util.Collections;

DeepgramClient client = DeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .build();

// Get project ID
ListProjectsV1Response projectsResponse = client.manage().v1().projects().list();
String projectId = projectsResponse.getProjects()
    .orElse(Collections.emptyList())
    .get(0)
    .getProjectId()
    .orElse("");

// List distribution credentials
ListProjectDistributionCredentialsV1Response credentialsResponse =
    client.selfHosted().v1().distributionCredentials().list(projectId);

var credentials = credentialsResponse.getDistributionCredentials()
    .orElse(Collections.emptyList());

System.out.printf("Distribution Credentials (%d):%n", credentials.size());
for (var cred : credentials) {
    System.out.println("  " + cred);
}

// Create credentials
// client.selfHosted().v1().distributionCredentials().create(projectId);

// Get specific credentials
// client.selfHosted().v1().distributionCredentials().get(projectId, credentialId);

// Delete credentials
// client.selfHosted().v1().distributionCredentials().delete(projectId, credentialId);
```

--------------------------------

### Agent WebSocket Connection

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Connect to Deepgram's voice agent for real-time conversational AI. This example shows how to establish a connection, send settings, inject user messages, and handle responses.

```APIDOC
## Agent WebSocket

Connect to Deepgram's voice agent for real-time conversational AI.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.resources.agent.v1.types.AgentV1InjectUserMessage;
import com.deepgram.resources.agent.v1.types.AgentV1Settings;
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgent;
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentThink;
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAudio;
import com.deepgram.resources.agent.v1.websocket.V1WebSocketClient;
import com.deepgram.types.OpenAiThinkProvider;
import com.deepgram.types.OpenAiThinkProviderModel;
import com.deepgram.types.ThinkSettingsV1;
import com.deepgram.types.ThinkSettingsV1Provider;
import java.util.concurrent.TimeUnit;

DeepgramClient client = DeepgramClient.builder().build();

V1WebSocketClient agentWs = client.agent().v1().v1WebSocket();

// Register event handlers
agentWs.onWelcome(welcome -> {
    System.out.println("Agent connected");

    agentWs.sendSettings(AgentV1Settings.builder()
        .audio(AgentV1SettingsAudio.builder().build())
        .agent(AgentV1SettingsAgent.builder()
                .think(AgentV1SettingsAgentThink.of(
                    ThinkSettingsV1.builder()
                        .provider(ThinkSettingsV1Provider.openAi(
                            OpenAiThinkProvider.builder()
                                .model(OpenAiThinkProviderModel.GPT4O_MINI)
                                .build()))
                        .prompt("You are a helpful voice assistant. Keep responses brief.")
                        .build()))
                .greeting("Hello! How can I help you today?")
                .build())
        .build());
});

agentWs.onSettingsApplied(applied -> {
    agentWs.sendInjectUserMessage(AgentV1InjectUserMessage.builder()
        .content("What is the capital of France?")
        .build());
});

agentWs.onConversationText(text -> {
    System.out.printf("[%s] %s%n", text.getRole(), text.getContent());
});

agentWs.onError(error -> {
    System.err.println("Error: " + error.getMessage());
});

// Connect and wait for the agent to respond
agentWs.connect().get(10, TimeUnit.SECONDS);
Thread.sleep(5000);

// Close when done
agentWs.close();
```
```

--------------------------------

### Route WebSocket via AWS SageMaker

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Configure the SDK to route WebSocket connections through AWS SageMaker by providing a SageMakerTransportFactory. This is useful for deploying Deepgram models on your own SageMaker endpoints. The SDK is used normally after setup, with the transport being transparent.

```java
// Add the SageMaker transport dependency
// implementation 'com.deepgram:deepgram-sagemaker:0.1.0'

import com.deepgram.DeepgramClient;
import com.deepgram.sagemaker.SageMakerConfig;
import com.deepgram.sagemaker.SageMakerTransportFactory;
import com.deepgram.resources.listen.v1.websocket.V1ConnectOptions;
import com.deepgram.types.ListenV1Model;

// Create SageMaker transport factory
var factory = new SageMakerTransportFactory(
    SageMakerConfig.builder()
        .endpointName("my-deepgram-endpoint")
        .region("us-west-2")
        .build()
);

// Build client with custom transport
DeepgramClient client = DeepgramClient.builder()
    .apiKey("unused")  // SageMaker uses AWS credentials
    .transportFactory(factory)
    .build();

// Use the SDK exactly as normal - transport is transparent
var ws = client.listen().v1().v1WebSocket();
ws.onResults(results -> {
    System.out.println("Transcript: " +
        results.getChannel().getAlternatives().get(0).getTranscript());
});

ws.connect(V1ConnectOptions.builder()
    .model(ListenV1Model.NOVA3)
    .build());

// ws.sendMedia(audioBytes);
```

--------------------------------

### Use Make for Development Tasks

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Leverage Make commands for common development tasks such as linting, building, testing, and code formatting.

```bash
make check             # lint + build + unit tests
```

```bash
make test-integration  # integration tests only
```

```bash
make test-all          # full test suite
```

```bash
make format            # auto-format code
```

--------------------------------

### Initialize Async Deepgram Client

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Create an instance of the asynchronous Deepgram client for non-blocking operations.

```java
import com.deepgram.AsyncDeepgramClient;

AsyncDeepgramClient asyncClient = AsyncDeepgramClient.builder().build();
```

--------------------------------

### Initialize Deepgram Client with API Key

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Create a Deepgram client using an API key. The SDK can automatically load the API key from the DEEPGRAM_API_KEY environment variable if not explicitly provided. Custom timeouts, retry logic, and headers can also be configured.

```java
import com.deepgram.DeepgramClient;

// Using environment variable (DEEPGRAM_API_KEY)
DeepgramClient client = DeepgramClient.builder().build();
```

```java
// Using API key directly
DeepgramClient client = DeepgramClient.builder()
    .apiKey("YOUR_DEEPGRAM_API_KEY")
    .build();
```

```java
// With custom configuration
DeepgramClient client = DeepgramClient.builder()
    .apiKey("YOUR_DEEPGRAM_API_KEY")
    .timeout(30)  // 30 seconds timeout
    .maxRetries(3)
    .addHeader("X-Custom-Header", "custom-value")
    .build();
```

--------------------------------

### List Projects (Java)

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Retrieves a list of all projects associated with the authenticated API key. It iterates through the projects and prints their names and IDs.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.types.ListProjectsV1Response;
import com.deepgram.types.ListProjectsV1ResponseProjectsItem;
import java.util.Collections;
import java.util.List;

DeepgramClient client = DeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .build();

ListProjectsV1Response response = client.manage().v1().projects().list();

List<ListProjectsV1ResponseProjectsItem> projects = 
    response.getProjects().orElse(Collections.emptyList());

System.out.printf("Found %d project(s):%n", projects.size());
for (ListProjectsV1ResponseProjectsItem project : projects) {
    String id = project.getProjectId().orElse("unknown");
    String name = project.getName().orElse("unnamed");
    System.out.printf("  Project: %s (ID: %s)%n", name, id);
}
```

--------------------------------

### Initialize Deepgram Client with Environment Variable API Key

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Initialize the Deepgram client without explicitly providing an API key, assuming it's set via the DEEPGRAM_API_KEY environment variable.

```java
// API key is loaded automatically from DEEPGRAM_API_KEY
DeepgramClient client = DeepgramClient.builder().build();
```

--------------------------------

### Transcribe with Paragraphs and Utterances in Java

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Enables paragraph and utterance segmentation for caption-friendly output. The visitor implementation iterates through speaker-labeled paragraphs and time-stamped utterances.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.resources.listen.v1.media.requests.ListenV1RequestUrl;
import com.deepgram.resources.listen.v1.media.types.MediaTranscribeResponse;
import com.deepgram.types.ListenV1Response;

DeepgramClient client = DeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .build();

ListenV1RequestUrl request = ListenV1RequestUrl.builder()
    .url("https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav")
    .smartFormat(true)
    .paragraphs(true)
    .utterances(true)
    .diarize(true)
    .build();

MediaTranscribeResponse result = client.listen().v1().media().transcribeUrl(request);

result.visit(new MediaTranscribeResponse.Visitor<Void>() {
    @Override
    public Void visit(ListenV1Response response) {
        var results = response.getResults();

        // Display paragraphs
        var alt = results.getChannels().get(0).getAlternatives().get().get(0);
        alt.getParagraphs().ifPresent(paragraphs -> {
            System.out.println("=== Paragraphs ===");
            paragraphs.getParagraphs().ifPresent(paras -> {
                for (var para : paras) {
                    float speaker = para.getSpeaker().orElse(0f);
                    System.out.printf("Speaker %.0f:%n", speaker);
                    para.getSentences().ifPresent(sentences -> {
                        for (var sentence : sentences) {
                            sentence.getText().ifPresent(text ->
                                System.out.println("  " + text));
                        }
                    });
                }
            });
        });

        // Display utterances with timestamps
        results.getUtterances().ifPresent(utterances -> {
            System.out.println("\n=== Utterances ===");
            for (var utterance : utterances) {
                float speaker = utterance.getSpeaker().orElse(0f);
                float start = utterance.getStart().orElse(0f);
                float end = utterance.getEnd().orElse(0f);
                String transcript = utterance.getTranscript().orElse("");
                System.out.printf("[%.2f - %.2f] Speaker %.0f: %s%n",
                    start, end, speaker, transcript);
            }
        });
        return null;
    }

    @Override
    public Void visit(com.deepgram.types.ListenV1AcceptedResponse accepted) {
        return null;
    }
});
```

--------------------------------

### Listen API - Real-time Streaming

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Initiate a real-time streaming transcription session using the Listen API WebSocket.

```APIDOC
### Real-time Streaming Transcription

Initiate a real-time streaming transcription session using the Listen API WebSocket.

```java
client.listen().v1().v1WebSocket()
```
```

--------------------------------

### Error Handling with Deepgram Java SDK

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Handle different error types including API errors, bad requests, and authentication failures. This example demonstrates try-catch blocks for specific Deepgram exceptions.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.core.DeepgramHttpException;
import com.deepgram.errors.BadRequestError;
import com.deepgram.resources.listen.v1.media.requests.ListenV1RequestUrl;
import com.deepgram.resources.listen.v1.media.types.MediaTranscribeResponse;

DeepgramClient client = DeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .build();

// Handle bad request error
try {
    ListenV1RequestUrl request = ListenV1RequestUrl.builder()
        .url("not-a-valid-url")
        .build();
    client.listen().v1().media().transcribeUrl(request);
} catch (BadRequestError e) {
    System.out.println("Caught BadRequestError (HTTP 400)");
    System.out.println("Status: " + e.statusCode());
    System.out.println("Body: " + e.body());
    System.out.println("Message: " + e.getMessage());
} catch (DeepgramHttpException e) {
    System.out.println("Caught API error");
    System.out.println("Status: " + e.statusCode());
    System.out.println("Body: " + e.body());
} catch (Exception e) {
    System.out.println("Caught exception: " + e.getClass().getSimpleName());
    System.out.println("Message: " + e.getMessage());
}

// Handle authentication error
try {
    DeepgramClient badClient = DeepgramClient.builder()
        .apiKey("invalid-api-key")
        .build();
    badClient.manage().v1().projects().list();
} catch (DeepgramHttpException e) {
    System.out.println("Authentication failed");
    System.out.println("Status: " + e.statusCode());  // 401
}
```

--------------------------------

### Listen API - Transcribe File

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Transcribe audio from a file's byte content using the Listen API.

```APIDOC
### Transcribe Audio from File

Transcribe audio from a file's byte content using the Listen API.

```java
client.listen().v1().media().transcribeFile(body)
```
```

--------------------------------

### Deepgram Client Authentication (Environment Variable)

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Instantiate the DeepgramClient using the DEEPGRAM_API_KEY environment variable for authentication.

```java
import com.deepgram.DeepgramClient;

// Using environment variable (DEEPGRAM_API_KEY)
DeepgramClient envClient = DeepgramClient.builder().build();
```

--------------------------------

### Manage Deepgram Projects

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Use these methods to manage your Deepgram projects, including listing, getting, updating, and deleting projects. Also includes management of API keys, members, usage, and models associated with a project.

```java
client.manage().v1().projects().list()                 // List all projects
```

```java
client.manage().v1().projects().get(projectId)         // Get project details
```

```java
client.manage().v1().projects().update(projectId, req) // Update project
```

```java
client.manage().v1().projects().delete(projectId)      // Delete project
```

```java
client.manage().v1().projects().keys().list(projectId) // List API keys
```

```java
client.manage().v1().projects().keys().create(id, req) // Create new key
```

```java
client.manage().v1().projects().keys().get(id, keyId)  // Get key details
```

```java
client.manage().v1().projects().keys().delete(id, key) // Delete key
```

```java
client.manage().v1().projects().members().list(id)     // List members
```

```java
client.manage().v1().projects().members().delete(p, m) // Remove member
```

```java
client.manage().v1().projects().usage().get(projectId) // Get usage summary
```

```java
client.manage().v1().projects().models().list(id)      // List project models
```

```java
client.manage().v1().models().list()                   // List all models
```

--------------------------------

### Live Transcription (Listen WebSocket)

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Stream audio for real-time speech-to-text using the Listen WebSocket API.

```APIDOC
## Live Transcription (Listen WebSocket)

### Description
Stream audio for real-time speech-to-text.

### Method
WebSocket connection

### Endpoint
(Not explicitly defined, handled by SDK)

### Parameters
#### Connection Options
- **V1ConnectOptions** (object) - Required - Options for the WebSocket connection.
  - **model** (ListenV1Model) - Required - The transcription model to use (e.g., ListenV1Model.NOVA3).

### Event Handlers
- **onResults**: Callback for transcription results.
- **onMetadata**: Callback for metadata events.
- **onError**: Callback for errors.

### Request Example
```java
import com.deepgram.DeepgramClient;
import com.deepgram.resources.listen.v1.types.ListenV1CloseStream;
import com.deepgram.resources.listen.v1.types.ListenV1CloseStreamType;
import com.deepgram.resources.listen.v1.websocket.V1WebSocketClient;
import com.deepgram.resources.listen.v1.websocket.V1ConnectOptions;
import com.deepgram.types.ListenV1Model;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.concurrent.TimeUnit;
import okio.ByteString;

DeepgramClient client = DeepgramClient.builder().build();
byte[] audioBytes = Files.readAllBytes(Path.of("audio.wav"));

V1WebSocketClient ws = client.listen().v1().v1WebSocket();

// Register event handlers
ws.onResults(results -> {
    String transcript = results.getChannel()
        .getAlternatives().get(0)
        .getTranscript();
    System.out.println("Transcript: " + transcript);
});

ws.onMetadata(metadata -> {
    System.out.println("Metadata received");
});

ws.onError(error -> {
    System.err.println("Error: " + error.getMessage());
});

// Connect with options (model is required)
ws.connect(V1ConnectOptions.builder()
    .model(ListenV1Model.NOVA3)
    .build())
    .get(10, TimeUnit.SECONDS);

ws.sendMedia(ByteString.of(audioBytes));
ws.sendCloseStream(ListenV1CloseStream.builder()
    .type(ListenV1CloseStreamType.CLOSE_STREAM)
    .build())
    .get(5, TimeUnit.SECONDS);

// Close when done
ws.close();
```
```

--------------------------------

### Agent API - Real-time Streaming

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Initiate a real-time agent interaction session using the Agent API WebSocket.

```APIDOC
### Real-time Agent WebSocket

Initiate a real-time agent interaction session using the Agent API WebSocket.

```java
client.agent().v1().v1WebSocket()
```
```

--------------------------------

### Speak API - Real-time Streaming

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Initiate a real-time streaming Text-to-Speech session using the Speak API WebSocket.

```APIDOC
### Real-time Streaming TTS

Initiate a real-time streaming Text-to-Speech session using the Speak API WebSocket.

```java
client.speak().v1().v1WebSocket()
```
```

--------------------------------

### Real-Time Live Transcription with Deepgram Java SDK

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Stream audio in real-time for live transcription using the Listen V1 WebSocket API. Requires setting up event handlers for results, metadata, and connection status before connecting. Ensure the DEEPGRAM_API_KEY environment variable is set.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.resources.listen.v1.types.ListenV1CloseStream;
import com.deepgram.resources.listen.v1.types.ListenV1CloseStreamType;
import com.deepgram.resources.listen.v1.websocket.V1ConnectOptions;
import com.deepgram.resources.listen.v1.websocket.V1WebSocketClient;
import com.deepgram.types.ListenV1Model;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;

DeepgramClient client = DeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .build();

V1WebSocketClient wsClient = client.listen().v1().v1WebSocket();
CountDownLatch closeLatch = new CountDownLatch(1);

// Register event handlers before connecting
wsClient.onConnected(() -> {
    System.out.println("Connected to Deepgram");
});

wsClient.onResults(result -> {
    if (result.getChannel() != null &&
        result.getChannel().getAlternatives() != null &&
        !result.getChannel().getAlternatives().isEmpty()) {

        String transcript = result.getChannel().getAlternatives().get(0).getTranscript();
        if (transcript != null && !transcript.isEmpty()) {
            boolean isFinal = result.getIsFinal().orElse(false);
            String label = isFinal ? "[final]  " : "[interim]";
            System.out.printf("%s %s%n", label, transcript);
        }
    }
});

wsClient.onMetadata(metadata -> {
    System.out.println("Metadata: request_id=" + metadata.getRequestId());
});

wsClient.onUtteranceEnd(utteranceEnd -> {
    System.out.println("--- utterance end ---");
});

wsClient.onSpeechStarted(speechStarted -> {
    System.out.println("Speech started");
});

wsClient.onError(error -> {
    System.err.println("Error: " + error.getMessage());
});

wsClient.onDisconnected(reason -> {
    System.out.println("Disconnected: code=" + reason.getCode() +
        ", reason=" + reason.getReason());
    closeLatch.countDown();
});

// Connect with model configuration
CompletableFuture<Void> connectFuture = wsClient.connect(
    V1ConnectOptions.builder()
        .model(ListenV1Model.NOVA3)
        .build());
connectFuture.get(10, TimeUnit.SECONDS);

// Stream audio data (in a real application)
// wsClient.sendMedia(audioBytes);

// Close the stream when done
wsClient.sendCloseStream(ListenV1CloseStream.builder()
    .type(ListenV1CloseStreamType.CLOSE_STREAM)
    .build());

closeLatch.await(15, TimeUnit.SECONDS);
wsClient.disconnect();
```

--------------------------------

### Agent API - List Models

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

List available agent models using the Agent API.

```APIDOC
### Agent (Voice Agent)

### List Agent Models

List available agent models using the Agent API.

```java
client.agent().v1().settings().think().models().list()
```
```

--------------------------------

### Authentication

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Handles authentication by generating access tokens.

```APIDOC
## Auth (Authentication)

### Grant Access Token
- **Method**: `grant(request)`
- **Description**: Generates an access token.
- **Parameters**:
  - `request` (object) - Required - The request payload for generating the token.
```

--------------------------------

### Transcribe with Advanced Options in Java

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Configures a transcription request with speaker diarization, smart formatting, and punctuation. Uses a visitor pattern to extract and print word-level timestamps and confidence scores.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.resources.listen.v1.media.requests.ListenV1RequestUrl;
import com.deepgram.resources.listen.v1.media.types.MediaTranscribeRequestModel;
import com.deepgram.resources.listen.v1.media.types.MediaTranscribeResponse;
import com.deepgram.types.ListenV1Response;
import com.deepgram.types.ListenV1ResponseResultsChannelsItemAlternativesItemWordsItem;

DeepgramClient client = DeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .build();

ListenV1RequestUrl request = ListenV1RequestUrl.builder()
    .url("https://dpgr.am/spacewalk.wav")
    .model(MediaTranscribeRequestModel.NOVA3)
    .smartFormat(true)
    .punctuate(true)
    .diarize(true)  // Speaker diarization
    .language("en-US")
    .build();

MediaTranscribeResponse result = client.listen().v1().media().transcribeUrl(request);

result.visit(new MediaTranscribeResponse.Visitor<Void>() {
    @Override
    public Void visit(ListenV1Response response) {
        var alt = response.getResults().getChannels().get(0)
            .getAlternatives().get().get(0);

        // Display transcript
        alt.getTranscript().ifPresent(transcript -> {
            System.out.println("Transcription:\n" + transcript);
        });

        // Display word-level details with timestamps
        alt.getWords().ifPresent(words -> {
            System.out.println("\nWord Details:");
            for (var word : words.subList(0, Math.min(10, words.size()))) {
                word.getWord().ifPresent(w -> {
                    double start = word.getStart().orElse(0.0);
                    double end = word.getEnd().orElse(0.0);
                    double confidence = word.getConfidence().orElse(0.0);
                    System.out.printf("  %-15s [%.2fs - %.2fs] (%.0f%%)%n",
                        w, start, end, confidence * 100);
                });
            }
        });
        return null;
    }

    @Override
    public Void visit(com.deepgram.types.ListenV1AcceptedResponse accepted) {
        return null;
    }
});
```

--------------------------------

### List Agent Think Models with Deepgram Java SDK

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Retrieve a list of available agent 'think' models using the Deepgram Java SDK. This requires an initialized Deepgram client.

```java
import com.deepgram.DeepgramClient;

DeepgramClient client = DeepgramClient.builder().build();

// List available agent think models
var models = client.agent().v1().settings().think().models().list();
```

--------------------------------

### Manage Deepgram Projects and Keys with Java SDK

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

This snippet demonstrates how to list projects, list API keys for a project, and retrieve usage statistics using the Deepgram Java SDK. Replace 'project-id' with your actual project ID.

```java
import com.deepgram.DeepgramClient;

DeepgramClient client = DeepgramClient.builder().build();

// List projects
var projects = client.manage().v1().projects().list();

// List API keys for a project
var keys = client.manage().v1().projects().keys().list("project-id");

// Get usage statistics
var usage = client.manage().v1().projects().usage().get("project-id");
```

--------------------------------

### Listen API - Transcribe URL

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Transcribe audio from a given URL using the Listen API.

```APIDOC
## Listen (Speech-to-Text)

### Transcribe Audio from URL

Transcribe audio from a given URL using the Listen API.

```java
client.listen().v1().media().transcribeUrl(request)
```
```

--------------------------------

### List and Manage API Keys

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Use this snippet to list, create, and delete API keys for a Deepgram project. Ensure the DEEPGRAM_API_KEY environment variable is set.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.types.ListProjectKeysV1Response;
import com.deepgram.types.ListProjectKeysV1ResponseApiKeysItem;
import com.deepgram.types.ListProjectsV1Response;
import java.util.Collections;
import java.util.List;

DeepgramClient client = DeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .build();

// Get the first project ID
ListProjectsV1Response projectsResponse = client.manage().v1().projects().list();
String projectId = projectsResponse.getProjects()
    .orElse(Collections.emptyList())
    .get(0)
    .getProjectId()
    .orElse("");

// List existing keys
ListProjectKeysV1Response keysResponse =
    client.manage().v1().projects().keys().list(projectId);

List<ListProjectKeysV1ResponseApiKeysItem> keys =
    keysResponse.getApiKeys().orElse(Collections.emptyList());

System.out.printf("API Keys (%d):%n", keys.size());
for (ListProjectKeysV1ResponseApiKeysItem keyItem : keys) {
    keyItem.getApiKey().ifPresent(key -> {
        System.out.printf("  Key ID: %s%n", key);
    });
    keyItem.getMember().ifPresent(member -> {
        System.out.printf("  Member: %s%n", member);
    });
}

// Create a new key (uncomment to use)
// CreateKeysRequest createRequest = CreateKeysRequest.builder()
//     .body(Map.of("comment", "SDK Example Key", "scopes", List.of("member")))
//     .build();
// client.manage().v1().projects().keys().create(projectId, createRequest);

// Delete a key (uncomment to use)
// client.manage().v1().projects().keys().delete(projectId, keyId);
```

--------------------------------

### Deepgram Client Authentication (Explicit API Key)

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Instantiate the DeepgramClient by providing your API key directly during builder configuration.

```java
import com.deepgram.DeepgramClient;

// Using API key directly
DeepgramClient explicitClient = DeepgramClient.builder()
    .apiKey("YOUR_DEEPGRAM_API_KEY")
    .build();
```

--------------------------------

### Run Deepgram Java SDK Tests

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Execute unit, integration, or all tests for the Deepgram Java SDK using Gradle. Integration tests require the DEEPGRAM_API_KEY environment variable to be set.

```bash
# Unit tests
./gradlew unitTest
```

```bash
# Integration tests (requires DEEPGRAM_API_KEY)
./gradlew integrationTest
```

```bash
# All tests
./gradlew test
```

--------------------------------

### Speak API - Generate Audio

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Generate speech audio from provided text using the Speak API.

```APIDOC
### Speak (Text-to-Speech)

### Generate Speech from Text

Generate speech audio from provided text using the Speak API.

```java
client.speak().v1().audio().generate(request)
```
```

--------------------------------

### Build Deepgram Client

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/docs/Migrating-v0.2-to-v0.3.md

Construct a Deepgram client instance. The default builder uses no API key, while the explicit builder allows specifying one.

```java
import com.deepgram.DeepgramClient;

DeepgramClient client = DeepgramClient.builder().build();

DeepgramClient explicitClient = DeepgramClient.builder()
    .apiKey("YOUR_DEEPGRAM_API_KEY")
    .build();
```

--------------------------------

### Speech-to-Text (Listen) - Transcribe from File

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Transcribes audio from a local file using the Deepgram SDK.

```APIDOC
## Speech-to-Text (Listen) - Transcribe from File

### Description
Transcribe pre-recorded audio from files.

### Method
```java
client.listen().v1().media().transcribeFile(byte[] audioData)
```

### Request Example
```java
import com.deepgram.DeepgramClient;
import com.deepgram.resources.listen.v1.media.types.MediaTranscribeResponse;
import java.nio.file.Files;
import java.nio.file.Path;

DeepgramClient client = DeepgramClient.builder().build();
byte[] audioData = Files.readAllBytes(Path.of("audio.wav"));
MediaTranscribeResponse result = client.listen().v1().media().transcribeFile(audioData);
```
```

--------------------------------

### Text-to-Speech Conversion with Deepgram Java SDK

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Convert text to natural-sounding speech audio using the Speak REST API and save the output to a file. Ensure the DEEPGRAM_API_KEY environment variable is set.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.resources.speak.v1.audio.requests.SpeakV1Request;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;

DeepgramClient client = DeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .build();

String text = "Hello! This is a text-to-speech example using the Deepgram Java SDK. "
    + "Deepgram's TTS API produces natural-sounding speech from text.";

// Build the TTS request
SpeakV1Request request = SpeakV1Request.builder()
    .text(text)
    .build();

// Generate audio stream
InputStream audioStream = client.speak().v1().audio().generate(request);

// Save audio to file
Path outputPath = Path.of("output.mp3");
long bytes = Files.copy(audioStream, outputPath, StandardCopyOption.REPLACE_EXISTING);
audioStream.close();

System.out.printf("Audio saved to %s (%d bytes)%n", outputPath, bytes);
```

--------------------------------

### Connect to Voice Agent API (Java)

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Connects to Deepgram's conversational voice agent API using WebSockets for real-time voice interactions. Configure LLM settings and handle various events like connection, welcome, settings applied, text, speaking events, audio, errors, and disconnection.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.resources.agent.v1.types.*;
import com.deepgram.resources.agent.v1.websocket.V1WebSocketClient;
import com.deepgram.types.OpenAiThinkProvider;
import com.deepgram.types.OpenAiThinkProviderModel;
import com.deepgram.types.ThinkSettingsV1;
import com.deepgram.types.ThinkSettingsV1Provider;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import okio.ByteString;

DeepgramClient client = DeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .build();

V1WebSocketClient wsClient = client.agent().v1().v1WebSocket();
CountDownLatch closeLatch = new CountDownLatch(1);

// Register event handlers
wsClient.onConnected(() -> {
    System.out.println("WebSocket connected");
});

wsClient.onWelcome(welcome -> {
    System.out.println("Agent welcome: request_id=" + welcome.getRequestId());

    // Configure the LLM think provider (OpenAI)
    OpenAiThinkProvider openAiProvider = OpenAiThinkProvider.builder()
        .model(OpenAiThinkProviderModel.GPT4O_MINI)
        .build();

    ThinkSettingsV1 thinkSettings = ThinkSettingsV1.builder()
        .provider(ThinkSettingsV1Provider.openAi(openAiProvider))
        .prompt("You are a helpful voice assistant. Keep your responses brief.")
        .build();

    AgentV1SettingsAgentContext agentContext = AgentV1SettingsAgentContext.builder()
        .think(AgentV1SettingsAgentContextThink.of(thinkSettings))
        .greeting("Hello! How can I help you today?")
        .build();

    AgentV1Settings settings = AgentV1Settings.builder()
        .audio(AgentV1SettingsAudio.builder().build())
        .agent(AgentV1SettingsAgent.of(agentContext))
        .build();

    wsClient.sendSettings(settings);
    System.out.println("Settings sent to agent");
});

wsClient.onSettingsApplied(applied -> {
    System.out.println("Settings applied successfully");
});

wsClient.onConversationText(text -> {
    System.out.printf("[%s] %s%n", text.getRole(), text.getContent());
});

wsClient.onUserStartedSpeaking(event -> {
    System.out.println(">> User started speaking");
});

wsClient.onAgentThinking(event -> {
    System.out.println(">> Agent thinking...");
});

wsClient.onAgentStartedSpeaking(event -> {
    System.out.println(">> Agent started speaking");
});

wsClient.onAgentV1Audio(audioData -> {
    System.out.printf("Received agent audio (%d bytes)%n", audioData.size());
});

wsClient.onError(error -> {
    System.err.println("Error: " + error.getMessage());
});

wsClient.onDisconnected(reason -> {
    System.out.println("Disconnected: " + reason.getCode());
    closeLatch.countDown();
});

// Connect
CompletableFuture<Void> connectFuture = wsClient.connect();
connectFuture.get(10, TimeUnit.SECONDS);

// Stream audio to agent
// wsClient.sendMedia(ByteString.of(audioBytes, 0, audioBytes.length));

closeLatch.await(60, TimeUnit.SECONDS);
wsClient.disconnect();
```

--------------------------------

### Configure Custom OkHttpClient with Timeouts

Source: https://context7.com/deepgram/deepgram-java-sdk/llms.txt

Use a custom OkHttpClient to set specific connection, read, and write timeouts. Note that providing a custom OkHttpClient prevents the SDK's built-in retry interceptor from being added automatically.

```java
import com.deepgram.DeepgramClient;
import com.deepgram.core.Environment;
import okhttp3.OkHttpClient;
import java.util.concurrent.TimeUnit;

// Custom HTTP client with specific timeouts
OkHttpClient httpClient = new OkHttpClient.Builder()
    .connectTimeout(30, TimeUnit.SECONDS)
    .readTimeout(30, TimeUnit.SECONDS)
    .writeTimeout(30, TimeUnit.SECONDS)
    .build();

// Note: When providing a custom OkHttpClient, the SDK's built-in
// retry interceptor is not added automatically
DeepgramClient client = DeepgramClient.builder()
    .apiKey(System.getenv("DEEPGRAM_API_KEY"))
    .httpClient(httpClient)
    .build();

// Custom base URL for on-premises deployments
DeepgramClient onPremClient = DeepgramClient.builder()
    .apiKey("YOUR_API_KEY")
    .environment(Environment.custom()
        .base("https://your-custom-endpoint.com")
        .build())
    .build();
```

--------------------------------

### Management API

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Manage projects, API keys, members, usage, and billing.

```APIDOC
## Management API

### Description
Manage projects, API keys, members, usage, and billing.

### Methods

#### List Projects

##### Method Signature
```java
client.manage().v1().projects().list()
```

#### List API Keys for a Project

##### Method Signature
```java
client.manage().v1().projects().keys().list(String projectId)
```

##### Parameters
- **projectId** (string) - Required - The ID of the project.

#### Get Usage Statistics

##### Method Signature
```java
client.manage().v1().projects().usage().get(String projectId)
```

##### Parameters
- **projectId** (string) - Required - The ID of the project.

### Request Example
```java
import com.deepgram.DeepgramClient;

DeepgramClient client = DeepgramClient.builder().build();

// List projects
var projects = client.manage().v1().projects().list();

// List API keys for a project
var keys = client.manage().v1().projects().keys().list("project-id");

// Get usage statistics
var usage = client.manage().v1().projects().usage().get("project-id");
```
```