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.
python -m pip install https://oruk.ai/sdk/oruk-0.2.15-py3-none-any.whlimport 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
# 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,experimentalorunavailable. Plaintextand 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.
<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
emotionsandstylesarrays 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 throughnuclear_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.
{
"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
nullwhen unavailable. It is separate from nuclear selection and transcription confidence. Preserve a returned numeric0. - words[].nuclear
trueselects the nucleus;falsemarks another word inside the same accepted phrase;nullmeans 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"andexperimental: true. A phrase score usesscore_semantics: "conditional_on_phrase_and_profile".
Handle missing or unavailable emphasis
| Status | What to do |
|---|---|
| experimental | Read the predicted word/phrase data with its experimental provenance. An empty phrases array is valid. |
| available | The extension has verified-phrase support. Inspect each phrase's origin and scheme. |
| unavailable | Use text. Word and phrase arrays are empty; reason explains why. The tagged string may be empty. |
| Both fields absent | Use 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
{
"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
{
"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 < and &; 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.
# 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.
# 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-Afterinterval and reduce concurrent requests.upload_busyaccepts another attempt with the same ID.model_busycloses 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.