clips, so a separate transcription call on the same audio is redundant.
Velma Triage (batch)
Returnsapplication/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
Response
Response
What you can configure
Configuration travels in oneconfig form field, holding either the literal string default or a JSON-encoded object.
A config with every key set
A config with every key set
GET /api/velma-2-batch/list-presets, which returns each preset’s identifier, name, short_description, and detailed_description:
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_clipis a transient preview. Multiple partials share oneclip_uuid, and the eventualclipreuses it, so a run of partials correlates with its final clip.clip_updatecan arrive any number of times for a finalized clip, always beforedone. The latest value for each field supersedes the value on theclipevent and on any earlier update. Readdeepfake_scorefrom the update: until a clip has a reading of its own, the score onclipandpartial_cliprepeats the most recent reading in the stream. Withaudio_quality_signalon, the clip’saudio_qualitymeasurement also arrives on the update.topicsandsummaryfully replace the previous event of that type. Never merge them.topic_sentimentsupersedes an earlier event for the same topic and speaker.conversation_dynamicsfully replaces the previous event of that type and arrives after each finalized clip, then once more beforedone.interruption,false_start, andrepeatare emitted once each, when first found; laterconversation_dynamicsevents keep listing them.assessmentevents can arrive well after the clip they judge. Theassessmentsevent beforedonerepeats all of them with coverage counts, so a stream with few events and lowturns_assessedis incomplete, not healthy.deepfake_summarycovers the conversation so far. The last one, immediately beforedone, is authoritative.
Try it
Python
Output
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.
Events received
Events received
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.
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
- What are behaviors?
- Using behaviors
- Custom behaviors
- Best practices
- Detection packages, ready-made behavior sets for fraud, trust and safety, compliance, and retention