Skip to main content

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
}
  • text is the transcript, possibly an empty string.
  • duration_seconds is the recording's duration.
  • silent indicates 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_REQUEST with 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.

See Errors, limits and retries.