Documentation
Developers
API keys, authentication, jobs, webhooks and code samples.
Start
- Developer API overviewWhat the Developer API does, the fifteen endpoints it exposes, and how a request is authenticated, answered and billed.
- Base URLThe one host every Developer API request goes to, how paths are versioned, and which workspace an API key belongs to.
- Get an API keyCreate a key in the portal, store the secret once, and make your first authenticated request.
- AuthenticationThe Authorization header, the API key format, the checks every request passes, and each authentication error with its cause and fix.
- Rate limitsHow many requests one API key can make per minute, the headers that report the count, what a 429 looks like, and how to back off.
- CreditsWhat each service costs in credits, how AI usage becomes credits, worked examples, and how a key's credit limit is enforced.
- Synchronous and asynchronous callsWhich of the two call styles fits a request, how a job moves through its four statuses, and how to poll for the result.
- Retry requests safelyTell a retry that costs nothing from one that creates a second job, keep the job id so you never have to send a request twice, and back off correctly on 429 and 5xx responses.
- Code samplesTwo complete programs per language, an asynchronous Text to Speech job from request to saved audio file and an asynchronous Speech to Text job from upload to transcript, plus the response envelope they all read.
- Connect EchoNova to ClaudeAdd EchoNova as a connector in Claude, see what each tool does, who can connect, how to disconnect, and how your data is handled.
Text to Speech
- Text to Speech quickstartList the voices, turn one Arabic sentence into audio with the synchronous endpoint, save the file, then run the same request as an asynchronous job and poll it.
- Text to Speech voices and optionsThe voice list and what each voice field means, how to pick a voice by language, and every request option with its type, range, default and effect.
- POSTGenerate speech from textStarts a Text to Speech job for 1 to 500 characters and returns its jobId. Get the audio from GET /v1/text-to-speech/jobs/{jobId} or the job.completed webhook. Cloned voices work with the sync endpoint only.
- POSTGenerate speech synchronouslyGenerates speech for 1 to 500 characters in one call and returns the audio URL with the credits charged.
- GETList available voicesLists the EchoNova voice library. Send a voice's id as voiceId when you generate speech.
- GETList Text to Speech jobsLists the API jobs in this key's workspace, paged with offset and limit. Needs Text to Speech access on the key.
- GETGet TTS job detailsReturns one API job of this key's workspace, with its audio URL once it has completed, whichever key created it. A job of another workspace answers 404. Needs Text to Speech access on the key.
- DELETEDelete a finished TTS job and its audioDeletes a completed or failed API job of this key's workspace, with its audio, whichever key created it. A job still in progress answers 400; a job of another workspace answers 404. Needs Text to Speech access on the key.
Speech to Text
- Speech to Text quickstartTranscribe a short audio file in one call, read the transcript and its duration, run a long file as an asynchronous job and poll it, then download it as subtitles with speaker labels.
- Speech to Text formats and outputWhat the upload endpoints accept, which checks run before a job starts, every field the responses carry, speaker identification, the TXT, SRT and JSON downloads, and what durationSeconds means.
- POSTTranscribe audio fileStarts a Speech to Text job for an uploaded audio file of up to 10 minutes and 150MB, and returns its jobId. Get the transcription from GET /v1/speech-to-text/jobs/{jobId} or the job.completed webhook.
- POSTTranscribe audio synchronouslyTranscribes an uploaded audio file of up to 10 minutes and 150MB in one call and returns the transcription with the credits charged.
- GETList Speech to Text jobsLists the API jobs in this key's workspace, paged with offset and limit. Needs Speech to Text access on the key.
- GETGet STT job detailsReturns 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.
- DELETEDelete a finished STT job and its audioDeletes a completed or failed API job of this key's workspace, with its audio, whichever key created it. A job still in progress answers 400; a job of another workspace answers 404. Needs Speech to Text access on the key.
- GETDownload a completed STT job as TXT, SRT or JSONReturns the transcript of a completed API job of this key's workspace as a file: txt is the transcription text, srt is subtitles of at most 7 seconds and two 42-character lines per cue, each prefixed with its speaker label when speakers were identified, and json carries the text, speakers and timed segments. lang sets the language of the speaker labels. A job that has not completed answers 400; a job of another workspace answers 404. Needs Speech to Text access on the key.
Sound Cleaning
- Sound Cleaning quickstartClean a recording of up to 10 minutes in one call, read the cleaned file link and its cost, tune the cleaner, then list your past jobs.
- POSTClean audio synchronouslyCleans an uploaded MP3, WAV, FLAC or OGG/Opus file of up to 10 minutes and 150MB in one call and returns the job with the cleaned file URL. Every tuning field is optional; an omitted one uses its default.
- GETList sound cleaning jobsLists the API jobs in this key's workspace, paged with offset and limit. Needs Sound Cleaning access on the key.
- GETGet sound cleaning job detailsReturns one API job of this key's workspace, with its cleaned file URL, whichever key created it. A job of another workspace answers 404. Needs Sound Cleaning access on the key.
- DELETEDelete a finished sound cleaning job and its audioDeletes a finished API job of this key's workspace, with its original and cleaned files, whichever key created it. A job of another workspace answers 404. Needs Sound Cleaning access on the key.
Webhooks
- Configure a webhookCreate a webhook endpoint in the portal, choose the events it receives, keep its signing secret, and disable or delete it later.
- Webhook eventsThe four events EchoNova sends, the headers on every delivery, and the exact JSON body of each event.
- Verify a webhook signatureRecompute the HMAC-SHA256 signature on every delivery, compare it in constant time, and reject requests that are stale or unsigned.
- Delivery, retries and failuresWhat counts as a successful delivery, the retry schedule, the delivery status values, when a webhook is disabled, and how to handle duplicates.
Operations
- Read your API activityOpen Developers Activity, read the Overview, Trends, Explore and Logs tabs, and know exactly which requests and credits the page counts.
- Read the request logOpen the Request Log tab, read what each column means, find the call your system made, and know which requests are never recorded.
- ErrorsEvery HTTP status and errorMessage the v1 API returns, when each one happens, what to do about it, and how asynchronous jobs report failure.
- Latency best practicesHow to get results back sooner and waste fewer requests, using the sync and async endpoints, the rate limit, the job timeout and the webhooks as they behave.
- Security best practicesHow to keep an API key from leaking, limit what a leaked key can do, replace a key safely, trust only genuine webhooks, and audit what your keys did.