Quickstart

POST /v1/audio/transcriptions takes an audio file and returns a verbatim transcript (fillers, repetitions and cut-offs included), an intended transcript (the fluent version), word timestamps for both, and an alignment that links the two.

export NYRA_API_KEY="nl_live_YxQFoF6p2xKvStMzWhYhwPMNSlEnWTwzYL83OJCbyTo"

curl https://api.nyra-labs.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $NYRA_API_KEY" \
  -F "file=@clip.wav" \
  -F "model=crisperwhisper-v2" \
  -F "language=en"

Parameters

The request is multipart/form-data; any other body answers 400 invalid_content_type before it is read.

Accepted formats

• wav
• mp3
• m4a (AAC)
• flac
• ogg (Vorbis or Opus)
• webm (audio only)

Any other format, and any file with a video stream, answers 400 unsupported_file_type. The model works on 16 kHz mono audio, so to keep requests no larger than necessary, resample your audio to 16 kHz before you send it.

Supported languages

language is an ISO-639-1 code (three letters where no two-letter code exists). These languages are officially supported:

The following languages are available in beta:

Case does not matter (DE is de). Region subtags are not accepted: send pt, not pt-BR.

Send language when you know it. When it is omitted, the model spends an extra decoding pass on the first 30 seconds of audio to detect the language, and a wrong guess (a short clip, a noisy opening, a name in another language) degrades the whole transcript. When you pass it, that pass is skipped and the result is the language you sent.

The response

For a clip in which someone says “I I want um to go home”:

{
  "language": "en",
  "duration": 2.84,
  "verbatim": {
    "text": "I I want um to go home",
    "words": [
      { "word": " I",    "start": 0.12, "end": 0.26, "alignment_index": 0 },
      { "word": " I",    "start": 0.34, "end": 0.48, "alignment_index": 1 },
      { "word": " want", "start": 0.52, "end": 0.81, "alignment_index": 2 },
      { "word": " um",   "start": 0.95, "end": 1.31, "alignment_index": 3 },
      { "word": " to",   "start": 1.58, "end": 1.69, "alignment_index": 4 },
      { "word": " go",   "start": 1.72, "end": 1.94, "alignment_index": 5 },
      { "word": " home", "start": 1.98, "end": 2.41, "alignment_index": 6 }
    ]
  },
  "intended": {
    "text": "I want to go home",
    "words": [
      { "word": " I",    "start": 0.34, "end": 0.48, "alignment_index": 1 },
      { "word": " want", "start": 0.52, "end": 0.81, "alignment_index": 2 },
      { "word": " to",   "start": 1.58, "end": 1.69, "alignment_index": 4 },
      { "word": " go",   "start": 1.72, "end": 1.94, "alignment_index": 5 },
      { "word": " home", "start": 1.98, "end": 2.41, "alignment_index": 6 }
    ]
  },
  "alignment": [
    { "type": "repetition", "verbatim": "I",    "intended": null },
    { "type": "match",      "verbatim": "I",    "intended": "I" },
    { "type": "match",      "verbatim": "want", "intended": "want" },
    { "type": "filler",     "verbatim": "um",   "intended": null },
    { "type": "match",      "verbatim": "to",   "intended": "to" },
    { "type": "match",      "verbatim": "go",   "intended": "go" },
    { "type": "match",      "verbatim": "home", "intended": "home" }
  ],
  "usage": { "type": "duration", "seconds": 3 }
}

verbatim and intended

Both are a text string plus a words list, and both come from one decode: CrisperWhisper 2 produces the two transcripts together rather than transcribing once and cleaning up afterwards, so they agree on what was in the audio and differ only in what they keep.

• verbatim is what was said. It keeps fillers (um, uh), repetitions, false starts, and cut-off words. Use it when the manner of speaking is the point: clinical assessment, speech therapy, fluency research, subtitles that must be faithful.
• intended is what was meant: the same speech read as fluent text. Use it for notes, search, summaries, or anything downstream that would trip over a stutter.

Words and timestamps

Each word has a start and end in seconds from the start of the recording, and keeps its leading space. Concatenating the words reproduces the track’s text:

assert "".join(w["word"] for w in track["words"]).strip() == track["text"]

The leading space is how a word tells you whether it began a new token or continued one; keep it if you rebuild text, strip it if you display words on their own.

Timestamps are per track: each transcript is timed from its own decode, so a word that appears in both tracks (the second I above) normally carries the same timing in both, but the two are not guaranteed to be identical to the millisecond.

alignment and alignment_index

alignment is the link between the two tracks, in reading order. Each entry names the token on the verbatim side, the token on the intended side (or null if there is none), and how they relate:

Each word’s alignment_index is the index of its entry in alignment, so you can walk from a verbatim word to its intended counterpart (or learn that it has none) without string matching. It is null when the classifier could not prove the link. A null is never a guess: the API does not invent links it cannot show.

alignment itself is null when the classifier could not run on this clip, which happens on very long or very dense recordings that exceed its bounds. That is not an error: verbatim and intended are complete and correct without it, and the request is billed normally.

Audio without speech

Silence, music or noise is a valid request, not an error: both transcripts come back with an empty text and an empty words list, alignment is [], and the audio is billed like any other. Check verbatim.text before assuming something was said.

usage

usage.seconds is the audio’s decoded duration rounded up to a whole second: what you were charged for, at $0.90 per audio hour ($0.00025 per second). The 2.84 s clip above is 3 seconds, $0.00075. See Billing.

Python

import os
import requests
with open("clip.wav", "rb") as audio:
    response = requests.post(
        "https://api.nyra-labs.com/v1/audio/transcriptions",
        headers={"Authorization": f"Bearer {os.environ['NYRA_API_KEY']}"},
        files={"file": ("clip.wav", audio, "audio/wav")},
        data={"model": "crisperwhisper-v2", "language": "en"},
        timeout=600,
    )
response.raise_for_status()
result = response.json()
print(result["verbatim"]["text"])
print(result["intended"]["text"])
for word in result["verbatim"]["words"]:
    print(f"{word['start']:6.2f} {word['end']:6.2f} {word['word']}")

Node

import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("file", await openAsBlob("clip.wav"), "clip.wav");
form.append("model", "crisperwhisper-v2");
form.append("language", "en");
const response = await fetch("https://api.nyra-labs.com/v1/audio/transcriptions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NYRA_API_KEY}` },
  body: form,
});
if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}
const result = await response.json();
console.log(result.verbatim.text);
console.log(result.intended.text);

Limits

Both the size and the length are checked before any money is reserved and before the audio reaches a model. Split long recordings client-side; a 25 MB budget fits about 13 minutes of 16 kHz mono WAV or well over an hour of compressed audio, so which limit you meet first depends on the format.

Response headers

Rate-limit headers (x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-reset-requests) are on every response too; see Authentication.

Retries and idempotency

The endpoint accepts an Idempotency-Key header of up to 255 characters. Once a request with a given key has completed, a retry with the same key within 24 hours replays the stored response: the same body and the same x-request-id, plus x-nyra-idempotent-replay: true, and nothing is charged again.

curl https://api.nyra-labs.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $NYRA_API_KEY" \
  -H "Idempotency-Key: 6f1c0b4e-2f19-4f0e-b2f1-9a3c5d7e8f01" \
  -F "file=@clip.wav" -F "model=crisperwhisper-v2" -F "language=en"

Two things it is not:

• It is not a lock. Two genuinely concurrent requests with the same key both run and both charge. Wait for the first to finish before retrying.
• It is not a cache under zero retention. If your organization stores no transcripts, the response is not kept either; a retry answers 400 idempotency_response_expired without running or charging again.

A key is bound to the model and language of its first request: a retry under the same key with a different language or model answers 400 idempotency_key_in_use rather than the other request’s transcript.

Keys are namespaced to your organization, so nobody else’s key collides with yours.

Errors

Every non-2xx response carries the same envelope:

{
  "error": {
    "message": "The audio is longer than the 3600 second limit. Split it into shorter files.",
    "type": "invalid_request_error",
    "param": "file",
    "code": "audio_too_long"
  }
}

code is the field to branch on; message is for humans and may change. param names the offending field when there is one.

insufficient_quota and rate_limit_exceeded share a status code but not a remedy: back off on the second, stop and top up on the first. Check code, not the status.

The API reference is generated from the same OpenAPI spec the server is built from. If a behaviour is not in the spec, it is not part of the public API.