Audio Transcriptions

The /v1/audio/transcriptions endpoint provides high-accuracy automatic speech recognition (ASR/STT) by proxying requests to state-of-the-art transcription models like Whisper through nRouter's unified gateway. The endpoint accepts multipart file uploads, provides automatic provider failover, and guarantees strict per-second billing at raw provider list prices.

POST https://api.nrouter.ai/v1/audio/transcriptions

Architectural Role & Lifecycle

Audio transcription workloads require streaming binary uploads and resilient execution for prolonged audio processing tasks. nRouter orchestrates transcription requests through a structured preflight pipeline:

1. Phase 1: Key Authentication & Tenancy Verification: Validates the caller's virtual key (sk-nrouter-...) against the tenant organization and verifies model entitlement for ASR engines.
2. Phase 2: Concurrency & Rate Limit Gating: Validates that the tenant organization has active RPM and concurrent job capacity before accepting the multipart payload stream.
3. Phase 3: Payload Inspection & Safety Screening: Verifies audio container integrity, size ceilings (25 MB maximum per upload), and applies prompt injection checks to the optional prompt steering parameter.
4. Phase 4: Duration Credit Reservation: Estimates audio duration from stream headers and places an atomic hold on organization credits. If the request is rejected during preflight, zero credits are deducted or held.
5. Upstream Execution & Settlement: Dispatches the audio stream to the designated provider. If an upstream outage occurs, nRouter executes automatic retry or fallback routing. Upon completion, exact audio duration in seconds is settled against the provider's published list price.

Request Parameters

Requests must be sent as multipart/form-data:

Response Formats & Payload Schemas

Standard JSON Response (response_format: "json")

{
  "text": "Welcome to nRouter, the multi-cloud enterprise AI routing gateway."
}

Verbose JSON Response (response_format: "verbose_json")

When detailed timing information is requested, verbose_json returns full metadata including segments, tokens, and word-level timestamps:

{
  "task": "transcribe",
  "language": "english",
  "duration": 4.82,
  "text": "Welcome to nRouter, the multi-cloud enterprise AI routing gateway.",
  "segments": [
    {
      "id": 0,
      "seek": 0,
      "start": 0.0,
      "end": 4.82,
      "text": " Welcome to nRouter, the multi-cloud enterprise AI routing gateway.",
      "tokens": [50364, 7062, 281, 412, 17820, 11, 264, 4833, 12, 11624, 7762, 9552, 26978, 13, 50605],
      "temperature": 0.0,
      "avg_logprob": -0.1824,
      "compression_ratio": 1.12,
      "no_speech_prob": 0.0014
    }
  ],
  "words": [
    { "word": "Welcome", "start": 0.0, "end": 0.52 },
    { "word": "to", "start": 0.54, "end": 0.72 },
    { "word": "nRouter", "start": 0.74, "end": 1.34 }
  ]
}

Headers Reference

Inbound Request Headers

Outbound Response Headers

SDK Code Examples

import { nRouter } from "@nrouter_ai/sdk";
import * as fs from "node:fs";

const client = new nRouter({
  apiKey: process.env.NROUTER_API_KEY,
});

const fileStream = fs.createReadStream("interview.mp3");

const transcription = await client.audio.transcriptions.create({
  file: fileStream,
  model: "whisper-1",
  language: "en",
  response_format: "verbose_json",
  timestamp_granularities: ["word", "segment"],
});

console.log("Transcribed Text:", transcription.text);
console.log(`Audio Duration: ${transcription.duration}s`);

Error Handling & Common Failure Modes

Every error response returns a standard JSON error object with a corresponding HTTP status code:

{
  "error": {
    "type": "gateway_error",
    "message": "Maximum content size of 25MB exceeded.",
    "code": "payload_too_large"
  }
}

curl -X POST "https://example.com/v1/audio/transcriptions" \  -F model="string" \  -F file="string"

{  "text": "The transcribed speech."}