Add read-aloud to a documentation site with the Speechify API

A listen button on documentation means users can hear a page while they scan it, commute, or follow a walkthrough. This tutorial adds one to a docs site with the Speechify API. It is framework-agnostic, with a concrete example you can copy. The runnable demo (demos/docs-read-aloud) is a zero-dependency Node server with a Listen button wired up.

The pattern is simple: the browser grabs the page text and posts it to a small backend endpoint; that endpoint calls Speechify with your key and hands the audio back. Your API key stays on the server and never reaches the browser. Choose batch when you want a downloadable file, streaming when you want it to start immediately.

Which endpoint do I need?

Two options, depending on how the audio should play.

• POST /v1/audio/speech returns one JSON response with the complete audio, base64-encoded. Good for a downloadable clip or a cached listen button.
• POST /v1/audio/stream returns audio in chunks. Better when you want playback to start before the whole page finishes generating.

For a docs read-aloud button, batch is simplest: generate the file and point the player at it.

How do I send the page text?

Pull the article text from the page, strip navigation and boilerplate so you only send content, and post it to your own endpoint. The synthesis call happens on the server, so the API key is never shipped to the browser.

Browser — the Listen button posts the page text to your endpoint and plays what comes back:

async function readAloud(text) {
  const res = await fetch("/api/speak", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text }),
  });
  const clip = await res.blob();
  new Audio(URL.createObjectURL(clip)).play();
}

Server — the endpoint holds the key and synthesizes with the @speechify/api SDK, then returns the audio bytes:

import { SpeechifyClient } from "@speechify/api";

const client = new SpeechifyClient({ token: process.env.SPEECHIFY_API_KEY });

// POST /api/speak  ->  { text }
const response = await client.audio.speech({
  input: text,
  voice_id: "geffen_32",
  model: "simba-3.2",
  audio_format: "mp3",
});
const audio = Buffer.from(response.audio_data, "base64");
// send `audio` back to the browser as the response body

That’s the whole relay: button → your endpoint → Speechify → audio back. The runnable demo wires exactly this with a zero-config Node server.

How do I keep the page scannable?

Keep the button small and top-of-page. Playback is an add-on, not the focus. Cache the generated file for static pages so repeat visits do not call the API again.

How do I handle long pages?

For long articles, streaming keeps the first sound fast. If you stick with batch, generate a single file for the whole page. Either way, send clean text and pick a presentable voice.

FAQ

Can I read any page aloud?

Yes, with the page’s text. Send the content you want spoken in the input.

Batch or streaming for read-aloud?

Batch is simpler for a button. Streaming starts faster on long pages.

Which model should I use?

simba-3.2 for English, simba-3.0 for multilingual docs.