Transcribe Audio

POST

audio

transcriptions

curl https://gateway.bud.studio/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.mp3" \
  -F "model=my-stt-deployment" \
  -F "language=en" \
  -F "response_format=verbose_json"

from openai import OpenAI

client = OpenAI(base_url="https://gateway.bud.studio/v1", api_key="YOUR_API_KEY")

with open("audio.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(
        model="my-stt-deployment",
        file=f,
        response_format="verbose_json",
    )
print(transcript.text)

{
  "text": "The quick brown fox jumps over the lazy dog."
}

{
  "task": "transcribe",
  "language": "en",
  "duration": 2.9,
  "text": "The quick brown fox jumps over the lazy dog.",
  "segments": [
    { "id": 0, "start": 0.08, "end": 2.7, "text": "The quick brown fox jumps over the lazy dog." }
  ],
  "words": [
    { "word": "The", "start": 0.08, "end": 0.24 },
    { "word": "quick", "start": 0.24, "end": 0.48 },
    { "word": "brown", "start": 0.48, "end": 0.8 }
  ]
}

curl https://gateway.bud.studio/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.mp3" \
  -F "model=my-stt-deployment" \
  -F "language=en" \
  -F "response_format=verbose_json"

from openai import OpenAI

client = OpenAI(base_url="https://gateway.bud.studio/v1", api_key="YOUR_API_KEY")

with open("audio.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(
        model="my-stt-deployment",
        file=f,
        response_format="verbose_json",
    )
print(transcript.text)

{
  "text": "The quick brown fox jumps over the lazy dog."
}

{
  "task": "transcribe",
  "language": "en",
  "duration": 2.9,
  "text": "The quick brown fox jumps over the lazy dog.",
  "segments": [
    { "id": 0, "start": 0.08, "end": 2.7, "text": "The quick brown fox jumps over the lazy dog." }
  ],
  "words": [
    { "word": "The", "start": 0.08, "end": 0.24 },
    { "word": "quick", "start": 0.24, "end": 0.48 },
    { "word": "brown", "start": 0.48, "end": 0.8 }
  ]
}

The request and response follow OpenAI’s audio/transcriptions API, so OpenAI SDKs work unchanged. The model is the name of your speech-to-text deployment, and the deployment decides which provider and model transcribe the audio.

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer authentication header
Content-Type	string	Yes	`multipart/form-data`

Form Data

Parameter	Type	Required	Description
file	file	Yes	The audio to transcribe, up to 25 MB and 30 minutes. See Audio files.
model	string	Yes	Name of a speech-to-text deployment. A deployment that does not transcribe returns `404`.
language	string	No	Language of the audio, as an ISO-639-1 code (`en`) or a language tag (`en-US`). Overrides the deployment’s default language. A code the provider does not support is dropped with an `x-bud-config-warning`.
response_format	string	No	`json`, `text`, `verbose_json`, `srt` or `vtt`. Default: `json`. See Response formats.
prompt	string	No	Text to guide the transcription, such as names or terms to expect. Used by OpenAI, Groq, Sarvam and self-hosted deployments; any other provider ignores it and the response carries an `x-bud-config-warning` saying so.
temperature	number	No	Sampling temperature, `0.0` to `1.0`. A value outside that range, or one that is not a number, is refused with `400`. Used by OpenAI, Groq, ElevenLabs and self-hosted deployments; any other provider ignores it with an `x-bud-config-warning`.
timestamp_granularities[]	array	No	`word`, `segment`, or both. Applies to `verbose_json` only. Without it, `verbose_json` includes `words` whenever the provider supplies them; with it, `words` is included only if `word` is listed. Any other value is refused with `400`.
deployment settings		No	`diarization`, `keyterms[]` and the other fields in Deployment settings override the deployment’s value for this request.

Audio files


File extensions	`flac`, `m4a`, `mp3`, `mp4`, `mpeg`, `mpga`, `oga`, `ogg`, `wav`, `webm`. Any other extension is refused with `400`.
Codecs	MP3, AAC, FLAC, Vorbis and PCM/WAV. Opus is not supported, which rules out most `.webm` files and Opus audio in `.ogg`; convert them to another format first.
Size	Up to 25 MB; a larger file is refused with `413`.
Length	Up to 30 minutes of audio; a longer file is refused with `413`.

Response formats

`response_format`	`Content-Type`	Body
`json`	`application/json`	`{"text": "…"}`
`text`	`text/plain`	The transcript as plain text.
`verbose_json`	`application/json`	The transcript with details; see the table below.
`srt`	`application/x-subrip`	SubRip subtitles, one cue per segment.
`vtt`	`text/vtt`	WebVTT subtitles, one cue per segment.

verbose_json fields:

Field	Description
`task`	`transcribe`, or `translate` on Translate Audio.
`language`	The language the provider detected, or the requested one when the provider does not report it. Some providers use two-letter codes (`en`), others three-letter ones (`eng`).
`duration`	Length of the audio in seconds.
`text`	The full transcript.
`segments`	Caption-sized spans with `id`, `start`, `end` and `text`: the same cues `srt` and `vtt` return. See Segments and subtitles.
`words`	Each word with `start` and `end` in seconds, plus `speaker` when the deployment has speaker diarization on. Present when the provider returns word timings, unless `timestamp_granularities[]` leaves out `word`.
`speakers`	The distinct speakers found, as `{"id": "…"}`. Present when diarization is on.
`alternatives`	Alternative transcripts, when the provider returns them.
`warnings`	The same messages as the `x-bud-config-warning` headers. Present when there are any.

Segments and subtitles

Providers return timings per word, so segments are built from those words. A segment ends:

after a word that ends a sentence (., ! or ?);
before a word that would make it longer than 84 characters (two 42-character subtitle lines) or 7 seconds;
before a word that follows a pause of 1 second or more;
before a word spoken by a different speaker, when the deployment has diarization on.

verbose_json, srt and vtt share these segments. If a provider returns text but no word timings, the transcript is one segment spanning the whole audio, and an x-bud-config-warning says so. Silent audio returns no segments.

Response headers

Header	Description
Content-Type	Depends on `response_format`; see above.
x-bud-config-warning	A request or deployment setting that could not be applied, such as a language the provider does not support or a `prompt` it cannot use. Repeated once per warning; the request still succeeds.
x-bud-config-warning-count	How many `x-bud-config-warning` headers were sent.

Deployment settings

Everything on a deployment’s Settings → Audio page is a default for every request to that deployment. The page shows only the settings the deployment’s provider and model support. A saved setting that the provider cannot apply is skipped with an x-bud-config-warning, and the request still succeeds. A request can override most of them for itself, using the form field in the last column. Settings that cost extra per request, and the noise filter, only the deployment controls. See Overriding settings per request.

Setting	What it does	Request field
Default language	The language of the audio, converted to the provider’s own language code.	`language`
Punctuation	Add punctuation and capitalization to the transcript.	`punctuation`
Noise suppression	Remove background noise from the audio before it is sent to the provider.	deployment only
Speaker labels	Tell speakers apart: each entry in `verbose_json.words` gets a `speaker`, the distinct speakers are listed in `speakers`, and subtitle cues break when the speaker changes.	`diarization`
Word timestamps	Return per-word timings in `verbose_json.words`. Switched on automatically for `verbose_json`, `srt` and `vtt`, which need them.	`timestamp_granularities[]`
Smart formatting	Format dates, times, currency, phone numbers and similar in a readable way.	`smart_format`
Spoken numbers as digits	Write spoken numbers as digits (“twenty five” → “25”).	`numerals`
Filler words	Keep filler words such as “um” and “uh” in the transcript.	`filler_words`
Profanity filter	Mask profanity in the transcript.	`profanity_filter` (can switch it on, not off)
Detect the language	Detect the spoken language instead of assuming one. The detected language is `verbose_json.language`.	`language_detection`
Boosted terms	Words and names the provider should expect, such as product names or jargon. On OpenAI deployments they are added after the request’s `prompt`.	`keyterms[]` (added to the deployment’s)
Redact	Categories of sensitive information to redact from the transcript, such as `pii`, `pci` or `phi`. The accepted values are the provider’s own.	`redaction[]` (added, never removed)
Alternatives	How many alternative transcripts to return, in `verbose_json.alternatives`.	deployment only
Translate into	Target languages for translation, on providers that can translate. OpenAI and Groq translate to English only, and the transcript comes back in English. Gladia and Speechmatics translate into other languages on live WebSocket sessions only, and AssemblyAI’s translation is not applied yet: on this endpoint the transcript stays in the spoken language.	deployment only; use Translate Audio for English

Overriding settings per request

The form fields in the table above are Bud additions to OpenAI’s request. All of them are optional, and a request that leaves them out gets the deployment’s settings, so plain OpenAI clients work unchanged. Each field applies to its own request only:

curl https://gateway.bud.studio/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@meeting.mp3" \
  -F "model=my-stt-deployment" \
  -F "response_format=verbose_json" \
  -F "diarization=true" \
  -F "keyterms[]=Kubernetes" \
  -F "keyterms[]=Dapr"

With an OpenAI SDK, pass them through the SDK’s extra-fields option. In Python, extra_body={"diarization": True, "keyterms": ["Kubernetes", "Dapr"]} sends exactly the form fields above.

Switches take true or false (1 or 0 also work). Any other value is refused with 400 naming the field.
language_detection=true and language in the same request are refused with 400. A request that names its language on a deployment that detects the language uses that language instead, and says so in an x-bud-config-warning.
keyterms[] and redaction[] take one value per form field, and add to the deployment’s list.
The two compliance settings only tighten. A request can switch profanity_filter on and add redaction[] categories. It cannot switch off or remove what the deployment set; trying says so in an x-bud-config-warning.
A field the provider cannot use is skipped with an x-bud-config-warning.
A field nothing recognises, such as a misspelling, is ignored and named in an x-bud-config-warning.
Self-hosted deployments receive only OpenAI’s own fields, so they ignore these, with a warning.

Errors

Errors use OpenAI’s error format; param names the field at fault when there is one.

404

{
  "error": {
    "message": "Model 'my-tts-deployment' not found or does not support audio_transcription",
    "type": "invalid_request_error",
    "param": "model",
    "code": null
  }
}

Status	When
`400`	A missing or invalid field; an unsupported file type or codec; an upload larger than the gateway accepts (the message states the limit); or a deployment whose provider settings cannot transcribe a file (`param: "model"`).
`401`	Missing or invalid API key. `code` is `missing_auth_header` or `unauthorized`.
`404`	`model` is not a deployment you can use, or does not support transcription.
`413`	The file is over 25 MB or 30 minutes.
`500`	The deployment is misconfigured, for example it has no provider credential.
`502`	The provider failed or refused the audio.

Supported providers

Any speech-to-text deployment works with this endpoint. The model catalog currently offers speech-to-text models from Deepgram, ElevenLabs, AssemblyAI, Speechmatics, Gladia, Rev AI, Groq, OpenAI, Azure, Cartesia, Amazon Transcribe and Google Cloud Speech-to-Text.

curl https://gateway.bud.studio/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.mp3" \
  -F "model=my-stt-deployment" \
  -F "language=en" \
  -F "response_format=verbose_json"

from openai import OpenAI

client = OpenAI(base_url="https://gateway.bud.studio/v1", api_key="YOUR_API_KEY")

with open("audio.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(
        model="my-stt-deployment",
        file=f,
        response_format="verbose_json",
    )
print(transcript.text)

{
  "text": "The quick brown fox jumps over the lazy dog."
}

{
  "task": "transcribe",
  "language": "en",
  "duration": 2.9,
  "text": "The quick brown fox jumps over the lazy dog.",
  "segments": [
    { "id": 0, "start": 0.08, "end": 2.7, "text": "The quick brown fox jumps over the lazy dog." }
  ],
  "words": [
    { "word": "The", "start": 0.08, "end": 0.24 },
    { "word": "quick", "start": 0.24, "end": 0.48 },
    { "word": "brown", "start": 0.48, "end": 0.8 }
  ]
}

Introduction

Gateway APIs

Python SDK & CLI

Headers

Form Data

Audio files

Response formats

Segments and subtitles

Response headers

Deployment settings

Overriding settings per request

Errors

Supported providers

​Headers

​Form Data

​Audio files

​Response formats

​Segments and subtitles

​Response headers

​Deployment settings

​Overriding settings per request

​Errors

​Supported providers

Headers

Form Data

Audio files

Response formats

Segments and subtitles

Response headers

Deployment settings

Overriding settings per request

Errors

Supported providers