API Reference

Audio

Transcribe or translate speech, generate audio from text, and discover the voices available to your organisation.

Transcribe audio

POST/v1/audio/transcriptions

Scopestt

Upload an audio file and return its transcription.

Request

Content-Type: multipart/form-data

filerequiredbinary: Audio file. The endpoint accepts common formats such as WAV, MP3, FLAC, OGG, M4A.
languagestring: ISO language hint to improve accuracy (e.g. "en", "nl").
promptstring: Optional text hint to bias recognition toward custom vocabulary, proper nouns, or a specific style. Capped at 896 characters; the gateway rejects longer prompts with a 422.
response_formatstring: Output format. JSON by default.
service_idstring: Optional. Route to a specific STT service (see GET /v1/services). Falls back to the org’s default STT service when omitted.

For more accurate transcription, set the source language and provide a short prompt with relevant names, jargon, or product terms.

bash

curl https://api.inferada.com/v1/audio/transcriptions \
  -H "Authorization: Bearer inf_YOUR_TOKEN" \
  -F file=@speech.mp3 \
  -F language=en \
  -F prompt='Acme Corp, Inferada'

Response · 200

textstring: Transcribed text.
durationnumber: Audio duration in seconds (when available).

json

{
  "text": "Hello, this is a transcription.",
  "duration": 4.2
}

Translate audio

POST/v1/audio/translations

Scopestt

Transcribe speech from an automatically detected source language and return the result in English.

Request

Content-Type: multipart/form-data

filerequiredbinary: Audio file. The endpoint accepts common formats such as WAV, MP3, FLAC, OGG, M4A.
promptstring: Optional text hint to bias recognition toward custom vocabulary or proper nouns. Capped at 896 characters; the gateway rejects longer prompts with a 422.
response_formatstring: Output format. JSON by default.
service_idstring: Optional. Route to a specific STT service (see GET /v1/services). Falls back to the org’s default STT service when omitted.

bash

curl https://api.inferada.com/v1/audio/translations \
  -H "Authorization: Bearer inf_YOUR_TOKEN" \
  -F file=@dutch-speech.mp3

Response · 200

textstring: English translation of the speech.
durationnumber: Audio duration in seconds (when available).

json

{
  "text": "Hello, this is a translation.",
  "duration": 4.2
}

Synthesise speech

POST/v1/audio/speech

Scopetts

Generate a binary audio stream from text in the requested format.

Request

voicerequiredstring: Voice ID. List available voices with /v1/audio/voices.
inputrequiredstring: Text to synthesise.
response_formatstring: mp3 (default), opus, flac, aac, wav or pcm.
speednumber: Playback speed multiplier. Default 1.0.
service_idstring: Optional. Route to a specific TTS service (see GET /v1/services). Falls back to the org’s default TTS service when omitted.
modelstring: Optional model identifier, usually inferred from the voice.

json

{
  "voice": "nl_BE-rdh-medium",
  "input": "Hallo, welkom.",
  "response_format": "mp3",
  "speed": 1.0
}

Response · 200

Binary audio stream. The Content-Type matches the requested format: audio/mpeg for MP3, audio/wav, audio/opus, audio/flac, audio/aac, or application/octet-stream for PCM.

bash

curl https://api.inferada.com/v1/audio/speech \
  -H "Authorization: Bearer inf_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "voice": "nl_BE-rdh-medium", "input": "Hallo." }' \
  --output out.mp3

Errors

If voice is unknown, the response is a 400 with the list of available voices inlined so your client can recover:

json

{
  "error": "Voice 'xyz' not found. Available voices: [...]",
  "available_voices": [
    { "id": "nl_BE-rdh-medium", "name": "RDH", "language": "nl" }
  ],
  "request_id": "..."
}

Choosing a voice

Available voices come from two backends. Choose a backend based on language coverage, voice quality, and latency:

Piper is lightweight and fast. It covers English (US/GB), French, German, Spanish, Dutch (NL/BE), Italian, Portuguese (BR/PT), Chinese (Mandarin) and Hindi. Voices come in low/medium/high quality tiers.
Kokoro offers more natural-sounding voices with higher latency. Use it for Japanese (Piper has no Japanese voices) or when you want a richer-sounding English voice and can afford the extra latency. All Kokoro voices report quality: "natural".

Your organisation can have either a combined TTS service (one record, both engines) or one or more single-backend services (one engine per record). Combined services prefix every voice id with the engine (e.g. piper:nl_BE-rdh-medium, kokoro:af_bella) and route on that prefix. Single-backend services return the raw upstream id (no prefix); pass service_id to steer to a specific one.

The gateway refreshes the voice catalogue from each backend. A newly added voice appears within five minutes.

List available voices

GET/v1/audio/voices

Scopetts

List voices from the default TTS service, or pass service_id to query a specific service.

Request

service_idstring: Optional. Discover voices on a specific TTS service. Falls back to the default when omitted.
languagestring: Optional. Filter by ISO language code, e.g. "en".

Response · 200

voices[].idstring: Unique voice identifier. Use this in /v1/audio/speech.
voices[].namestring: Human-readable display name.
voices[].languagestring: ISO language code (e.g. "nl", "en").
voices[].qualitystring | null: Quality tier when available.

json

{
  "voices": [
    {
      "id": "nl_BE-rdh-medium",
      "name": "RDH",
      "language": "nl",
      "quality": "medium"
    }
  ]
}