# oruk Speech API — instructions for coding agents

oruk is a speech lab. Resonance 1 is its default English file model. API v1 supports 25-language file transcription with Spectra-2 and 32-locale live transcription with Realtime. Spectra-2 returns all 15 emotion and 16 speaking-style scores for the whole clip; original Resonance 1 and Fourier return selected labels with timed segments. Language coverage, input limits and output fields depend on the model. Transcription coverage does not establish expression accuracy in every language.

## Fastest path: the hosted MCP server

oruk runs a remote MCP (Model Context Protocol) server at `https://oruk.ai/mcp`
(Streamable HTTP, no local install). It exposes transcription, tone/emotion
analysis, model/pricing lookup, and no-account trial keys as tools. Configure
it with an `Authorization: Bearer <key>` header, or let it mint a trial key.
Setup snippets for Cursor, Claude Code, VS Code, Codex, and Windsurf:
https://oruk.ai/docs/mcp

## Integrate in three steps

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.

1. Create an API key at https://oruk.ai/account/api-keys. Choose a subscription with a standard 7-day trial at https://oruk.ai/pricing.
2. Send audio as multipart form data with a Bearer token:

```bash
curl --fail --location --output sample.wav \
  https://oruk.ai/samples/oruk-quickstart.wav
curl --fail-with-body https://speech-api.oruk.ai/v1/audio/analysis \
  -H "Authorization: Bearer $ORUK_API_KEY" \
  -F file=@sample.wav -F model=oruk-resonance
```

3. Parse the JSON response: `text` (transcript), `emotions` and `styles`
   (label + score), `segments` (time-local labels), and `usage`
   (measured and billable audio seconds). Subscription charges follow the plan allowance and overage rate, not reference cost fields in the response.

## Endpoints

- `POST /v1/audio/transcriptions` — transcript; language and timing support vary by model
- `POST /v1/audio/emotions` — multilabel emotion scores
- `POST /v1/audio/styles` — multilabel speaking-style scores
- `POST /v1/audio/affect` — emotion + style, no transcript
- `POST /v1/audio/analysis` — Spectra-2: multilingual transcript + clip scores; original Resonance 1/Fourier: English transcript + selected labels + timed segments + tagged text
- `POST /v1/audio/resonance-2` — clip-level expression scores, without transcription
- `WS /v1/audio/resonance-2/stream` — expression scores for explicitly committed PCM ranges
- `WS /v1/realtime?model=oruk-realtime` — multilingual token deltas + phrase emotion
- `GET /v1/models` — served model catalog
- `GET /v1/pricing` — reference cost fields; subscription plans are at https://oruk.ai/pricing

Base URL: `https://speech-api.oruk.ai/v1`. Auth: `Authorization: Bearer <key>`.
Input limits are model-specific. Spectra-2: mono 16 kHz WAV, finalized FLAC or raw PCM, 45 ms–60 seconds, 4 MiB file plus 16 KiB multipart overhead. Hosted Orukeet: 60 seconds and 4 MiB for the complete multipart request, including form overhead. Resonance 1 and Fourier: WAV, FLAC, MP3, M4A, OGG or WebM, 30 MB and 60 minutes. See each model's full contract below.
Start with `oruk-resonance`, the flagship speech recognition model and default
for recorded English transcription, emotion, and speaking style. Other models:
`oruk-spectra-2` (multilingual transcription and clip-level scores), `oruk-resonance-2` (expression scores without transcription), `oruk-fourier` (transcript plus native 15-label emotion), `oruk-realtime`
(streaming), and `oruk-proficiency-1` (speaking-proficiency checks). Choose a current model ID from the catalog; retired IDs return 400 `model_retired`.

## SDKs

- Python: `python -m pip install https://oruk.ai/sdk/oruk-0.2.15-py3-none-any.whl` → `from oruk import Oruk`
- TypeScript: `npm install https://oruk.ai/sdk/oruk-ai-sdk-0.2.15.tgz` → `import { Oruk } from "@oruk-ai/sdk"`

These commands install SDK 0.2.15 from Oruk's versioned archives. Reuse one client across requests; Spectra-2 sessions prepare automatically where available. Explicit request IDs and retry protections are preserved.

Verified registry release pages: [PyPI 0.2.14](https://pypi.org/project/oruk/0.2.14/) and
[npm 0.2.10](https://www.npmjs.com/package/@oruk-ai/sdk/v/0.2.10).
Versioned download mirrors and examples remain at https://oruk.ai/docs/sdks.

For Pipecat voice pipelines, install the separate community adapter with
`python -m pip install 'pipecat-oruk==0.1.0rc3' 'pipecat-ai==1.8.1'`.
Use `from pipecat_oruk import OrukSTTService`. Oruk maintains this release candidate;
it is not an upstream Pipecat release. The rc3 hosted adapter source matches the
rc1 source tested with Pipecat 1.8.1 on Python 3.11–3.14. The original recorded
rc1 check covers speech transport, not a verified full STT/LLM/TTS conversation.
Pinned file-stream and browser speech examples: https://oruk.ai/docs/sdks#pipecat. Keep ORUK_API_KEY on the
server. Phrase results arrive separately from transcript deltas; join using the
adapter's stream/turn identity and phrase ID.

## Constraints to respect

- Realtime accepts mono signed PCM16 in 32 locales for up to 10 minutes and
  returns phrase-level emotion scores. Full 15-emotion, 16-style, and unified
  analysis are available through the file API; Spectra-2 adds 25-language transcription with clip-level scores.
- Outputs are acoustic annotations of how speech sounds — do not
  present them as facts about a speaker's inner state, and do not use them as
  the sole basis for consequential decisions.

## Hume migration

Start with https://oruk.ai/hume-migration to assess dependencies and compare native Oruk contracts. Legacy expression measurement and EVI require different migration work. Oruk does not synthesize speech or emulate EVI; an EVI replacement needs the customer's selected STT, LLM, TTS, tools and transport. Keep recordings and exports in customer-controlled storage. Export checklist and cutover planning: https://oruk.ai/guides/hume-evi-migration#export.

## Machine-readable references

- [OpenAPI schema](https://oruk.ai/openapi.json)
- [Short product reference](https://oruk.ai/llms.txt)
- [Full product reference](https://oruk.ai/llms-full.txt)
- [Docs and playground](https://oruk.ai/docs)
- [Status](https://oruk.ai/status)

## 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.

## 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.


## Continuous pronunciation and legacy CEFR

oruk Proficiency: preview; continuous-pilot-v2 word and recording pronunciation scores on 0–1, plus independently computed legacy CEFR (A1–C2, cefr_score 0–5) and fluency. Use proficiency.continuous_check for pronunciation validity; the original top-level check controls CEFR validity and billing. Subscription accounts use plan minutes. Full model and compatibility guide: https://oruk.ai/docs#proficiency.

The new score is a human-rating regression estimate, not native-speaker likelihood or accentedness. Keep null scores as null. Legacy numeric fields remain present on insufficient_audio responses for compatibility; do not treat them as grades. speech_seconds and transcript_used retain legacy meanings; continuous_metadata holds alignment duration and the caller-supplied-reference flag. Partial pronunciation alignment does not make a valid CEFR check free. No accent classification or phone-level diagnostics are returned. For Node.js callers, the direct example at https://oruk.ai/examples/proficiency.mjs reads the new fields without relying on older SDK declarations.


## 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