Skip to main content
POST
/
v1
/
audio
/
transcriptions
Create transcription
curl --request POST \
  --url https://beta.api.voiceos.com/v1/audio/transcriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "messages": "<string>",
  "dictionary": [
    "<string>"
  ]
}
'
{
  "text": "<string>"
}
Creates a transcription from an audio file. You can optionally provide chat-style messages and dictionary terms to improve recognition.
This endpoint requires a developer API key on beta. Use either Authorization: Bearer vos_... or X-Api-Key: vos_....

​
Authentication

Send a developer API key in either header: 
Authorization: Bearer vos_...
or: 
X-Api-Key: vos_...

​
Endpoint

POST https://beta.api.voiceos.com/v1/audio/transcriptions
Content-Type: multipart/form-data

​
Request body

​
file
file
required
Audio file to transcribe. Supported formats: wav, webm, mp3, m4a, and ogg.
​
messages
string
Optional. JSON string containing an array of chat-style messages. Omit this field to run plain transcription from audio only.
​
languages
"auto" | string | string[]
Language constraint. Omit or set to "auto" for auto-detect, pass a single language code like "en", or pass an array like ["en", "ja"].
​
dictionary
string[]
Optional JSON array or comma-separated list of explicit dictionary terms.
​
response_format
"json"
Response format. Only json is supported.

​
Response

​
text
string
Final transcript output.

​
Example

curl https://beta.api.voiceos.com/v1/audio/transcriptions \
  -H "Authorization: Bearer vos_..." \
  -F "file=@sample.mp3" \
  -F 'messages=[{"role":"system","content":"You are in a voice agent coding session."},{"role":"user","content":"Mention QdrantVectorCache, LangGraph, and RAGPipelineConfig."}]' \
  -F 'languages=["en","ja"]' \
  -F 'dictionary=["VoiceOS","ASR"]' \
  -F 'response_format=json'

​
Errors

StatusCodeMeaning
400invalid_requestmessages, languages, or dictionary failed validation.
400missing_fileThe multipart request did not include file.
400unsupported_audio_typeThe uploaded file type is not supported.
400unsupported_response_formatOnly response_format=json is supported.
415unsupported_media_typeRequest was not multipart/form-data.
502transcription_failedASR or LLM provider failed.