curl --request POST \
--url https://api.pyai.com/v1/voice/design \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "<string>",
"candidates": 3,
"sample_text": "<string>",
"language": "en",
"attributes": {
"gender": "<string>",
"age": "<string>",
"accent": "<string>",
"pace": 123,
"energy": 123
}
}
'import requests
url = "https://api.pyai.com/v1/voice/design"
payload = {
"prompt": "<string>",
"candidates": 3,
"sample_text": "<string>",
"language": "en",
"attributes": {
"gender": "<string>",
"age": "<string>",
"accent": "<string>",
"pace": 123,
"energy": 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({
prompt: '<string>',
candidates: 3,
sample_text: '<string>',
language: 'en',
attributes: {
gender: '<string>',
age: '<string>',
accent: '<string>',
pace: 123,
energy: 123
}
})
};
fetch('https://api.pyai.com/v1/voice/design', 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/voice/design",
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([
'prompt' => '<string>',
'candidates' => 3,
'sample_text' => '<string>',
'language' => 'en',
'attributes' => [
'gender' => '<string>',
'age' => '<string>',
'accent' => '<string>',
'pace' => 123,
'energy' => 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/voice/design"
payload := strings.NewReader("{\n \"prompt\": \"<string>\",\n \"candidates\": 3,\n \"sample_text\": \"<string>\",\n \"language\": \"en\",\n \"attributes\": {\n \"gender\": \"<string>\",\n \"age\": \"<string>\",\n \"accent\": \"<string>\",\n \"pace\": 123,\n \"energy\": 123\n }\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/voice/design")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"<string>\",\n \"candidates\": 3,\n \"sample_text\": \"<string>\",\n \"language\": \"en\",\n \"attributes\": {\n \"gender\": \"<string>\",\n \"age\": \"<string>\",\n \"accent\": \"<string>\",\n \"pace\": 123,\n \"energy\": 123\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pyai.com/v1/voice/design")
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 \"prompt\": \"<string>\",\n \"candidates\": 3,\n \"sample_text\": \"<string>\",\n \"language\": \"en\",\n \"attributes\": {\n \"gender\": \"<string>\",\n \"age\": \"<string>\",\n \"accent\": \"<string>\",\n \"pace\": 123,\n \"energy\": 123\n }\n}"
response = http.request(request)
puts response.read_body{
"design_id": "dsn_a1b2c3",
"status": "queued",
"candidates": 3,
"estimated_seconds": 25
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}Design a voice from a prompt
Generate a brand-new synthetic voice from a text description (distinct from cloning, which copies a real person). Async: returns 202 with a design_id; poll GET /v1/voice/design/{id} for candidate previews, then POST /v1/voice/design/{id}/save to keep one. Send a stable Idempotency-Key when retrying create: the same organization and key receive the original response without another job or billable unit. Requires the speak:design scope.
curl --request POST \
--url https://api.pyai.com/v1/voice/design \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "<string>",
"candidates": 3,
"sample_text": "<string>",
"language": "en",
"attributes": {
"gender": "<string>",
"age": "<string>",
"accent": "<string>",
"pace": 123,
"energy": 123
}
}
'import requests
url = "https://api.pyai.com/v1/voice/design"
payload = {
"prompt": "<string>",
"candidates": 3,
"sample_text": "<string>",
"language": "en",
"attributes": {
"gender": "<string>",
"age": "<string>",
"accent": "<string>",
"pace": 123,
"energy": 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({
prompt: '<string>',
candidates: 3,
sample_text: '<string>',
language: 'en',
attributes: {
gender: '<string>',
age: '<string>',
accent: '<string>',
pace: 123,
energy: 123
}
})
};
fetch('https://api.pyai.com/v1/voice/design', 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/voice/design",
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([
'prompt' => '<string>',
'candidates' => 3,
'sample_text' => '<string>',
'language' => 'en',
'attributes' => [
'gender' => '<string>',
'age' => '<string>',
'accent' => '<string>',
'pace' => 123,
'energy' => 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/voice/design"
payload := strings.NewReader("{\n \"prompt\": \"<string>\",\n \"candidates\": 3,\n \"sample_text\": \"<string>\",\n \"language\": \"en\",\n \"attributes\": {\n \"gender\": \"<string>\",\n \"age\": \"<string>\",\n \"accent\": \"<string>\",\n \"pace\": 123,\n \"energy\": 123\n }\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/voice/design")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"<string>\",\n \"candidates\": 3,\n \"sample_text\": \"<string>\",\n \"language\": \"en\",\n \"attributes\": {\n \"gender\": \"<string>\",\n \"age\": \"<string>\",\n \"accent\": \"<string>\",\n \"pace\": 123,\n \"energy\": 123\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pyai.com/v1/voice/design")
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 \"prompt\": \"<string>\",\n \"candidates\": 3,\n \"sample_text\": \"<string>\",\n \"language\": \"en\",\n \"attributes\": {\n \"gender\": \"<string>\",\n \"age\": \"<string>\",\n \"accent\": \"<string>\",\n \"pace\": 123,\n \"energy\": 123\n }\n}"
response = http.request(request)
puts response.read_body{
"design_id": "dsn_a1b2c3",
"status": "queued",
"candidates": 3,
"estimated_seconds": 25
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}Authorizations
Use Authorization: Bearer pyai_live_... (or pyai_test_...).
Headers
Customer-stable retry token. Reuse it only for retries of the same create request.
1 - 255^[^\s]+$Body
Natural-language description of the voice.
How many candidate voices to generate.
1 <= x <= 4Optional line the previews speak.
Language spoken by the preview. Other languages are not supported for voice design.
en, zh, ja, ko, de, fr, ru, pt, es, it Optional structured hints folded into the prompt.
Show child attributes
Show child attributes