Audio formats

Choose the format with response_format. The default is mp3, which every player and browser plays.

`response_format`	Content-Type	Audio	Characters per request
`mp3` (default)	`audio/mpeg`	Compressed	4,096
`wav`	`audio/wav`	16-bit, mono, 24 kHz, with a WAV header	4,096
`pcm`	`audio/pcm`	Raw 16-bit signed little-endian, mono, 24 kHz, no header (as in OpenAI)	4,096
`aac`	`audio/mp4`	AAC in an MP4 (M4A) file	About 900 (one chunk)
`opus`	`audio/opus`	Compressed	About 900 (one chunk)
`flac`	`audio/flac`	Lossless	About 900 (one chunk)

Any other value is refused with 400 unsupported_format. The format does not change the price.

Which one to use

mp3 for files to store, download or play in a browser. It is small, plays everywhere, and takes the longest text.
pcm to play audio as it arrives in your own code, or to feed it into another audio pipeline: there is no header or container to parse, so every byte is audio.
wav when a tool needs an uncompressed file it can open.
aac, opus and flac when your platform needs exactly that format, for short text only.

Long text and formats

Text longer than 900 billable characters is spoken in chunks and joined into one file (Streaming and long text). mp3, wav and pcm can be joined; aac, opus and flac cannot, so in those formats the whole text must fit in one chunk, and longer text is refused with 400 input_too_long_for_format. For long text, ask for mp3, wav or pcm, and convert afterwards if you need another format.

Ask for wav

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": "Daniel",
       "input": "Hello from Aderra.", "response_format": "wav"}' \
  --output hello.wav

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

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

A wav is streamed, so its header can’t know the final length: its RIFF and data sizes are set to the maximum, meaning “until the end of the file”, the usual convention for streaming WAV. Most players and libraries accept it. If a tool needs exact sizes, rewrite the header once the file is complete, or ask for pcm and add your own header, as below.

Ask for pcm

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": "Daniel",
       "input": "Hello from Aderra.", "response_format": "pcm"}' \
  --output hello.pcm

import wave

audio = client.audio.speech.create(
    model="aderra-voice-1",
    voice="Daniel",
    input="Hello from Aderra.",
    response_format="pcm",
)
pcm = audio.read()

# Wrap the raw samples in a WAV file with exact sizes.
with wave.open("hello.wav", "wb") as f:
    f.setnchannels(1)       # mono
    f.setsampwidth(2)       # 16-bit
    f.setframerate(24000)   # 24 kHz
    f.writeframes(pcm)

const audio = await client.audio.speech.create({
  model: 'aderra-voice-1',
  voice: 'Daniel',
  input: 'Hello from Aderra.',
  response_format: 'pcm',
});
// 16-bit signed little-endian samples, mono, 24,000 a second
const pcm = Buffer.from(await audio.arrayBuffer());
console.log(`${pcm.length / 2 / 24000} seconds`);

Play raw pcm

A pcm file has no header, so tell the player what it holds: 16-bit signed little-endian (s16le) at 24,000 Hz. Mono is the default for raw audio, so no channel option is needed:

ffplay -f s16le -ar 24000 -autoexit hello.pcm

To convert it to a file any player opens:

ffmpeg -f s16le -ar 24000 -ac 1 -i hello.pcm hello.wav

GET /v1/audio/models gives each format’s content_type and max_characters, and sample_rate, channels and bits_per_sample for pcm and wav, under data[0].response_formats.