Skip to main content
POST
Design voice previews
Submit a voice description (prompt, 20–1,000 characters) with model: "eleven_ttv_v3". To choose what the voice reads, supply 100–1,000 characters in controls.auditionText; omit it to generate audition text automatically.
  1. On HTTP 202, poll the returned task ID with the same API key, or set webhookEndpointId in the request for a completion callback. Auditions are asynchronous; streaming and WebSocket delivery are unavailable.
  2. On success, listen to the three MP3 previews in outputs.audios. Each has a candidateId valid only within this task. The response includes the actual auditionText.
  3. To use a preview for speech or dialogue, save that candidate to obtain a voiceId.
The audition text is billed once for all three previews. For an estimate, send the same body before submitting. Without an Idempotency-Key, another submission starts a separately billable audition; 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

Without this header each submission starts an independent, billable audition. To retry safely, use the original API key, Idempotency-Key and body. Changing the body under the same key returns 409.

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

Body

application/json
model
enum<string>
required
Available options:
eleven_ttv_v3
prompt
string
required

Voice description, measured in Unicode code points after trimming surrounding whitespace.

Required string length: 20 - 1000
mode
enum<string>
default:voice_design
Available options:
voice_design
controls
object
providerOptions
object
webhookEndpointId
string<uuid>

Registered completion webhook owned by the same API key.

Response

Accepted task or existing task for this idempotency key. Poll until settlement and delivery complete.

id
string
required
model
enum<string>
required
Available options:
eleven_v3,
eleven_v4,
eleven_v4_turbo,
eleven_ttv_v3
status
enum<string>
required
Available options:
queued,
processing,
succeeded,
failed,
cancelled
outputs
object
required
auditionText
string

Actual text returned by a successful Voice Design task, available until retention expires.

usage
object
error
any
mediaExpiresAt
string<date-time> | null

End of media retention, when set. Save a Voice Design candidate before this time.

phase
enum<string>

The result is being checked. Poll this task for its outcome.

Available options:
reconciliationRequired
createdAt
string<date-time>
updatedAt
string<date-time>