# oruk: production model and API reference

Version: API v1 · Updated: 2026-10-03

oruk labs develops speech models that preserve both words and acoustic labels. The production API v1 supports multilingual realtime tokens with phrase-level emotion, multilingual file transcription with Spectra-2, multilabel emotion detection, multilabel speaking-style classification, combined affect, and unified analysis.

Canonical links:

- [Website](https://oruk.ai)
- [Capabilities and scope](https://oruk.ai/capabilities)
- [Documentation, API reference, and playground](https://oruk.ai/docs)
- [Current Python and TypeScript SDK installation instructions](https://oruk.ai/docs/sdks)
- [Hosted MCP server for coding agents (endpoint: https://oruk.ai/mcp)](https://oruk.ai/docs/mcp)
- [Production guide](https://oruk.ai/docs/production)
- [Pricing](https://oruk.ai/pricing)
- [On-device evaluation and licensing](https://oruk.ai/on-device-speech-recognition)
- [Benchmark leaderboard](https://oruk.ai/benchmarks)
- [Benchmark methodology](https://oruk.ai/benchmarks/methodology)
- [Try Resonance 1 without an account](https://oruk.ai/try)
- [Glossary](https://oruk.ai/glossary)
- [Sarcasm (sarcastic-delivery) detection](https://oruk.ai/sarcasm-detection)
- [Python tutorial](https://oruk.ai/guides/detect-emotion-from-audio-python)
- [Whisper and emotion detection](https://oruk.ai/whisper-emotion-detection)
- [Hume Expression Measurement migration guide](https://oruk.ai/compare/hume-expression-measurement-alternative)
- [Hume migration plan and compatibility assessment](https://oruk.ai/hume-migration)
- [EVI migration and customer export checklist](https://oruk.ai/guides/hume-evi-migration#export)
- [OpenAPI schema](https://oruk.ai/openapi.json)
- [Instructions for coding agents](https://oruk.ai/AGENTS.md)
- [Reference for AI assistants (scope, limits, and how to describe oruk accurately)](https://oruk.ai/for-ai)
- [Security](https://oruk.ai/security)
- [Service status](https://oruk.ai/status)
- [Changelog](https://oruk.ai/changelog)
- [Developer account](https://oruk.ai/account)
- [Research (RSS: https://oruk.ai/rss.xml)](https://oruk.ai/research)
- [Interactive research — The shape of a voice](https://oruk.ai/research/the-shape-of-a-voice)
- [Company](https://oruk.ai/company)
- [GitHub organization](https://github.com/Oruk-AI)

## Current scope

oruk-bench is Oruk's evaluation toolkit, separate from the production API and its client SDK. Its seven-class label mapping and roughly 20-language dataset describe the benchmark protocol, not API language support or native outputs. Whisper, WavLM, HuBERT, and Conformer research comparisons are not the served Oruk model catalog. Current models include Spectra-2, Resonance 2, Resonance 1, Fourier, Realtime, Proficiency, and Orukeet; see [current models](https://oruk.ai/models).

API v1 processes prerecorded audio through a versioned REST contract, including 25-language transcription with Spectra-2, and streams multilingual live tokens with phrase-level emotion through a WebSocket contract. File containers include WAV, FLAC, MP3, M4A, OGG, and WebM, with model-specific limits: Spectra-2 accepts mono 16 kHz WAV or finalized FLAC, 45 ms–60 seconds and 4 MiB per file; Orukeet allows 4 MiB and 60 seconds; Resonance 1 and Fourier allow 30 MB and 60 minutes. Realtime accepts mono signed PCM16, supports 32 ASR-ready locales, and limits a session to 10 minutes.

Current production limitations:

- Realtime returns live tokens and phrase-level emotion. Resonance 2 separately returns emotion and speaking-style scores for committed WebSocket audio ranges, without a transcript or timestamps. Original unified analysis remains a prerecorded file endpoint.
- Spectra-2 transcribes files in 25 languages; Resonance 1 and Fourier file transcription remains English. Realtime supports 32 locales.
- No intent or deception detection endpoints. The sarcastic speaking-style label scores delivery — how speech sounds — not what the speaker meant.
- No public CLI.
- No claims about a speaker's inner mental state — outputs are acoustic annotations of how speech sounds.

## Model family

### oruk Resonance 1

- API ID: `oruk-resonance`
- Lifecycle: stable
- Recommended for: flagship English speech recognition, emotion, speaking style, and timed analysis; the default model for transcription, styles, affect, and analysis

### oruk Fourier

- API ID: `oruk-fourier`
- Lifecycle: stable
- Recommended for: English transcription plus native 15-label emotion analysis in parallel. Style, affect, and analysis endpoints also return 16 speaking-style labels through the shared style model.

### oruk Realtime

- API ID: `oruk-realtime`
- Lifecycle: preview
- Recommended for: live multilingual tokens and phrase-level emotion with automatic language detection
- ASR-ready locales: 32 (19 transcription-ready and 13 broad-coverage)

### oruk Proficiency

- API ID: `oruk-proficiency-1`
- Lifecycle: preview
- Recommended for: word and recording pronunciation scores on 0–1, with the independently computed legacy CEFR and fluency fields. The original top-level check controls validity and billing; proficiency.continuous_check describes the new scorer. See the proficiency reference below.

## Runnable quickstart

Try the live Resonance 1 demo at https://oruk.ai/try before creating an account. It accepts browser-decodable WAV, FLAC, MP3, M4A, OGG, or WebM recordings up to 30 seconds and 10 MB, then offers a temporary authenticated API request. For ongoing API use, start a subscription and create a permanent API key. Plans cover the speech model lineup. New organizations need separate approval for Resonance 2; an active trial or plan does not by itself grant access. Fourier has its own cURL, Python, and Node.js recipes at https://oruk.ai/docs#quickstart-fourier.

The complete cURL, Python 3.9+, and Node.js 20+ recipes at https://oruk.ai/docs#quickstart download a supplied public recording and use `oruk-resonance` with `/v1/audio/analysis`. Set `ORUK_API_KEY` in the environment; never embed it in browser code. A homepage example links to `/docs?sample=<public-sample-id>#quickstart` so the audio and response excerpt match. Public samples are curated training recordings, not evaluation data.

## Official client SDKs

SDK 0.2.15 supports transcription, speech analysis, model-specific task flags, and automatic Spectra-2 sessions where available. Install Python from Oruk's versioned archive with `python -m pip install https://oruk.ai/sdk/oruk-0.2.15-py3-none-any.whl` (Python 3.10+) or TypeScript from Oruk's versioned archive with `npm install https://oruk.ai/sdk/oruk-ai-sdk-0.2.15.tgz` (Node.js 18+ or a compatible fetch runtime). Reuse one client across requests. Existing explicit request IDs and retry protections are preserved. The clients also support emotion, speaking style, affect, proficiency and supported diarization parameters. The verified PyPI release is 0.2.14; the verified npm registry release remains 0.2.10.

[Python release](https://pypi.org/project/oruk/0.2.14/) · [TypeScript registry release](https://www.npmjs.com/package/@oruk-ai/sdk/v/0.2.10) · [Examples and versioned download mirrors](https://oruk.ai/docs/sdks)

For Python voice pipelines, Oruk also maintains `pipecat-oruk==0.1.0rc3`, a separate community integration published on PyPI. It streams interim/final transcription and independent phrase-emotion events through Oruk Realtime. Its hosted adapter source matches rc1, which was tested with Pipecat 1.8.1 on Python 3.11–3.14. This is a release candidate, not an upstream Pipecat release. See the pinned installation and file/browser examples at https://oruk.ai/docs/sdks#pipecat. The original rc1 production speech demo is not an independent accuracy benchmark or a verified full STT/LLM/TTS conversation.

## API contract

Authentication uses a bearer API key. Production keys begin with `oruk_live_`; temporary quickstart keys begin with `oruk_test_` and expire after 30 minutes. Keys are displayed once. Never put a key in a URL or query string.

- `POST /v1/audio/transcriptions`: returns transcript text
- `POST /v1/audio/emotions`: emotion labels only. On oruk-resonance (the default) only the encoder and affect head run; the transcription decoder is never invoked, no transcript is produced, and one audio minute uses one plan minute, as with unified analysis.
- `POST /v1/audio/styles`: returns speaking-style labels without transcript text
- `POST /v1/audio/affect`: returns emotion and style labels
- `POST /v1/audio/analysis`: returns transcript, emotion, style, segments, and tagged text
- `POST /v1/audio/resonance-2`: clip-level continuous emotion and speaking-style scores
- `WS /v1/audio/resonance-2/stream`: the same expression scores for explicitly committed PCM ranges
- `WS /v1/realtime?model=oruk-realtime`: returns transcript deltas, phrase-level emotion events, final text, and audio usage
- `POST /v1/audio/proficiency`: continuous word and recording pronunciation scores on 0–1, legacy CEFR and fluency, transcript, and measured usage
- `GET /v1/models`: returns the live model catalog and readiness
- `GET /v1/pricing`: returns reference cost fields, not subscription invoice charges
- `GET /livez` and `GET /readyz`: service health

File inference endpoints use `multipart/form-data` with a required `file` and optional `model`. With `model=oruk-resonance`, the optional `diarize=true` field labels speakers: the speaker-labeling pass identifies turns, then Resonance 1 transcribes and labels each turn, so every segment carries a `speaker` field (`speaker_0`, `speaker_1`, ...) with its own text, emotions, and styles; the response also carries `diarized: true` and a `speakers` list. Optional `num_speakers` (1-32) requests a known count; the provider may return fewer speakers when there is insufficient evidence. Overlapping voices are not separated into isolated audio. Short turns can be missed, merged, or attributed incorrectly. Diarization is included in plan minutes; other models return `400 diarization_unsupported`, and an unavailable diarizer returns `503 diarization_upstream_failed`. Realtime accepts a bearer key during the WebSocket handshake, or `oruk-api-key.<key>` as a browser-compatible subprotocol; API keys never belong in the URL.

Realtime PCM enters transcription immediately while an independent acoustic path closes phrases after 600 ms of silence by default. `session.update` accepts `phrase_emotions` (default `true`), `phrase_silence_ms` (200–2000), `phrase_max_ms` (1000–15000), and `diarize` (default `false`). Successful phrase events use `conversation.item.input_audio_emotion.completed` with `phrase_id`, start/end seconds, a `speaker` field, aligned text, ranked emotions, and a top emotion. With `diarize: true` the session runs streaming speaker diarization alongside transcription: `speaker` is `speaker_0`, `speaker_1`, ... in order of first appearance (stable for the session), speaker changes can split buffered phrases, and `conversation.item.input_audio_speaker.started` / `.ended` events report turn boundaries with a `timestamp`. Late speaker events can leave already emitted phrases with mixed speech or the wrong speaker. Live diarization is included in plan minutes; without the flag `speaker` is `null`. Parse the variable-length emotion label/score array rather than hard-coding seven labels. A September 6 live preview check returned frustrated. A phrase-level analysis failure emits `conversation.item.input_audio_emotion.failed` without stopping transcript deltas.

### Word confidence and tagged text

For Resonance 1 file results, `segments[].words[].confidence` can be `null` or
absent when the service does not return transcription confidence. This is not
zero confidence, a transcription failure, or an emotion score. Word timestamps
can still be present. Preserve numeric `0` separately from missing confidence;
do not substitute affect scores or infer confidence from word duration.

Resonance 1 analysis may return `Hello. <|happy|> <|warm|>` as `tagged_text`.
These unpaired tags annotate the segment, not just its last word. With one
segment, the tags can appear at the end of the full transcript. Use `text` for
plain transcription and each segment's `start`, `end`, `emotions`, and `styles`
for timed annotations. Do not parse tags as XML or assume every model uses the
same format. Spectra-2 file results have no word timings, timed segments or
`tagged_text`.

## MCP server

oruk runs a hosted Model Context Protocol server at `https://oruk.ai/mcp` over
streamable HTTP. There is nothing to install. Setup snippets for Cursor, Claude
Code, VS Code, Codex, and Windsurf are at https://oruk.ai/docs/mcp.

Authentication is a bearer token in the client's `Authorization` header, or an
`api_key` argument on individual calls. Eight tools are exposed:

- `oruk_plan_hume_migration`: bounded guidance from redacted feature enums and counts; no source, paths, audio, credentials or provider responses
- `oruk_analyze_speech`: transcript, emotion, and speaking style in one call
- `oruk_transcribe_audio`: transcription only
- `oruk_analyze_tone`: emotion and speaking style without a transcript
- `oruk_check_usage`: key validation, subscription state, included and remaining minutes, and recent usage
- `oruk_create_trial_key`: mints a trial key with no account and no card
- `oruk_list_models`: model catalog, pricing, labels, and limits
- `oruk_get_started`: quickstart and per-client configuration

`oruk_plan_hume_migration`, `oruk_list_models`, `oruk_get_started`, and `oruk_create_trial_key` need no
credentials. A minted trial key is good for three requests and expires after
30 minutes, which is enough to evaluate the API before creating an account.

The migration planning tool does not inspect code, generate or apply patches,
run inference, or validate score equivalence. Source-bound proposals use the
separate local planner and require manual integration and validation.

MCP audio is supplied as a public URL (up to 30 MB) or inline base64 bytes (up to
8 MiB decoded). Both accept up to 60 minutes of English speech. Full mode preserves
the labels and segments returned by the API, subject to response-size limits;
it does not expose scores for unreturned labels.

## On-device evaluation and licensing

oruk also scopes English speech models for offline deployment on phones,
wearables, and edge hardware. This is a target-hardware evaluation and
per-device licensing program, not a self-serve API endpoint. Transcription,
acoustic emotion labels, and speaking-style tasks are adapted and validated
on the customer's chipset and audio. Generic model-size, memory, power, and
latency figures are not published because they depend on the hardware, task,
and acceptance criteria. On-device outputs do not infer intent, deception,
truth, or a speaker's inner state.

## Multilabel behavior

Emotion has 15 labels and speaking style has 16. Scores are independent model outputs: they do not sum to one and are not probabilities of a speaker’s inner state. A clip may return several emotions, several styles, or no selected style. If no emotion crosses its model-specific threshold, the highest-scoring emotion is returned as a fallback.

For audio longer than one model context, the response includes contiguous time-local segments. Top-level labels aggregate the selected segment scores; segment labels should be used when emotion or style changes over time.

## Pricing and plans

Every subscription includes separate Orukeet and other-model allowances. Hobby is $9/month with up to 20,000 Orukeet transcription minutes plus 250 other-model minutes; Builder is $49/month with 108,888 plus 2,500; Production is $199/month with 442,222 plus 20,000. Enterprise terms are arranged with the team. Orukeet transcription uses $0.00045/minute ($0.027/hour); emotion detection adds $0.008/minute and speaker diarization adds $0.004/minute from the same allowance. Per-request rounding to one microdollar can reduce the transcription-minute estimates. Other-model overage is $0.020/$0.015/$0.012 per minute for Hobby/Builder/Production. Both allowances reset monthly, including on annual plans (20% off the base subscription). Extra usage shares one monthly spending cap, initially the monthly fee or discounted monthly equivalent. Standard self-serve trials last 7 days, require a card, charge $0 today, and include a quarter of both monthly allowances; overage is disabled during trials. Existing credit balances remain available under their original terms. See https://oruk.ai/pricing.

API usage responses and GET /v1/pricing may expose versioned reference cost fields. These do not determine subscription charges. Use your plan’s included minutes and overage rate; account usage and invoices reflect actual billing.

## Data handling

Demo and playground files selected for batch testing are staged in a private temporary cache before you click Run. Upload handles expire after 10 minutes. Replacing a file or closing the demo requests deletion sooner. Staged files are not used for training.

Oruk’s standard inference paths discard request audio after processing. Resonance 2 streams buffer audio during the live session, and completed Resonance 2 result payloads are saved for durable settlement and same-ID replay. Authorized replay is available for 24 hours; this does not promise physical deletion at that exact time. File diarization sends audio to pyannoteAI, whose Media API retains uploads for up to 48 hours and speaker-label job outputs for up to 24 hours. See https://docs.pyannote.ai/data-retention. Customer audio and outputs are not used to train, fine-tune, or evaluate models without explicit written agreement. Live speaker labeling also streams audio to pyannoteAI. These paths are not a promise of zero retention across all providers. Spectra-2 processes audio in North America, Europe, or Asia, routing each request by proximity, service health, and available capacity. Other standard speech inference remains in the United States. Optional task processing may occur outside the United States. If your application requires a specific processing region, retention term, or deployment boundary, confirm the complete configuration with Oruk before sending audio. Request identifiers, model, task, duration, usage, and timestamps are retained for billing, security, and support. These records do not contain audio or transcripts. Processing details: https://oruk.ai/security#processing.

## Evaluation

speech-emotion-bench (July 2026 report): open models are scored on the full 64,384-clip evaluation across ~20 languages and 7 emotion classes (anger, happiness, sadness, fear, disgust, surprise, neutral). Closed/API and audio-LLM systems are scored on a fixed 5,000-clip stratified subset. Every row uses the same label mapping and scorer, but not identical audio. Rescoring open models on the same subset shifts results by less than two points.

Headline results (seven-class accuracy):

- oruk Resonance 1 (July 2026 evaluation checkpoint): 77.8% (0.816 macro F1). Caveat stated on every results page: the oruk entry is trained in-distribution; other systems are zero-shot.
- emotion2vec+ seed (highest-scoring open model in this release): 68.7%
- Hume legacy 48-dimension prosody (highest-scoring legacy commercial API snapshot): 49.6%; not a measurement of current Hume Tagger or Prosody
- Gemini 3 Flash Preview (highest-scoring frontier multimodal API in this release): 46.0%
- GPT-Audio 1.5: 43.3% · Behavioral Signals: 44.1% · audEERING devAIce: 42.2% · Empath: 25.3%
- Text-only LLMs from transcripts (GPT-5.2, Claude Opus 4.8, etc.): 37–41%

Per-emotion F1, oruk Resonance 1 vs best frontier multimodal API (Gemini 3 Flash Preview): Disgust 0.905 vs 0.185, Fear 0.864 vs 0.355, Surprise 0.858 vs 0.268, Anger 0.806 vs 0.462, Neutral 0.756 vs 0.529, Sadness 0.746 vs 0.313, Happiness 0.737 vs 0.502.

Full leaderboard: https://oruk.ai/benchmarks. Protocols, downloadable result artifacts, source treatment, sample counts, and limitations: https://oruk.ai/benchmarks/methodology. Results from a benchmark-specific checkpoint should be interpreted under that benchmark's dataset, label mapping, and scoring protocol rather than treated as a universal production score.

## Reference definitions

Long-form definitions with a page each, covering how the measurement works and what our results show. Method terms: voice activity detection (https://oruk.ai/glossary/voice-activity-detection), word error rate (https://oruk.ai/glossary/word-error-rate), mel spectrogram (https://oruk.ai/glossary/mel-spectrogram), speech prosody (https://oruk.ai/glossary/speech-prosody), macro F1 (https://oruk.ai/glossary/macro-f1). Corpora: IEMOCAP (https://oruk.ai/glossary/iemocap), CREMA-D (https://oruk.ai/glossary/crema-d), RAVDESS (https://oruk.ai/glossary/ravdess), MELD (https://oruk.ai/glossary/meld-dataset). The remaining terms, including all 15 emotion and 16 speaking-style labels, are defined on https://oruk.ai/glossary.

## Hume product-snapshot context (July 2026)

Hume's current official page advertises Tagger for offline analysis across 600+ expression dimensions and Prosody for real-time signals: https://www.hume.ai/expression-measurement-api. Those current products were not evaluated in oruk's July 2026 release. The Hume leaderboard row is a dated legacy 48-dimension prosody snapshot and must not be treated as evidence about current Hume availability or performance. oruk publishes a dated comparison with correction notes at https://oruk.ai/compare/oruk-vs-hume-ai and a current-options page at https://oruk.ai/compare/hume-ai-alternatives. oruk Realtime provides phrase-level emotion scores alongside live transcript tokens; it is not a high-dimensional expression or prosody API and therefore does not replace Hume Prosody.

## Responsible use

Emotion and speaking-style outputs are probabilistic, subjective acoustic annotations. Accuracy can vary by channel, language, speaker population, and context. These outputs should not be used as the sole basis for consequential decisions in employment, credit, healthcare, education, housing, insurance, or law enforcement.

## Orukeet: downloadable speech recognition

Orukeet is a separate open speech recognition model for 25 languages, built from NVIDIA Parakeet TDT 0.6B v3. Native Q8/F16, ONNX INT8 and NeMo weights run locally. The downloadable model is separate from the hosted English preview, `oruk-orukeet`, which offers optional emotion detection and speaker diarization. The native package returns text and window-level segment times; language is null, not an inferred language label.

Use Python 3.12+ and the published Orukeet 0.1.1 wheel. The installer downloads and verifies the weights and native runtime; recognition then uses local files. Code is MIT; weights and fitted kernels are CC BY-SA 4.0.

- [Install Orukeet and transcribe a recording](https://oruk.ai/guides/orukeet-local-transcription)
- [Model, evaluation and limitations](https://oruk.ai/research/orukeet)
- [Code and native package](https://github.com/Oruk-AI/orukeet)
- [Weights and model card](https://huggingface.co/oruk/orukeet)


## Orukeet transcription preview

Model `oruk-orukeet`: POST https://speech-api.oruk.ai/v1/audio/transcriptions using an existing Oruk Bearer API key. English, 60 seconds, 4 MiB complete multipart request. Base transcription $0.00045/audio minute ($0.027/hour), included in each plan’s Orukeet allowance; extra usage shares the plan’s spending cap. Optional flags: emotion_detection=true (+$0.0080/min), diarize=true (+$0.0040/min), num_speakers=1..32 when diarizing. Requested tasks must succeed; no silent fallback. All timestamps are seconds; transcription alone has no word timings. Native PCM WebSocket: wss://orukeet-direct.oruk.ai/v1/audio/transcriptions/stream; POST /v1/client-token produces a 60-second single-use browser token. Streamed audio returns final text at commit, not partial word hypotheses. Model: https://oruk.ai/models/orukeet; contract: https://oruk.ai/docs#orukeet; pricing/benchmark comparison: https://oruk.ai/compare/orukeet-vs-whisper. Optional diarization has separate temporary retention; see https://oruk.ai/privacy.

## Spectra-2 — production multilingual transcription and clip scores

Spectra-2 (`oruk-spectra-2`) is a production model on the main Oruk API: `POST /v1/audio/analysis` or `POST /v1/audio/transcriptions`, with an existing Oruk Bearer key. Send multipart fields `model=oruk-spectra-2` and exactly one `file`. Both routes return `text`, `duration`, all 15 `emotions` and 16 `styles` as label/score pairs, and `usage`. Scores cover the whole clip, range independently from 0 to 1, and do not sum to one. Batch results have no word timings, timed segments or speaker labels.

Streaming upload: `wss://speech-api.oruk.ai/v1/audio/spectra-2/stream` accepts an Authorization bearer header from server clients. Send a start message with model, task, pcm_s16le format, 16000 sample_rate, one channel, and a request_id; then binary audio frames of at most 32 KiB. Send `finish` to receive one final batch-shaped result after processing and billing. No provisional words or automatic endpoint detection. One 45 ms–60 s recording per connection, completed within 75 seconds. Cancel before finish to avoid inference. After finish, disconnect does not cancel billing; retain the request ID and check Usage. The account playground supports browser microphone streaming without exposing an API key. Protocol and Python example: https://oruk.ai/docs#spectra-2-streaming.

Supported transcription languages: Bulgarian (bg), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), English (en), Estonian (et), Finnish (fi), French (fr), German (de), Greek (el), Hungarian (hu), Italian (it), Latvian (lv), Lithuanian (lt), Maltese (mt), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Slovak (sk), Slovenian (sl), Spanish (es), Swedish (sv), Ukrainian (uk). Language detection is automatic; do not send a language parameter. Emotion and speaking-style labels use the same English names for every language. Names and codes are also available as `language_details` in the public model catalog and the OpenAPI Spectra-2 contract.

Input is mono 16 kHz WAV, finalized FLAC or raw PCM, 45 ms–60 seconds, at most 4 MiB per file; the multipart envelope has a further 16 KiB allowance. Raw PCM requires file MIME audio/pcm for signed 16-bit little-endian samples or audio/f32le for float32 little-endian samples. WAV/FLAC may be detected from their headers. No optional task flags are accepted.

One audio minute uses one shared speech understanding plan minute, with a one-second minimum. Existing trial limits, overage rates and spending caps apply. Legacy reference rates are $0.012/minute for analysis and $0.008/minute for transcription; these reference cost fields are not a subscription invoice. Existing model defaults remain unchanged.

Keep the same X-Request-ID, endpoint and exact file bytes after a network error or 5xx response; automatically creating a new ID can repeat inference and charges. Pending or uncertain requests return 409 request_in_progress; completed IDs return 409 request_already_completed. Changed bytes, task, model or key return 409 idempotency_conflict. Audio and responses are not retained for replay. On 429 upload_busy or model_busy, wait at least Retry-After seconds and reduce concurrency. Retry upload_busy with the same ID. A model_busy attempt is closed without inference or a charge: use a new ID after waiting. A 409 request_failed ID is closed; resolve the original error before a new attempt. Errors include error.code, error.message and error.request_id. Keep API keys server-side and share request IDs with support.

Spectra-2 processes audio in North America, Europe, or Asia, routing each request by proximity, service health, and available capacity. Confirm the configuration with Oruk before sending audio if you require a specific processing region. Processing details: https://oruk.ai/security#processing.

Model catalog: https://oruk.ai/models#spectra-2. Languages: https://oruk.ai/docs#spectra-2-languages. Full contract: https://oruk.ai/docs#spectra-2. OpenAPI: https://oruk.ai/openapi.json.

## Resonance 2 — available in preview

Resonance 2 (`oruk-resonance-2`) is the new emotion and speaking-style model. Call the dedicated `POST /v1/audio/resonance-2?regime=f1` route. It uses existing Bearer keys and the same price and shared speech understanding minutes as Resonance 1. One audio minute uses one plan minute; existing trial limits, overage rates, and spending caps apply. No new plan or add-on is needed. New organizations require separate Resonance 2 approval; request access at https://oruk.ai/account/model-access. Plan or trial activation alone does not grant access. Legacy metered pricing matches Resonance 1 affect: $0.0100/audio minute, with a one-second minimum.

Input: WAV, FLAC, MP3, M4A, OGG, WebM; 0.1–120 seconds, 30 MiB. Output: 31 continuous `scores`, six signed `axes`, 19 `unipolar` scores, and threshold-selected `labels`; no transcript, timestamps, or diarization. The POST returns one result; use the separate WebSocket route for streamed PCM and explicit commits. Axes are sad__happy, worried__relieved, disappointed__hopeful, hesitant__confident, tired__energetic, formal__casual. Negative favors the first label; positive favors the second; zero means no preference. A value of -0.8 means a 0.8 dominance score for the first label, not a categorical probability. Both ends cannot be selected together. Unpaired labels stay in [0,1]; scores do not sum to one. The default `f1` and optional `precision` regimes change selection thresholds, not continuous scores. Language-independent accuracy is not established.

Use ordinary HTTP for the file route or the WebSocket protocol below; SDK 0.2.15 has no dedicated Resonance 2 helper for either transport. The default model `oruk-resonance` and its existing routes stay available. Full contract and billing: https://oruk.ai/docs#resonance-2.

WebSocket: `wss://speech-api.oruk.ai/v1/audio/resonance-2/stream`, with Bearer authorization in the upgrade headers. Wait for `ready` (`sample_rate: 16000`, `encoding: float32le`, `idempotency: shared_http_ws`), then send mono 16 kHz float32 little-endian PCM without a WAV header in binary frames of 1–16,000 finite samples (at most 64,000 bytes). Commit JSON selects the buffered range: `{"type":"commit","id":"YOUR_STABLE_REQUEST_ID","start_sample":0,"end_sample":32000,"regime":"f1","scope":"live"}`. The end offset is exclusive. Public commits accept 0.1–120 seconds; `scope` is optional (`live` or `clip`) and does not reduce that limit. For live updates, use rolling windows up to 20 seconds, then commit the full clip. Website demos enforce 20-second live windows and 30-second clips. Results arrive as `{"type":"result","id":"…","result":{…},"timings_ms":{…}}`; `result` has the same scores and aggregation as HTTP, without transcription, timestamps, or diarization. Every new commit has the same billing rules as an HTTP request; overlapping analyses count separately. Authorization and available usage are checked for each commit. Use the original API key and the same ID, decoded PCM and regime for HTTP/WS replay; HTTP uses `X-Request-ID`. Completed results can be replayed for 24 hours without another charge, subject to live authorization. This replay window is not a physical-deletion guarantee. A pending request returns `409 request_in_progress`; do not switch to a fresh ID after an uncertain result. Send `{"type":"reset"}` between clips. Limits: 120 seconds buffered audio, 256 commits, 30-second idle timeout, 10-minute session. Reset does not reset commit or lifetime limits. Use a server-side WebSocket client with header support; this route has no browser API-key subprotocol and keys must not be placed in URLs. Full protocol: https://oruk.ai/docs#resonance-2-streaming.

Research and reproducibility: https://oruk.ai/research/resonance-2#reproduce-diagnostic.
The downloadable archive includes 546 original parsed response receipts, the
calibration thresholds, protocol, and an offline scorer. It replays the reported
single-sentence acted-speech diagnostic; it is not a fresh independent evaluation.
Training overlap is unaudited, and these development-data results do not establish
accuracy on other speakers, languages, or recording conditions.
Download: https://oruk.ai/research/resonance-2/reproduction-2026-09-19.zip.


## Proficiency: continuous pronunciation and legacy CEFR

`POST https://speech-api.oruk.ai/v1/audio/proficiency`, `model=oruk-proficiency-1`.
The request, Bearer authentication and original CEFR response contract are unchanged.

### Two independent outputs

The `continuous-pilot-v2` model returns recording and word pronunciation scores
on 0–1, plus recording accuracy, fluency and prosody. Higher means higher rated
pronunciation proficiency. These regression estimates are not probabilities,
percentiles, native-speaker likelihoods or accent-strength scores.

The original `fluency_cefr-v2-final` model independently returns CEFR A1–C2,
`cefr_score` on 0–5, band probabilities and confidence, categorical fluency,
`fluency_score` on 0–10, and utterance-fluency features. CEFR is not calculated
from the new score. Existing clients can keep their original response parsing.

| Read | Purpose |
|---|---|
| `proficiency.score` | Recording pronunciation score or null |
| `proficiency.words[]` | Word text, start/end seconds, score or null, scored/unscorable status |
| `proficiency.components` | Accuracy, fluency and prosody, each 0–1, or null |
| `proficiency.status` | `scored`, `partial_word_scores` or `unscorable` |
| `proficiency.continuous_check` | Pronunciation `scored`, `insufficient_audio` or `unavailable`; no billing flag |
| `proficiency.continuous_metadata` | Aligned speech seconds, word count, caller-supplied-reference flag |
| `check` | Original CEFR validity and the request's billing decision |
| `proficiency.legacy_check` | Alias of the original top-level check |

Original `proficiency.speech_seconds` remains VAD-based, `word_count` keeps
legacy tokenization, and `transcript_used` means the original model used text,
including automatic ASR. Only `continuous_metadata.transcript_used` indicates
that the caller supplied the reference.

### Input and status handling

Send multipart `file` and optional `transcript`. A supplied transcript must be
the words spoken or a verified reading prompt; it skips ASR and supplies the
alignment reference. Without it, Resonance 1 transcribes once and both models
use that text. Keep the API key on your backend.

Accepted containers: WAV, FLAC, MP3, M4A, OGG and WebM; maximum 30 MB and
600 seconds. Use at least five seconds of audible English. Short prompted
recordings suit V2; 30–60 seconds of spontaneous speech suit the original CEFR
estimate. A materially mismatched prompt can make alignment unreliable.

Preserve null continuous scores. A partial result may still contain usable
word scores. The continuous model does not manufacture a recording score from
incomplete evidence; show unavailable instead of replacing null with zero.

The original top-level `check.status` governs CEFR usability and billing:

- `scored`: valid CEFR check.
- `low_confidence`: valid, but CEFR band probability is below 0.5; obtain more speech.
- `insufficient_audio`: invalid and free. The recording is under five seconds,
  or has fewer than four detected speech seconds and fewer than six transcript words.

Numeric legacy estimates remain present even for invalid checks, matching the
old non-null response schema. Never use them as grades when the check is
invalid. A valid CEFR result with partial V2 alignment is still billable. There
is one request charge, not separate charges for the two models. Subscriptions
use plan minutes; existing metered accounts retain their per-check terms.
Read `usage`, `check.billable` and your account terms. A duplicate request ID
returns 409. A failed additive scorer can return `continuous_check.status:
"unavailable"` while preserving a valid CEFR response.

### How it works

1. A CTC aligner places the reference words in the audio.
2. The frozen Resonance encoder runs once per window. Final and layer-8 frames
   are pooled over word boundaries.
3. Local acoustics, expected pronunciation phones and context feed two small
   word-scoring heads. Separate continuous heads produce the recording score
   and components. V2 gives rare, weaker training bands more weight; it does
   not impose a score cap or force a histogram.
4. The original acoustic and utterance-fluency model scores CEFR independently.

Windows are at most 30 seconds. Longer recordings use word-count-weighted
aggregates of complete windows. Unknown pronunciations, invalid alignments or
words crossing windows can yield partial scores. Long-form aggregation has
not been independently validated against human ratings.

### Benchmark and limits

The reused SpeechOcean762 benchmark includes 15,931 words from 125 Mandarin-L1
speakers reading short English utterances. Weak/intermediate word MAE improved
from 0.3043 to 0.1883; mean MAE across five bands improved from 0.2219 to
0.1671. Overall word MAE worsened from 0.0770 to 0.1283. Recording MAE remains
0.0687 over 2,496 recordings. These are human-rating errors, not ASR word error
rate. The test set had already been inspected; this is not fresh independent
validation. Evaluate your target speakers, languages and conditions before
choosing application thresholds.

The new model does not supply accent classification, accentedness, phone-level
diagnostics, grammar or vocabulary assessment. Expected phones are inputs.
Do not use `1 - score` as accentedness. The separate legacy CEFR result is an
estimate, not a language certificate.

### References

- [API guide and live response excerpt](https://oruk.ai/docs#proficiency)
- [Python and Node.js usage](https://oruk.ai/docs/sdks)
- [OpenAPI](https://oruk.ai/openapi.json)

Verified September 17, 2026: twelve public HTTP cases passed, with exact legacy
field/metadata/check parity and original-schema validation in eight response
cases. Existing clients need no request changes to receive the additive fields.


## Resonance 2 access

Resonance 2 requires organization approval for new accounts. Existing accounts retain access. GET /v1/models/oruk-resonance-2/access reports status; POST the same endpoint with bearer authorization and JSON {"use_case":"Describe your application in 10–2,000 characters"} requests approval (202 pending). Use https://oruk.ai/account/model-access without an API key. Unapproved inference returns 403 model_access_required before billing. Approval works with existing API keys and normal plan/credit limits. A Resonance 2 trial invitation requires card-backed checkout, grants seven days on a self-serve plan, and then renews at the selected plan price unless canceled. The homepage demo remains public.


## OrukZero — synthetic speech detection

Model ID: `orukzero`. POST https://speech-api.oruk.ai/v1/audio/synthetic-speech
with an Oruk Bearer API key, multipart `file`, and optional `model=orukzero`.
OrukZero is included at no additional charge with every active paid Oruk plan.
It consumes no credits, included plan minutes, or metered overage, even when
other model allowances are exhausted. Free trials and prepaid-only accounts
are not paid subscriptions. Existing renewal grace for past-due plans applies.
This is an exception to the plan-minute billing of other speech models.

English speech; one WAV/FLAC/OGG/MP3, 1–60 seconds, 8–48 kHz, mono/stereo,
maximum 12 MiB. Limit: 60 requests/minute per API key; honor Retry-After on 429.
Response: model=orukzero, prediction=human|synthetic, synthetic_score, threshold=0.5,
duration, model_revision, segments, usage.billed=false,
usage.billing_mode=included_with_paid_plan, credits_used=0, plan_minutes_used=0.
Scores are uncalibrated, not proof of authenticity. Long-clip aggregation is experimental.
401 means invalid key; 402 means paid plan required; 503 means temporarily unavailable.
Uploaded audio is transient and not retained by this endpoint.
The legacy request model ID oruk-synthetic-speech-1-preview remains an alias;
new integrations and all responses use orukzero. The endpoint URL is unchanged.
Docs: https://oruk.ai/docs/synthetic-speech
Schema: https://oruk.ai/docs/synthetic-speech/openapi.json
Authenticated access check: GET https://speech-api.oruk.ai/v1/models/orukzero/access