Text to Speech

Choose a Model and Voice

Text to speech converts an input string into audio. Use it for narration, spoken responses, and audio playback in your application. Complete the quickstart first to set AUDIOLAB_API_KEY and AUDIOLAB_API_URL and verify your connection. Confirm that the key has audio.write access and your workspace has available credits.

Use tts/auto with voice: "auto" to let Router choose an eligible combination. To control the voice, select an exact model ID from the speech catalog and use a voice supported by that model.

Voice identifiers, languages, text limits, and output formats differ by provider. A voice ID from one provider cannot be assumed to work with another. Check the model’s capabilities before adding native options.

Generate and Save Audio

The following server-side example uses Node.js 22 or later, with no additional packages. Save it as speech.mjs after exporting the variables from the quickstart:

import { writeFile } from "node:fs/promises";

const response = await fetch(
  `${process.env.AUDIOLAB_API_URL}/v1/audio/speech`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AUDIOLAB_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "tts/auto",
      input: "Your next idea starts here.",
      voice: "auto",
      response_format: "mp3",
    }),
  },
);

const requestId = response.headers.get("x-request-id");
if (!response.ok) {
  throw new Error(`Speech failed (${response.status}, ${requestId}): ${await response.text()}`);
}

await writeFile("speech.mp3", Buffer.from(await response.arrayBuffer()));
console.log("Saved speech.mp3", { requestId });

Run the file and open the generated MP3:

node speech.mjs

The successful HTTP response is audio, not JSON. This example buffers the complete short response before saving it. For larger outputs, stream the response body to your application’s destination instead of keeping it all in memory.

Match the Output to Playback

Use mp3 for a convenient file in this example. Other formats depend on the selected model. If you request raw PCM, your player must know the sample rate, sample format, and channel count; raw audio has no file header to describe them.

Pass only options supported by the model. The normalized speed field and provider.options are not promises that every provider implements the same controls. The speech reference defines the request fields and validation rules.

The HTTP speech endpoint rejects Idempotency-Key. If a connection fails after generation begins, inspect the request before submitting another billable generation.

Stream Speech or Generate It in the Background

For incremental text input and audio output, use the speech WebSocket endpoint. Its session events differ from downloading the streamed HTTP response above. Connect from your backend and follow the selected model’s audio format and completion events.

Background generation is model-specific. Supported MiniMax async models require ?async=true and workspace audio storage. Retain the returned job ID and use Retrieve Speech to check progress and download the completed audio. Save the result before it expires; storage and privacy settings can make it unavailable.