Audio Transcriptions API
Sample requests and responses for transcribing audio with the Agentaus API.
Send one audio file and get its transcript back. The whole transcript is returned in one response, or streamed with
stream=true.Endpoint
POST
/api/v1/audio/transcriptions
Create a Transcription
Requires header
Authorization: Bearer <token> and a multipart/form-data body with one audio file.curl https://<host>/api/v1/audio/transcriptions \ -H "Authorization: Bearer $API_KEY" \ -F [email protected] \ -F model=agentaus-models
Response
{
"text": "Hello, this is the transcript of the meeting.",
"usage": {
"type": "tokens",
"output_tokens": 25,
"total_tokens": 25
}
}file
Audio file
BehaviorExtension is one of
mp3, mpeg, mpga, wav, m4a, mp4, ogg, flac, webm. Not empty, max 200 MBOther files return 400Bad Request.
model
agentaus-modelsBehaviorThe only option (default)
Other values return 400Bad Request.
response_format
jsonBehaviorReturns
text and usage (default)textBehavior
200, Content-Type: text/plain, body is the transcript only (no usage)Other values (
verbose_json, srt, vtt, diarized_json) return 400Bad Request.language
enBehaviorThe only language for now (default)
Other values return 400Bad Request.
stream
falseBehaviorThe whole transcript is returned in one response (default)
trueBehaviorServer-sent events, see Streaming.
response_format is then ignoredResponse
response_format: json (default)
json
{
"text": "Hello, this is the transcript of the meeting.",
"usage": {
"type": "tokens",
"output_tokens": 25,
"total_tokens": 25
}
}text
Typestring
NotesThe transcript
usage
Billed per token from your API balance.
type
Typestring
Notes
"tokens"output_tokens
Typeinteger
NotesOutput tokens of the transcription
total_tokens
Typeinteger
NotesEquals
output_tokens — no input tokens are countedjson
"usage": { "type": "tokens", "output_tokens": 25, "total_tokens": 25 }Streaming
200, Content-Type: text/event-stream, one data: <json> event per update:text
data: {"type":"transcript.text.delta","delta":"Hello, this is"}
data: {"type":"transcript.text.delta","delta":" the transcript of the meeting."}
data: {"type":"transcript.text.done","text":"Hello, this is the transcript of the meeting.","usage":{"type":"tokens","output_tokens":25,"total_tokens":25}}- Only text that extends what was already sent goes out as a delta. The
transcript.text.doneevent always has the final text. - Errors before the stream starts (400Bad Request, 402Payment Required, 404Not Found, …) are normal responses. After it starts, the status is already
200, so a failure is a last event:
text
data: {"type":"error","error":{"message":...,"type":"server_error",...}}Errors
json
{
"error": {
"message": "Audio file is larger than 200MB",
"type": "invalid_request_error",
"param": null,
"code": null
}
}400Bad Request
type
invalid_request_errorMeaningNo file; unsupported type, empty or larger than 200 MB; unsupported
model, response_format or language401Unauthorized
type—
MeaningPlain-text body, not JSON. Missing, invalid or expired token
402Payment Required
type
insufficient_quotaMeaningAPI balance too low to reserve the credit:
"You exceeded your current quota."403Forbidden
type—
MeaningPlain-text body, not JSON. No permission
404Not Found
type
not_found_errorMeaningTranscription is not available:
"Transcription is not available."429Too Many Requests
type
rate_limit_errorMeaningRate limit exceeded. Retry after
Retry-After seconds500Internal Server Error
type
server_errorMeaningAny other failure:
"Unable to transcribe the audio file"503Service Unavailable
type
overloaded_errorMeaning
"Platform is at capacity, please retry shortly." Retry after Retry-After seconds503Service Unavailable
type—
MeaningPlain-text body, not JSON. Backend temporarily unavailable — retry
504Gateway Timeout
type
server_errorMeaningNo result before the timeout:
"Transcription timed out"