curl --request POST \
--url https://api.pyai.com/v1/audio/speech \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": "<string>",
"model": "pyai-speak",
"voice": "<string>",
"response_format": "wav",
"sample_rate": 28000,
"speed": 123,
"stream": true,
"speech_session_id": "<string>",
"seed": 123,
"temperature": 123
}
'import requests
url = "https://api.pyai.com/v1/audio/speech"
payload = {
"input": "<string>",
"model": "pyai-speak",
"voice": "<string>",
"response_format": "wav",
"sample_rate": 28000,
"speed": 123,
"stream": True,
"speech_session_id": "<string>",
"seed": 123,
"temperature": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
input: '<string>',
model: 'pyai-speak',
voice: '<string>',
response_format: 'wav',
sample_rate: 28000,
speed: 123,
stream: true,
speech_session_id: '<string>',
seed: 123,
temperature: 123
})
};
fetch('https://api.pyai.com/v1/audio/speech', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pyai.com/v1/audio/speech",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'input' => '<string>',
'model' => 'pyai-speak',
'voice' => '<string>',
'response_format' => 'wav',
'sample_rate' => 28000,
'speed' => 123,
'stream' => true,
'speech_session_id' => '<string>',
'seed' => 123,
'temperature' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pyai.com/v1/audio/speech"
payload := strings.NewReader("{\n \"input\": \"<string>\",\n \"model\": \"pyai-speak\",\n \"voice\": \"<string>\",\n \"response_format\": \"wav\",\n \"sample_rate\": 28000,\n \"speed\": 123,\n \"stream\": true,\n \"speech_session_id\": \"<string>\",\n \"seed\": 123,\n \"temperature\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.pyai.com/v1/audio/speech")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"input\": \"<string>\",\n \"model\": \"pyai-speak\",\n \"voice\": \"<string>\",\n \"response_format\": \"wav\",\n \"sample_rate\": 28000,\n \"speed\": 123,\n \"stream\": true,\n \"speech_session_id\": \"<string>\",\n \"seed\": 123,\n \"temperature\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pyai.com/v1/audio/speech")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"input\": \"<string>\",\n \"model\": \"pyai-speak\",\n \"voice\": \"<string>\",\n \"response_format\": \"wav\",\n \"sample_rate\": 28000,\n \"speed\": 123,\n \"stream\": true,\n \"speech_session_id\": \"<string>\",\n \"seed\": 123,\n \"temperature\": 123\n}"
response = http.request(request)
puts response.read_body"<string>"{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}Synthesize speech
OpenAI-compatible text-to-speech. Returns audio bytes. The serving adapter defaults to incremental delivery from the streaming lane. Set stream: false when you require a complete buffered body with Content-Length. Requires the speak:synthesize scope.
curl --request POST \
--url https://api.pyai.com/v1/audio/speech \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": "<string>",
"model": "pyai-speak",
"voice": "<string>",
"response_format": "wav",
"sample_rate": 28000,
"speed": 123,
"stream": true,
"speech_session_id": "<string>",
"seed": 123,
"temperature": 123
}
'import requests
url = "https://api.pyai.com/v1/audio/speech"
payload = {
"input": "<string>",
"model": "pyai-speak",
"voice": "<string>",
"response_format": "wav",
"sample_rate": 28000,
"speed": 123,
"stream": True,
"speech_session_id": "<string>",
"seed": 123,
"temperature": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
input: '<string>',
model: 'pyai-speak',
voice: '<string>',
response_format: 'wav',
sample_rate: 28000,
speed: 123,
stream: true,
speech_session_id: '<string>',
seed: 123,
temperature: 123
})
};
fetch('https://api.pyai.com/v1/audio/speech', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pyai.com/v1/audio/speech",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'input' => '<string>',
'model' => 'pyai-speak',
'voice' => '<string>',
'response_format' => 'wav',
'sample_rate' => 28000,
'speed' => 123,
'stream' => true,
'speech_session_id' => '<string>',
'seed' => 123,
'temperature' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pyai.com/v1/audio/speech"
payload := strings.NewReader("{\n \"input\": \"<string>\",\n \"model\": \"pyai-speak\",\n \"voice\": \"<string>\",\n \"response_format\": \"wav\",\n \"sample_rate\": 28000,\n \"speed\": 123,\n \"stream\": true,\n \"speech_session_id\": \"<string>\",\n \"seed\": 123,\n \"temperature\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.pyai.com/v1/audio/speech")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"input\": \"<string>\",\n \"model\": \"pyai-speak\",\n \"voice\": \"<string>\",\n \"response_format\": \"wav\",\n \"sample_rate\": 28000,\n \"speed\": 123,\n \"stream\": true,\n \"speech_session_id\": \"<string>\",\n \"seed\": 123,\n \"temperature\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pyai.com/v1/audio/speech")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"input\": \"<string>\",\n \"model\": \"pyai-speak\",\n \"voice\": \"<string>\",\n \"response_format\": \"wav\",\n \"sample_rate\": 28000,\n \"speed\": 123,\n \"stream\": true,\n \"speech_session_id\": \"<string>\",\n \"seed\": 123,\n \"temperature\": 123\n}"
response = http.request(request)
puts response.read_body"<string>"{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}Authorizations
Body
A stock voice id from GET /v1/voices (e.g. stock_dorit_en_us) or a cloned voice id (e.g. voice_abc) created via /v1/voice/clones. Omit to use the platform default voice (stock_dorit_en_us). For drop-in OpenAI compatibility, the preset names alloy, echo, fable, onyx, nova, and shimmer are also accepted and map to PyAI stock voices.
Output audio format. The response Content-Type varies by format (audio/wav, audio/mpeg, audio/ogg, audio/aac, audio/flac, audio/pcm, audio/basic). pcm returns raw, headerless 16-bit little-endian mono samples (no container) at sample_rate, the format voice-agent orchestrators (e.g. Vapi custom-voice, LiveKit/Pipecat) feed directly into their pipelines. g711_ulaw/g711_alaw return raw, headerless G.711 telephony audio at a fixed 8 kHz mono (for Twilio/Plivo/FreeSWITCH); sample_rate does not apply and is rejected unless set to 8000.
wav, mp3, opus, aac, flac, pcm, g711_ulaw, g711_alaw Optional output sample rate in Hz (8000-48000), e.g. 8000/16000 for telephony or 24000 for wideband. Omit to use the native 24 kHz. Most relevant with response_format: pcm. Does not apply to g711_ulaw/g711_alaw, which are always 8 kHz mono (a conflicting value is rejected).
8000 <= x <= 48000Optional named delivery direction, rendered in the same voice in streaming or buffered mode. Inspect the voice's speak_emotions in GET /v1/voices; an empty or absent list means directed emotion is unavailable. Unsupported voice/emotion combinations return 400 unsupported_parameter. neutral preserves ordinary delivery on every voice. An unavailable emotional rendering returns an error instead of a neutral replacement. Intensity and free-form instructions are not supported on Speak; supplying either returns 400 unsupported_parameter.
neutral, happy, sad, angry, fearful, surprised Use incremental audio delivery. The default is true: the adapter forwards validated chunks as they arrive. Set false to use the blocking lane and receive a complete buffered body with a Content-Length. Every catalog voice accepts both values. A voice whose serving fleet has no streaming lane is rendered on the blocking lane and the response carries x-pyai-stream: buffered — same body, same format, higher time-to-first-byte.
Call-stable voice recovery (enabled organizations and supported stock voices only). Send the same unique call ID and voice on every utterance and retry. The engine is selected before the first audio response and cannot change for this call. Sessions last at most 24 hours; never reuse a call ID. A backup voice may differ from the requested stock voice, but stays fixed for the whole call. Recovery audio is buffered and reports x-pyai-speech-profile: recovery. Omit this field for ordinary synthesis without external voice recovery. Directed emotions and custom/cloned voices are not eligible.
1 - 128Response
Audio bytes. Bytes are delivered incrementally by default; stream: false returns a complete buffered body. The Content-Type varies by response_format: audio/wav (wav), audio/mpeg (mp3), audio/ogg (opus), audio/aac (aac), audio/flac (flac), audio/pcm (pcm, raw/headerless), and audio/basic (g711_ulaw/g711_alaw, raw/headerless G.711 at 8 kHz mono).
The response is of type file.