Documentation
Developers / Speech to Text
Transcribe audio synchronously
https://api.echonova.ai/v1/speech-to-text/syncTranscribes an uploaded audio file of up to 10 minutes and 150MB in one call and returns the transcription with the credits charged.
Headers
Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.
Request body
multipart/form-data
Audio file (up to 10 minutes, 150MB).
auto lets the service decide (Arabic today, which also handles mixed and clean English speech); ar for Arabic and mixed Arabic/English; en only for wholly English speech. Arabic sent as en comes back garbled.
Write spoken numbers as digits (صفر واحد واحد → 011). Set false to keep them as words. Applies to Arabic; English transcripts are never converted.
Identify who speaks when: the finished job then lists the speakers and the transcript split into timed segments, each tagged with its speaker. Leave it out or send false for the transcript text alone.
Response
200 application/json Every response uses this envelope.
The result.
The id of the job the call created.
completed. A synchronous call creates its job already completed.
The transcript text.
Length of the audio in seconds, as measured.
Language the transcription was requested with.
Whether spoken numbers were written as digits. Jobs from before the option read true.
Whether speaker identification was requested with identify_speakers. Jobs from before the option read false.
The transcript in timed pieces, each with its speaker, sorted by start. Empty unless speakers were identified.
Where the piece starts, in seconds from the start of the audio.
Where the piece ends, in seconds from the start of the audio.
What was said in this piece.
The id of the speaker (spk0, spk1, ...), numbered by first appearance; null when the speaker is unknown.
The speakers heard, in order of first appearance. Empty unless speakers were identified.
The speaker id the segments use.
How long this speaker talks, in seconds.
Credits charged, a whole number.
true for a successful call.
Repeats the HTTP status.
null on success.
Errors
Same envelope, with success false and data null. All errors
When. The Content-Type header says multipart/form-data but carries no boundary, usually because the client set the header by hand.
Fix. Remove the hand-written header and let the client set it with the boundary.
When. The form has a part with a field name other than file, or more than one part named file (only one file is accepted).
Fix. Send exactly one file part, and name it file.
When. The form has no file part, or the request was not multipart at all.
Fix. Send a multipart form with one part named file.
When. The part's Content-Type does not start with audio/; <type> is what the client sent.
Fix. Set the part's type, for example audio/wav or audio/mpeg.
When. The file's duration is over 10 minutes.
Fix. Split the recording into parts of 10 minutes or less.
When. The file is empty or could not be decoded as audio.
Fix. Check the file plays, or export it again in a common format.
When. The language form field holds something other than auto, ar or en.
Fix. Send auto, ar or en, or leave the field out.
When. The numbers_as_digits form field is not true, false, 1 or 0.
Fix. Send true or false, or leave the field out.
When. The identify_speakers form field is not true, false, 1 or 0.
Fix. Send true or false, or leave the field out.
When. The Authorization header is missing or is not Bearer ek_..., no key matches the token, or the key is deleted, disabled or its account is closed.
Fix. Send Authorization: Bearer ek_... with an enabled key from this environment.
When. The workspace balance cannot cover the charge for this call; nothing ran and nothing was charged.
Fix. Add credits to the workspace.
When. The workspace that owns the key has no subscription.
Fix. Check the workspace's plan in the portal.
When. The subscription is in a state other than active or trial.
Fix. Renew the subscription.
When. The key is restricted and Speech to Text is not among its services.
Fix. Edit the key and grant Speech to Text, or use another key.
When. The upload is over 150 MB; the request is cut off before the file is read.
Fix. Re-encode at a lower bitrate or as mono.
When. The key made more than 100 requests to one endpoint in 60 seconds, or one IP address made more than 100 requests to one endpoint in 60 seconds (the IP limit is counted before the key is checked, so it can answer with no key at all); a Retry-After header carries the seconds to wait.
Fix. Wait Retry-After seconds, then retry.
When. The call would take the key past its Credit Limit for this billing cycle; nothing ran and there is no Retry-After header.
Fix. Raise or clear the limit on the key, or wait for the next cycle.
When. An error the API did not classify.
Fix. Check the request, then retry after a short wait; contact support if it persists.
When. Too many uploads were being measured at once, or measuring timed out; nothing was charged.
Fix. Retry after a short wait.
When. Transcription was unavailable for the request; the charge is refunded.
Fix. Retry once; if the same file fails every time, send it to POST /v1/speech-to-text, whose job carries the reason in error.
When. A transient outage inside the API.
Fix. Retry after a short wait.
When. A transient timeout inside the API.
Fix. Retry after a short wait.
curl -X POST "https://api.echonova.ai/v1/speech-to-text/sync" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@audio.mp3;type=audio/mpeg"{
"data": {
"jobId": "66e3f2a1c9d4b8a1f0e12345",
"status": "completed",
"transcription": "مرحبا بكم في إيكونوڤا",
"durationSeconds": 15.51,
"language": "ar",
"numbersAsDigits": true,
"identifySpeakers": true,
"segments": [
{
"start": 0.38,
"end": 4.12,
"text": "السلام عليكم، كيف حالك؟",
"speaker": "spk0"
}
],
"speakers": [
{
"id": "spk0",
"talkTime": 88.1
}
],
"creditsConsumed": 26
},
"success": true,
"statusCode": 200,
"errorMessage": null
}