Skip to main content
Velma Triage analyzes conversations rather than audio characteristics. It evaluates a configured set of behaviors against the transcript and reports which ones were detected, with the clips that triggered each detection, alongside a conversation type, per-speaker roles, topics, per-topic sentiment, and a summary. Behaviors come from a catalog of presets, from definitions written for the deployment, or from both. Velma transcribes as part of its analysis. The diarized transcript is returned as clips, so a separate transcription call on the same audio is redundant.

Velma Triage (batch)

Returns application/json. duration_ms, clips, behaviors, and model_version are always present. The rest depend on configuration. Each entry in clips carries clip_uuid, text, start_ms, duration_ms, speaker_label, language, and the optional emotion, accent, and deepfake_score signals, which are null unless enabled in the stt block. Each clip also carries deepfake: a standalone reading (from the clip’s own deepfake_score alone) and a context reading (informed by the speaker’s earlier clips, with a changed flag set when the verdict flips from that speaker’s previous clip). deepfake is null exactly when deepfake_score is null. Each entry in behaviors carries behavior_uuid, behavior_name, speaker_label, detected, confidence, evidence_clip_uuids, definitive_clip_uuid, reasoning, occurrence_index, occurrence_count, truncated, and trigger_limit. Entries appear for every behavior evaluated, so detected: false means the behavior was checked and not found. When a behavior’s trigger_limit allows more than one detection, a speaker can have several entries for the same behavior, one per occurrence. occurrence_index numbers them from 1, occurrence_count is how many were returned, and truncated is true when more occurrences were found than trigger_limit allowed. See Detecting a behavior more than once. conversation_type_pick and each entry in participant_role_picks carry a confidence and a selection_source of inferred, auto_selected_single_option, or default, which distinguishes a real inference from a fallback.

Try it

Output

What you can configure

Configuration travels in one config form field, holding either the literal string default or a JSON-encoded object.
Passing a custom config without a behaviors key evaluates no behaviors. There is no implicit run-everything. This differs from conversation_types and participant_roles, which do fall back to built-in defaults when omitted.Omitting config entirely, or sending the literal default, loads a curated built-in configuration that does include behaviors. To evaluate against a broad set, list the preset:<identifier> references explicitly.
Preset identifiers come from GET /api/velma-2-batch/list-presets, which returns each preset’s identifier, name, short_description, and detailed_description:
A malformed config, an unknown preset identifier, or a definition missing a required field is rejected with 422.

Audio formats

Accepted extensions: .aac, .aiff, .flac, .mov, .mp3, .mp4, .ogg, .opus, .wav, .webm. Maximum file size is 100 MB. Files above it are rejected with 413. Empty files are rejected with 400.

Velma Triage (streaming)

The same analysis, emitted as typed JSON events while the conversation is still running. Connect, send the config as the first text frame, then stream audio. Several events have update semantics worth building for:
  • partial_clip is a transient preview. Multiple partials share one clip_uuid, and the eventual clip reuses it, so a run of partials correlates with its final clip.
  • clip_update can arrive any number of times for a finalized clip, always before done. The latest value for each field supersedes the value on the clip event and on any earlier update. Read deepfake_score from the update: until a clip has a reading of its own, the score on clip and partial_clip repeats the most recent reading in the stream. With audio_quality_signal on, the clip’s audio_quality measurement also arrives on the update.
  • topics and summary fully replace the previous event of that type. Never merge them. topic_sentiment supersedes an earlier event for the same topic and speaker.
  • conversation_dynamics fully replaces the previous event of that type and arrives after each finalized clip, then once more before done. interruption, false_start, and repeat are emitted once each, when first found; later conversation_dynamics events keep listing them.
  • assessment events can arrive well after the clip they judge. The assessments event before done repeats all of them with coverage counts, so a stream with few events and low turns_assessed is incomplete, not healthy.
  • deepfake_summary covers the conversation so far. The last one, immediately before done, is authoritative.
Event shapes and field definitions are on the Velma Triage Streaming reference.

Try it

Python
Output
Each partial_clip overwrites the one before it on the same terminal line, so the in-progress text is visible in place until its clip replaces it.
A stream ends with an empty text frame. A shell pipe sends binary frames only, so curl and websocat cannot close a stream cleanly. Use one of the clients above.

What you can configure

The config object is the same one used by batch, sent as the first text frame instead of a form field. Because it rides on that frame, language and custom_terms in the stt block travel with it and need no separate transport. These keys select the events that are only emitted on request. All four keys are shared with batch, which returns the same data as response fields instead of events; see the config table in the batch section above.
The config frame must arrive before any audio. Sending audio first closes the connection with 1003.

Audio formats

Self-describing formats. aac, aiff, flac, mp3, ogg, wav, webm. Auto-detected when audio_format is omitted. Raw formats. s8, s16le, s16be, s24le, s24be, s32le, s32be, u8, u16le, u16be, u24le, u24be, u32le, u32be, f32le, f32be, f64le, f64be, mulaw, alaw. Headerless, so audio_format, sample_rate, and num_channels are all required. sample_rate accepts 8000, 11025, 16000, 22050, 32000, 44100, 48000, 96000.

Behaviors

Combining with Deepfake Detection

Behavior detections say what a caller did, not whether the voice was synthetic. Screen a call for voice fraud runs Velma Triage alongside Deepfake Detection on one recording and combines both outputs into a single decision.

API reference