Developer documentation
Speech API quickstart
Analyze an English recording with Resonance 1 to get a transcript, emotion and speaking-style labels. These complete Python, Node.js and cURL recipes download sample audio, make one API request and check for errors. Use an active plan or trial and a server-side API key.
Choose the right starting point
This example uses the stable English file API: WAV, FLAC, MP3, M4A, OGG or WebM, up to 30 MB and 60 minutes. One audio minute uses one speech understanding minute. Plans and trial allowances.
- For short multilingual files: Spectra-2 transcription in 25 languages.
- For expression without transcription: Resonance 2 scores and access approval.
- For live speech: Realtime tokens and phrase emotion.
1. Set your API key
Create a key in your account. Store it on your server, outside source control. Replace the placeholder below in your terminal; never ship a permanent key in browser JavaScript. To try your own recording first, use the public speech demo.
export ORUK_API_KEY='your-api-key'2. Run one request
Each recipe uses 1029_IEO_HAP_HI.wav, a 2.1-second recording. Running the API request consumes account usage. Select a language below; the setup and run commands are included.
Requires cURL 7.76+ and uuidgen (included with macOS; available in uuid-runtime on Ubuntu). Paste this into your terminal.
# Set ORUK_API_KEY to your secret API key first.
: "${ORUK_API_KEY:?Set ORUK_API_KEY first.}"
curl --fail --silent --show-error --location --max-time 30 --output '1029_IEO_HAP_HI.wav' 'https://oruk.ai/samples/emotional/1029_IEO_HAP_HI.wav' || exit 1
curl --fail-with-body --silent --show-error --max-time 180 'https://speech-api.oruk.ai/v1/audio/analysis' \
-H "Authorization: Bearer $ORUK_API_KEY" \
-H "X-Request-ID: $(uuidgen)" \
--form-string 'model=oruk-resonance' \
-F 'file=@"1029_IEO_HAP_HI.wav"'3. Read the output
This is the saved response excerpt for the supplied recording. A new request also returns a result ID, timed segments and usage, and may change with model updates. Label scores are independent; they do not sum to one.
{
"object": "speech.result",
"task": "analysis",
"model": "oruk-resonance",
"text": "It's 11 o'clock!",
"duration": 2.06875,
"emotions": [
{
"label": "frustrated",
"score": 0.9688562154769897
},
{
"label": "happy",
"score": 0.9241418242454529
}
],
"styles": [
{
"label": "energetic",
"score": 0.9967268705368042
},
{
"label": "impatient",
"score": 0.9473810195922852
},
{
"label": "irritated",
"score": 0.8933094143867493
},
{
"label": "playful",
"score": 0.7969253659248352
}
]
}The CREMA-D sample was used in training and selected for this demo. It is not evaluation evidence. Audio license. For your own recordings, use local files and retain full responses before interpreting them.
Handle errors before adding retries
- 401 or 402
- Check the key, subscription, allowance and spending limit. Do not retry an unchanged request automatically.
- 400, 413 or 422
- Correct the audio format, size or request fields before retrying.
- 429, 5xx or a lost connection
- Bound retries and preserve the original request ID. A lost connection does not prove the server did no work. Follow the endpoint’s idempotency behavior and check account usage.