Documentation
Developers / Speech to Text
Get STT job details
https://api.echonova.ai/v1/speech-to-text/jobs/{jobId}Returns one API job of this key's workspace, with its transcription once it has completed, whichever key created it. A job of another workspace answers 404. Needs Speech to Text access on the key.
Headers
Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.
Path parameters
The jobId the API returned when the job was created.
Response
200 application/json Every response uses this envelope.
The result.
The job id.
pending, processing, completed or failed.
The transcript text. Absent until the job completes.
Length of the audio in seconds. An estimate while processing, the measured length once completed.
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.
The reason the job failed. Absent unless status is failed.
When the job was created, ISO 8601 in UTC.
true for a successful call.
Repeats the HTTP status.
null on success.
Errors
Same envelope, with success false and data null. All errors
When. jobId is not a 24-character hexadecimal id.
Fix. Use the id exactly as the create call returned it.
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 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 job id is unknown, or the job belongs to another workspace or was made in the portal.
Fix. Use a jobId from this workspace's API jobs.
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. An error the API did not classify.
Fix. Check the request, then retry after a short wait; contact support if it persists.
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 "https://api.echonova.ai/v1/speech-to-text/jobs/{jobId}" \
-H "Authorization: Bearer YOUR_API_KEY"{
"data": {
"id": "66e3f2a1c9d4b8a1f0e12346",
"status": "completed",
"transcription": "مرحبا بكم في إيكونوڤا",
"durationSeconds": 312.4,
"language": "ar",
"numbersAsDigits": true,
"identifySpeakers": true,
"segments": [
{
"start": 0.38,
"end": 4.12,
"text": "السلام عليكم، كيف حالك؟",
"speaker": "spk0"
}
],
"speakers": [
{
"id": "spk0",
"talkTime": 88.1
}
],
"creditsConsumed": 521,
"error": null,
"createdAt": "2026-09-15T10:21:04.512Z"
},
"success": true,
"statusCode": 200,
"errorMessage": null
}