POST/v1/audio/transcriptions

Transcriptions

Transcribe audio into text.

OpenAI-dialect speech-to-text. The audio upload and the whole request are bounded by the 8 MiB gateway body cap.

Request body (multipart)

Field	Type	Required	Notes
`model`	string	yes	An STT alias (e.g. a Whisper-family model).
`file`	file (binary)	yes	The audio file.
`language`	string	no	ISO-639-1 hint.
`prompt`	string	no	Optional context/style prompt.
`response_format`	string	no	`json` (default), `verbose_json`, `text`, `srt`, `vtt`.
`temperature`	number	no	Sampling temperature.
`timestamp_granularities`	string[]	no	`word` and/or `segment` (with `verbose_json`).

Response formats

json / verbose_json → JSON body with provider_metadata.
text / srt / vtt → returned verbatim; provider_metadata is in the X-TF-* headers only.

Code sample

curl https://api.<domain>/v1/audio/transcriptions \
  -H "Authorization: Bearer $TOKENFACTORY_API_KEY" \
  -F model=whisper-1 \
  -F "[email protected]"

from openai import OpenAI

client = OpenAI(
    base_url="https://api.<domain>/v1",
    api_key=os.environ["TOKENFACTORY_API_KEY"],
)

with open("recording.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(
        model="whisper-1",
        file=f,
    )
print(transcript.text)

JSON response

{
  "text": "Today is a wonderful day…",
  "usage": { "type": "duration", "seconds": 12.3 },
  "provider_metadata": { "provider": "vllm-staging", "actual_model": "whisper-large-v3" }
}

With response_format: "verbose_json" the body also carries language, duration, segments[], and words[] when the provider reports them. usage is kept exactly as the provider reported it (duration-based or token-based) — never invented.

Errors

Standard error surface — see Errors.

Translations

POST /v1/audio/translations — same contract as transcriptions; the output is English text regardless of the spoken language.

Request body (multipart)

Field	Type	Required	Notes
`model`	string	yes	An STT alias.
`file`	file (binary)	yes	The audio file.
`prompt`	string	no	Optional context.
`response_format`	string	no	`json` (default), `verbose_json`, `text`, `srt`, `vtt`.
`temperature`	number	no	Sampling temperature.

Code sample

curl https://api.<domain>/v1/audio/translations \
  -H "Authorization: Bearer $TOKENFACTORY_API_KEY" \
  -F model=whisper-1 \
  -F "file=@german_speech.mp3"

Response

Same shapes as transcriptions (text + optional verbose fields + usage + provider_metadata; non-JSON formats returned verbatim with side-channel headers).

Errors

Standard error surface — see Errors.