Transcriptions
POST https://api-staging.heimdallm.com/api/v1/audio/transcriptionsOpenAI-compatible speech to text. Requires a bearer API key. Use a model whose
input modality is audio — filter the model list or look for "input_modalities": ["audio"]
in the catalogue.
The audio goes up either of two ways: as a file part in a multipart/form-data body, capped at
25 MiB, with every other field beside it as a form field — what OpenAI-dialect client libraries
already send — or as base64 bytes under input_audio on a JSON body, for an upload over that cap.
Streaming is not supported.
Request body
| Field | Type | Notes |
|---|---|---|
file | file | Multipart only. Required there. Formats follow the endpoint — wav, mp3, m4a, flac and ogg are typical. |
input_audio.data | string | JSON body only. Required there. Base64-encoded audio, raw bytes rather than a data URI. A string that is not base64 is refused rather than decoded. |
input_audio.format | string | JSON body only. Required there. wav, mp3, flac, m4a, ogg, webm, aac. |
model | string | Required. |
language | string | Source language, from the endpoint's declared list where it declares one. Supplying it skips detection; naming a language no live endpoint of the model declares is refused before an engine is reached. The model object's supported_languages names what is available. |
prompt | string | Free text biasing the decoder towards spellings and proper nouns it would otherwise miss. |
response_format | string | json (default), text, or verbose_json, where the endpoint declares it. |
max_completion_tokens | integer | Positive transcript generation token limit, within the selected endpoint's declared range. |
temperature | number (0–1) | Decoding temperature. |
use_beam_search | boolean | Select beam search where the endpoint declares it; otherwise sampling is used. |
n | integer | Beam width for an endpoint that declares it. The response still contains one transcript. |
length_penalty | number | Beam search length penalty where the endpoint declares it. |
timestamp_granularities[] | string | word or segment, repeated. verbose_json only. |
provider | object | Provider preferences, plus provider.options — provider-specific passthrough keyed by provider slug. |
Endpoints differ in which of these they honour: each publishes its own supported_parameters in the
catalogue, and that list is the promise. A parameter absent from it is not honoured
there, whatever the dialect allows.
The reference Qwen3-ASR endpoint also declares max_completion_tokens (1–448), top_p, top_k, min_p, seed,
frequency_penalty, presence_penalty, and repetition_penalty. Their value domains appear on the
endpoint listing. Send numeric values as form fields in multipart requests or as JSON numbers with
input_audio; routing checks the selected seller's declaration before sending them upstream.
The reference endpoint declares no beam search: its engine does not answer a beam-search request, so
use_beam_search, n and length_penalty are not declared there. A request naming one is routed to a
seller that declares it and refused when none does.
Example
curl https://api-staging.heimdallm.com/api/v1/audio/transcriptions \
-H "Authorization: Bearer $HEIMDALL_API_KEY" \
-F file=@interview.mp3 \
-F model="openai/whisper-large-v3-turbo"{
"text": " The sky above the port was the color of television, tuned to a dead channel.",
"model": "openai/whisper-large-v3-turbo",
"provider": "ImpCC",
"usage": { "seconds": 5, "cost": 0.00003 }
}
The same audio sent instead as JSON:
{
"model": "openai/whisper-large-v3-turbo",
"input_audio": { "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…", "format": "wav" }
}
response_format: verbose_json adds task, duration, language and segments (and words, where
the endpoint produces them); segments and words carry speaker where the endpoint returns diarization.
Response fields
| Field | Type | Notes |
|---|---|---|
text | string | The transcript. |
model | string | The model that served the request. |
provider | string | The serving provider's display name. (Heimdallm) |
task | string | The task performed. verbose_json only. |
duration | number | The endpoint's own measurement of the audio, fractional as it reported it. verbose_json only. |
language | string | Detected or supplied source language. verbose_json only. |
segments | array | Timed segments, each carrying speaker where the endpoint returns diarization. verbose_json only. |
words | array | Word timings, each carrying speaker where present. verbose_json only, where produced. |
usage.seconds | integer | Whole seconds, rounded up from the endpoint's measurement, for a duration-priced endpoint; omitted when not reported. |
usage.input_tokens | integer | Input tokens, for a token-priced endpoint; omitted when not reported. |
usage.output_tokens | integer | Output tokens, for a token-priced endpoint; omitted when not reported. |
usage.total_tokens | integer | input_tokens + output_tokens; omitted when not reported. |
usage.cost | number | Exact charge in USD. (Heimdallm) |
Pricing
A transcription is billed by exactly one unit per call: per second of audio for a duration-priced
endpoint, or per token for one priced by them — never both. Model pages show the applicable price;
the catalogue publishes a duration price as pricing.audio_second, a per-second decimal string, and a token
price the same way a chat model's pricing.prompt/pricing.completion are.
The X-Generation-Id and X-Provider-Name headers are sent as on chat completions.
An unreported figure is omitted from usage; it is not a measured zero. usage.cost remains the
finalized charge, and an explicitly reported zero remains 0.