SfVoiceMedia (sf_voice v0.1.1)

Elixir SDK for the sf-voice media API.

build a client with new/2, then call the public functions to ingest, query, and search media.

quick start

client = SfVoiceMedia.new("sk-...")

# 1. ingest a media file — returns immediately with a task id
{:ok, %{task_id: tid}} =
  SfVoiceMedia.ingest(client, %{source: :url, url: "https://example.com/clip.mp4"})

# 2. wait for indexing to complete — raises on failure or timeout
task = SfVoiceMedia.poll_task!(client, tid)

# 3. search across your indexed media with natural language
{:ok, %{results: results}} =
  SfVoiceMedia.search(client, %{query: "product roadmap discussion"})

# results carry timestamps so you can jump to the exact moment
Enum.each(results, fn r ->
  IO.puts("#{r.asset_id} at #{r.start_ms}ms — #{r.match_type}")
end)

all functions return {:ok, result} or {:error, %SfVoiceMedia.Error{}}. poll_task!/3 raises SfVoiceMedia.Error on timeout or task failure.

Summary

Functions

delete_asset(client, id)

Soft-deletes an asset so it is excluded from list results while the backend retains the record.

get_asset(client, id)

Retrieve a library asset by its ID.

get_task(client, task_id)

Fetches the current state of an ingestion task.

ingest(client, request)

Submit a media file for ingestion from a URL or an S3 key.

list_assets(client, params \\ %{})

lists assets in the library, paginated.

new(api_key, opts \\ [])

Builds a SfVoiceMedia.Client preconfigured with the given API key and optional settings.

poll_task!(client, task_id, opts \\ [])

Polls an ingestion task until its status becomes "ready" or "failed".

search(client, request)

Run a semantic search over indexed media.

Functions

delete_asset(client, id)

@spec delete_asset(SfVoiceMedia.Client.t(), String.t()) ::
  :ok | {:error, SfVoiceMedia.Error.t()}

Soft-deletes an asset so it is excluded from list results while the backend retains the record.

Returns :ok if the deletion was successful (HTTP 204), {:error, %SfVoiceMedia.Error{}} otherwise.

Examples

:ok = SfVoiceMedia.delete_asset(client, "ast_abc123")

get_asset(client, id)

@spec get_asset(SfVoiceMedia.Client.t(), String.t()) ::
  {:ok, SfVoiceMedia.Types.asset()} | {:error, SfVoiceMedia.Error.t()}

Retrieve a library asset by its ID.

Returns {:ok, asset} when the asset is found, or {:error, %SfVoiceMedia.Error{}} on failure.

get_task(client, task_id)

@spec get_task(SfVoiceMedia.Client.t(), String.t()) ::
  {:ok, SfVoiceMedia.Types.task()} | {:error, SfVoiceMedia.Error.t()}

Fetches the current state of an ingestion task.

Returns {:ok, task} where task is a map describing the task (includes a "status" field), or {:error, %SfVoiceMedia.Error{}} on failure.

Examples

{:ok, %{status: "ready", asset_id: aid}} = SfVoiceMedia.get_task(client, "task_abc123")

ingest(client, request)

@spec ingest(SfVoiceMedia.Client.t(), SfVoiceMedia.Types.ingest_request()) ::
  {:ok, SfVoiceMedia.Types.ingest_response()} | {:error, SfVoiceMedia.Error.t()}

Submit a media file for ingestion from a URL or an S3 key.

Returns immediately with a task identifier that can be inspected with get_task/2 or awaited with poll_task/3.

Returns

{:ok, response} — successful response containing at least task_id and optionally asset_id and other task metadata.
{:error, %SfVoiceMedia.Error{}} — request failed; contains error details.

list_assets(client, params \\ %{})

@spec list_assets(SfVoiceMedia.Client.t(), SfVoiceMedia.Types.list_assets_params()) ::
  {:ok, SfVoiceMedia.Types.asset_list_response()}
  | {:error, SfVoiceMedia.Error.t()}

lists assets in the library, paginated.

examples

{:ok, %{items: items, page_info: info}} =
  SfVoiceMedia.list_assets(client, %{page: 1, limit: 20})

# no params — uses server defaults
{:ok, %{items: items}} = SfVoiceMedia.list_assets(client)

new(api_key, opts \\ [])

@spec new(
  String.t(),
  keyword()
) :: SfVoiceMedia.Client.t()

Builds a SfVoiceMedia.Client preconfigured with the given API key and optional settings.

Options

:base_url — API base URL; defaults to "https://api.sf-voice.com". A trailing / is removed.
:http_opts — keyword list forwarded to Req for every request; defaults to [].

Examples

client = SfVoiceMedia.new("sk-my-api-key")

client = SfVoiceMedia.new("sk-my-api-key",
  base_url: "https://staging.api.sf-voice.com",
  http_opts: [receive_timeout: 10_000]
)

poll_task!(client, task_id, opts \\ [])

Polls an ingestion task until its status becomes "ready" or "failed".

polls get_task/2 at a fixed interval. returns the final task map when the task reaches "ready". raises SfVoiceMedia.Error if the task fails or the timeout is exceeded.

options

:interval_ms — milliseconds to wait between polls (default: 1_500)
:timeout_ms — maximum total wait in milliseconds (default: 120_000)

examples

task = SfVoiceMedia.poll_task!(client, tid)
task = SfVoiceMedia.poll_task!(client, tid, interval_ms: 2_000, timeout_ms: 60_000)

search(client, request)

@spec search(SfVoiceMedia.Client.t(), SfVoiceMedia.Types.search_request()) ::
  {:ok, SfVoiceMedia.Types.search_response()} | {:error, SfVoiceMedia.Error.t()}

Run a semantic search over indexed media.

The request map must include a :query string and may include optional parameters such as :types (list of asset types), :threshold (similarity threshold), and :limit (maximum results). Returns the API response wrapped in {:ok, result} or {:error, %SfVoiceMedia.Error{}}.

Examples

{:ok, %{results: results}} =
  SfVoiceMedia.search(client, %{query: "product roadmap discussion"})

{:ok, %{results: results}} =
  SfVoiceMedia.search(client, %{
    query: "quarterly targets",
    types: [:conversation],
    threshold: 0.7,
    limit: 10
  })