> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gengen.farm/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Design v3

> Design three voice previews from a description and audition text.

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.

```bash theme={"dark"}
curl https://gengen.farm/v1/audio/voice-designs \
  -H "Authorization: Bearer $GENGEN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "eleven_ttv_v3",
    "prompt": "A warm, clear adult narrator with a calm delivery and a neutral English accent.",
    "controls": {
      "auditionText": "Welcome to our quiet garden. Take a moment to breathe, enjoy the morning light, and imagine a fresh beginning."
    }
  }'
```

1. On HTTP 202, [poll the returned task ID](https://docs.gengen.farm/api-reference/elevenlabs/get-generation.md) with the same API key, or set `webhookEndpointId` in the request for a [completion callback](https://docs.gengen.farm/api-reference/elevenlabs/create-webhook.md). 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](https://docs.gengen.farm/api-reference/elevenlabs/save-candidate.md) to obtain a `voiceId`.

The audition text is billed once for all three previews. For an [estimate](https://docs.gengen.farm/api-reference/elevenlabs/estimate-voice-design.md), send the same body before submitting. Without an `Idempotency-Key`, another submission starts a separately billable audition; see [retrying a request](https://docs.gengen.farm/api-reference/elevenlabs/overview.md#retrying-a-request).


## OpenAPI

````yaml openapi/audio.yaml POST /audio/voice-designs
openapi: 3.1.0
info:
  title: GENGEN Audio API
  version: 1.0.0
  description: >-
    Speech, dialogue, voice design, workspace voices, realtime sessions and
    completion webhooks.
servers:
  - url: https://gengen.farm/api/gengen/v1
security:
  - bearerAuth: []
paths:
  /audio/voice-designs:
    post:
      tags:
        - Voices
      summary: Design voice previews
      description: >-
        Create an asynchronous audition with three MP3 previews from one voice
        description.
      operationId: audio-create-voice-design
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            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.
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[!-~]{1,128}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoiceDesignRequest'
      responses:
        '202':
          description: >-
            Accepted task or existing task for this idempotency key. Poll until
            settlement and delivery complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioTask'
        default:
          description: >-
            Request failed, including invalid input (400), invalid credentials
            (401/403), insufficient balance (402), idempotency conflict (409),
            admission limit (429), or unavailable service (503).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    VoiceDesignRequest:
      type: object
      additionalProperties: false
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          enum:
            - eleven_ttv_v3
        mode:
          type: string
          enum:
            - voice_design
          default: voice_design
        prompt:
          type: string
          minLength: 20
          maxLength: 1000
          description: >-
            Voice description, measured in Unicode code points after trimming
            surrounding whitespace.
        controls:
          type: object
          additionalProperties: false
          properties:
            auditionText:
              type: string
              minLength: 100
              maxLength: 1000
              description: >-
                Optional audition text, measured in Unicode code points after
                trimming. Omit to generate text automatically with a maximum
                1000-character reservation.
            outputFormat:
              type: string
              enum:
                - mp3_44100_128
              default: mp3_44100_128
        providerOptions:
          type: object
          additionalProperties: false
          required:
            - elevenlabs
          properties:
            elevenlabs:
              type: object
              additionalProperties: false
              properties:
                seed:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: >-
                    Seed for generating voice previews. Reuse it with the same
                    inputs to reproduce the voice.
                shouldEnhance:
                  type: boolean
                  default: true
                  description: Enhance the voice description before generating previews.
        webhookEndpointId:
          type: string
          format: uuid
          description: Registered completion webhook owned by the same API key.
      example:
        model: eleven_ttv_v3
        prompt: >-
          A warm, clear adult narrator with a calm delivery and a neutral
          English accent.
        controls:
          auditionText: >-
            Welcome to our quiet garden. Take a moment to breathe, enjoy the
            morning light, and imagine a fresh beginning.
    AudioTask:
      type: object
      properties:
        id:
          type: string
        model:
          type: string
          enum:
            - eleven_v3
            - eleven_v4
            - eleven_v4_turbo
            - eleven_ttv_v3
        status:
          type: string
          enum:
            - queued
            - processing
            - succeeded
            - failed
            - cancelled
        outputs:
          type: object
          properties:
            audios:
              type: array
              items:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                  candidateId:
                    type: string
                    description: >-
                      Voice Design only. Task-local candidate identity; cannot
                      be used as a speech voice ID.
                    enum:
                      - candidate-1
                      - candidate-2
                      - candidate-3
                  durationSeconds:
                    type: number
                    description: Duration of a Voice Design preview in seconds.
                  contentType:
                    type: string
                  bytes:
                    type: number
                  expiresAt:
                    type: string
                    format: date-time
                required: []
          required: []
        auditionText:
          type: string
          description: >-
            Actual text returned by a successful Voice Design task, available
            until retention expires.
        usage:
          $ref: '#/components/schemas/Usage'
        error: 9c588c0e-0639-46c9-ab7b-287f973ebc46
        mediaExpiresAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            End of media retention, when set. Save a Voice Design candidate
            before this time.
        phase:
          type: string
          enum:
            - reconciliationRequired
          description: The result is being checked. Poll this task for its outcome.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - model
        - status
        - outputs
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
      required:
        - error
    Usage:
      type: object
      properties:
        inputCharacters:
          type: number
        billableCharacters:
          type: number
        chargedUsd:
          type: number
      required: []
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.