Skip to content

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.

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.

Terminal · macOS / Linux
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.

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

Saved Resonance 1 response excerpt
{
  "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.

Apply the production retry and observability guide.