> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raidzero.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Java

> sf-voice-media-java SDK reference for Java 17+: synchronous client for ingesting media assets, polling indexing tasks, and running scoped search.

`sh.sf-voice:sf-voice-media-java` — synchronous Java client, builder pattern throughout, Java 17+.

Use this SDK when a blocking client fits your service or batch job. Kotlin users should use the coroutine-native SDK.

## Install

```kotlin build.gradle.kts theme={null}
dependencies {
    implementation("sh.sf-voice:sf-voice-media-java:0.1.1")
}
```

```groovy build.gradle theme={null}
dependencies {
    implementation 'sh.sf-voice:sf-voice-media-java:0.1.1'
}
```

```xml pom.xml theme={null}
<dependency>
    <groupId>sh.sf-voice</groupId>
    <artifactId>sf-voice-media-java</artifactId>
    <version>0.1.1</version>
</dependency>
```

## Create a client

```java theme={null}
import com.sfvoice.media.SfVoiceMediaClient;

SfVoiceMediaClient client = new SfVoiceMediaClient(
    System.getenv("SF_VOICE_API_KEY"),
    "https://api.sf-voice.com"
);
```

## Ingest

```java theme={null}
import com.sfvoice.media.models.IngestRequest;
import com.sfvoice.media.models.IngestResponse;

IngestRequest req = IngestRequest.fromUrl(
        "call_001",
        "https://storage.example.com/calls/001.mp3"
    )
    .assetClass("customer_acme")
    .mediaKind("audio")
    .build();

IngestResponse resp = client.ingest(req);
String taskId = resp.getTaskId();
```

## Poll until ready

```java theme={null}
import com.sfvoice.media.models.Task;

Task task = client.pollTask(taskId, 2000, 120_000);

if ("failed".equals(task.getStatus())) {
    throw new RuntimeException("indexing failed: " + task.getError());
}
```

`pollTask(taskId, intervalMs, timeoutMs)` blocks until the task reaches `ready` or `failed`, or throws if the timeout is exceeded.

## Search

```java theme={null}
import com.sfvoice.media.models.SearchRequest;
import com.sfvoice.media.models.SearchResponse;

SearchRequest req = SearchRequest.query("customer asks about pricing")
    .assetClass("customer_acme")
    .types(List.of("transcript"))
    .threshold(0.7f)
    .limit(10)
    .build();

SearchResponse resp = client.search(req);

for (var result : resp.getResults()) {
    System.out.printf("%s %d–%dms (%.2f)%n",
        result.getAssetId(), result.getStartMs(), result.getEndMs(), result.getScore());
}
```

## Assets

```java theme={null}
// list
var resp = client.listAssets(1, 20);

// get one
var asset = client.getAsset("call_001");

// delete
client.deleteAsset("call_001");
```

## Errors

```java theme={null}
import com.sfvoice.media.SfVoiceMediaException;

try {
    client.search(req);
} catch (SfVoiceMediaException e) {
    System.err.println(e.getCode() + " " + e.getStatus() + ": " + e.getMessage());
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.