Transcriptions

Transcribe audio files to text using the Sansa API

Converts an audio file to text. Compatible with the OpenAI audio.transcriptions SDK client.

POST /v1/audio/transcriptions

The request body must be multipart/form-data. See the code panel for examples in Python, TypeScript, and curl.

Form Parameters

file

Required. The audio file to transcribe. Must be multipart/form-data.

Supported formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm.

Maximum file size: 25 MB.

model

Optional. Default: "gpt-4o-transcribe" (OpenAI SDK compatibility).

Value	Behavior
`sansa-auto`, `whisper-1`, `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, or omitted	Routes to Sansa's default transcription model (`google/gemini-2.5-flash-lite`)
Any other catalog model id	Uses that model directly; must support audio input (`audio` in `input_modalities`)

Invalid or unknown model ids return 400 with invalid_model. Models without audio support return 400 with a descriptive invalid_model message.

language

Optional. ISO-639-1 language code (e.g., "en", "fr", "de"). Providing the language improves accuracy and speed. If omitted, the model detects the language automatically.

prompt

Optional. A text string to guide the model's style or provide context for the audio. Useful for supplying proper nouns, acronyms, or domain-specific vocabulary that the model might otherwise transcribe incorrectly.

temperature

Default: 0.0. Sampling temperature between 0.0 and 1.0. Lower values produce more deterministic output.

response_format

Default: "json". Controls the output format.

Value	Description
`"json"`	Returns `{"text": "...", "usage": {...}}` with token counts, duration, and billed cost
`"text"`	Returns the transcription as a plain string

Only "json" and "text" are supported. Other values return 400 with code unsupported_response_format.

call_name

Optional. Legacy top-level dashboard label for the request (max 64 characters, non-whitespace). Prefer sansa or metadata instead; see Request labels below.

sansa

Optional. A JSON object string in the multipart form. Preferred container for Sansa-specific fields such as call_name and end_user_id. Example form value:

{"call_name": "voicemail-transcribe", "end_user_id": "user-42"}

metadata

Optional. A JSON object string in the multipart form. Fallback container for the same keys when you can't send a sansa object. Other keys are accepted but not stored.

Request labels

Optional labels help you filter activity in the dashboard.

Because transcriptions use multipart/form-data, sansa and metadata are sent as JSON-encoded form field strings (not nested objects in a JSON body).

Field	Precedence	Purpose
`call_name`	`sansa.call_name`, then `metadata.call_name`, then top-level `call_name`	Request label in the dashboard (max 64 chars)
`end_user_id`	`sansa.end_user_id`, then `metadata.end_user_id`	Customer end-user label in activity (max 512 chars)

Invalid values return 400 with invalid_call_name or invalid_end_user_id. Malformed sansa or metadata JSON returns 400 with invalid_request.

curl -X POST https://api.sansaml.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $SANSA_API_KEY" \
  -F "[email protected]" \
  -F 'sansa={"call_name":"voicemail-transcribe","end_user_id":"user-42"}'

Returns

JSON (default)

{
  "text": "Hello, world. This is a transcription of the audio.",
  "usage": {
    "seconds": 9.2,
    "total_tokens": 113,
    "input_tokens": 83,
    "output_tokens": 30,
    "cost": 0.000508
  }
}

Field	Description
`text`	The transcribed text
`usage.seconds`	Audio duration in seconds (exact for WAV; estimated from file size for other formats)
`usage.input_tokens`	Input tokens billed for the request
`usage.output_tokens`	Output tokens for the transcribed text
`usage.total_tokens`	`input_tokens` + `output_tokens`
`usage.cost`	Total billed cost in USD

Text

A plain string with the transcription. The Content-Type header will be text/plain. Token and cost details are not included in the body when response_format is "text".

Errors

HTTP Status	Code	When
`400`	`invalid_request`	File missing, filename missing, or file is empty
`400`	`invalid_file_format`	File extension not in supported formats
`400`	`file_too_large`	File exceeds 25 MB
`400`	`invalid_model`	Unknown model id, or model does not support audio input
`403`	`endpoint_not_allowed`	API key endpoint allowlist excludes `audio.transcriptions`
`403`	`model_not_allowed`	Resolved model is outside the key's model allowlist
`400`	`unsupported_response_format`	`response_format` is not `"json"` or `"text"`
`400`	`invalid_call_name`	`call_name` is empty, whitespace-only, or exceeds 64 characters
`400`	`invalid_end_user_id`	`end_user_id` is empty, whitespace-only, or exceeds 512 characters
`401`	`unauthorized`	Invalid or missing API key
`402`	`insufficient_credits`	Account balance is zero or negative
`429`	`rate_limit_exceeded`	Too many requests
`500`	`internal_error`	Unexpected server error

Billing

Billed like Completions. On JSON responses, the amount is usage.cost.

Audio in chat completions

To ask questions about audio, or send it in a conversation, use input_audio content parts on Completions instead.