Authentication
Every request carries an API key in the Authorization header:
Keys are issued per organization from the dashboard.
Key format
A key is a prefix followed by 32 bytes of randomness encoded in base62 — 51 characters in total:
Live and test keys
You choose the mode when you create a key in the dashboard.
Use a test key to build and check your integration without cost. Switch to a live key to get real transcripts. See test keys for how a test key differs.
Only the SHA-256 hash of a key is stored, so the plaintext is shown once at
creation and cannot be recovered afterwards. Lose it and you mint a new one.
The dashboard and the API only ever show the first 12 characters
(nl_live_YxQF), which is enough to tell your keys apart and useless on its
own.
A key carries its organization, its scopes, an optional expiry, its own rate limit, and a last-used timestamp.
Test keys
A key that starts with nl_test_ is a test key. It never runs the model and
never costs anything, so you can wire up an integration without spending
balance or GPU time.
A test key answers the same way a live key does, with these differences:
- The transcript is a dummy. It is the same text for the same audio length and
language, and its length follows the duration of your audio. - The answer takes about one second.
- The response has the header
x-nyra-test-mode: true. A live key never sets it. x-nyra-cost-usdis0.000000. No wallet hold is placed and no ledger entry is written.
Everything else is identical. The body has the same fields: verbatim,
intended, word timestamps for both, alignment, duration, language and
usage. Your request is checked the same way, so a missing model, an
unsupported language, an oversized file or a file that is not audio gives the
same error as with a live key. The request still appears in the request
explorer, marked as not billable.
Do not use a test key to judge transcription quality. For that, use a live key or the dashboard playground. Playground runs are billed like live requests.
Errors
Authentication failures return the standard error envelope with
type: "authentication_error" and HTTP 401.
No key at all:
A key that is unknown, malformed, revoked or expired. The key is echoed back redacted to its first 8 and last 4 characters, so you can tell which key failed without the error log becoming a place credentials leak:
All four causes return the same message. Distinguishing “unknown” from “revoked” would confirm to whoever holds a leaked key that it used to be real.
Scopes
A key can be narrowed to a subset of the API. The available scopes are:
A key created without scopes is unrestricted — that is the default. Narrowing is opt-in, and it is worth doing for any key that leaves your own infrastructure: a key that only transcribes cannot enumerate the catalogue, and a key that only reads the catalogue cannot spend money.
Calling an endpoint your key lacks the scope for returns HTTP 403:
Rate limits
Limits are per key and reset on a rolling one-minute window. The default is
600 requests per minute; a lower or higher limit can be set on each key in
the dashboard. Every /v1 response carries:
Counters are shared across every API instance, so a limit is a limit no matter which server answers.
Exceeding the limit returns HTTP 429:
A request that arrives with no usable key is limited by client IP instead,
at a deliberately low rate — it is on its way to a 401 regardless.