Streaming and long text

Streaming

The audio is streamed as it is generated: the first audio arrives in about half a second, while a long text takes much longer to finish. Play or save it as it arrives instead of waiting for the whole file. Every request is streamed; there is nothing to turn on.

cURL

# curl writes the file as the audio arrives
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": "Reid", "input": "A long chapter..."}' \
  --output chapter.mp3

Python

with client.audio.speech.with_streaming_response.create(
    model="aderra-voice-1",
    voice="Reid",
    input="A long chapter...",
) as response:
    response.stream_to_file("chapter.mp3")

# Or handle the bytes yourself, for example to play them
with client.audio.speech.with_streaming_response.create(
    model="aderra-voice-1",
    voice="Reid",
    input="A long chapter...",
    response_format="pcm",
) as response:
    for chunk in response.iter_bytes():
        player.write(chunk)  # your audio output

Node

import fs from 'node:fs';

const response = await client.audio.speech.create({
  model: 'aderra-voice-1',
  voice: 'Reid',
  input: 'A long chapter...',
});

const file = fs.createWriteStream('chapter.mp3');
for await (const chunk of response.body) {
  file.write(chunk); // or send it on to a player
}
file.end();

To play the audio as it arrives, ask for pcm: every byte is a sample, 16-bit mono at 24 kHz, so you can hand chunks to an audio output as they come. See Audio formats.

What streaming changes

• Errors before the audio starts keep their status codes and JSON bodies (see Errors). Once audio is flowing, the status is already 200: a failure then shows as a truncated or aborted stream. Check that the stream ended normally before you treat the file as complete.
• Billing. The charge is made when the stream completes. If the stream ends early because of a failure on Aderra’s side, it is not charged. If your client disconnects mid-audio, it is charged, because the audio was generated.
• x-aderra-billed-micro arrives with the first bytes, so it is the price that is charged when the stream completes.
• A streamed wav has its RIFF and data sizes set to the maximum, meaning “until the end of the file”. See Audio formats.

Long text

input takes up to 4,096 billable characters. Aderra speaks it in chunks of up to 900 billable characters, split at sentence ends, and joins them into one file, streamed as each chunk is spoken. The x-aderra-chunks response header says how many chunks were spoken.

• A sentence longer than a chunk is cut between words; a word longer than a chunk is cut where it reaches the limit.
• aac, opus and flac files can’t be joined, so in those formats the text must fit in one chunk: longer text is refused with input_too_long_for_format. Use mp3, wav or pcm for long text.
• If any chunk fails on Aderra’s side, the request fails and nothing is charged.
• For more than 4,096 characters, split the text yourself and send several requests. Limits and quotas has a helper that does it.