elevenlabs Voices API

openapi: 3.2.0
info:
  title: ElevenLabs Voices API
  description: The ElevenLabs Voices API provides management capabilities for the voice library, including listing, retrieving, creating, editing, and deleting voices. Developers can access a library of over 5,000 pre-built voices and manage their own custom voices. The API also supports voice design, voice settings management, and voice library sharing.
  version: '1.0'
  contact:
    name: ElevenLabs Support
    url: https://help.elevenlabs.io
  termsOfService: https://elevenlabs.io/terms-of-service
servers:
- url: https://api.elevenlabs.io
  description: Production Server
security:
- apiKeyAuth: []
tags:
- name: Voices
  description: Endpoints for managing voices including listing, creating, editing, and deleting voices in the library.
paths:
  /v1/voices:
    get:
      operationId: listVoices
      summary: List voices
      description: Returns a list of all available voices, including pre-built and custom voices. Each voice includes metadata such as name, labels, description, and available settings.
      tags:
      - Voices
      parameters:
      - name: show_legacy
        in: query
        required: false
        description: Whether to include legacy voices in the response.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: List of voices retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceListResponse'
        '401':
          description: Unauthorized - invalid or missing API key
  /v1/voices/{voice_id}:
    get:
      operationId: getVoice
      summary: Get voice
      description: Returns metadata about a specific voice including its settings, samples, labels, and description.
      tags:
      - Voices
      parameters:
      - $ref: '#/components/parameters/voiceId'
      - name: with_settings
        in: query
        required: false
        description: Whether to include the voice settings in the response.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Voice details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Voice'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Voice not found
    delete:
      operationId: deleteVoice
      summary: Delete voice
      description: Deletes a voice from the user's voice library. This action is irreversible and removes all associated samples and settings.
      tags:
      - Voices
      parameters:
      - $ref: '#/components/parameters/voiceId'
      responses:
        '200':
          description: Voice deleted successfully
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Voice not found
  /v1/voices/{voice_id}/edit:
    post:
      operationId: editVoice
      summary: Edit voice
      description: Updates the metadata and settings for an existing voice. Allows changing the name, description, labels, and uploading new samples.
      tags:
      - Voices
      parameters:
      - $ref: '#/components/parameters/voiceId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EditVoiceRequest'
      responses:
        '200':
          description: Voice updated successfully
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Voice not found
  /v1/voices/add:
    post:
      operationId: addVoice
      summary: Add voice
      description: Creates a new voice from uploaded audio samples. The voice can then be used with text-to-speech and other audio generation endpoints.
      tags:
      - Voices
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AddVoiceRequest'
      responses:
        '200':
          description: Voice created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddVoiceResponse'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing API key
components:
  schemas:
    VoiceSample:
      type: object
      properties:
        sample_id:
          type: string
          description: Unique identifier for the audio sample.
        file_name:
          type: string
          description: Original file name of the uploaded sample.
        mime_type:
          type: string
          description: MIME type of the audio sample.
        size_bytes:
          type: integer
          description: Size of the audio sample in bytes.
    Voice:
      type: object
      properties:
        voice_id:
          type: string
          description: Unique identifier for the voice.
        name:
          type: string
          description: Display name of the voice.
        category:
          type: string
          description: Category of the voice such as premade, cloned, or designed.
          enum:
          - premade
          - cloned
          - designed
          - professional
        labels:
          type: object
          description: Key-value labels describing voice characteristics such as accent, age, gender, and use case.
          additionalProperties:
            type: string
        description:
          type: string
          description: Human-readable description of the voice.
        preview_url:
          type: string
          format: uri
          description: URL to a preview audio sample of the voice.
        settings:
          $ref: '#/components/schemas/VoiceSettings'
        samples:
          type: array
          description: Audio samples associated with the voice.
          items:
            $ref: '#/components/schemas/VoiceSample'
    AddVoiceRequest:
      type: object
      required:
      - name
      - files
      properties:
        name:
          type: string
          description: The name for the new voice.
        description:
          type: string
          description: Description of the voice.
        labels:
          type: string
          description: JSON string of key-value label pairs for the voice.
        files:
          type: array
          description: Audio sample files for creating the voice. Minimum 60 seconds of clean audio recommended.
          items:
            type: string
            format: binary
    EditVoiceRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The new name for the voice.
        description:
          type: string
          description: Updated description of the voice.
        labels:
          type: string
          description: JSON string of key-value label pairs for the voice.
        files:
          type: array
          description: New audio sample files to add to the voice.
          items:
            type: string
            format: binary
    AddVoiceResponse:
      type: object
      properties:
        voice_id:
          type: string
          description: The identifier of the newly created or added voice.
    VoiceSettings:
      type: object
      properties:
        stability:
          type: number
          description: Controls the stability of the generated voice output.
          minimum: 0
          maximum: 1
        similarity_boost:
          type: number
          description: Controls how closely the AI adheres to the original voice.
          minimum: 0
          maximum: 1
        style:
          type: number
          description: Controls the expressiveness and style of the speech delivery.
          minimum: 0
          maximum: 1
          default: 0
        use_speaker_boost:
          type: boolean
          description: Enables speaker boost to increase voice clarity.
          default: true
    VoiceListResponse:
      type: object
      properties:
        voices:
          type: array
          description: List of available voices.
          items:
            $ref: '#/components/schemas/Voice'
  parameters:
    voiceId:
      name: voice_id
      in: path
      required: true
      description: The identifier of the voice.
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: xi-api-key
      description: ElevenLabs API key passed in the xi-api-key header for authentication.
externalDocs:
  description: ElevenLabs Voices API Documentation
  url: https://elevenlabs.io/docs/api-reference/voices/get