Appearance
Speech to text
POST /v1/audio/transcriptions
Upload an audio file and get its transcript back. Billed per second of audio.
python
with open("call.wav", "rb") as audio:
result = client.audio.transcriptions.create(model="cadence-stt", file=audio)
print(result.text)js
import fs from 'node:fs'
const result = await client.audio.transcriptions.create({
model: 'cadence-stt',
file: fs.createReadStream('call.wav'),
})
console.log(result.text)bash
curl https://api.xvoice.dev/v1/audio/transcriptions \
-H "Authorization: Bearer $XVOICE_API_KEY" \
-F model=cadence-stt \
-F file=@call.wavThis endpoint needs the whole file up front. For audio that is still being captured, such as a live call, use realtime transcription.
Request body
Send the request as multipart/form-data.
| Field | Type | Required | Description |
|---|---|---|---|
file | file | yes | The audio. At most 25 MB and 10 minutes |
model | string | yes | An STT model id: cadence-stt |
language | string | no | The language spoken, as an ISO 639-1 code such as en. Omit it to detect the language automatically |
prompt | string | no | Context or spellings to steer the transcript, such as names and terms. At most 1,000 characters |
response_format | string | no | json (default) or text |
stream | boolean | no | Return the transcript as server-sent events. Default false. See Streaming |
Set language only to the language actually spoken
The model writes the transcript in the language you name. Passing en for German speech produces an English translation, not a German transcript. If you are not sure, leave language out.
The languages cadence-stt supports are listed in supported_languages on the model. Any other code fails with unsupported_language.
Audio files
Uploads can be FLAC, M4A, MP3, MP4, OGG, WAV or WebM.
WAV with 16-bit PCM is the most reliable input. If a file in another format fails with unsupported_audio_format, convert it to WAV and send it again:
bash
ffmpeg -i input.m4a -ac 1 -ar 16000 -c:a pcm_s16le input.wavMono audio at 16 kHz is enough for speech, and keeps files small: 10 minutes is about 19 MB.
Response
With response_format=json (the default):
json
{
"text": "Thanks for calling. How can I help you today?",
"usage": {"type": "duration", "seconds": 4.2}
}usage.seconds is the duration of the audio as we measured it, and it is what you are billed for.
With response_format=text, the body is the transcript as text/plain.
Streaming
With stream=true, the transcript arrives as server-sent events in the same shape as OpenAI's API, so existing code for streamed transcription works unchanged.
INFO
cadence-stt currently sends the whole transcript in a single delta once it is complete, so streaming does not make text appear sooner. Your code will not need to change when deltas become incremental. For text while someone is still speaking, use realtime transcription.
python
with open("call.wav", "rb") as audio:
stream = client.audio.transcriptions.create(
model="cadence-stt", file=audio, stream=True
)
for event in stream:
if event.type == "transcript.text.delta":
print(event.delta, end="", flush=True)
elif event.type == "transcript.text.done":
print()text
data: {"type":"transcript.text.delta","delta":"Thanks for calling."}
data: {"type":"transcript.text.done","text":"Thanks for calling.","usage":{"type":"duration","seconds":2.0}}- Deltas are only ever appended, never revised.
transcript.text.donecarries the full transcript, so you can wait for it alone if you only want the final text.response_formathas no effect when streaming.- A failure after the stream has started arrives as an
errorevent, which the OpenAI SDKs raise from the loop. A stream that stops with noerrorevent means the connection dropped.
Limits
| Limit | Value |
|---|---|
| File size | 25 MB |
| Duration | 10 minutes (600 seconds) |
prompt | 1,000 characters |
To transcribe a longer recording, split it into parts of up to 10 minutes and send one request per part. Each part is billed for its own audio, so splitting costs nothing extra.
Each request also counts against your organization's audio seconds per minute.
Billing
You are billed per second of audio, as measured from the file, and never rounded up to the minute. A request rejected before transcription starts, such as a file that is too large, is not billed. A streamed request that has already delivered text is billed even if you disconnect. Prices are on xvoice.dev.
Errors
| Code | Status | Cause |
|---|---|---|
invalid_model | 400 | No such model, or not an STT model |
unsupported_language | 400 | The model does not support that language |
file_too_large | 400 | The file is over 25 MB |
audio_too_long | 400 | The audio is longer than 10 minutes |
invalid_audio | 400 | The file is unreadable, in an unsupported format, or has no audio |
unsupported_audio_format | 400 | The model cannot transcribe this encoding. Send 16-bit PCM WAV |
invalid_input | 400 | The model could not process this audio |
input_too_long | 400 | The audio is longer than the model can handle in one request |
validation_error | 422 | A field failed validation, such as a prompt over 1,000 characters. param names the field |
model_unavailable | 404 | The model cannot serve requests right now. Retry later |
model_error | 500 | The model failed on this request. Retry once |
model_overloaded | 503 | The model is at capacity. Retry after retry-after |
service_unavailable | 503 | A temporary problem on our side. Retry after retry-after |
stream_interrupted | — | Sent in band: the stream ended early |
Account-level errors (401, 402, 429) are listed on Errors.