Text To Speech (Speak)

POST /v1/audio/speech

​

Speaker diarization and speech generation

​

Synthesize your first clip

pip install pyai-sdk
# or
npm install @pyai/sdk

curl https://api.pyai.com/v1/audio/speech \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pyai-speak",
    "input": "Your appointment is confirmed for Thursday at two.",
    "voice": "stock_dorit_en_us",
    "response_format": "wav"
  }' \
  --output confirmation.wav

import os
from pyai import PyAI

pyai = PyAI(api_key=os.environ["PYAI_API_KEY"])
audio = pyai.audio.speech(
    input="Your appointment is confirmed for Thursday at two.",
    voice="stock_dorit_en_us",
    response_format="wav",
)
open("confirmation.wav", "wb").write(audio)

import PyAI from "@pyai/sdk";
import { writeFile } from "node:fs/promises";

const pyai = new PyAI({ apiKey: process.env.PYAI_API_KEY! });
const audio = await pyai.audio.speech({
  input: "Your appointment is confirmed for Thursday at two.",
  voice: "stock_dorit_en_us",
  response_format: "wav",
});
await writeFile("confirmation.wav", Buffer.from(audio));

​

Choose a voice from the catalog

curl "https://api.pyai.com/v1/voices?language=en&source=stock" \
  -H "Authorization: Bearer $PYAI_API_KEY"

• voice_id is the canonical input.
• aliases are permanent convenience inputs on the advertised surfaces.
• available_on tells you whether the voice works on Speak, Omni, or both.
• synthesis_modes tells you which stream values the voice accepts. Every Speak voice accepts both; an empty list means the voice has no Speak surface at all.
• speak_emotions lists qualified emotion directions for this voice. An empty or absent list means directed emotion is unavailable.
• tier and pricing describe the customer-facing quality tier and its catalog treatment. Check the pricing page for current commercial terms.

​

Natural voices

• English en1 (canonical id stock_aria_en) works on Speak in both streaming and buffered modes. The same id is available on Omni. It is the only Natural-tier voice in the catalog today; the former Hindi Natural aliases hi5–hi8 are retired. Hindi is served by the Standard-tier voices, which work on both Speak and Omni.
• Check the pricing page for current voice-tier treatment.

​

Emotion direction

const { data: voices } = await pyai.voices.list();
const voice = voices.find((voice) => voice.speak_emotions?.includes("happy"));
if (!voice) throw new Error("No voice currently advertises happy delivery.");
const audio = await pyai.audio.speechStream({
  input: "Your appointment is confirmed for Thursday at two.",
  voice: voice.voice_id,
  emotion: "happy",
});

​

Streaming vs buffered delivery

• Use true when playback should start as bytes arrive.
• Use false when your client requires a complete body and Content-Length. Every catalog voice accepts both values, so the documented request above works for any voice_id you find in GET /v1/voices. Some voices (today: Hindi and a few es / fr / de rows) are served from a fleet that has no streaming lane. Those are rendered on the blocking lane whichever value you send, and the response says so with x-pyai-stream: buffered: same status, same body, same response_format, higher time-to-first-byte. Nothing to retry, nothing to branch on unless you are measuring TTFB.

​

Consume bytes as they arrive

const controller = new AbortController();
const response = await fetch("https://api.pyai.com/v1/audio/speech", {
  method: "POST",
  signal: controller.signal,
  headers: {
    Authorization: `Bearer ${process.env.PYAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "pyai-speak",
    input: "Your appointment is confirmed for Thursday at two.",
    voice: "stock_dorit_en_us",
    response_format: "pcm",
    stream: true,
  }),
});

if (!response.ok || !response.body) throw new Error(`Speak failed: ${response.status}`);
console.info("effective delivery", response.headers.get("x-pyai-stream") ?? "incremental");

const reader = response.body.getReader();
try {
  for (;;) {
    const { done, value } = await reader.read();
    if (done) break;
    enqueuePcmForPlayback(value); // application-owned queue; returns immediately
  }
} catch (error) {
  // Some audio may already be audible. Record the partial result and use a
  // product-specific recovery policy instead of blindly retrying the sentence.
  handlePartialSynthesisFailure(error);
}

// On interruption: controller.abort(); clearQueuedAudio();

curl https://api.pyai.com/v1/audio/speech \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "This response is returned as one complete file.",
    "voice": "stock_dorit_en_us",
    "response_format": "mp3",
    "stream": false
  }' \
  --output complete.mp3

​

Input length

​

Output formats and sample rates

​

Stock, cloned, or designed

• Stock: select a row from GET /v1/voices; no enrollment required.
• Clone: enroll a voice you have explicit permission to use. See Clone.
• Design: create a new synthetic voice from a text description with /v1/voice/design, preview candidates, and save one into your voice library.

curl https://api.pyai.com/v1/voice/design \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: support-voice-v1" \
  -d '{
    "prompt": "A calm, clear support voice with measured pacing.",
    "candidates": 3,
    "sample_text": "Thanks for calling. How can I help?"
  }'

​

Compatibility and unsupported controls