Quick start

This page goes from nothing to a transcript. The same shape applies to every other Modulate model: one key, one request, one response.

Before starting

Get an API key

Create a free account, then create a key from the API Keys tab in the dashboard.

Store the key

Set it as an environment variable rather than hard-coding it.

export MODULATE_API_KEY=your_api_key_here

Get a sample audio file

Download the sample clip into the working directory. The examples below read audio.mp3 from there.

curl -sSO https://docs.modulate.ai/samples/audio.mp3

The sample is 17 seconds of one speaker. Any speech clip of 5 to 30 seconds works in its place.

The curl example pipes the response through jq to render it. The Python example needs requests:

brew install jq          # or: apt install jq
pip install requests

Make the first call

curl -sS -X POST https://platform.modulate.ai/api/velma-2-stt-batch \
  -H "X-API-Key: $MODULATE_API_KEY" \
  -F "upload_file=@audio.mp3" \
| jq -r 'if .detail then "error: \(.detail)" else
    .text, (.utterances[] | "  [\(.start_ms)ms] Speaker \(.speaker): \(.text)")
  end'

import os, requests

response = requests.post(
    "https://platform.modulate.ai/api/velma-2-stt-batch",
    headers={"X-API-Key": os.environ["MODULATE_API_KEY"]},
    files={"upload_file": open("audio.mp3", "rb")},
)
response.raise_for_status()
result = response.json()

print(result["text"])
for u in result["utterances"]:
    print(f"  [{u['start_ms']}ms] Speaker {u['speaker']}: {u['text']}")

import fs from "fs";
import FormData from "form-data";

const form = new FormData();
form.append("upload_file", fs.createReadStream("audio.mp3"), { filename: "audio.mp3" });

const response = await fetch("https://platform.modulate.ai/api/velma-2-stt-batch", {
  method: "POST",
  headers: { "X-API-Key": process.env.MODULATE_API_KEY, ...form.getHeaders() },
  body: form,
});

const result = await response.json();

if (!response.ok) {
  console.error(`error: ${result.detail}`);
  process.exit(1);
}

console.log(result.text);
for (const u of result.utterances) {
  console.log(`  [${u.start_ms}ms] Speaker ${u.speaker}: ${u.text}`);
}

Output

Thanks for holding. I've pulled up your account, and it looks like the charge you're asking about posted on Tuesday afternoon. I can open a dispute for you right now, or if you'd rather, I can walk you through what the merchant listed on the statement first. Either way, nothing is final until you confirm it.
  [350ms] Speaker 1: Thanks for holding.
  [1510ms] Speaker 1: I've pulled up your account, and it looks like the charge you're asking about posted on Tuesday afternoon.
  [7030ms] Speaker 1: I can open a dispute for you right now, or if you'd rather, I can walk you through what the merchant listed on the statement first.
  [14590ms] Speaker 1: Either way, nothing is final until you confirm it.

A rejected call prints the server’s message in place of the transcript:

Output

error: Invalid API key

Every error response carries a detail field, which is what the if at the front of the jq filter reads. The same guard is on the curl example for every endpoint. The response is application/json.

Response

{
  "text": "Thanks for holding. I've pulled up your account, and it looks like the charge you're asking about posted on Tuesday afternoon. I can open a dispute for you right now, or if you'd rather, I can walk you through what the merchant listed on the statement first. Either way, nothing is final until you confirm it.",
  "duration_ms": 17496,
  "utterances": [
    {
      "utterance_uuid": "5bed95f4-bd8f-495c-a6b8-5acd2f8aa549",
      "text": "Thanks for holding.",
      "start_ms": 350,
      "duration_ms": 1040,
      "speaker": 1,
      "language": "en",
      "emotion": null,
      "accent": null,
      "deepfake_score": null
    },
    {
      "utterance_uuid": "3d534a5f-30a6-48e2-b3f5-bf1b5e735e7b",
      "text": "I've pulled up your account, and it looks like the charge you're asking about posted on Tuesday afternoon.",
      "start_ms": 1510,
      "duration_ms": 5520,
      "speaker": 1,
      "language": "en",
      "emotion": null,
      "accent": null,
      "deepfake_score": null
    },
    {
      "utterance_uuid": "829017e8-54f6-48d0-8150-89a90e2fb5c0",
      "text": "I can open a dispute for you right now, or if you'd rather, I can walk you through what the merchant listed on the statement first.",
      "start_ms": 7030,
      "duration_ms": 7080,
      "speaker": 1,
      "language": "en",
      "emotion": null,
      "accent": null,
      "deepfake_score": null
    },
    {
      "utterance_uuid": "70507be1-ebf2-4346-a0bb-c867da72e756",
      "text": "Either way, nothing is final until you confirm it.",
      "start_ms": 14590,
      "duration_ms": 2560,
      "speaker": 1,
      "language": "en",
      "emotion": null,
      "accent": null,
      "deepfake_score": null
    }
  ]
}

text is the full transcript. utterances breaks it into speaker turns with millisecond timing and a language detected per utterance. emotion, accent, and deepfake_score are null until those signals are enabled. See Transcription. Response formats differ across the API. Most endpoints return JSON, PII/PHI Redaction batch returns multipart/form-data, and the streaming endpoints return sequences of JSON messages, some interleaved with binary audio frames. Each capability page states the format for its endpoints.

Go deeper by capability

Each page states what the endpoint returns, what can be configured, the accepted audio formats, and a runnable call for every endpoint in that family.

Velma Triage

Behaviors, topics, sentiment, and a summary across a whole conversation.

Transcription

Multilingual, English Fast, and Multilingual Fast. Batch and streaming.

Deepfake Detection

Per-frame synthetic-voice verdicts on files or live audio.

PII/PHI Redaction

A redacted transcript plus audio with the sensitive ranges silenced.

Emotion Detection

A whole-file emotion label plus a per-window time series.

Accent Detection

A whole-file accent label plus a per-window time series.

Music & Speech Detection

Frame-level music and speech probabilities.

AI Music Detection

Whether a track contains AI-generated vocals or instrumentals.

Audio Event Detection

Which non-speech sound events are present, from a vocabulary of 42 spanning instruments to gunshots.

Language Detection

The spoken language of a clip, with a confidence score.

Which API should I use? works from the output backwards to the endpoint that produces it.

Combine models

One endpoint answers one question. Most production decisions read two or more outputs together.

Screen a call for voice fraud

Run Deepfake Detection and Velma Triage on one recording, aggregate the frame verdicts, and combine both outputs into a single screening decision.

Get started

By capability

Build end to end

Guides

Before starting

Make the first call

Go deeper by capability

Velma Triage

Transcription

Deepfake Detection

PII/PHI Redaction

Emotion Detection

Accent Detection

Music & Speech Detection

AI Music Detection

Audio Event Detection

Language Detection

Combine models

Screen a call for voice fraud

​Before starting

​Make the first call

​Go deeper by capability

Velma Triage

Transcription

Deepfake Detection

PII/PHI Redaction

Emotion Detection

Accent Detection

Music & Speech Detection

AI Music Detection

Audio Event Detection

Language Detection

​Combine models

Screen a call for voice fraud

Before starting

Make the first call

Go deeper by capability

Combine models