Skip to content

Developer documentation

Resonance 2 API reference

Resonance 2 analyzes how speech sounds. Send a recording or commit a WebSocket audio range to receive 31 emotion and speaking-style scores with six signed axes. It does not transcribe speech. The preview uses your speech understanding allowance, and new organizations need separate model approval.

Preview

Resonance 2: emotion and speaking style

Analyze vocal expression with oruk-resonance-2. The model returns continuous scores for 15 emotions and 16 speaking styles. Six opposite pairs share signed axes, so both ends of a pair can never be selected together.

Access approval

Existing accounts keep access. New organizations need approval for Resonance 2, separate from plan activation. Request it from Model access or with the API below. Approval covers every API key in the organization. The homepage demo stays available without approval.

Request Resonance 2 access
curl --fail-with-body 'https://speech-api.oruk.ai/v1/models/oruk-resonance-2/access' \
  -H "Authorization: Bearer $ORUK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"use_case":"Voice coaching for consenting participants in our application."}'

POST returns 202 while pending. GET on the same path returns status and approved. Inference returns 403 with model_access_required until approved; denied requests are not billed. Approval alone does not add credit or activate a plan. A Resonance 2 invitation code provides a seven-day trial on a self-serve tier, requires a credit card, and grants access immediately after completed checkout. The trial becomes a paid subscription unless canceled.

Same plans, same price

Same price as Resonance 1. One audio minute uses one minute from your existing speech understanding allowance, with the same overage rate. No plan change or separate add-on.

Use your existing Bearer API key. Monthly and annual plans share the same audio-minute accounting, trial allowance, and spending cap. Usage is measured by the second with a one-second minimum. Legacy metered accounts use the Resonance 1 affect rate, $0.0100 per audio minute.

File request (HTTP)

POST /v1/audio/resonance-2 accepts multipart file and optional model=oruk-resonance-2. Use WAV, FLAC, MP3, M4A, OGG, or WebM: 0.1–120 seconds, up to 30 MiB. Audio is decoded to mono 16 kHz. The query parameter regime=f1 is the default; regime=precision selects the more conservative label thresholds. Continuous scores stay the same.

Resonance 2 · cURL
curl --fail-with-body 'https://speech-api.oruk.ai/v1/audio/resonance-2?regime=f1' \
  -H "Authorization: Bearer $ORUK_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -F model=oruk-resonance-2 \
  -F file=@clip.wav

This POST returns one clip-level affect result after the upload. It does not return a transcript, word timings, speaker diarization, or streaming events. The separate WebSocket route below accepts audio while it is being recorded. Keep using oruk-resonance for transcription and unified analysis. SDK 0.2.10 has no dedicated Resonance 2 helper; use an HTTP request for this contract.

Download the Resonance 2 OpenAPI schema.

Stream audio over WebSocket

Connect to wss://speech-api.oruk.ai/v1/audio/resonance-2/stream with Authorization: Bearer $ORUK_API_KEY in the upgrade request. Use a server-side WebSocket client that supports headers. This route does not accept an API key in the URL or a browser authentication subprotocol; keep your key on your server. The public microphone demos use a separate server-authenticated connection.

Wait for type: ready with sample_rate: 16000, encoding: float32le, and idempotency: shared_http_ws. Send mono 16 kHz float32 little-endian PCM as binary frames, without a WAV header. Each frame holds 1–16,000 finite samples (at most 64,000 bytes). The buffer holds up to 120 seconds. Audio frames alone do not request inference; send a JSON commit to analyze a buffered range. Sample offsets start at zero; end_sample is exclusive.

Commit the first two seconds of buffered audio
{
  "type": "commit",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "start_sample": 0,
  "end_sample": 32000,
  "regime": "f1",
  "scope": "live"
}

Generate a new stable request ID for each analysis. Use regime: f1 (default) or precision. Public API commits can select 0.1–120 seconds; scope is optional and accepts live or clip. For live updates, use rolling windows of up to 20 seconds, then commit the full clip when recording stops. Public commits are not capped at 20 seconds by scope: live. The website demos have tighter limits: 20 seconds per live window and 30 seconds per full clip.

A successful commit returns {"type":"result","id":"…","result":{…},"timings_ms":{…}}. The result has the same fields, window aggregation, and label thresholds as HTTP. Errors use type: error with id, status, and error. These are expression snapshots of the committed range, without a transcript, word timestamps, diarization, or automatic speech-boundary events.

Each new commit uses the same billing rules as an HTTP request, including the one-second minimum. Repeated analyses of overlapping ranges count separately. Authorization, model access, and available usage are checked live for every commit. After a lost response, use the original API key and the same ID, decoded PCM, and regime over WebSocket or HTTP; set HTTP X-Request-IDto the commit ID. A completed result can be replayed for 24 hours without a second charge, while a revoked or expired key remains invalid. Only 409 request_in_progressmeans the original analysis is still pending; a conflicting payload must not be retried as a fresh paid request automatically.

Send {"type":"reset"} between clips to clear the audio buffer and restart sample offsets at zero. A session allows at most 256 commits, 10 minutes total, and 30 seconds without a received message. Resetting does not reset these limits. SDK 0.2.10 has no dedicated Resonance 2 streaming helper; use this WebSocket protocol directly. Upload streaming avoids resending the buffered audio at each commit; response time still includes admission, inference, result storage, and network travel.

Read continuous scores

Each axis ranges from −1 to +1. Negative values favor the first label; positive values favor the second. Zero means no preference between them. For example, sad__happy: -0.8 gives sad a score of 0.8 and happy a score of 0. This is an 80% dominance score, not an 80% probability of a person being sad.

Six signed emotion and style axes
Axis key−1+1
sad__happysadhappy
worried__relievedworriedrelieved
disappointed__hopefuldisappointedhopeful
hesitant__confidenthesitantconfident
tired__energetictiredenergetic
formal__casualformalcasual

The remaining 19 labels range independently from 0 to 1: excited, angry, frustrated, scared, disgusted, surprised, embarrassed, proud, neutral, passionate, irritated, warm, playful, sarcastic, deadpan, sincere, skeptical, impatient, distracted. Scores do not sum to one. The selected labels list applies the chosen thresholds and may be empty; the model never forces a top label.

Response fields

scores · axes · unipolar · labels
All 31 label scores, six signed axes, 19 independent scores, and selected label/score pairs.
duration · window_count · aggregation
Measured seconds and the number of nonoverlapping 20-second windows. Longer clips average window logits before calibration; aggregation is mean_window_logits.
model · model_revision · calibration_revision · regime
Model identity, pinned artifact revisions, and the selected threshold regime.
abstained · abstention_reason
Exact digital silence returns zero scores, no labels, and digital_silence. This is not a general voice-activity detector.
id · object · task · usage
Request identity, speech.affect.result, affect, and measured/billable seconds. Reference cost fields are not the subscription invoice.

Keep the same X-Request-ID, audio, and regime when retrying a request. Completed results can be replayed for 24 hours without a second charge; changing the audio or regime with the same ID returns 409. Back off on 429 or 503 and retry.

The model reads acoustic expression without requiring a transcript or language code. Performance varies by language and recording conditions; language-independent accuracy is not established. Scores describe how speech sounds, not a person’s inner state.

To inspect the evaluation, download the 546 recorded responses and replay the diagnostic. The package includes calibration thresholds, the protocol, and an offline scorer. It uses acted recordings of one sentence from development data, with unaudited training overlap. It is not an independent evaluation of the current API on new audio.