Skip to main content

Audio Transcription, Translation & Speech API

GoRoute AI Gateway provides full OpenAI-compatible support for multi-modal audio processing across three core capabilities:

  1. Speech-to-Text Transcription (POST /v1/audio/transcriptions): Transcribes audio in its original language using OpenAI Whisper or open-source equivalents.
  2. Audio Translation (POST /v1/audio/translations): Transcribes audio from any supported source language directly into English.
  3. Text-to-Speech Synthesis (POST /v1/audio/speech): Synthesizes lifelike spoken audio from text using multi-voice neural models (tts-1, tts-1-hd).

Endpoint Specifications​

EndpointMethodInput TypeDescription
/v1/audio/transcriptionsPOSTmultipart/form-dataConverts spoken audio into text.
/v1/audio/translationsPOSTmultipart/form-dataTranscribes and translates non-English audio to English.
/v1/audio/speechPOSTapplication/jsonGenerates streaming audio from textual input.
  • Authentication: Bearer sk-gw-... (Virtual Key or Master Admin Key)
  • Supported Audio Codecs: mp3, opus, aac, flac, wav, m4a, webm
  • Max Audio File Upload: 25 MB (enforced via http.MaxBytesReader)

Architecture: Zero-Memory Retryable Disk Spooling​

When handling large audio uploads, loading entire audio files into memory buffers would cause severe memory pressure and garbage collection pauses under high concurrent loads. Furthermore, if an upstream provider fails mid-flight, a pure streaming pipeline cannot retry because the HTTP request body stream has already been consumed.

GoRoute solves this with Zero-Memory Disk Spooling:

1. POST /v1/audio/transcriptions (Multipart 25MB) 2. Spool stream to disk (gw-audio-*.tmp) 3. Stream from disk spool 4. HTTP 503 Service Unavailable 5. Rewind file descriptor (Seek 0, Zero GC) 6. Re-stream from disk spool 7. HTTP 200 OK (Transcription JSON) 8. Unlink & remove spool file 9. Return Transcript + Telemetry Client GoRoute AI Gateway Primary Provider (STT) Fallback Provider (STT)
  1. Disk Spooling: Incoming multipart files are written directly to a temporary file (gw-audio-*.tmp) in chunks using io.Copy.
  2. Infinite Rewindability: The gateway's reliability layer can rewind the file descriptor (Seek(0, io.SeekStart)) to replay the exact audio bytes to healthy fallback deployments without re-reading from the client.
  3. Immediate Cleanup: Once the upstream completes (or fails all retries), the temporary file is safely unlinked (defer os.Remove(spoolPath)).

Speech-to-Text Transcription (/v1/audio/transcriptions)​

Multipart Parameters​

  • file (binary, required): The audio file to transcribe.
  • model (string, optional, default: whisper-1): Speech model identifier.
  • language (string, optional): ISO-639-1 language code (e.g. en, es, fr, de).
  • prompt (string, optional): An optional text guide to establish spelling, jargon, or punctuation context.
  • response_format (string, optional, default: json): Format of the transcript: json, text, verbose_json, srt, vtt.
  • temperature (float, optional, default: 0): Sampling temperature between 0 and 1.

FinOps Accounting for STT​

Whisper models bill based on audio duration rather than text tokens. GoRoute records exact duration in integer milliseconds (duration_ms) and computes spend in micro-dollars using 64-bit integer ceiling arithmetic:

Cost (µ$) = ⌈ (DurationMs * AudioSTTCostMicrosPerSecond + 999) / 1000 ⌉

Text-to-Speech Synthesis (/v1/audio/speech)​

JSON Request Schema​

{
"model": "tts-1",
"input": "GoRoute AI Gateway synthesizes audio with low latency and streaming responses.",
"voice": "alloy",
"response_format": "mp3",
"speed": 1.0
}
FieldTypeRequiredDescription
modelstringNoTTS model (tts-1 or tts-1-hd). Default: tts-1.
inputstringYesText to convert to speech (up to 4096 characters).
voicestringNoVoice profile: alloy, echo, fable, onyx, nova, shimmer. Default: alloy.
response_formatstringNoOutput format: mp3, opus, aac, flac, wav, pcm. Default: mp3.
speedfloatNoPlayback speed from 0.25 to 4.0. Default: 1.0.

FinOps Accounting for TTS​

TTS is priced strictly per 1,000 input characters. GoRoute enforces ceiling integer division so that short sentences never truncate fractional micro-dollars to zero:

Cost (µ$) = ⌈ (CharCount * AudioTTSCostMicrosPer1KChars + 999) / 1000 ⌉

Code Examples​

# 1. Transcribe Audio
curl -X POST http://localhost:8080/v1/audio/transcriptions \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-F "file=@meeting_recording.mp3" \
-F "model=whisper-1" \
-F "language=en"

# 2. Translate Foreign Audio to English
curl -X POST http://localhost:8080/v1/audio/translations \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-F "file=@spanish_interview.wav" \
-F "model=whisper-1"

# 3. Text-to-Speech Synthesis
curl -X POST http://localhost:8080/v1/audio/speech \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-H "Content-Type: application/json" \
-d '{
"model": "tts-1",
"input": "Welcome to GoRoute AI Gateway. High reliability multi-modal routing.",
"voice": "nova",
"response_format": "mp3"
}' \
--output welcome.mp3

Response Headers & Telemetry​

HeaderDescription
X-Gateway-Request-IdUnique ID prefixed with stt_, stt_translation_, or tts_
X-Gateway-ProviderUpstream provider executing audio inference (e.g. openai)
X-Gateway-Cost-MicrosMicro-dollar spend incurred by the operation
X-Gateway-Pricing-StatusPrice provenance (verified, custom, unknown)