Audio Transcriptions

POST /v1/audio/transcriptions

Upload an audio file and receive a normalized transcript. The endpoint follows the OpenAI audio transcription shape closely, with Tresor receipt metadata added on JSON responses.

Headers

Request body

Send multipart/form-data.

Routing behavior

Audio transcriptions do not accept a client-provided failover array.

• Use an explicit compound route such as eu/privatemode/whisper-large-v3 when you need a fixed provider and region.
• Use a bare model key or auto/auto/... when you want the router to choose an eligible route automatically.
• tresor.requested_route reports the normalized route you asked for.
• tresor.routed_model reports the route that actually served the request.
• tresor.failover is true when the router had to switch away from the initially preferred route during automatic routing.
• With automatic routing, tresor.requested_route and tresor.routed_model can differ even when tresor.failover is false.

For the distinction between automatic route switching and client retries, see Routing failover and Retries and transient errors.

Accepted content types

• audio/flac
• audio/m4a
• audio/mp4
• audio/mpeg
• audio/ogg
• audio/wav
• audio/webm
• audio/x-m4a

These MIME types are accepted by the Tresor router. Actual compatibility is still provider- and model-specific, so an upstream route can reject a file that passed router validation.

For the broadest compatibility across transcription routes, prefer audio/wav or audio/mpeg. In current validation, Tinfoil whisper-large-v3-turbo accepted WAV input while rejecting an M4A upload upstream.

Known route-specific notes:

• global/tinfoil/whisper-large-v3-turbo: prefer WAV or MP3; current validation accepted WAV while rejecting M4A upstream.
• global/tinfoil/voxtral-small-24b: provider docs advertise MP3 or WAV and up to 30 minutes for transcription, but provider-side size checks can still reject compressed uploads well below the router cap.
• eu/privatemode/whisper-large-v3: current provider docs advertise up to 50 MB per request.

Default upload limit: 25 MiB per request.

Example request

curl https://api.tresor.co/v1/audio/transcriptions \
  -H "Authorization: Bearer $TRESOR_API_KEY" \
  -F "model=auto/auto/whisper-large-v3" \
  -F "file=@./meeting.mp3;type=audio/mpeg" \
  -F "response_format=json"

Response

json

{
  "text": "Hello and welcome to the meeting.",
  "language": "en",
  "duration": 12.5,
  "tresor": {
    "receipt_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "requested_route": "auto/auto/whisper-large-v3",
    "routed_model": "eu/privatemode/whisper-large-v3",
    "failover": false,
    "usage": {
      "billing_unit": "audio_minute",
      "audio_seconds": 12.5
    }
  }
}

Minute-priced transcription routes return billing_unit = audio_minute while still reporting clip duration in audio_seconds. Request-priced transcription routes return billing_unit = request. Token-priced transcription routes return billing_unit = token and may include prompt and completion token counts in tresor.usage.

text

When response_format=text, the response body is plain text. Tresor metadata moves to response headers:

• X-Tresor-Routed-Model
• X-Tresor-Receipt-Id when receipts are enabled

If you need requested_route for a text response, keep the original request or fetch the signed receipt; there is no X-Tresor-Requested-Route header.

verbose_json

Adds normalized segments[] timing information. language is currently required.

Errors

Error bodies follow the standard error envelope.

See also

• Audio transcription guide
• Models
• Usage
• Receipts