docs.sf-voice.sh

https://docs.sf-voice.sh
Admin
This environment does not appear to contain a recognizable software project or documentation...
Tokens:17,296
Snippets:191
Trust Score:2.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Go SDK

Source: https://docs.sf-voice.sh/sdks/go

Install the Go SDK using the go get command.

```sh
go get github.com/sf-voice/sf-voice-media-go@v0.1.1
```

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

### Full Quickstart Example

Source: https://docs.sf-voice.sh/quickstart

A comprehensive example demonstrating the complete workflow: client creation, media ingestion, task polling, and search, with error handling for API-specific errors.

```typescript
import { SfVoiceMedia, SfVoiceMediaError } from "@sf-voice/media";

const client = new SfVoiceMedia({
  baseUrl: "https://api.sf-voice.com",
  apiKey: process.env.SF_VOICE_API_KEY!,
});

try {
  const { task_id } = await client.ingest({
    source: "url",
    asset_id: "call_001",
    asset_class: "customer_acme",
    url: "https://example.com/call.mp3",
    media_type: "audio",
    types: ["audio", "transcript"],
  });

  const task = await client.pollTask(task_id);

  if (task.status === "failed") {
    throw new Error(task.error ?? "indexing failed");
  }

  const { results } = await client.search({
    query: "customer asks about pricing",
    asset_class: "customer_acme",
  });

  console.log(results);
} catch (err) {
  if (err instanceof SfVoiceMediaError) {
    console.error(err.code, err.status, err.message);
  }
  throw err;
}
```

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

### Install TypeScript SDK

Source: https://docs.sf-voice.sh/quickstart

Install the SF Voice Media SDK using your preferred package manager (pnpm, npm, or bun).

```sh
pnpm add @sf-voice/media@0.1.1
```

```sh
npm install @sf-voice/media@0.1.1
```

```sh
bun add @sf-voice/media@0.1.1
```

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

### Install Kotlin SDK

Source: https://docs.sf-voice.sh/sdks/kotlin

Add the sf-voice-media-kotlin dependency to your project's build.gradle.kts file.

```APIDOC
## Install Kotlin SDK

### Description
Add the sf-voice-media-kotlin dependency to your project's build.gradle.kts file.

### Code
```kotlin
// build.gradle.kts
dependencies {
    implementation("sh.sf-voice:sf-voice-media-kotlin:0.1.1")
}
```
```

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

### Install Kotlin SDK

Source: https://docs.sf-voice.sh/sdks/kotlin

Add the sf-voice-media-kotlin dependency to your build.gradle.kts file.

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

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

### List, Get, and Delete Assets

Source: https://docs.sf-voice.sh/sdks/typescript

Demonstrates how to list paginated assets, retrieve a single asset by its ID, and delete an asset.

```typescript
// list (paginated)
const { items, page_info } = await client.listAssets({ page: 1, limit: 20 });

// single
const asset = await client.getAsset("call_001");

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

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

### Error Handling

Source: https://docs.sf-voice.sh/sdks/elixir

Explains the structure of the SfVoiceMedia.Error struct and provides an example of how to handle errors.

```APIDOC
## Errors

### Description
Explains the structure of the SfVoiceMedia.Error struct and provides an example of how to handle errors.

### Error Struct
`%SfVoiceMedia.Error{}` has three fields:
- **code** (integer or string) - The error code.
- **message** (string) - A human-readable error message.
- **status** (string) - The status of the operation when the error occurred.

### Usage Example
```elixir
case SfVoiceMedia.search(client, %{query: "...", asset_class: "customer_acme"}) do
  {:ok, result} -> result
  {:error, %SfVoiceMedia.Error{code: code, message: msg}} ->
    Logger.error("search failed: #{code} — #{msg}")
    {:error, code}
end
```
```

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

### Get Asset

Source: https://docs.sf-voice.sh/sdks/typescript

Retrieves a single asset by its ID.

```APIDOC
## GET /assets/{asset_id}

### Description
Retrieves a specific asset by its unique identifier.

### Method
GET

### Endpoint
/assets/{asset_id}

### Parameters
#### Path Parameters
- **asset_id** (string) - Required - The unique identifier of the asset.
```

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

### Manage Assets: List, Get, Delete

Source: https://docs.sf-voice.sh/sdks/rust

Perform asset management operations: list all assets, retrieve a specific asset by ID, or delete an asset. These operations are asynchronous.

```rust
// list
let resp = client.list_assets(None).await?;

// get one
let asset = client.get_asset("call_001").await?;

// delete
client.delete_asset("call_001").await?;
```

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

### Search Result Example

Source: https://docs.sf-voice.sh/how-it-works

Search results provide the asset_id, a relevance score, and millisecond timestamps (start_ms, end_ms) indicating the match's position within the source media. The match_type specifies what was matched.

```json
{
  "asset_id": "call_8294",
  "score": 0.87,
  "start_ms": 42000,
  "end_ms": 58000,
  "match_type": "transcript"
}
```

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

### Handle SfVoiceMedia Errors

Source: https://docs.sf-voice.sh/sdks/elixir

Handle potential errors from the SfVoiceMedia SDK, which are represented by the %SfVoiceMedia.Error{} struct. This example shows how to log the error code and message when a search operation fails.

```elixir
case SfVoiceMedia.search(client, %{query: "...", asset_class: "customer_acme"}) do
  {:ok, result} -> result
  {:error, %SfVoiceMedia.Error{code: code, message: msg}} ->
    Logger.error("search failed: #{code} — #{msg}")
    {:error, code}
end
```

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

### Fetch Dependencies

Source: https://docs.sf-voice.sh/sdks/elixir

After adding the dependency, run this command to fetch it.

```sh
mix deps.get
```

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

### Create SfVoiceMedia Client

Source: https://docs.sf-voice.sh/sdks/rust

Instantiate the SfVoiceMedia client with the API endpoint and your API key. Ensure the API key is available as an environment variable.

```rust
use sf_voice_media::SfVoiceMedia;

let client = SfVoiceMedia::new(
    "https://api.sf-voice.com",
    std::env::var("SF_VOICE_API_KEY").unwrap(),
)?;
```

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

### Create Go Client

Source: https://docs.sf-voice.sh/sdks/go

Create a new client instance for the SF Voice API using the default HTTP client.

```go
import sfvoice "github.com/sf-voice/sf-voice-media-go"

client := sfvoice.New(
    "https://api.sf-voice.com",
    os.Getenv("SF_VOICE_API_KEY"),
)
```

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

### Get Task Status Once

Source: https://docs.sf-voice.sh/sdks/typescript

Retrieve the current status of a task without continuous polling. Useful for periodic checks.

```typescript
const task = await client.getTask(task_id);
// task.status: "pending" | "indexing" | "ready" | "failed"
```

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

### Create a client

Source: https://docs.sf-voice.sh/sdks/java

Instantiate the SfVoiceMediaClient using your API key and the API endpoint.

```APIDOC
## Create a client

Instantiate the SfVoiceMediaClient using your API key and the API endpoint.

```java
import com.sfvoice.media.SfVoiceMediaClient;

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

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

### Create sf-voice Media Client

Source: https://docs.sf-voice.sh/sdks/cpp

Initializes the sf-voice media client with the API endpoint and an API key. The API key should be set as an environment variable SF_VOICE_API_KEY.

```cpp
#include <sf_voice/client.hpp>

sfvoice::SfVoiceMedia client(
    "https://api.sf-voice.com",
    std::getenv("SF_VOICE_API_KEY")
);
```

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

### Create SfVoiceMediaClient

Source: https://docs.sf-voice.sh/sdks/kotlin

Instantiate the SfVoiceMediaClient using your API key and the base API URL. Ensure the API key is set as an environment variable.

```kotlin
import com.sfvoice.media.SfVoiceMediaClient

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

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

### Create a client

Source: https://docs.sf-voice.sh/sdks/typescript

Instantiate the SfVoiceMedia client with your API key and base URL. The client is used to interact with the SF Voice API.

```APIDOC
## Create a client

Instantiate the `SfVoiceMedia` client with your API key and base URL.

```ts
import { SfVoiceMedia } from "@sf-voice/media";

const client = new SfVoiceMedia({
  baseUrl: "https://api.sf-voice.com",
  apiKey: process.env.SF_VOICE_API_KEY!,
});
```

### Options

| Option      | Type     | Default  | Description                      |
| ----------- | -------- | -------- | -------------------------------- |
| `baseUrl`   | `string` | —        | Required.                        |
| `apiKey`    | `string` | —        | Required. Sent as `X-API-Key`. |
| `timeoutMs` | `number` | `30_000` | Per-request abort timeout.     |
```

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

### Create SfVoiceMedia Client

Source: https://docs.sf-voice.sh/quickstart

Initialize the SfVoiceMedia client with your API key and the base URL for the API.

```typescript
import { SfVoiceMedia } from "@sf-voice/media";

const client = new SfVoiceMedia({
  baseUrl: "https://api.sf-voice.com",
  apiKey: process.env.SF_VOICE_API_KEY!,
});
```

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

### Create an sf_voice Client

Source: https://docs.sf-voice.sh/sdks/elixir

Initialize the sf_voice client with the API endpoint and your API key. The API key is typically retrieved from environment variables. Additional HTTP options can be passed for custom configurations.

```elixir
client = SfVoiceMedia.new("https://api.sf-voice.com",
  api_key: System.get_env("SF_VOICE_API_KEY")
)
```

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

### Create SfVoiceMediaClient

Source: https://docs.sf-voice.sh/sdks/kotlin

Instantiate the SfVoiceMediaClient using your API key and the base API URL.

```APIDOC
## Create SfVoiceMediaClient

### Description
Instantiate the SfVoiceMediaClient using your API key and the base API URL.

### Code
```kotlin
import com.sfvoice.media.SfVoiceMediaClient

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

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

### Create Go Client with Custom HTTP Client

Source: https://docs.sf-voice.sh/sdks/go

Create a new client instance with a custom http.Client, allowing for configuration like timeouts.

```go
client := sfvoice.NewWithHTTPClient(baseURL, apiKey, &http.Client{
    Timeout: 30 * time.Second,
})
```

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

### Create SfVoiceMediaClient

Source: https://docs.sf-voice.sh/sdks/java

Instantiate the synchronous Java client using your API key and the API endpoint.

```java
import com.sfvoice.media.SfVoiceMediaClient;

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

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

### Add sf_voice_media to Cargo.toml

Source: https://docs.sf-voice.sh/sdks/rust

Add the sf_voice_media crate and tokio to your project's dependencies in Cargo.toml.

```toml
[dependencies]
sf_voice_media = "0.1.1"
tokio = { version = "1", features = ["full"] }
```

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

### Manage Assets using Go SDK

Source: https://docs.sf-voice.sh/sdks/go

Perform operations on assets including listing, retrieving a specific asset by ID, and deleting an asset.

```go
// list
resp, err := client.ListAssets(ctx, &sfvoice.ListAssetsParams{Page: 1, Limit: 20})
```

```go
// get one
asset, err := client.GetAsset(ctx, "call_001")
```

```go
// delete
err = client.DeleteAsset(ctx, "call_001")
```

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

### Ingest Asset using Go SDK

Source: https://docs.sf-voice.sh/sdks/go

Ingest an asset by providing its source URL, asset ID, class, media type, and desired output types.

```go
resp, err := client.Ingest(ctx, &sfvoice.IngestRequest{
    Source:     "url",
    AssetID:    "call_001",
    AssetClass: "customer_acme",
    URL:        "https://storage.example.com/calls/001.mp3",
    MediaType:  "audio",
    Types:      []string{"audio", "transcript"},
})
if err != nil {
    return err
}
taskID := resp.TaskID
```

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

### ListAssets

Source: https://docs.sf-voice.sh/sdks/go

Lists all available assets with pagination support.

```APIDOC
## ListAssets

### Description
Lists all available assets with pagination support.

### Method
GET

### Endpoint
/assets

### Parameters
#### Query Parameters
- **Page** (integer) - Optional - The page number for pagination. Defaults to 1.
- **Limit** (integer) - Optional - The number of assets to return per page. Defaults to 20.

### Response
#### Success Response (200)
- **Assets** (array of objects) - A list of assets.
  - [Asset object details would be described here if available in source]

### Response Example
```json
{
  "Assets": [
    {
      "AssetID": "call_001",
      "MediaType": "audio"
    }
  ]
}
```
```

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

### Ingest Media from URL

Source: https://docs.sf-voice.sh/sdks/rust

Ingest media by providing a URL. You can specify asset ID, asset class, and media type. The SDK returns a task ID for tracking.

```rust
use sf_voice_media::{SfVoiceMedia, IngestRequest, MediaType};

let resp = client.ingest(
    IngestRequest::from_url("https://storage.example.com/calls/001.mp3")
        .asset_id("call_001")
        .asset_class("customer_acme")
        .media_type(MediaType::Audio)
        .build(),
).await?;

let task_id = resp.task_id;
```

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

### Ingest Audio/Video from URL

Source: https://docs.sf-voice.sh/sdks/typescript

Submit an asset for indexing by providing its URL. The ingestion process returns a task ID immediately.

```typescript
const { task_id } = await client.ingest({
  source: "url",
  asset_id: "call_001",
  asset_class: "customer_acme",
  url: "https://storage.example.com/calls/001.mp3",
  media_type: "audio",
  types: ["audio", "transcript"],
  metadata: { caller: "+14155550199" },
});
```

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

### Add sf-voice-media-java Dependency

Source: https://docs.sf-voice.sh/sdks/java

Add the sf-voice-media-java dependency to your build file for Java 17+.

```kotlin
dependencies {
    implementation("sh.sf-voice:sf-voice-media-java:0.1.1")
}
```

```groovy
dependencies {
    implementation 'sh.sf-voice:sf-voice-media-java:0.1.1'
}
```

```xml
<dependency>
    <groupId>sh.sf-voice</groupId>
    <artifactId>sf-voice-media-java</artifactId>
    <version>0.1.1</version>
</dependency>
```

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

### Include sf-voice in CMake Project

Source: https://docs.sf-voice.sh/sdks/cpp

Demonstrates how to fetch and include the sf-voice C++ library in your CMake project. Ensure CPR and nlohmann/json are available.

```cmake
include(FetchContent)
FetchContent_Declare(
  sf_voice
  GIT_REPOSITORY https://github.com/sf-voice/sf-voice-core
  GIT_TAG        main
  SOURCE_SUBDIR  cpp
)
FetchContent_MakeAvailable(sf_voice)

target_link_libraries(your_target PRIVATE sf_voice)
```

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

### Search Transcripts using Go SDK

Source: https://docs.sf-voice.sh/sdks/go

Search through transcripts with a query, specifying asset class, desired types, a similarity threshold, and a limit for results.

```go
resp, err := client.Search(ctx, &sfvoice.SearchRequest{
    Query:      "customer asks about pricing",
    AssetClass: "customer_acme",
    Types:      []string{"transcript"},
    Threshold:  0.7,
    Limit:      10,
})
if err != nil {
    return err
}

for _, r := range resp.Results {
    fmt.Printf("%s %d–%dms (%.2f)\n", r.AssetID, r.StartMs, r.EndMs, r.Score)
}
```

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

### Manage Assets

Source: https://docs.sf-voice.sh/sdks/kotlin

Perform operations on assets including listing all assets, retrieving a specific asset by ID, and deleting an asset.

```kotlin
// list
val resp = client.listAssets(page = 1, limit = 20)

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

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

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

### Ingest Audio/Video from File Buffer

Source: https://docs.sf-voice.sh/sdks/typescript

Ingest assets by uploading a file buffer (Blob, ArrayBuffer, or Uint8Array). Ensure the correct content type is specified.

```typescript
const buffer = await file.arrayBuffer();

const { task_id } = await client.ingest({
  source: "file",
  asset_id: "call_001",
  asset_class: "customer_acme",
  file: buffer,
  filename: "001.mp3",
  content_type: "audio/mpeg",
  media_type: "audio",
  types: ["audio", "transcript"],
});
```

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

### List Assets

Source: https://docs.sf-voice.sh/sdks/kotlin

Retrieve a paginated list of all available assets.

```APIDOC
## List Assets

### Description
Retrieve a paginated list of all available assets.

### Method
`listAssets`

### Parameters
#### Query Parameters
- **page** (Int) - Optional - The page number to retrieve (default: 1).
- **limit** (Int) - Optional - The number of assets per page (default: 20).

### Code
```kotlin
val resp = client.listAssets(page = 1, limit = 20)
```
```

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

### Add sf_voice to Mix Dependencies

Source: https://docs.sf-voice.sh/sdks/elixir

Add the sf_voice dependency to your project's mix.exs file to include it in your project.

```elixir
def deps do
  [
    {:sf_voice, "~> 0.1.1"}
  ]
end
```

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

### Manage Assets

Source: https://docs.sf-voice.sh/sdks/java

Perform basic asset management operations including listing all assets, retrieving a specific asset by ID, and deleting an asset.

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

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

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

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

### Search All Indexed Assets

Source: https://docs.sf-voice.sh/sdks/typescript

Execute a search query across all indexed assets in your account. Use with caution as it can be resource-intensive and may expose sensitive data if not properly managed.

```typescript
const { results } = await client.search({
  query: "AI interrupted the caller",
  scope: "all",
});
```

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

### Ingest Audio/Video from S3

Source: https://docs.sf-voice.sh/sdks/typescript

Ingest assets directly from an S3 bucket by specifying the S3 key. This method is suitable for server-side processing.

```typescript
const { task_id } = await client.ingest({
  source: "s3",
  asset_id: "call_001",
  asset_class: "customer_acme",
  s3_key: "calls/customer_acme/001.mp3",
  media_type: "audio",
  types: ["audio", "transcript"],
});
```

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

### Assets

Source: https://docs.sf-voice.sh/sdks/elixir

Provides functions to list, retrieve, and delete assets.

```APIDOC
## Assets

### Description
Provides functions to list, retrieve, and delete assets.

### Functions
#### List Assets
`SfVoiceMedia.list_assets(client, params)`
- **client** (map) - The SfVoiceMedia client.
- **params** (map) - Pagination parameters, e.g., `%{page: 1, limit: 20}`.
- **Returns**: `{:ok, response}` or `{:error, %SfVoiceMedia.Error{}}`.

#### Get Asset
`SfVoiceMedia.get_asset(client, asset_id)`
- **client** (map) - The SfVoiceMedia client.
- **asset_id** (string) - The ID of the asset to retrieve.
- **Returns**: `{:ok, asset}` or `{:error, %SfVoiceMedia.Error{}}`.

#### Delete Asset
`SfVoiceMedia.delete_asset(client, asset_id)`
- **client** (map) - The SfVoiceMedia client.
- **asset_id** (string) - The ID of the asset to delete.
- **Returns**: `{:ok, _}` or `{:error, %SfVoiceMedia.Error{}}`.

### Usage Example
```elixir
# list
{:ok, resp} = SfVoiceMedia.list_assets(client, %{page: 1, limit: 20})

# get one
{:ok, asset} = SfVoiceMedia.get_asset(client, "call_001")

# delete
{:ok, _} = SfVoiceMedia.delete_asset(client, "call_001")
```
```

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

### Poll Task Status with Pattern Matching

Source: https://docs.sf-voice.sh/sdks/elixir

Check the status of a task using `get_task/2` and pattern matching. This allows for handling different task statuses like 'ready', 'failed', or 'still_running' without exceptions.

```elixir
case SfVoiceMedia.get_task(client, task_id) do
  {:ok, %{status: "ready"}} -> :indexed
  {:ok, %{status: "failed", error: reason}} -> {:error, reason}
  {:ok, _} -> :still_running
  {:error, err} -> {:error, err}
end
```

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

### Manage Assets

Source: https://docs.sf-voice.sh/sdks/elixir

Perform operations on assets including listing all assets with pagination, retrieving a specific asset by its ID, and deleting an asset.

```elixir
# list
{:ok, resp} = SfVoiceMedia.list_assets(client, %{page: 1, limit: 20})

# get one
{:ok, asset} = SfVoiceMedia.get_asset(client, "call_001")

# delete
{:ok, _} = SfVoiceMedia.delete_asset(client, "call_001")
```

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

### Search Assets by Asset Class

Source: https://docs.sf-voice.sh/sdks/typescript

Perform a search query within a specific asset class. This helps scope results to relevant recordings.

```typescript
const { results } = await client.search({
  query: "customer asks about cancelling their subscription",
  asset_class: "customer_acme",
  types: ["transcript"],
  threshold: 0.7,
  limit: 10,
});
```

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

### Handle API Errors using Go SDK

Source: https://docs.sf-voice.sh/sdks/go

Catch and log non-2xx API responses which return a *sfvoice.Error, extracting status, code, and message.

```go
var apiErr *sfvoice.Error
if errors.As(err, &apiErr) {
    log.Printf("api error %d [%s]: %s", apiErr.Status, apiErr.Code, apiErr.Message)
}
```

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

### Search Media Assets

Source: https://docs.sf-voice.sh/sdks/rust

Perform a search query against media assets. You can specify the search text, asset class, a confidence threshold, and the number of results to limit.

```rust
use sf_voice_media::SearchRequest;

let resp = client.search(
    SearchRequest::new("customer asks about pricing")
        .asset_class("customer_acme")
        .threshold(0.7)
        .limit(10)
        .build(),
).await?;

for result in &resp.results {
    println!("{} {}–{}ms ({:.2})", result.asset_id, result.start_ms, result.end_ms, result.score);
}
```

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

### Error Handling with SfVoiceMediaError

Source: https://docs.sf-voice.sh/sdks/typescript

Shows how to catch and handle specific errors from the SDK, including accessing error codes, status, and messages.

```typescript
import { SfVoiceMediaError } from "@sf-voice/media";

try {
  await client.search({ query: "...", asset_class: "customer_acme" });
} catch (err) {
  if (err instanceof SfVoiceMediaError) {
    console.error(err.code);    // machine-readable code
    console.error(err.status);  // HTTP status
    console.error(err.message); // human-readable
  }
}
```

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

### Ingest Media

Source: https://docs.sf-voice.sh/sdks/kotlin

Ingest media from a URL by providing the source URL and media type. This returns a task ID for tracking the ingestion process.

```kotlin
import com.sfvoice.media.IngestRequest
import com.sfvoice.media.MediaType

val resp = client.ingest(
    IngestRequest(
        source = "url",
        url = "https://storage.example.com/calls/001.mp3",
        mediaType = MediaType.Audio
    )
)
val taskId = resp.taskId
```

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

### Configure Poll Options

Source: https://docs.sf-voice.sh/sdks/rust

Customize polling behavior by providing PollOptions to `poll_task`. Options include `interval_ms` for polling frequency and `timeout_ms` for the maximum wait time. Defaults are 1500ms and 120s.

```rust
`poll_task` takes optional `PollOptions { interval_ms, timeout_ms }`. Defaults: 1500ms interval, 120s timeout.
```

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

### Ingest Media from S3

Source: https://docs.sf-voice.sh/sdks/rust

Ingest media stored in S3 by providing the object key. Similar to URL ingestion, you can set asset ID, class, and type.

```rust
use sf_voice_media::IngestRequest;

let resp = client.ingest(
    IngestRequest::from_s3("calls/customer_acme/001.mp3")
        .asset_id("call_001")
        .asset_class("customer_acme")
        .media_type(MediaType::Audio)
        .build(),
).await?;
```

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

### Ingest Media with sf-voice

Source: https://docs.sf-voice.sh/sdks/cpp

Ingests media into the sf-voice system. Specify the source, asset details, URL, media type, and desired output types. The result contains a task ID for tracking.

```cpp
sfvoice::IngestRequest req;
req.source      = "url";
req.asset_id    = "call_001";
req.asset_class = "customer_acme";
req.url         = "https://storage.example.com/calls/001.mp3";
req.media_type  = "audio";
req.types       = {"audio", "transcript"};

auto result = client.ingest(req).get();

if (!result) {
    std::cerr << result.error().message << "\n";
    return;
}

auto task_id = result.value().task_id;
```

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

### Search Media Content

Source: https://docs.sf-voice.sh/sdks/kotlin

Perform a search query against the media content. Specify search types, a confidence threshold, and a limit for results. Results include asset ID, timestamps, and score.

```kotlin
import com.sfvoice.media.SearchMatchType
import com.sfvoice.media.SearchRequest

val resp = client.search(
    SearchRequest(
        query = "customer asks about pricing",
        types = listOf(SearchMatchType.Conversation),
        threshold = 0.7f,
        limit = 10
    )
)

resp.results.forEach { r ->
    println("${r.assetId} ${r.startMs}–${r.endMs}ms (${r.score})")
}
```

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

### Handle SfVoiceMediaException

Source: https://docs.sf-voice.sh/sdks/kotlin

Catch and handle SfVoiceMediaException to gracefully manage API errors, including error codes, status, and messages.

```kotlin
import com.sfvoice.media.SfVoiceMediaException
import com.sfvoice.media.SearchRequest

try {
    client.search(SearchRequest(query = "..."))
} catch (e: SfVoiceMediaException) {
    println("${e.code} ${e.status}: ${e.message}")
}
```

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

### Error handling

Source: https://docs.sf-voice.sh/sdks/java

Catch and handle potential API errors using the SfVoiceMediaException class, which provides error codes, status, and messages.

```APIDOC
## Error handling

Catch and handle potential API errors using the SfVoiceMediaException class, which provides error codes, status, and messages.

```java
import com.sfvoice.media.SfVoiceMediaException;

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

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

### Ingest Media Asset

Source: https://docs.sf-voice.sh/sdks/elixir

Ingest a media asset by providing its source URL and metadata. The response contains a task ID that can be used to track the ingestion status. Request keys are atoms, while response keys are strings.

```elixir
{:ok, resp} = SfVoiceMedia.ingest(client, %{
  source: "url",
  asset_id: "call_001",
  asset_class: "customer_acme",
  url: "https://storage.example.com/calls/001.mp3",
  media_type: "audio",
  types: ["audio", "transcript"],
  metadata: %{caller: "+14155550199"}
})

task_id = resp.task_id
```

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

### Ingest Media Asset

Source: https://docs.sf-voice.sh/quickstart

Ingest an audio or video asset by providing a URL, a unique asset ID, and asset class for grouping. Specify the media type and desired output types (e.g., audio, transcript).

```typescript
const { task_id } = await client.ingest({
  source: "url",
  asset_id: "call_001",
  asset_class: "customer_acme",
  url: "https://example.com/call.mp3",
  media_type: "audio",
  types: ["audio", "transcript"],
});
```

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

### GetAsset

Source: https://docs.sf-voice.sh/sdks/go

Retrieves details for a specific asset by its ID.

```APIDOC
## GetAsset

### Description
Retrieves details for a specific asset by its ID.

### Method
GET

### Endpoint
/assets/{assetID}

### Parameters
#### Path Parameters
- **assetID** (string) - Required - The ID of the asset to retrieve.

### Response
#### Success Response (200)
- **Asset** (object) - The details of the requested asset.
  - **AssetID** (string) - The ID of the asset.
  - **MediaType** (string) - The media type of the asset.
  - [Other asset details would be described here if available in source]

### Response Example
```json
{
  "Asset": {
    "AssetID": "call_001",
    "MediaType": "audio"
  }
}
```
```

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

### Search Media Assets

Source: https://docs.sf-voice.sh/sdks/java

Perform a scoped search within media assets based on a query, asset class, and confidence threshold. Results include asset ID, timestamps, and score.

```java
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());
}
```

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

### Poll Task Until Ready

Source: https://docs.sf-voice.sh/sdks/java

Block until an indexing task is ready or fails, or until a specified timeout is reached. Handles task failure by throwing an exception.

```java
import com.sfvoice.media.models.Task;

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

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

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

### Handle SfVoiceMediaException

Source: https://docs.sf-voice.sh/sdks/java

Catch and handle SfVoiceMediaException to gracefully manage API errors, logging the error code, status, and message.

```java
import com.sfvoice.media.SfVoiceMediaException;

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

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

### Ingest

Source: https://docs.sf-voice.sh/sdks/go

Ingests media assets by providing a source URL and associated metadata. It returns a TaskID to poll for the processing status.

```APIDOC
## Ingest

### Description
Ingests media assets by providing a source URL and associated metadata. It returns a TaskID to poll for the processing status.

### Method
POST

### Endpoint
/ingest

### Parameters
#### Request Body
- **Source** (string) - Required - The source of the media (e.g., "url").
- **AssetID** (string) - Required - A unique identifier for the asset.
- **AssetClass** (string) - Required - The class or category of the asset.
- **URL** (string) - Required - The URL of the media file.
- **MediaType** (string) - Required - The type of media (e.g., "audio").
- **Types** (array of strings) - Required - The types of processing to perform (e.g., ["audio", "transcript"]).

### Response
#### Success Response (200)
- **TaskID** (string) - The ID of the ingestion task.

### Request Example
```json
{
  "Source": "url",
  "AssetID": "call_001",
  "AssetClass": "customer_acme",
  "URL": "https://storage.example.com/calls/001.mp3",
  "MediaType": "audio",
  "Types": ["audio", "transcript"]
}
```

### Response Example
```json
{
  "TaskID": "task_abc123"
}
```
```

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

### Handle Result Type

Source: https://docs.sf-voice.sh/sdks/cpp

Illustrates how to check the success or failure of an API call returning std::future<Result<T>>. Access the value on success or error details on failure.

```cpp
if (result) {
    // result.value() — the response
} else {
    // result.error().code, result.error().message, result.error().status
}
```

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

### Specify Indexed Content Types

Source: https://docs.sf-voice.sh/how-it-works

Control which aspects of an asset are indexed for search by specifying an array of types. Common types include 'audio', 'video', and 'transcript'.

```typescript
types: ["audio", "video", "transcript"]
```

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

### Asset Type Definition

Source: https://docs.sf-voice.sh/sdks/typescript

Defines the structure of an asset object, including its ID, media type, status, and metadata.

```typescript
type Asset = {
  asset_id: string;
  asset_class?: string;
  media_type: "audio" | "video";
  source_type: "url" | "s3" | "file";
  types: Array<"audio" | "video" | "transcript">
  status: "pending" | "indexing" | "ready" | "failed";
  metadata?: Record<string, string | number | boolean>;
  duration_ms?: number;
  created_at: string;
  updated_at: string;
};
```

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

### Ingest Media Asset

Source: https://docs.sf-voice.sh/sdks/java

Ingest a media asset from a URL, specifying asset details and desired output types. The response contains a task ID for polling.

```java
import com.sfvoice.media.models.IngestRequest;
import com.sfvoice.media.models.IngestResponse;

IngestRequest req = IngestRequest.fromUrl("https://storage.example.com/calls/001.mp3")
    .assetId("call_001")
    .assetClass("customer_acme")
    .mediaType("audio")
    .types(List.of("audio", "transcript"))
    .build();

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

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

### Search Specific Assets by ID

Source: https://docs.sf-voice.sh/sdks/typescript

Search for information within a predefined list of asset IDs. This is useful for targeted retrieval.

```typescript
const { results } = await client.search({
  query: "pricing question",
  asset_ids: ["call_001", "call_002"],
});
```

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

### Handle SfVoiceMedia Errors

Source: https://docs.sf-voice.sh/sdks/rust

Handle potential errors from the SDK, including API-specific errors with codes and messages, transport-level HTTP errors, and polling timeouts.

```rust
use sf_voice_media::SfVoiceMediaError;

match client.search(req).await {
    Ok(resp) => { /* use resp */ } 
    Err(SfVoiceMediaError::Api { code, message, status }) => {
        eprintln!("api error {status} [{code}]: {message}");
    }
    Err(SfVoiceMediaError::Http(e)) => {
        eprintln!("transport error: {e}");
    }
    Err(SfVoiceMediaError::PollTimeout { task_id }) => {
        eprintln!("timed out polling {task_id}");
    }
}
```

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

### Ingest media

Source: https://docs.sf-voice.sh/sdks/java

Ingest media assets by providing a URL and specifying asset details like ID, class, media type, and desired output types.

```APIDOC
## Ingest media

Ingest media assets by providing a URL and specifying asset details like ID, class, media type, and desired output types.

```java
import com.sfvoice.media.models.IngestRequest;
import com.sfvoice.media.models.IngestResponse;

IngestRequest req = IngestRequest.fromUrl("https://storage.example.com/calls/001.mp3")
    .assetId("call_001")
    .assetClass("customer_acme")
    .mediaType("audio")
    .types(List.of("audio", "transcript"))
    .build();

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

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

### Search

Source: https://docs.sf-voice.sh/sdks/go

Searches for assets based on a query and specified criteria. Returns a list of matching results with relevance scores.

```APIDOC
## Search

### Description
Searches for assets based on a query and specified criteria. Returns a list of matching results with relevance scores.

### Method
POST

### Endpoint
/search

### Parameters
#### Request Body
- **Query** (string) - Required - The search query.
- **AssetClass** (string) - Required - The class of assets to search within.
- **Types** (array of strings) - Required - The types of data to search (e.g., ["transcript"]).
- **Threshold** (float) - Optional - The minimum relevance score threshold.
- **Limit** (integer) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- **Results** (array of objects) - A list of search results.
  - **AssetID** (string) - The ID of the asset.
  - **StartMs** (integer) - The start time in milliseconds.
  - **EndMs** (integer) - The end time in milliseconds.
  - **Score** (float) - The relevance score of the result.

### Response Example
```json
{
  "Results": [
    {
      "AssetID": "call_001",
      "StartMs": 1500,
      "EndMs": 3000,
      "Score": 0.85
    }
  ]
}
```
```

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

### Search Assets

Source: https://docs.sf-voice.sh/sdks/typescript

Searches for assets based on various criteria. Allows filtering by query, asset types, class, IDs, scope, confidence threshold, and pagination.

```APIDOC
## POST /search

### Description
Searches for assets based on natural language queries and various filters.

### Method
POST

### Endpoint
/search

### Parameters
#### Query Parameters
- **query** (string) - Required - Natural language query.
- **types** (string[]) - Optional - Allowed values: "audio", "video", "transcript". Searches all if omitted.
- **asset_class** (string) - Optional - Restrict search to a specific logical group.
- **asset_ids** (string[]) - Optional - Restrict search to a specific set of assets.
- **scope** (string) - Optional - Set to "all" to search across indexed assets.
- **threshold** (number) - Optional - `0.0`–`1.0`. Default `0.5`. Higher values yield fewer, more confident results.
- **page** (number) - Optional - Page number for pagination.
- **limit** (number) - Optional - Results per page. Maximum of 50.

### Response
#### Success Response (200)
- **items** (array) - Array of SearchResult objects.
- **page_info** (object) - Pagination information.

### Result Shape
```ts
type SearchResult = {
  asset_id: string;
  score: number;      // 0.0–1.0
  start_ms: number;   // offset into the recording
  end_ms: number;
  match_type: "audio" | "video" | "transcript";
  thumbnail_url?: string;
};
```
```

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

### Search indexed assets

Source: https://docs.sf-voice.sh/sdks/typescript

Search across indexed recordings for specific queries. Supports searching by asset class, specific asset IDs, or all indexed assets.

```APIDOC
## Search

`search(request)` returns timestamped matches across indexed recordings.

### By asset class

Searches within a specified asset class.

```ts
const { results } = await client.search({
  query: "customer asks about cancelling their subscription",
  asset_class: "customer_acme",
  types: ["transcript"],
  threshold: 0.7,
  limit: 10,
});
```

### By specific assets

Searches within a list of specific asset IDs.

```ts
const { results } = await client.search({
  query: "pricing question",
  asset_ids: ["call_001", "call_002"],
});
```

### Search all indexed assets

Searches across all indexed assets. Use with caution as it can be less performant and may expose data across different scopes.

<Warning>
  `scope: "all"` searches across your indexed assets. Use `asset_class` or `asset_ids` for anything customer-facing.
</Warning>

```ts
const { results } = await client.search({
  query: "AI interrupted the caller",
  scope: "all",
});
```
```

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

### Ingest Media

Source: https://docs.sf-voice.sh/sdks/kotlin

Ingest media content by providing a source URL and specifying the media type. This returns a task ID to track the ingestion process.

```APIDOC
## Ingest Media

### Description
Ingest media content by providing a source URL and specifying the media type. This returns a task ID to track the ingestion process.

### Method
`ingest`

### Parameters
#### Request Body
- **source** (string) - Required - The source of the media (e.g., "url").
- **url** (string) - Required - The URL of the media file.
- **mediaType** (MediaType) - Required - The type of media (e.g., `MediaType.Audio`).

### Response
#### Success Response
- **taskId** (string) - The ID of the ingestion task.

### Code
```kotlin
import com.sfvoice.media.IngestRequest
import com.sfvoice.media.MediaType

val resp = client.ingest(
    IngestRequest(
        source = "url",
        url = "https://storage.example.com/calls/001.mp3",
        mediaType = MediaType.Audio
    )
)
val taskId = resp.taskId
```
```

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

### Asset management

Source: https://docs.sf-voice.sh/sdks/java

Manage ingested assets, including listing all assets, retrieving a specific asset by ID, and deleting an asset.

```APIDOC
## Asset management

Manage ingested assets, including listing all assets, retrieving a specific asset by ID, and deleting an asset.

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

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

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

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

### Poll Task Status until Ready using Go SDK

Source: https://docs.sf-voice.sh/sdks/go

Poll a task until it is completed or fails, with configurable interval and timeout. Handles potential timeout errors.

```go
task, err := client.PollTask(ctx, taskID, &sfvoice.PollOptions{
    IntervalMs: 2000,
    TimeoutMs:  120000,
})
if err != nil {
    return err // *sfvoice.PollTimeoutError if timed out
}

if task.Status == sfvoice.TaskStatusFailed {
    return fmt.Errorf("indexing failed: %s", task.Error)
}
```

```go
var pollErr *sfvoice.PollTimeoutError
if errors.As(err, &pollErr) {
    log.Printf("timed out polling task %s", pollErr.TaskID)
}
```

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

### Search Transcripts

Source: https://docs.sf-voice.sh/sdks/cpp

Searches ingested media transcripts for specific queries. Filters by asset class, desired types, and a similarity threshold. Results include asset ID and time range.

```cpp
sfvoice::SearchRequest req;
req.query       = "customer asks about pricing";
req.asset_class = "customer_acme";
req.types       = {"transcript"};
req.threshold   = 0.7f;

auto result = client.search(req).get();

if (result) {
    for (const auto& r : result.value().results) {
        std::cout << r.asset_id << " "
                  << r.start_ms << "–" << r.end_ms << "ms\n";
    }
}
```

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

### Search Transcripts

Source: https://docs.sf-voice.sh/quickstart

Perform a search query against indexed transcripts within a specified asset class. Results include asset ID, start/end timestamps, and a confidence score.

```typescript
const { results } = await client.search({
  query: "customer asks about pricing",
  asset_class: "customer_acme",
  types: ["transcript"],
  threshold: 0.7,
});

for (const r of results) {
  console.log(r.asset_id, r.start_ms, r.end_ms, r.score);
}
```

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

### Ingest Asset with ID

Source: https://docs.sf-voice.sh/how-it-works

Ingest an asset using its URL, providing a unique asset_id for later retrieval and joining with your system's data. The asset_class helps define search boundaries.

```typescript
await client.ingest({
  source: "url",
  asset_id: "call_8294",
  asset_class: "customer_acme",
  url: "https://storage.example.com/calls/8294.mp3",
});
```

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

### Search Media

Source: https://docs.sf-voice.sh/sdks/kotlin

Perform a search query against the indexed media. You can specify match types, a confidence threshold, and the number of results to return.

```APIDOC
## Search Media

### Description
Perform a search query against the indexed media. You can specify match types, a confidence threshold, and the number of results to return.

### Method
`search`

### Parameters
#### Request Body
- **query** (string) - Required - The search query string.
- **types** (List<SearchMatchType>) - Optional - A list of media types to search within (e.g., `listOf(SearchMatchType.Conversation)`).
- **threshold** (Float) - Optional - The minimum confidence score for a match (e.g., 0.7f).
- **limit** (Int) - Optional - The maximum number of results to return (e.g., 10).

### Response
#### Success Response
- **results** (List<SearchResult>) - A list of search results, each containing `assetId`, `startMs`, `endMs`, and `score`.

### Code
```kotlin
import com.sfvoice.media.SearchMatchType
import com.sfvoice.media.SearchRequest

val resp = client.search(
    SearchRequest(
        query = "customer asks about pricing",
        types = listOf(SearchMatchType.Conversation),
        threshold = 0.7f,
        limit = 10
    )
)

resp.results.forEach { r ->
    println("${r.assetId} ${r.startMs}–${r.endMs}ms (${r.score})")
}
```
```
Tokens:
Raw