Get an API key | EchoNova Docs

Base URL https://api.echonova.ai

An API key lets your own backend call the Developer API on behalf of your workspace. You create it in the portal, copy the secret once, and send it as a bearer token on every request.

What you need

An EchoNova account and a workspace. Sign in at /auth/sign-in.
The workspace owner's access, which includes the developer_api.manage permission.
An active or trial subscription on the workspace. The API rejects keys from a workspace without one.
A free slot under your plan's limit on active keys. The portal tells you when you are at the limit.

Steps

Step 1: Open the API Keys tab

Go to /developers?tab=api-keys, or open Developers in the portal and select the API Keys tab. Keys you already created are listed here.

Step 2: Create the key

Select Create Key and fill in the form.

Field	What to enter
Name	Required. 1 to 100 characters. Name the system that will hold the key.
Credit Limit	Optional. A whole number of credits, up to 3,000,000,000, that this key may spend per billing cycle. The − and + buttons step by 10,000. Clear it for no limit.
Services	Set Access or No Access for Text to Speech, Speech to Text and Sound Cleaning.
Allow requests made with this credential.	On by default. Turn it off to create the key in the Disabled state.

Select Create.

The portal will not save a key without at least one service with Access. A key made before this change with no service selected can still call every service, so open it and choose its services.

Shape each key for one system. A leaked key can then be disabled without stopping anything else, and a call in the request log names the system that made it.

Recommended

billing-service, Access on Text to Speech only, Credit Limit a little above its normal monthly use.

Less effective

main, Access on every service, no credit limit, shared by every system you run.

Step 3: Save the secret

The dialog changes to Key Created Successfully and shows the secret under Secret Key. The secret starts with ek_. Select Copy to put it on your clipboard, or Download JSON to save a file named after the key that holds it as secret_key.

The secret is shown once. After you close this dialog the portal displays only the first 8 characters. If you lose the secret, delete the key and create a new one.

Step 4: Make a request

Send the secret as a bearer token in the Authorization header. This call lists the voices your key can use:

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

import requests

response = requests.get(
    "https://api.echonova.ai/v1/text-to-speech/voices",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())

const response = await fetch('https://api.echonova.ai/v1/text-to-speech/voices', {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
console.log(await response.json());

A 200 response with a list of voices means the key works.

What happens next

The key appears in the list with its Name, the first 8 characters of the secret, the Created date, the Last Used date and its Status.
Every request that passes authentication updates Last Used.
Use the switch on the row to disable or enable the key. A disabled key is rejected until you enable it again.
Open the row menu to Edit the name, credit limit, services and state, or to Delete the key. Deleting asks you to confirm and cannot be undone.
If the key has a credit limit, usage counts from the start of your billing cycle and resets on the key's first metered call of a new cycle; see Credits. When usage passes 80% of the limit, a spending.warning webhook event is sent once per cycle. When usage reaches the limit, spending.exhausted is sent on every such call.
A call that would cross the limit is rejected with 429, whichever service it is for. Nothing is charged.

Limits

Limit	Value	Applies to
Name length	1 to 100 characters	Create and Edit
Credit limit	Up to 3,000,000,000 whole credits, or empty for no limit	Each key, per billing cycle
Active keys per workspace	Set by your plan	Creating a key
Services a key can call	Text to Speech, Speech to Text, Sound Cleaning	Requests made with the key

Troubleshooting

401 Unauthorized

The request reached the API without a usable key. One of these is true: the Authorization header is missing, it does not use the Bearer scheme, the token does not start with ek_, the key was deleted, the key is disabled, or the account that owns it is closed. Check the header, then check the key's Status in the portal.

403 Subscription expired or inactive

The workspace that owns the key has no active or trial subscription. Renew the subscription, then retry.

403 This API key does not have access to Text-to-Speech services

The key has at least one service on Access, and the one you called is not among them. The same message exists for Speech-to-Text and Sound Cleaning. Edit the key and grant Access to the service, or use a different key.

429 Monthly spending limit exhausted

A call would take the key past its credit limit for this billing cycle. Raise the limit under Edit, clear it for no limit, or wait for the next cycle.

API-key limit reached

The portal shows this dialog when your plan's count of active keys is used up. Delete a key you no longer use, or upgrade the plan.

FAQ

Can I see the secret again?

No. The portal shows only the first 8 characters. Delete the key and create a new one.

Does one key work for every workspace?

No. A key belongs to the workspace it was created in. See Base URL.

What does disabling a key do?

Requests made with it get 401 until you enable it again. The key keeps its name, credit limit, services and usage.

What happens to the credit limit when I edit it?

The new limit applies to the next request. Usage already recorded in this cycle stays counted.

Who can create or delete keys?

The workspace owner, whose role has the developer_api.manage permission.