Skip to main content
POST
Design a voice from a prompt

Authorizations

Authorization
string
header
required

Use Authorization: Bearer pyai_live_... (or pyai_test_...).

Headers

Idempotency-Key
string

Customer-stable retry token. Reuse it only for retries of the same create request.

Required string length: 1 - 255
Pattern: ^[^\s]+$

Body

application/json
prompt
string
required

Natural-language description of the voice.

candidates
integer
default:3

How many candidate voices to generate.

Required range: 1 <= x <= 4
sample_text
string

Optional line the previews speak.

language
enum<string>
default:en

Language spoken by the preview. Other languages are not supported for voice design.

Available options:
en,
zh,
ja,
ko,
de,
fr,
ru,
pt,
es,
it
attributes
object

Optional structured hints folded into the prompt.

Response

Design job accepted

design_id
string
Example:

"dsn_a1b2c3"

status
string
Example:

"queued"

candidates
integer
Example:

3

estimated_seconds
integer
Example:

25