Create speech

POST

/v1/audio/speech

const url = 'https://api.aderra.ai/v1/audio/speech';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"model":"aderra-voice-1","input":"Hello from Aderra.","voice":"Hazel","response_format":"mp3"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.aderra.ai/v1/audio/speech \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "model": "aderra-voice-1", "input": "Hello from Aderra.", "voice": "Hazel", "response_format": "mp3" }'

Text to speech, OpenAI-compatible: the OpenAI SDKs’ audio.speech.create works with the base URL changed. Returns the audio bytes in the requested response_format.

Streamed. The audio is sent as it is generated (chunked transfer): the first audio arrives in about half a second, while a long text takes much longer to finish. Errors before the audio starts keep their status codes. Once audio is flowing the status is already 200, and an early failure shows as a truncated or aborted stream. The charge is made when the stream completes: an early end caused by Aderra is not charged; a client that disconnects mid-audio is charged, since the audio was generated. A streamed wav has its RIFF and data sizes set to the maximum (“until the end of the file”).

API keys only. Speech is paid from the API wallet; a terminal key is refused with 403 api_key_required.

Long text. Up to 4,096 billable characters in mp3, wav and pcm. The text is spoken in chunks of up to 900 billable characters, split at sentence ends, and joined into one stream (x-aderra-chunks says how many). aac, opus and flac cannot be joined, so text longer than one chunk is refused in those formats with input_too_long_for_format.

Billing. Per billable character, quoted per 1,000 in GET /v1/usage/prices. Chinese, Japanese and Korean characters count 3. If any chunk fails, the request fails and nothing is charged.

Authorizations

bearerAuth
apiKeyHeader

Request Body^required

application/json

object

model

required

string

Allowed values: aderra-voice-1

input

required

The text to speak, up to 4,096 billable characters (Chinese, Japanese and Korean characters count 3). Longer than 900 is spoken in chunks and joined, in mp3, wav and pcm only.

string

>= 1 characters <= 4096 characters

voice

required

One of 200 voices, every one speaking every supported language. Case-insensitive. List them, with their gender, age, accent, use cases, style and a sample, with GET /v1/audio/voices, or listen at https://aderra.ai/docs/api/voices/. An unknown voice is refused with invalid_voice.

string

response_format

pcm is raw 16-bit signed little-endian mono at 24 kHz, as in OpenAI; wav is the same audio with a header. aac is served as an MP4 (M4A) file, Content-Type audio/mp4. aac, opus and flac are limited to one chunk (about 900 billable characters).

string

default: mp3

Allowed values: mp3 aac wav pcm opus flac

speed

Speaking speed. Outside 0.7 to 1.3 is refused with invalid_speed.

number

default: 1 >= 0.7 <= 1.3

language

ISO 639-1 code such as en or fr (a region suffix such as fr-CA or pt_BR is accepted and dropped). Absent: detected from the text, English when it cannot be told.

string

Example

{
  "model": "aderra-voice-1",
  "input": "Hello from Aderra.",
  "voice": "Hazel",
  "response_format": "mp3"
}

Responses

200

The audio, streamed as it is generated. The Content-Type follows response_format (aac is served as audio/mp4).

string format: binary

aac: AAC audio in an MP4 (M4A) file.

string format: binary

Headers

x-aderra-chunks

integer

Example

How many chunks the text was spoken in and joined from.

x-aderra-billed-micro

string

Example

The price, in micro-credits, charged when the stream completes.

x-aderra-characters

integer

Example

The billable characters you were charged for (CJK characters count 3).

400

invalid_request_error with code: invalid_json, model_not_found, invalid_input (empty), input_too_long (over 4,096 billable characters), input_too_long_for_format (aac, opus or flac text longer than one chunk), invalid_voice, unsupported_format, invalid_speed or unsupported_language. param names the field.

application/json

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Example

{
  "error": {
    "message": "Unknown voice \"Bob\". List the 200 voices with GET /v1/audio/voices, or see https://aderra.ai/docs/api/voices/.",
    "type": "invalid_request_error",
    "param": "voice",
    "code": "invalid_voice"
  }
}

401

authentication_error / unauthorized: the key is missing, unknown or revoked.

application/json

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Example

{
  "error": {
    "type": "billing_error"
  }
}

402

insufficient_credits (type insufficient_quota, with requiredMicro): the API wallet cannot pay for this input. api_wallet_empty when the wallet is empty, and key_spend_cap_reached when the key hit its monthly cap.

application/json

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Example

{
  "error": {
    "type": "billing_error"
  }
}

403

api_key_required (a terminal key), or account_suspended.

application/json

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Example

{
  "error": {
    "type": "billing_error"
  }
}

413

request_too_large: the body is over the size limit.

application/json

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Example

{
  "error": {
    "type": "billing_error"
  }
}

429

rate_limited or too_many_concurrent_requests (wait for Retry-After), or provider_busy when the voice service is busy. Nothing is charged.

application/json

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Example

{
  "error": {
    "type": "billing_error"
  }
}

Headers

Retry-After

integer

Example

Whole seconds to wait before trying again.

502

api_error / provider_failed: the voice could not be generated. Nothing is charged.

application/json

object

error

required

object

type

string

param

The request field at fault, when there is one (speech).

string | null

code

The machine-readable reason. A string, except on upstream_error where it is the upstream HTTP status.

One of:

string
integer

string

message

string

Example

{
  "error": {
    "type": "billing_error"
  }
}

Create speech

Authorizations

Request Bodyrequired

Example

Responses

200

Headers

Example

Example

Example

400

Example

401

Example

402

Example

403

Example

413

Example

429

Example

Headers

Example

502

Example

Request Body^required