Asynchronous transcription

For long files (a 60-minute call recording takes a few minutes to recognise) the request does not have to stay open: send a webhook_url, get a job id at once, and receive the result on your server when it is ready. Works with the native API and with OpenAI model names (OpenAI SDK: extra_body), with every option (normalize, mode, diarize, gender_detection, hints, hint_context, speaker_lock, voice_isolation, response_format including the OpenAI formats). Live streaming is unchanged.

Field	Meaning
`webhook_url`	`https://` URL that receives the result (`POST`, JSON). Must resolve to a public address; redirects are not followed
`webhook_secret`	Optional (1–256 characters): the webhook is signed with it (`X-Mihu-Signature`)
`webhook_metadata`	Optional, up to 4 KB: echoed back as `metadata` (JSON is returned as JSON, anything else as a string; e.g. your call id)
`file_url`	Optional, instead of `file`: `https://` URL the server downloads the audio from (up to 1 GB, 10 minutes, at most 5 redirects, public addresses only). Also works without `webhook_url`

Not combinable with stream=true. Maximum audio length: 4 hours.

1. Submit → `202`

curl https://stt.eu.mihu.ai/v1/audio/transcriptions -H "Authorization: Bearer $KEY" \
  -F file=@call-60min.mp3 -F model=umay -F language=tr -F diarize=true \
  -F webhook_url=https://example.com/hooks/stt -F webhook_secret=$WEBHOOK_SECRET -F 'webhook_metadata={"call_id": "C-1042"}'

The answer comes as soon as the file is uploaded and decoded (a few seconds for an hour of audio):

{"id": "6f1d2c3b-9a4e-4b7c-8d2f-1e0a5b9c7d36", "object": "transcription.job", "status": "queued", "duration": 3600.0,
 "created_at": 1793145600,
 "source": {"type": "upload", "filename": "call-1042.wav", "size_bytes": 115200044},
 "request": {"model": "umay", "language": "tr", "response_format": "json", "language_model": true, "normalize": true,
             "diarize": true, "gender_detection": false, "speaker_lock": false, "voice_isolation": false, "hints": false,
             "max_speakers": 8}}

Billing: the audio duration is counted once, when the job is accepted (this 202); status reads and the webhook are not counted. Errors in the request (unknown option, language, bad webhook_url or file_url, unreadable audio) come at once as 400, exactly like a synchronous request.

Status	Meaning
`202`	Accepted; the result follows on the webhook
`400`	Invalid field, `webhook_url` / `file_url` not `https` or pointing to a private address, `file_url` download failed
`413`	`file_url` larger than 1 GB, upload larger than 1 GB, audio longer than 4 hours
`429`	More than 20 jobs of this API key waiting or running; retry when one has finished
`503`	Server queue full; retry later

2. Webhook

POST to webhook_url, Content-Type: application/json:

{"event": "transcription.completed", "id": "6f1d2c3b-9a4e-4b7c-8d2f-1e0a5b9c7d36", "object": "transcription.job",
 "status": "completed", "message": "Transcription of call-1042.wav (3600 s, tr) completed in 212.4 s.",
 "model": "umay", "language": "tr", "duration": 3600.0, "processing_time": 212.4,
 "created_at": 1793145600, "started_at": 1793145603, "completed_at": 1793145815, "expires_at": 1793149415,
 "source": {"type": "upload", "filename": "call-1042.wav", "size_bytes": 115200044},
 "request": {"model": "umay", "language": "tr", "response_format": "json", "language_model": true, "normalize": true,
             "diarize": true, "gender_detection": false, "speaker_lock": false, "voice_isolation": false, "hints": false,
             "max_speakers": 8},
 "result": {"text": "…", "model": "umay", "language": "tr", "duration": 3600.0, "processing_time": 212.4, "segments": […]},
 "metadata": {"call_id": "C-1042"}}

result is the body the same synchronous request answers: the native JSON, or the OpenAI body for OpenAI model names ({"text", "usage", …}, verbose_json, diarized_json); text, srt and vtt come as a string. (A job decodes the ~28-second parts of a long file one at a time, so a few words of a long file can differ from a synchronous run, as they also can between two synchronous runs under different load.)
event says what finished: transcription.completed or transcription.failed (also in the X-Mihu-Event header). message is the same in one human-readable line. source is the audio: \{"type": "upload", "filename", "size_bytes"\} or \{"type": "file_url", "url", "filename", "size_bytes"\} (the URL without its query string, so pre-signed credentials are never echoed). request lists the options the job ran with, defaults filled in. Your webhook_metadata comes back as metadata.
Job ids are UUIDs.
On failure: "event": "transcription.failed", "status": "failed" and "error": {"status": 400, "message": "…"} instead of result.
Headers: X-Mihu-Webhook-Id (= job id, the same on every attempt: use it to ignore duplicates), X-Mihu-Event, X-Mihu-Timestamp (Unix seconds), X-Mihu-Attempt, and with a secret X-Mihu-Signature: sha256=<hex HMAC-SHA256(webhook_secret, "\{timestamp\}.\{raw body\}")>.
Answer with any 2xx within 10 seconds (store the body, process it later). Anything else, a timeout or a redirect counts as a failed attempt; it is retried after 1 s, 10 s, 1 min, 5 min and 30 min (6 attempts, ~36 minutes), then given up (the result can still be read with GET until it expires).

Verify the signature (reject old timestamps, compare in constant time):

import hashlib, hmac, time

def verify(headers, raw_body: bytes, secret: str, tolerance=300) -> bool:
    ts, sig = headers.get("X-Mihu-Timestamp", ""), headers.get("X-Mihu-Signature", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
        return False
    want = "sha256=" + hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, want)

const crypto = require("crypto");

function verify(headers, rawBody /* Buffer */, secret, tolerance = 300) {
  const ts = headers["x-mihu-timestamp"] || "", sig = headers["x-mihu-signature"] || "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > tolerance) return false;
  const want = "sha256=" + crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest("hex");
  return sig.length === want.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want));
}

Use the raw request body as received (before JSON parsing).

3. Status and result: `GET /v1/audio/transcriptions/{id}`

Same API key (tenant) as the request that created the job; any other key gets 404.

{"id": "6f1d2c3b-9a4e-4b7c-8d2f-1e0a5b9c7d36", "object": "transcription.job", "status": "processing", "model": "umay",
 "language": "tr", "duration": 3600.0, "created_at": 1793145600, "started_at": 1793145601, "completed_at": null,
 "processing_time": null, "progress": 0.42, "expires_at": null,
 "source": {"type": "upload", "filename": "call-1042.wav", "size_bytes": 115200044}, "request": {"model": "umay", …},
 "webhook": {"state": "waiting", "attempts": 0, "last_status": null, "last_error": null, "next_attempt_at": null},
 "metadata": {"call_id": "C-1042"}}

status: queued → processing → completed | failed. progress (0–1) while processing where it can be measured (model=umay), else null. Once completed the answer also has event, message and result (or error), and webhook.state shows the delivery: pending, delivered, failed. Polling instead of a webhook is fine (every 10–30 s).

Data retention

The audio is deleted as soon as recognition has finished (uploaded and downloaded files right after decoding; the decoded audio kept for a queued job is deleted when the job ends).
The job with its result is deleted 1 hour after completion; afterwards GET answers 404. Transcripts are not kept longer. Everything stays on the server of the region you call.

OpenAI SDK

import json
from openai import OpenAI
client = OpenAI(base_url="https://stt.eu.mihu.ai/v1", api_key=KEY)

raw = client.audio.transcriptions.with_raw_response.create(
    model="gpt-4o-transcribe", file=open("call-60min.mp3", "rb"), language="tr", response_format="verbose_json",
    extra_body={"webhook_url": "https://example.com/hooks/stt", "webhook_secret": SECRET,
                "webhook_metadata": json.dumps({"call_id": "C-1042"}), "diarize": True})
job = json.loads(raw.http_response.text)          # {"id": "<uuid>", "status": "queued", "duration": …, "created_at": …, "source": …, "request": …}

The SDK expects a transcription in the answer, so read the 202 from the raw response as above. The webhook’s result is the OpenAI body of the chosen response_format. webhook_metadata may also be a dict in extra_body (the SDK sends it as webhook_metadata[key] fields; it comes back as an object with string values).

Downloading from a URL: `file_url`

curl https://stt.eu.mihu.ai/v1/audio/transcriptions -H "Authorization: Bearer $KEY" \
  -F file_url=https://storage.example.com/calls/C-1042.wav?sig=... -F model=umay -F language=tr \
  -F webhook_url=https://example.com/hooks/stt

Pre-signed storage links (S3, GCS, Azure) work; the link must stay valid until the 202 arrives. Without webhook_url the request waits for the result as usual.

Getting Started

API Reference

Transcription

Voice

1. Submit → `202`

2. Webhook

3. Status and result: `GET /v1/audio/transcriptions/{id}`

Data retention

OpenAI SDK

Downloading from a URL: `file_url`

​1. Submit → 202

​2. Webhook

​3. Status and result: GET /v1/audio/transcriptions/{id}

​Data retention

​OpenAI SDK

​Downloading from a URL: file_url

1. Submit → `202`

2. Webhook

3. Status and result: `GET /v1/audio/transcriptions/{id}`

Data retention

OpenAI SDK

Downloading from a URL: `file_url`