> For the full page index, fetch https://echonova.ai/llms.txt

# Developer API overview

What the Developer API does, the fifteen endpoints it exposes, and how a request is authenticated, answered and billed.

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.

| Method   | Path                              | What it does                                                      | Reference                                                             |
| -------- | --------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------- |
| `POST`   | `/v1/text-to-speech`              | Start a Text to Speech job and return its id                      | [Generate speech from text](/docs/reference/tts-generate-async)       |
| `POST`   | `/v1/text-to-speech/sync`         | Generate speech and return the audio URL in one call              | [Generate speech synchronously](/docs/reference/tts-generate-sync)    |
| `GET`    | `/v1/text-to-speech/voices`       | List the voices you can use                                       | [List available voices](/docs/reference/tts-list-voices)              |
| `GET`    | `/v1/text-to-speech/jobs`         | List the API jobs of the workspace for Text to Speech             | [List Text to Speech jobs](/docs/reference/tts-list-jobs)             |
| `GET`    | `/v1/text-to-speech/jobs/{jobId}` | Get one Text to Speech job                                        | [Get TTS job details](/docs/reference/tts-get-job)                    |
| `POST`   | `/v1/speech-to-text`              | Upload an audio file, start a transcription job and return its id | [Transcribe audio file](/docs/reference/stt-transcribe)               |
| `POST`   | `/v1/speech-to-text/sync`         | Upload an audio file and return the transcription in one call     | [Transcribe audio synchronously](/docs/reference/stt-transcribe-sync) |
| `GET`    | `/v1/speech-to-text/jobs`         | List the API jobs of the workspace for Speech to Text             | [List Speech to Text jobs](/docs/reference/stt-list-jobs)             |
| `GET`    | `/v1/speech-to-text/jobs/{jobId}` | Get one Speech to Text job                                        | [Get STT job details](/docs/reference/stt-get-job)                    |
| `POST`   | `/v1/sound-cleaning`              | Upload audio of up to 10 minutes and return the cleaned file link | [Clean audio](/docs/reference/clean-create)                           |
| `GET`    | `/v1/sound-cleaning/jobs`         | List the API jobs of the workspace for Sound Cleaning             | [List sound cleaning jobs](/docs/reference/clean-list-jobs)           |
| `GET`    | `/v1/sound-cleaning/jobs/{jobId}` | Get one Sound Cleaning job                                        | [Get Sound Cleaning job details](/docs/reference/clean-get-job)       |
| `DELETE` | `/v1/text-to-speech/jobs/{jobId}` | Delete one Text to Speech job and its stored file                 | [Delete a TTS job](/docs/reference/tts-delete-job)                    |
| `DELETE` | `/v1/speech-to-text/jobs/{jobId}` | Delete one Speech to Text job and its stored file                 | [Delete an STT job](/docs/reference/stt-delete-job)                   |
| `DELETE` | `/v1/sound-cleaning/jobs/{jobId}` | Delete one Sound Cleaning job and its stored file                 | [Delete a Sound Cleaning job](/docs/reference/clean-delete-job)       |

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](/docs/developers/base-url). Every request
carries your API key as a bearer token in the `Authorization` header; see
[Authentication](/docs/developers/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.

```json
{
  "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](/docs/developers/sync-vs-async) 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](/docs/developers/webhooks-configure)
for setup and
[Verify a webhook signature](/docs/developers/webhooks-verify-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](/docs/developers/base-url)
- [Get an API key](/docs/developers/get-an-api-key)
- [Authentication](/docs/developers/authentication)
- [Rate limits](/docs/developers/rate-limits)
- [Credits](/docs/developers/credits)
- [Text to Speech quickstart](/docs/developers/tts-quickstart)
- [Speech to Text quickstart](/docs/developers/stt-quickstart)
- [Sound Cleaning quickstart](/docs/developers/clean-quickstart)
- [What is EchoNova](/docs/get-started/what-is-echonova)