Skip to content

Developer documentation

Spectra-2 API reference

Spectra-2 transcribes short recordings in 25 languages and returns 15 emotion and 16 speaking-style scores in the same request. Use HTTP or stream the upload, then read the final result. Existing Oruk keys and speech understanding minutes apply; no separate model approval is required.

Spectra-2 · Production API

Transcription, emotion and speaking style

Spectra-2 transcribes 25 languages and returns 15 emotion and 16 speaking-style scores for the whole recording. Use your existing Oruk API key and shared speech understanding minutes: one audio minute uses one plan minute, with a one-second minimum. Your plan's trial allowance, overage rate and spending cap apply.

Try Spectra-2 with your account, or use the SDK examples below in your app. See the tagged transcript and word-level output.

Set ORUK_API_KEY on your server. Use a mono 16 kHz recording.

Set up Python
python -m pip install https://oruk.ai/sdk/oruk-0.2.15-py3-none-any.whl
Python
import os
from oruk import Oruk

with Oruk(api_key=os.environ["ORUK_API_KEY"]) as client:
    result = client.analyze("clip.flac", model="oruk-spectra-2")
    status = result.get("prosody", {}).get("status")
    tagged = result.get("tagged_transcript")
    print(tagged if status in ("available", "experimental")
          and isinstance(tagged, str) and tagged else result["text"])
    print(result["emotions"], result["styles"])

Reuse one SDK client across recordings. It prepares available sessions automatically to reduce repeat-call latency. To prepare before your first recording, call client.prepare_spectra2() in Python or await client.prepareSpectra2() in Node.js. You can still send ordinary requests if preparation returns false. FLAC reduces upload size while preserving the audio. Keep API keys on your server.

For Python file uploads, install the SDK with soundfile>=0.13,<1 and create Oruk(api_key=key, compress_audio=True). It sends eligible 16-bit WAV recordings as smaller, lossless FLAC files. It never resamples or reduces audio precision. Both SDKs track available session capacity before sending the next recording.

cURL example
Spectra-2 · cURL
# Keep this ID if you need to retry this request.
REQUEST_ID="$(uuidgen)"
curl --fail-with-body --connect-timeout 10 --max-time 90 \
  https://speech-api.oruk.ai/v1/audio/analysis \
  -H "Authorization: Bearer $ORUK_API_KEY" \
  -H "X-Request-ID: $REQUEST_ID" \
  -F model=oruk-spectra-2 \
  -F 'file=@clip.wav;type=audio/wav'

Send exactly one file and model=oruk-spectra-2 as multipart form data. Use mono 16 kHz WAV or finalized FLAC, from 45 ms to 60 seconds and up to 4 MiB per file. The complete multipart request allows another 16 KiB for its envelope. No language code or task flags are needed.

Raw PCM uses the same limits: set the file MIME type to audio/pcm for signed 16-bit little-endian samples, or audio/f32le for 32-bit little-endian floats. For example, -F 'file=@clip.pcm;type=audio/pcm'. WAV and FLAC can also be recognized from their file headers.

POST /v1/audio/transcriptions accepts the same fields and returns the same transcript and scores with task: transcription. Both endpoints return one JSON result after the upload. Emotion and speaking-style scores cover the whole clip. Optional prosody output can include word timings and selected emphasis; it does not add speaker labels or locate emotions within the recording.

text · duration
The transcript and recording length in seconds.
emotions · styles
All 15 emotion and 16 speaking-style label/score pairs. Each score ranges from 0 to 1; labels can coexist and scores do not sum to one. They describe acoustic expression.
tagged_transcript · prosody
Optional fields from capable builds. Check prosody.status: available, experimental or unavailable. Plain text and clip-level scores remain usable when these fields are absent or unavailable.
id · object · model · task · usage
Result identity, speech.result, oruk-spectra-2, the requested task, and measured/billable audio seconds. Reference cost fields are not your subscription invoice.

When provided, prosody.words includes word times and nullable prominence and nuclear-position values. A null nuclear position is unknown, not false. An <emph> span in tagged_transcript marks a selected nuclear word within an accepted phrase; a recording need not contain one. Predicted phrases remain experimental, and their scores are conditional on the predicted phrase and annotation profile, not joint correctness.

The Python and Node.js SDK 0.2.15 transports preserve these returned JSON fields. Its published TypeScript declarations do not yet name the extension; the example above checks optional fields before using them. The separate AI SDK adapter does not expose prosody or tagged transcripts; use the Oruk client or direct HTTP when you need those fields.

Response guide

Words, expression, and emphasis in one response

Your normal Spectra-2 request can now return tagged_transcript and prosody alongside text and all 31 expression scores. Both optional fields arrive together. There is no extra request flag or separate charge. The current emphasis output is experimental.

What was said

text is the plain transcript. Word timings, when available, are in prosody.words.

How it sounded

emotions and styles contain independent scores for the whole clip.

Which word stood out

<emph> marks the selected nuclear accent: a phrase's main stressed word.

Read the tagged transcript

In this illustrative example, great. is selected as the nucleus. The happy and warm wrappers cover the entire clip, including the words outside <emph>. IDs, times, and scores below are example values.

Tagged transcript · illustrative example
<transcript start="0" end="1.8"><happy score="0.82" start="0" end="1.8" scope="clip"><warm score="0.7" start="0" end="1.8" scope="clip">That sounds <emph phrase="p1" scheme="aix_marsec_iu_v1" score="0.91" origin="model_predicted" experimental="true" confidence="conditional_on_predicted_phrase">great.</emph></warm></happy></transcript>
<transcript start="0" end="1.8">
The recording span in seconds. Removing tags and decoding the escaped characters recovers text, including punctuation and spacing.
<happy score="0.82" … scope="clip">
A clip-level expression score. The markup displays labels scoring at least 0.5; read the full emotions and styles arrays for every score. These tags do not locate emotion in time.
<emph phrase="p1" …>great.</emph>
The nuclear word selected within phrase p1. Join that phrase to its word through nuclear_word_id. IDs are opaque references within a response.

The score on <emph> is conditional on the predicted phrase and annotation profile. It is not the probability that the phrase boundary and selected word are both correct. confidence="conditional_on_predicted_phrase"describes that meaning; it is not another numeric score.

Use the structured word and phrase data

Use these fields for your own timeline or highlighting. Times are seconds from the start of the recording. This excerpt omits identity, score arrays, and usage; the full response is available below.

Structured prosody · response excerpt
{
  "text": "That sounds great.",
  "duration": 1.8,
  "prosody": {
    "version": "spectra2.prosody.v1",
    "status": "experimental",
    "words": [
      {
        "word_id": "w1",
        "text": "That",
        "start_s": 0,
        "end_s": 0.28,
        "prominence": null,
        "nuclear": false
      },
      {
        "word_id": "w2",
        "text": "sounds",
        "start_s": 0.28,
        "end_s": 0.78,
        "prominence": 0.32,
        "nuclear": false
      },
      {
        "word_id": "w3",
        "text": "great.",
        "start_s": 0.78,
        "end_s": 1.8,
        "prominence": 0.86,
        "nuclear": true
      }
    ],
    "phrases": [
      {
        "phrase_id": "p1",
        "scheme": "aix_marsec_iu_v1",
        "start_s": 0,
        "end_s": 1.8,
        "nuclear_word_id": "w3",
        "score": 0.91,
        "score_semantics": "conditional_on_phrase_and_profile",
        "origin": "model_predicted",
        "experimental": true
      }
    ]
  }
}
words[].prominence
An acoustic prominence score from 0 to 1, or null when unavailable. It is separate from nuclear selection and transcription confidence. Preserve a returned numeric 0.
words[].nuclear
true selects the nucleus; false marks another word inside the same accepted phrase; null means no accepted phrase supplies that word's nuclear position. Unknown is not a negative label.
phrases[].scheme · origin · experimental
The annotation profile and phrase provenance. Current predicted phrases use origin: "model_predicted" and experimental: true. A phrase score uses score_semantics: "conditional_on_phrase_and_profile".

Handle missing or unavailable emphasis

How to handle each Spectra-2 prosody status
StatusWhat to do
experimentalRead the predicted word/phrase data with its experimental provenance. An empty phrases array is valid.
availableThe extension has verified-phrase support. Inspect each phrase's origin and scheme.
unavailableUse text. Word and phrase arrays are empty; reason explains why. The tagged string may be empty.
Both fields absentUse text and the expression scores. Do not create word labels from missing data.

No <emph> span does not mean the speaker was neutral. A valid experimental result can have word timings and prominence scores while every nuclear position is null.

Unavailable-output example
Unavailable prosody · response excerpt
{
  "text": "That sounds great.",
  "tagged_transcript": "",
  "prosody": {
    "version": "spectra2.prosody.v1",
    "status": "unavailable",
    "reason": "not_available",
    "words": [],
    "phrases": []
  }
}
Complete illustrative JSON response · all 31 scores
Complete Spectra-2 analysis response · illustrative
{
  "id": "00000000-0000-4000-8000-000000000001",
  "object": "speech.result",
  "model": "oruk-spectra-2",
  "task": "analysis",
  "text": "That sounds great.",
  "duration": 1.8,
  "emotions": [
    {
      "label": "happy",
      "score": 0.82
    },
    {
      "label": "excited",
      "score": 0.04
    },
    {
      "label": "hopeful",
      "score": 0.04
    },
    {
      "label": "sad",
      "score": 0.04
    },
    {
      "label": "worried",
      "score": 0.04
    },
    {
      "label": "angry",
      "score": 0.04
    },
    {
      "label": "frustrated",
      "score": 0.04
    },
    {
      "label": "disappointed",
      "score": 0.04
    },
    {
      "label": "scared",
      "score": 0.04
    },
    {
      "label": "disgusted",
      "score": 0.04
    },
    {
      "label": "surprised",
      "score": 0.04
    },
    {
      "label": "embarrassed",
      "score": 0.04
    },
    {
      "label": "proud",
      "score": 0.04
    },
    {
      "label": "relieved",
      "score": 0.04
    },
    {
      "label": "neutral",
      "score": 0.04
    }
  ],
  "styles": [
    {
      "label": "energetic",
      "score": 0.04
    },
    {
      "label": "passionate",
      "score": 0.04
    },
    {
      "label": "irritated",
      "score": 0.04
    },
    {
      "label": "warm",
      "score": 0.7
    },
    {
      "label": "playful",
      "score": 0.04
    },
    {
      "label": "sarcastic",
      "score": 0.04
    },
    {
      "label": "deadpan",
      "score": 0.04
    },
    {
      "label": "hesitant",
      "score": 0.04
    },
    {
      "label": "confident",
      "score": 0.04
    },
    {
      "label": "sincere",
      "score": 0.04
    },
    {
      "label": "skeptical",
      "score": 0.04
    },
    {
      "label": "tired",
      "score": 0.04
    },
    {
      "label": "formal",
      "score": 0.04
    },
    {
      "label": "casual",
      "score": 0.04
    },
    {
      "label": "impatient",
      "score": 0.04
    },
    {
      "label": "distracted",
      "score": 0.04
    }
  ],
  "tagged_transcript": "<transcript start=\"0\" end=\"1.8\"><happy score=\"0.82\" start=\"0\" end=\"1.8\" scope=\"clip\"><warm score=\"0.7\" start=\"0\" end=\"1.8\" scope=\"clip\">That sounds <emph phrase=\"p1\" scheme=\"aix_marsec_iu_v1\" score=\"0.91\" origin=\"model_predicted\" experimental=\"true\" confidence=\"conditional_on_predicted_phrase\">great.</emph></warm></happy></transcript>",
  "prosody": {
    "version": "spectra2.prosody.v1",
    "status": "experimental",
    "words": [
      {
        "word_id": "w1",
        "text": "That",
        "start_s": 0,
        "end_s": 0.28,
        "prominence": null,
        "nuclear": false
      },
      {
        "word_id": "w2",
        "text": "sounds",
        "start_s": 0.28,
        "end_s": 0.78,
        "prominence": 0.32,
        "nuclear": false
      },
      {
        "word_id": "w3",
        "text": "great.",
        "start_s": 0.78,
        "end_s": 1.8,
        "prominence": 0.86,
        "nuclear": true
      }
    ],
    "phrases": [
      {
        "phrase_id": "p1",
        "scheme": "aix_marsec_iu_v1",
        "start_s": 0,
        "end_s": 1.8,
        "nuclear_word_id": "w3",
        "score": 0.91,
        "score_semantics": "conditional_on_phrase_and_profile",
        "origin": "model_predicted",
        "experimental": true
      }
    ]
  },
  "usage": {
    "audio_seconds": 1.8,
    "billable_seconds": 1.8,
    "rate_per_minute_usd": "0.0120",
    "estimated_cost_usd": "0.000360",
    "pricing_version": "2026-09-26",
    "billing_unit": "audio_second"
  }
}

For display, assign the returned string to textContent or render it as a React text value. Audio transcripts can contain escaped characters such as &lt; and &amp;; do not inject the string with innerHTML. The playground's Reading tab prints the markup and its JSON tab shows the full response.

These fields are returned on the final batch or streaming result. Early transcript events carry plain text; wait for the final result to add emphasis. The format does not add speaker diarization or word-level emotion labels. The combined extension is limited to 64 KiB of UTF-8 JSON, with at most 512 words and 256 phrases.

Supported languages

Transcription supports these 25 languages. Language detection is automatic; send the recording without a language parameter. The codes below are for reference.

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

Emotion and speaking-style scores use the same English label names in every response.

Streaming audio

Send microphone audio while someone speaks over wss://speech-api.oruk.ai/v1/audio/spectra-2/stream. The connection uploads the recording continuously. Send finish when they stop to receive the same whole-recording transcript and 31 scores as a batch request. Results are final; provisional words and automatic end-of-speech detection are not part of this endpoint.

Authenticate with your API key in the WebSocket Authorization header from your server. Send the start message below, then binary mono 16 kHz PCM16 little-endian frames, each at most 32 KiB. Frames of 20–100 ms work well; each connection accepts at most 4,096 client messages. A connection accepts one recording of 45 ms–60 seconds. Send a start message within 10 seconds and finish within 75 seconds. The account playground handles browser microphone access for you.

Spectra-2 streaming · Python
# pip install websockets
import asyncio, json, os, uuid, wave
from websockets.asyncio.client import connect

async def main():
    request_id = str(uuid.uuid4())  # Save this ID if completion is uncertain.
    print("request_id:", request_id, flush=True)
    with wave.open("clip.wav", "rb") as audio:
        assert (audio.getnchannels(), audio.getframerate(), audio.getsampwidth()) == (1, 16000, 2)
        async with connect(
            "wss://speech-api.oruk.ai/v1/audio/spectra-2/stream",
            additional_headers={"Authorization": "Bearer " + os.environ["ORUK_API_KEY"]},
            max_size=131072, open_timeout=15,
        ) as socket:
            await socket.send(json.dumps({
                "type": "start", "model": "oruk-spectra-2", "task": "analysis",
                "format": "pcm_s16le", "sample_rate": 16000, "channels": 1,
                "request_id": request_id,
            }))
            ready = json.loads(await socket.recv())
            if ready["type"] != "ready":
                raise RuntimeError(ready)
            # Replace this loop with frames from your microphone.
            while chunk := audio.readframes(1600):
                await socket.send(chunk)
                await asyncio.sleep(len(chunk) / 32000)
            await socket.send('{"type":"finish"}')
            result = json.loads(await socket.recv())
            if result["type"] != "result":
                raise RuntimeError(result)
            print(json.dumps(result["result"], indent=2))

asyncio.run(main())

The server sends ready, followed by result or error after finishing. result.result follows the batch response schema. Use task: transcription for the transcription task. Both tasks return every score. Session setup, recording time, and stop-to-result time are separate measurements.

Send {"type":"cancel"} or close before finish to cancel without inference. After finish, processing and billing may complete even if you disconnect. Keep the request ID and check Usage before starting a replacement request. There is no automatic reconnect or replay. An existing prepared API session can be supplied through X-Oruk-Session; use one of its reserved request IDs in the start message and finish before its expires_at_ms. Ordinary API-key connections support the full 60 seconds without a prepared session.

Prepare a direct connection for shorter recordings

Prepare before speaking to reduce the wait after Stop. First call POST /v1/audio/sessions, then POST /v1/audio/stream-sessions with your API key, the returned X-Oruk-Session, and one of its request IDs as X-Request-ID. Send {"model":"oruk-spectra-2","task":"analysis"} as JSON. Open the returned URL using its protocol and ticket as WebSocket subprotocols. Keep both setup calls and your API key on your server. Do not log session tickets.

Each prepared session has a 30-second lifetime, including setup. Start promptly and keep the recording within the max_audio_seconds in ready, finishing before expires_at_ms. Preparation does not extend an existing session. If direct setup is unavailable, or you need a longer recording, choose the ordinary stream before recording. The result and account charges follow the same rules as batch. There is no automatic retry after Finish.

Prepared Spectra-2 streaming · Python
# pip install httpx websockets
import asyncio, json, os, time, uuid, wave
import httpx
from websockets.asyncio.client import connect

async def main():
    base = "https://speech-api.oruk.ai"
    async with httpx.AsyncClient(
        headers={"Authorization": "Bearer " + os.environ["ORUK_API_KEY"]},
        timeout=15, follow_redirects=False,
    ) as client:
        response = await client.post(base + "/v1/audio/sessions", json={
            "model": "oruk-spectra-2", "id": str(uuid.uuid4()),
        })
        response.raise_for_status()
        prepared = response.json()
        request_id = prepared["request_ids"][0]
        response = await client.post(base + "/v1/audio/stream-sessions", headers={
            "X-Oruk-Session": prepared["token"], "X-Request-ID": request_id,
        }, json={"model": "oruk-spectra-2", "task": "analysis"})
        response.raise_for_status()  # If unavailable, choose an ordinary stream before recording.
        session = response.json()

    print("request_id:", request_id, flush=True)  # Keep this ID; never log the ticket.
    with wave.open("clip.wav", "rb") as audio:
        assert (audio.getnchannels(), audio.getframerate(), audio.getsampwidth()) == (1, 16000, 2)
        async with connect(session["url"], subprotocols=[session["protocol"], session["ticket"]],
                           compression=None, max_size=131072, open_timeout=10) as socket:
            assert socket.subprotocol == session["protocol"]
            await socket.send(json.dumps({
                "type": "start", "model": "oruk-spectra-2", "task": "analysis",
                "format": "pcm_s16le", "sample_rate": 16000, "channels": 1,
                "request_id": request_id, "transcript_events": True,
            }))
            ready = json.loads(await asyncio.wait_for(socket.recv(), 10))
            if (ready.get("type") != "ready" or ready.get("request_id") != request_id
                    or ready.get("transcript_events") is not True):
                raise RuntimeError(ready)
            if audio.getnframes() / 16000 >= ready["max_audio_seconds"] - 1:
                await socket.send('{"type":"cancel"}')
                raise ValueError("Use an ordinary stream for this longer recording.")
            # Send 100 ms microphone frames. Honor the returned deadline.
            while chunk := audio.readframes(1600):
                if time.time() * 1000 >= session["expires_at_ms"] - 1000:
                    await socket.send('{"type":"cancel"}')
                    raise TimeoutError("Session expired before Finish; no inference requested.")
                await socket.send(chunk)
                await asyncio.sleep(len(chunk) / 32000)
            await socket.send('{"type":"finish"}')
            # One deadline covers both events. Never reconnect or replay after Finish.
            deadline = time.monotonic() + 45
            transcript = json.loads(await asyncio.wait_for(socket.recv(), 45))
            if (transcript.get("type") != "transcript" or transcript.get("request_id") != request_id
                    or transcript.get("is_final") is not True or not isinstance(transcript.get("text"), str)):
                raise RuntimeError(transcript)
            print(transcript["text"], flush=True)
            result = json.loads(await asyncio.wait_for(socket.recv(), max(0, deadline - time.monotonic())))
            if (result.get("type") != "result" or result.get("request_id") != request_id
                    or result.get("result", {}).get("text") != transcript["text"]):
                raise RuntimeError(result)
            print(json.dumps(result["result"], indent=2))

asyncio.run(main())

Set transcript_events: true in the start message to receive final text as soon as it is ready after Finish. The server acknowledges this option in ready, then sends a transcript event with text, is_final: true, and the same request_id. Display that text immediately and keep listening for result, which includes the same text and all 31 scores. These are two events from one analysis and one charge. The transcript covers the complete recording.

Try your recording

Upload a recording and use your API key to see the transcript and every score.

Errors and retries

Keep the same X-Request-ID, endpoint and exact file bytes when retrying. Re-encoding a recording creates different input. A pending or uncertain request returns 409 request_in_progress; a completed ID returns 409 request_already_completed. Responses and audio are not retained for replay. Changing the audio, task, model or key with the same ID returns 409 idempotency_conflict. After a network error or a 5xx response, keep the original ID; automatically generating a new one can run and charge the request again.

400 · 413 · 415
Check the fields, audio format, duration and upload size before sending corrected input with a new request ID.
401 · 402 · 403
Check the API key, account access, remaining minutes and spending cap. Resolve the account issue before retrying.
429 upload_busy · model_busy
Wait at least the Retry-After interval and reduce concurrent requests. upload_busy accepts another attempt with the same ID. model_busy closes the attempt without inference or a charge; use a new ID after waiting.
409 request_failed
That attempt was rejected before successful inference. Resolve its original error before starting another request with a new ID.

Errors include error.code, error.message and error.request_id. Save the request ID when contacting support. Keep API keys on your server, outside browser code and source control.

For repeated calls, reuse your HTTP client to keep the connection open. FLAC reduces upload size without changing the audio. The main OpenAPI schema includes the complete request and response fields.