Developer API overview

The Developer API lets your own systems call EchoNova's speech services over HTTPS. It exposes three services: Text to Speech, which turns text into audio spoken by a voice from the voice library, Speech to Text, which transcribes an audio file, and Sound Cleaning, which cleans a short recording. You call it with an API key created in the portal, and every call is billed in credits against your workspace.

Endpoints

The API has fifteen endpoints, all under /v1. Each one has a reference page with the request fields, the response shape and code samples.

Any API key in the workspace with access to that product can list, get and delete its jobs, even jobs made by a key that was later deleted. A key without access to the product gets 403. A job of another workspace, or one made in the portal, answers 404. Only a completed or failed job can be deleted.

Base URL and authentication

Every request goes to one host, and the callout at the top of this page shows it; see Base URL. Every request carries your API key as a bearer token in the Authorization header; see Authentication.

Response shape

Every response, success or error, is one JSON object with the same four fields. A successful call returns HTTP 200, including POST calls.

{
  "success": true,
  "statusCode": 200,
  "errorMessage": null,
  "data": {}
}

On an error, success is false, data is null, statusCode matches the HTTP status and errorMessage holds a short string you can log.

Synchronous and asynchronous calls

Text to Speech and Speech to Text offer a synchronous endpoint and an asynchronous one. Sound Cleaning is synchronous only. The synchronous endpoint waits for the work to finish and returns the result in the response. The asynchronous endpoint returns at once with a jobId and a status; the job moves through pending and processing and ends as completed or failed, and you fetch the result from the job endpoint or receive it through a webhook. Synchronous and asynchronous calls explains how to choose between them.

Webhooks

Instead of polling a job, you can register an HTTPS endpoint in the portal under Developers on the Webhooks tab. EchoNova then sends a signed request for four events: job.completed and job.failed when a job ends, and spending.warning and spending.exhausted when a key approaches or reaches its credit limit. See Configure a webhook for setup and Verify a webhook signature for the check your endpoint must run.

FAQ

Which endpoint do I call first?

GET /v1/text-to-speech/voices. It needs only your key, charges nothing, and a 200 proves the key and the host are right.

Do POST calls return 201?

No. Every successful call, including POST, returns HTTP 200 with success set to true.

Can one key see another key's jobs?

Yes, inside one workspace. Any API key in the workspace with access to that product can list, get and delete its jobs, even jobs made by a key that was later deleted. A key without access to the product gets 403. Rate limits and credit limits stay per key.

Is the Developer API the same as the portal?

The same speech services. The portal adds Assets and agents, which are not in the API.

Related

Read these next, in order:

• Base URL
• Get an API key
• Authentication
• Rate limits
• Credits
• Text to Speech quickstart
• Speech to Text quickstart
• Sound Cleaning quickstart
• What is EchoNova