Audio Speech
Synthesize natural speech audio from input text using OpenAI-compatible text-to-speech models with customizable voices, multiple codecs, and list pricing.
The /v1/audio/speech endpoint provides low-latency streaming text-to-speech (TTS) synthesis across top-tier providers through an OpenAI-compatible wire. Routing through nRouter delivers multi-provider failover, pre-call moderation, transparent character-level billing at raw list prices, and edge telemetry.
POST https://api.nrouter.ai/v1/audio/speechRequests run preflight as Chat Completions: key validation, rate limits, and content inspection (x-nr-guardrails: blocked returns HTTP 400 with zero spend). Character-based reservations settle upon streaming completion.
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | Yes | — | Model ID (e.g. tts-1, tts-1-hd). |
input | string | Yes | — | Text to synthesize (max 4,096 characters). |
voice | string | Yes | — | Voice persona (alloy, echo, fable, onyx, nova, shimmer). |
response_format | string | No | mp3 | Format: mp3, opus, aac, flac, wav, pcm. |
speed | number | No | 1.0 | Speed multiplier from 0.25 to 4.0. |
Examples
curl -X POST https://api.nrouter.ai/v1/audio/speech \
-H "Authorization: Bearer $NROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tts-1","voice":"alloy","input":"Hello from nRouter."}' \
--output speech.mp3Headers & Errors
Required request headers: Authorization: Bearer sk-nrouter-... and Content-Type: application/json. Response Content-Type matches the audio MIME type; telemetry includes x-nr-request-id, x-nr-latency-ms, x-nr-request-cost, x-nr-model. See Chat Completions.
| HTTP Status | Error Code | Reason |
|---|---|---|
| 400 Bad Request | invalid_request | Missing required parameters, invalid speed, or text exceeding 4,096 characters. |
| 400 Bad Request | guardrail_blocked | Input text violated moderation or injection thresholds. |
| 401 Unauthorized | invalid_api_key | Virtual key missing, expired, or invalid. |
| 402 Payment Required | insufficient_credits | Organization balance insufficient for character reservation. |
| 404 Not Found | model_not_found | Speech model unrecognized or unauthorized. |
| 429 Too Many Requests | rate_limit_exceeded | RPM ceiling exceeded; check x-nr-limit-source. |
Authorization
NRouterApiKey Your nRouter virtual key (sk-nrouter-…). Sent as Authorization: Bearer sk-nrouter-….
In: header
Header Parameters
Target MCP server ID when routing MCP tool calls or prompts through the gateway
Caller SDK runtime language identification (e.g. typescript, python, rust, go)
Caller session identifier allowed at edge for grouping related client turns
Inbound trace detail level override for request lifecycle spans
Value in
- "off"
- "stages"
- "verbose"
Inbound stage-level trace emission override
Value in
- "off"
- "stages"
- "verbose"
Accepted so a client sending it is not refused; the value is not recorded and not propagated. Every response carries the gateway's own trace ID in this header, never the one sent.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/audio/speech" \ -H "Content-Type: application/json" \ -d '{ "model": "string", "input": "string", "voice": "string" }'"audio/mpeg bytes (rendered as an <audio> player)"