Transcribe audio
POST /projects/:projectid/audio/transcriptions
Converts a recording into text. Send the actual audio bytes; a URL or Library file ID is not accepted as the audio source.
Authentication and limits
Use a project key with speech.transcribe in Authorization, without Bearer. Replace :projectid with the key's project ID.
The audio limit is 25 MiB (26,214,400 bytes) before base64 encoding. Request-size limits also apply: JSON bodies have a 20 MiB limit, and base64 makes the request larger than the original recording. Prefer multipart for files, especially larger ones; a recording below the audio limit can still be too large as JSON.
Common decodable containers include MP3, M4A, WAV, OGG, and WebM. A filename extension alone does not guarantee that the recording can be decoded.
Upload an audio file
Using the Quickstart variables:
curl --include --request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--form "file=@./recording.wav" \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/audio/transcriptions"
Send one recording in the multipart file field. Let curl set the multipart content type and boundary; do not manually set Content-Type: application/json or a bare multipart/form-data header.
There is no need to create a Library file first, and this call does not add the recording to the Library.
Send base64 JSON instead
For small recordings, send Content-Type: application/json and an audio field containing the base64-encoded file bytes:
{
"audio": "BASE64_ENCODED_AUDIO_BYTES"
}
Replace the placeholder with the encoding itself, without a data-URL prefix. Do not send a local filename, remote URL, or the literal placeholder. Use only one input method per request.
The public endpoint does not expose model selection, a language override, timestamp formats, or speaker-diarisation options.
Response
200 OK returns:
{
"text": "Move the Thursday meeting to Friday morning.",
"duration_seconds": 3.8,
"silent": false
}
textis the transcript, possibly an empty string.duration_secondsis the recording's duration.silentindicates whether the recording was detected as silent.
An empty transcript is not automatically an error. silent: true suggests checking that the microphone actually captured audio. With silent: false, the recording can contain sound without recognisable speech.
Review transcripts before using them for important actions; audio quality and background noise affect results.
Errors
- 400: no usable audio was supplied or the decoded audio exceeds the endpoint limit. JSON uses
BAD_REQUESTwith a message. - 401: missing or invalid project credential.
- 403: missing
speech.transcribe. - 413: the request body is too large for request handling; reduce it or use multipart.
- 429: request-rate limit reached.
- 502: audio decoding or transcription failed, returned as
UPSTREAM_FAILURE.
Malformed multipart bodies can be rejected before the endpoint handles them, so do not assume every error uses the same JSON format. Split large recordings into manageable pieces, preserve their order, and handle HTTP errors before reading text.