openapi: 3.1.0
info:
  title: ElevenLabs Audio Isolation Agents Voices API
  description: The ElevenLabs Audio Isolation API removes background noise from audio recordings, isolating vocal tracks from ambient sounds and interference. This is useful for cleaning up recordings, improving audio quality for podcasts and interviews, and preparing audio files for further processing such as voice cloning or transcription.
  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:
    AddVoiceResponse:
      type: object
      properties:
        voice_id:
          type: string
          description: The identifier of the newly created or added voice.
    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
    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'
    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.
    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'
    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
  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 Audio Isolation API Documentation
  url: https://elevenlabs.io/docs/api-reference/audio-isolation/audio-isolation