Quickstart

Install the TypeScript SDK, ingest one recording, wait for it to index, and run a search.

Get an API token

Sign in to the dashboard and open Settings → API tokens to create one. New orgs see a one-click onboarding modal that mints a token labeled default. The full token is shown once — copy it into a password manager or secrets store before closing the dialog. See API tokens for revocation and best practices. Export the token where the SDK can read it:

export SF_VOICE_API_KEY="sk_live_…"

Install

pnpm add @sf-voice/media@0.1.1

npm install @sf-voice/media@0.1.1

bun add @sf-voice/media@0.1.1

Create a client

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

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

Ingest a recording

Pass your own asset_id — this is how you’ll identify the recording in search results. Use asset_class to group recordings that belong to the same customer or workspace.

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"],
});

Wait for indexing

const task = await client.pollTask(task_id, {
  intervalMs: 2_000,
  timeoutMs: 120_000,
});

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

Search

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);
}

Results include start_ms and end_ms so you can jump a player to the matching segment.

Full example

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;
}

Get Started

Platform

SDKs

Examples

Changelog