Synchronous and asynchronous calls

Text to Speech and Speech to Text each expose the same two call styles. A synchronous call holds the connection open and returns the result in its response. An asynchronous call returns a job id at once and does the work in the background; you read the result from the job endpoint or receive it through a webhook. This page explains what each style does, when to use it, and how a job moves from start to finish.

The two styles

The request body is the same for both Text to Speech endpoints, and the multipart/form-data upload is the same for both Speech to Text endpoints. The reference pages list every field: Generate speech synchronously, Generate speech from text, Transcribe audio synchronously and Transcribe audio file.

What both styles share

• The charge comes first. The API prices the request, charges the workspace, and only then does the work. If the balance cannot cover it, the call is rejected with 402 and Insufficient subscription balance before anything runs. See Credits.
• Every call creates a job. A synchronous call creates the job already completed; an asynchronous call creates it pending. Both appear in GET /v1/text-to-speech/jobs or GET /v1/speech-to-text/jobs, newest first, and both can be read back from GET .../jobs/{jobId}. Any key in the workspace with access to that product can read the job.
• A failure is refunded. When a synchronous call fails, you get an error response and the charge is refunded. When an asynchronous job fails, its status becomes failed, error holds the reason, and the charge is refunded.
• The same envelope. Every response is { "success", "statusCode", "errorMessage", "data" } and every successful call, including POST, returns HTTP 200. See Developer API overview.

Choosing a style

Use the synchronous endpoint when all of these hold:

• You need the result inside the same request, for example to answer a chat message or to play a prompt on a call.
• The input is within the limit: audio of 10 minutes or less for Speech to Text, 500 characters for Text to Speech. Both endpoints of each service share the limit, so input size never forces the choice.
• Your client can keep an HTTP connection open for as long as the work takes. The API sets no timeout of its own on a synchronous call, so set your client timeout with the input size in mind.

Use the asynchronous endpoint in every other case:

• Batches. Submit many jobs, then poll them or let webhooks tell you when each one is done.
• Clients with a short HTTP timeout, or work you do not want to block on.
• Anything where you want a job.completed or job.failed event delivered to your own endpoint instead of holding a connection.

Match the style to who is waiting. A person waiting on a reply wants one round trip; a batch wants a free connection and a webhook.

Recommended

• A chat reply: POST /v1/text-to-speech/sync, result in the response.
• Five hundred recordings overnight: POST /v1/speech-to-text for each, with a webhook on job.completed and job.failed.

Less effective

• A chat reply: POST /v1/text-to-speech, then a poll loop that holds the user for the same time plus a polling interval.
• Five hundred recordings overnight: POST /v1/speech-to-text/sync in parallel with a 30-minute client timeout on every connection.

Job lifecycle

A job has four statuses: pending, processing, completed and failed. An asynchronous job passes through them in this order:

POST accepted
     |
     v
  pending  -->  processing  -->  completed
                    |
                    +--------->  failed

Three rules hold for every job:

• A job ends once. A job cannot go from completed to failed, or be completed twice.
• A job cannot stay processing forever. A job that has been processing for longer than 10 minutes is marked failed with error set to Job timed out — AI server did not respond; the status changes within 15 minutes of the POST. The credits are refunded. This timeout sends no job.failed webhook, so a poll loop, or a fallback poll after 15 minutes of silence, is the way to learn about it.
• A rejection at submission is reported twice. If the job is refused when the POST submits it, the job is marked failed, the credits are refunded, and the POST itself returns an error, most often 503 with Speech generation is temporarily unavailable. Please try again. or Transcription is temporarily unavailable. Please try again.. The failed job stays in your job list.

A synchronous call has a shorter story: the job appears as completed when the result is ready, and if the call fails no job is created at all. You get the error response and the refund.

Polling a job

Read the job with GET /v1/text-to-speech/jobs/{jobId} or GET /v1/speech-to-text/jobs/{jobId}, using the jobId from the POST response. Stop when status is completed or failed.

curl https://api.echonova.ai/v1/text-to-speech/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

import time
import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

while True:
    job = requests.get(
        f"https://api.echonova.ai/v1/text-to-speech/jobs/{job_id}",
        headers=headers,
    ).json()["data"]
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(3)

print(job["status"], job.get("audioUrl") or job.get("error"))

const headers = { Authorization: 'Bearer YOUR_API_KEY' };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

let job;
for (;;) {
  const response = await fetch(`https://api.echonova.ai/v1/text-to-speech/jobs/${jobId}`, { headers });
  job = (await response.json()).data;
  if (job.status === 'completed' || job.status === 'failed') break;
  await sleep(3000);
}

console.log(job.status, job.audioUrl ?? job.error);

The job object names its id id, while the POST that started it returned jobId. The fields:

audioUrl is a signed link to a WAV file, and it expires. Every GET of the job returns a fresh link, so poll again rather than storing the URL. Fetch the file with a plain GET and no Authorization header.

Two things to keep in mind while polling:

• Every poll counts against the rate limit of 100 requests per 60 seconds per key on that endpoint. Wait a few seconds between polls. See Rate limits.
• Give the loop a deadline. Every job reaches completed or failed within 15 minutes of entering processing.

The full pattern, with backoff on 429 and 5xx, is on Retry requests safely.

Webhooks instead of polling

When an asynchronous job ends, the API sends job.completed or job.failed to every enabled webhook in the workspace that subscribes to that event. job.completed carries the result itself, audioUrl for Text to Speech and transcription for Speech to Text, so you do not need to call the job endpoint afterwards. job.failed carries error. Synchronous calls never emit either event, and neither does the 10-minute timeout. See Configure a webhook and Webhook events.

Limits

FAQ

Does the asynchronous endpoint accept longer input?

No. Both Text to Speech endpoints take up to 500 characters, and both Speech to Text endpoints take up to 10 minutes of audio.

Can I get diacritics on an asynchronous job?

No. tashkeel takes effect on POST /v1/text-to-speech/sync only. The asynchronous endpoint accepts the field and synthesises the text as written.

Does a synchronous call show up in my job list?

Yes, already completed, with the same creditsConsumed, audioUrl or transcription as the response.

Why did my job end as failed with no webhook?

It timed out after more than 10 minutes in processing, and the timeout sends no event. Poll the job when 15 minutes have passed without one.

Is the result kept after the job ends?

Yes. GET .../jobs/{jobId} returns the transcript, or a fresh audioUrl, until you delete the job with DELETE .../jobs/{jobId} or close your account. Any key in the workspace with access to that product can delete its jobs. A job of another workspace answers 404.

Related

• Text to Speech quickstart
• Speech to Text quickstart
• Retry requests safely
• Code samples
• Configure a webhook
• Webhook events
• Get TTS job details
• Get STT job details
• Credits
• Rate limits