Skip to main content
POST
Save a Voice Design preview as a private voice
Choose a preview from outputs.audios of a successful Voice Design task. Use the API key that created the task. Put the full task ID (including audio:) in the path, and send the preview’s candidateId and your chosen voice_name in the body.
Save before the task’s mediaExpiresAt. The voice keeps the original design prompt as its description and remains available after the previews expire. Saving uses one private voice slot with no separate save fee. On 201 with status: "active", use the returned voiceId for speech or dialogue with any active key in the workspace. On 202, poll the returned statusUrl. Repeating a save without an Idempotency-Key can occupy another slot; see retrying a request.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

Scoped to the workspace and creation operation. Without this header each submission is independent and can occupy another slot. To retry safely, reuse the same key and input. Changing the input under the same key returns 409.

Required string length: 1 - 128
Pattern: ^[!-~]{1,128}$

Path Parameters

generationId
string
required

ID of a successful Voice Design task created by this API key.

Body

application/json
candidateId
enum<string>
required

The selected preview's candidateId from outputs.audios.

Available options:
candidate-1,
candidate-2,
candidate-3
voice_name
string
required

Name to use for the saved voice.

Required string length: 1 - 100

Response

Saved voice or idempotent replay. Use for generation when active.

name
string
required
kind
enum<string>
required
Available options:
clone,
design
status
enum<string>
required
Available options:
creating,
reconciling,
active,
verificationRequired,
failed,
deleting,
deleted
models
string[]
required
operationId
string<uuid>

Creation tracking ID returned while pending.

statusUrl
string

Relative URL for polling a pending creation with the workspace API key.

id
string

Same as voiceId once the voice has an ID.

voiceId
string

Same value as id. Use for speech and dialogue when active.

message
string

Optional provider explanation on a failed or reconciling private voice. Use status to determine the outcome.