> ## 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.

# Save a Voice Design candidate

Choose a preview from `outputs.audios` of a successful [Voice Design task](https://docs.gengen.farm/api-reference/elevenlabs/voice-designs.md). 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.

```bash theme={"dark"}
curl "https://gengen.farm/v1/audio/voice-designs/$GENERATION_ID/save" \
  -H "Authorization: Bearer $GENGEN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"candidateId":"candidate-2","voice_name":"Narrator"}'
```

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](https://docs.gengen.farm/api-reference/elevenlabs/overview.md#choose-a-voice) 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`](https://docs.gengen.farm/api-reference/elevenlabs/get-voice-operation). Repeating a save without an `Idempotency-Key` can occupy another slot; 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/{generationId}/save
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/{generationId}/save:
    post:
      tags:
        - Voices
      summary: Save a Voice Design preview as a private voice
      operationId: audio-save-design-candidate
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            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.
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[!-~]{1,128}$
        - name: generationId
          in: path
          required: true
          schema:
            type: string
          description: ID of a successful Voice Design task created by this API key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - candidateId
                - voice_name
              properties:
                candidateId:
                  type: string
                  enum:
                    - candidate-1
                    - candidate-2
                    - candidate-3
                  description: The selected preview's candidateId from outputs.audios.
                voice_name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Name to use for the saved voice.
      responses:
        '201':
          description: Saved voice or idempotent replay. Use for generation when active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateVoice'
        '202':
          description: Creation is pending confirmation. Poll the returned statusUrl.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PrivateVoice'
                  - type: object
                    required:
                      - operationId
                      - statusUrl
        '422':
          description: >-
            Read error.message for the rejection reason. Replaying the same
            keyed request returns that rejection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            For audio.voice_limit, free a private slot. For
            audio.provider_rate_limited, wait and retry with the original input
            and key if supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: >-
            Invalid request or authorization, changed idempotency input (409),
            expired candidate or removed voice (410), payload too large (413),
            provider rejection (422), full workspace (429), or service
            unavailable (503).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PrivateVoice:
      type: object
      required:
        - name
        - kind
        - status
        - models
      properties:
        operationId:
          type: string
          format: uuid
          description: Creation tracking ID returned while pending.
        statusUrl:
          type: string
          description: >-
            Relative URL for polling a pending creation with the workspace API
            key.
        id:
          type: string
          description: Same as voiceId once the voice has an ID.
        voiceId:
          type: string
          description: Same value as id. Use for speech and dialogue when active.
        name:
          type: string
        kind:
          type: string
          enum:
            - clone
            - design
        status:
          type: string
          enum:
            - creating
            - reconciling
            - active
            - verificationRequired
            - failed
            - deleting
            - deleted
        message:
          type: string
          description: >-
            Optional provider explanation on a failed or reconciling private
            voice. Use status to determine the outcome.
        models:
          type: array
          items:
            type: string
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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