Audio Translations

The /v1/audio/translations endpoint translates spoken audio from over 90 source languages directly into English text using state-of-the-art ASR models like Whisper. By wrapping translation workloads within nRouter's unified gateway, engineering teams gain multi-provider failover, strict multi-tenant budget ceilings, and zero-markup provider pass-through pricing.

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

Architectural Role & Lifecycle

Translating spoken audio requires reliable stream processing and automatic fallback when upstream cloud providers experience transient degradation:

1. Phase 1: In-Memory Key Auth & ACLs: Verifies virtual key hash (sk-nrouter-...) and checks tenant permissions for the target audio translation model.
2. Phase 2: Tenant Rate Limits & Budget Check: Validates the organization's sliding-window RPM quotas and verifies balance availability.
3. Phase 3: Stream Inspection & Prompt Guardrails: Validates the audio container structure and inspects any guiding prompt for prompt injections. If safety rules trigger, the request is halted with HTTP 400 (x-nr-guardrails: blocked).
4. Phase 4: Duration Credit Reservation: Places an atomic credit hold based on estimated audio duration. If the request was halted in preflight, $0 is deducted or held.
5. Provider Execution & Final Settlement: Sends the multipart stream to the upstream provider. Upon receiving the translated English transcript, nRouter calculates the exact duration in seconds, settles against the provider list price, and emits telemetry headers.

Request Parameters

The request body must be submitted as multipart/form-data:

Response Payloads

Standard JSON (response_format: "json")

{
  "text": "Hello, how are you today? We are testing multi-cloud voice routing."
}

Verbose JSON (response_format: "verbose_json")

{
  "task": "translate",
  "language": "spanish",
  "duration": 5.48,
  "text": "Hello, how are you today? We are testing multi-cloud voice routing.",
  "segments": [
    {
      "id": 0,
      "seek": 0,
      "start": 0.0,
      "end": 5.48,
      "text": " Hello, how are you today? We are testing multi-cloud voice routing.",
      "tokens": [50364, 2425, 11, 703, 389, 345, 1909, 30, 775, 389, 4268, 5978, 12, 11624, 4678, 26978, 13, 50638],
      "temperature": 0.0,
      "avg_logprob": -0.198,
      "compression_ratio": 1.08,
      "no_speech_prob": 0.002
    }
  ]
}

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("spanish_audio.mp3");

const translation = await client.audio.translations.create({
  file: fileStream,
  model: "whisper-1",
  response_format: "verbose_json",
});

console.log("English Translation:", translation.text);
console.log(`Original Audio Duration: ${translation.duration}s`);

Error Codes & Failure Handling

Errors return standard JSON error structures with descriptive error messages:

{
  "error": {
    "type": "gateway_error",
    "message": "Unsupported file format. Please upload an MP3, MP4, MPEG, MPGA, M4A, WAV, or WEBM file.",
    "code": "invalid_request"
  }
}

Audio Translation Architecture & Billing Mechanics

The audio translation pipeline combines acoustic feature extraction, multi-lingual phoneme recognition, and neural machine translation into a single unified step.

Duration-Based Billing Precision

Unlike LLM completions which charge per token, audio translation is priced per second of parsed audio duration:

• Phase 4 Credit Reservation: The gateway inspects container headers (e.g. ID3 tags, RIFF chunks) during initial upload to estimate duration and place a credit hold.
• Exact Duration Settlement: Spend settles at exact list prices rounded to the nearest millisecond upon completion.
• Zero Cost on Rejections: If a file upload is rejected by edge WAF or guardrails (e.g. unsupported container or file size ceiling), $0 is reserved or charged.

Best Practices for Multilingual Ingestion

1. Chunking Long Recordings: For recordings exceeding 25 MB or 15 minutes, split audio files into continuous segments at natural pauses using tools like FFmpeg or WebAudio.
2. Steering Context with Prompts: Provide relevant terminology, company names, or industry acronyms in the optional prompt parameter to anchor the translation vocabulary.
3. Format Selection: Uploading compressed formats such as MP3 or Opus encoded M4A drastically cuts network transmission latency compared to raw PCM WAV files without sacrificing translation accuracy.

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

{  "text": "Hello, how are you?"}