Text to speech

POSThttps://api.aderra.ai/v1/audio/speech

Turn text into natural speech. OpenAI-compatible: the OpenAI SDK works with a changed base URL. API keys only: speech is paid from the API wallet, and a terminal key is refused with 403 api_key_required.

200 voices, and every voice speaks all 60 languages. Listen to them on Voices.
Six formats: mp3, wav, pcm, aac, opus and flac.
Up to 4,096 characters per request, streamed as it is generated: the first audio arrives in about half a second.

Request body

modelstringrequired: aderra-voice-1
inputstringrequired: The text, up to 4,096 billable characters in mp3, wav and pcm; about 900 in aac, opus and flac. See Limits and quotas.
voicestringrequired: One of 200 voices, for example Hazel, Reid or Brooke: list them with GET /v1/audio/voices. Every voice speaks every language. Case does not matter.
response_formatstringoptional: mp3 (default), aac, wav, pcm, opus or flac. See Audio formats.
speednumberoptional: From 0.7 to 1.3. Default 1. See Speed.
languagestringoptional: An ISO 639-1 code such as en or fr. Absent: detected from the text. See Languages.

curl https://api.aderra.ai/v1/audio/speech \
  -H "Authorization: Bearer $ADERRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aderra-voice-1",
    "voice": "Hazel",
    "input": "Hello from Aderra."
  }' \
  --output hello.mp3

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.aderra.ai/v1",
                api_key=os.environ["ADERRA_API_KEY"])

audio = client.audio.speech.create(
    model="aderra-voice-1",
    voice="Hazel",
    input="Hello from Aderra.",
)
audio.write_to_file("hello.mp3")

import fs from 'node:fs';
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.aderra.ai/v1',
  apiKey: process.env.ADERRA_API_KEY,
});

const audio = await client.audio.speech.create({
  model: 'aderra-voice-1',
  voice: 'Hazel',
  input: 'Hello from Aderra.',
});
fs.writeFileSync('hello.mp3', Buffer.from(await audio.arrayBuffer()));

Response: audio/mpegStreamed as it is generated; the Content-Type follows response_format. Headers x-aderra-billed-micro, x-aderra-characters and x-aderra-chunks give the price, the characters billed and the chunks spoken.

Before you start

Create an API key on the Developers page and add funds to the API wallet. See Authentication and Pricing.
Export it as ADERRA_API_KEY, which every example in this section reads.
Run the request above. It saves the audio as hello.mp3.

Next steps

VoicesListen to all 200 voices and list them from code with GET /v1/audio/voices, filtered by gender, age, accent, use case and style.

LanguagesThe 60 languages, how the language is detected and when to set it.

Audio formatsmp3, wav, pcm, aac, opus and flac: sample rates, limits and how to play raw pcm.

SpeedSlow a voice down or speed it up, from 0.7 to 1.3.

Streaming and long textPlay audio as it arrives, and how long text is split and joined.

Limits and quotasCharacters per request, rate limits, and text longer than 4,096 characters.

ErrorsEvery error code and what to do about it.

Best practicesWrite text that reads well aloud, and get audio faster.

Read the model from code

GEThttps://api.aderra.ai/v1/audio/models

The speech model and everything it accepts: its languages, formats, speed range, limits, price and how many voices match each filter. Build a language or format picker from it instead of hard-coding these pages. Any Aderra key works, API or terminal, and the call is free.

Field	What it is
`id`	The `model` to send: `aderra-voice-1`
`endpoint`	`/v1/audio/speech`
`voices`	How many voices there are
`voice_filters`	For `gender`, `age`, `accent`, `use_case` and `style`: each value and how many voices have it. The values `GET /v1/audio/voices` filters on
`languages`	Every supported language, `code` and English `name`
`response_formats`	Each `format` with its `content_type` and `max_characters`; `pcm` and `wav` also give `sample_rate`, `channels` and `bits_per_sample`
`default_format`	`mp3`
`speed`	`min`, `max` and `default`
`max_characters`, `chunk_characters`	4,096 and 900 billable characters. See Limits and quotas
`streaming`	`true`: the audio is streamed as it is generated
`per_thousand_characters`	The price per 1,000 billable characters, in credits (1,000 credits = $1)

curl https://api.aderra.ai/v1/audio/models \
  -H "Authorization: Bearer $ADERRA_API_KEY"

import os, requests

model = requests.get(
    "https://api.aderra.ai/v1/audio/models",
    headers={"Authorization": f"Bearer {os.environ['ADERRA_API_KEY']}"},
    timeout=30,
).json()["data"][0]

print(model["id"], model["speed"], len(model["languages"]))

const res = await fetch('https://api.aderra.ai/v1/audio/models', {
  headers: { Authorization: `Bearer ${process.env.ADERRA_API_KEY}` },
});
const [model] = (await res.json()).data;

console.log(model.id, model.speed, model.languages.length);

{
  "object": "list",
  "data": [{
    "id": "aderra-voice-1",
    "object": "model",
    "type": "text_to_speech",
    "endpoint": "/v1/audio/speech",
    "voices": 200,
    "voice_filters": {
      "gender": { "male": 119, "female": 81 },
      "age": { "middle_aged": 119, "young": 74, "old": 7 },
      "accent": { "american": 32, "indian": 30, "british": 17, "…": "…" },
      "use_case": { "narration": 122, "conversational": 96, "…": "…" },
      "style": { "friendly": 91, "calm": 83, "…": "…" }
    },
    "languages": [{ "code": "af", "name": "Afrikaans" }, "…"],
    "response_formats": [
      { "format": "mp3", "content_type": "audio/mpeg", "max_characters": 4096 },
      { "format": "pcm", "content_type": "audio/pcm", "max_characters": 4096,
        "sample_rate": 24000, "channels": 1, "bits_per_sample": 16 },
      "…"
    ],
    "default_format": "mp3",
    "speed": { "min": 0.7, "max": 1.3, "default": 1 },
    "max_characters": 4096,
    "chunk_characters": 900,
    "streaming": true,
    "per_thousand_characters": "30"
  }]
}

Response: application/jsonNot billed. A missing, unknown or revoked key gets 401 unauthorized.

Price

Speech is priced per billable character, quoted per 1,000: today $0.03 per 1,000 characters (see Models). Most characters count 1, spaces and punctuation included. Chinese, Japanese and Korean characters count 3, because each one speaks about three times as much audio. The voice does not change the price, and neither does the format or the speed.

The live price is on the Developers page, in GET /v1/audio/models (per_thousand_characters, in credits) and in GET /v1/usage/prices (speech[0].per_thousand_characters). Each response gives its price in x-aderra-billed-micro (micro-credits, charged when the stream completes) and how many billable characters it counted in x-aderra-characters. If any chunk fails on Aderra’s side, the request fails and nothing is charged; see Streaming for what a disconnect costs. Listing voices and models is free.