curl -X POST "$BASE_URL/whisper-transcribe" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F "file=@recording.webm" \
-F "language=en"
{
"success": true,
"text": "Plan a four lesson unit on photosynthesis for second years.",
"language": "english",
"duration": 4.2
}
Assist
Transcription
Speech-to-text for voice input.
POST
/
whisper-transcribe
curl -X POST "$BASE_URL/whisper-transcribe" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F "file=@recording.webm" \
-F "language=en"
{
"success": true,
"text": "Plan a four lesson unit on photosynthesis for second years.",
"language": "english",
"duration": 4.2
}
Accepts an audio payload and returns a transcript. Used for voice input into
planning and chat surfaces.
The request is
Failures carry
multipart/form-data, not JSON — this is the only endpoint on
the platform that does not take a JSON body.
Request
file
required
The audio blob. Sent as a multipart part, not base64 in a JSON field. A
missing or non-file
file part returns 400.string
default:"en"
ISO language hint passed to the model.
string
Biases the transcription. Defaults to a teaching-domain prompt that primes the
model for lesson planning, curriculum and assessment vocabulary, and asks for
proper punctuation and capitalisation.
string
default:"json"
Passed straight through to the upstream model.
curl -X POST "$BASE_URL/whisper-transcribe" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F "file=@recording.webm" \
-F "language=en"
Response
boolean
true when transcription succeeded.string
The transcript, trimmed.
string
Language as reported by the model.
number
Audio duration as reported by the model.
{
"success": true,
"text": "Plan a four lesson unit on photosynthesis for second years.",
"language": "english",
"duration": 4.2
}
language and duration are passed through from the upstream response, so they
are absent when the configured response_format does not include them. Only
text is guaranteed.Errors
| Status | Cause |
|---|---|
| 400 | No file part, or the upstream model rejected the audio. |
| 405 | Anything other than POST. |
| 500 | Server missing its upstream API key. |
| 502 | Upstream returned a 5xx. |
details alongside error: the upstream status and the first
500 characters of its body, so a rejected payload can be diagnosed without
server log access.
The model defaults to
gpt-4o-transcribe, which supersedes whisper-1 — the
endpoint name predates the swap. It can be pinned back to whisper-1 by
environment variable without a redeploy, which is needed only for the
verbose_json, srt and vtt formats that gpt-4o-transcribe does not
support.The deployed transcription proxy is richer than earlier written specifications
of it. Treat the running service as authoritative and do not redeploy from an
older spec document.