openapi: 3.2.0
info:
  title: ElevenLabs API Documentation Music Finetunes API
  description: This is the documentation for the ElevenLabs API. You can use this API to use our service programmatically, this is done by using your API key. You can find your API key in the dashboard at https://elevenlabs.io/app/settings/api-keys.
  version: '1.0'
tags:
- name: music-finetunes
  description: Create and manage music finetunes.
paths:
  /v1/music/finetunes:
    get:
      tags:
      - music-finetunes
      summary: Get Music Finetunes
      description: List music finetunes accessible to you (your own, workspace-shared, and ElevenLabs-curated), with optional filtering, sorting, and cursor pagination.
      operationId: get_finetunes
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Used for fetching the next page. Cursor is returned in the response.
          title: Cursor
        description: Used for fetching the next page. Cursor is returned in the response.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 150
          minimum: 1
          description: How many finetunes to return. Max 150, default 50.
          default: 50
          title: Page Size
        description: How many finetunes to return. Max 150, default 50.
      - name: visibility
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/FinetuneVisibility'
          - type: 'null'
          description: Filter by visibility. 'private' returns private finetunes; 'workspace' returns workspace-shared finetunes; 'public' returns public finetunes, which are currently ElevenLabs curated finetunes. Omit to return all accessible finetunes.
          title: Visibility
        description: Filter by visibility. 'private' returns private finetunes; 'workspace' returns workspace-shared finetunes; 'public' returns public finetunes, which are currently ElevenLabs curated finetunes. Omit to return all accessible finetunes.
      - name: created_by
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/FinetuneCreatedBy'
          - type: 'null'
          description: Filter by creator. 'self' returns finetunes you created; 'workspace' returns finetunes created by workspace teammates; 'elevenlabs' returns ElevenLabs curated finetunes. Omit to return finetunes from all creators.
          title: Created By
        description: Filter by creator. 'self' returns finetunes you created; 'workspace' returns finetunes created by workspace teammates; 'elevenlabs' returns ElevenLabs curated finetunes. Omit to return finetunes from all creators.
      - name: sort
        in: query
        required: false
        schema:
          enum:
          - created_at
          - name
          type: string
          description: Sort by field (created_at or name)
          default: created_at
          title: Sort
        description: Sort by field (created_at or name)
      - name: sort_direction
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          description: Sort direction (asc or desc)
          default: desc
          title: Sort Direction
        description: Sort direction (asc or desc)
      - name: xi-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
          title: Xi-Api-Key
        description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MusicFinetunePageResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - music
      - finetunes
      x-fern-sdk-method-name: list
    post:
      tags:
      - music-finetunes
      summary: Create Music Finetune
      description: Create a new music finetune
      operationId: create_finetune
      parameters:
      - name: xi-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
          title: Xi-Api-Key
        description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_Create_Music_Finetune_v1_music_finetunes_post'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MusicFinetuneResponseModel'
        '403':
          description: Missing permissions to manage music finetunes.
        '404':
          description: Finetune not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - music
      - finetunes
      x-fern-sdk-method-name: create
  /v1/music/finetunes/{finetune_id}:
    get:
      tags:
      - music-finetunes
      summary: Get Music Finetune
      description: Get a music finetune.
      operationId: get_finetune
      parameters:
      - name: finetune_id
        in: path
        required: true
        schema:
          type: string
          title: Finetune Id
      - name: xi-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
          title: Xi-Api-Key
        description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MusicFinetuneResponseModel'
        '403':
          description: Missing permissions to manage music finetunes.
        '404':
          description: Finetune not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - music
      - finetunes
      x-fern-sdk-method-name: get
    patch:
      tags:
      - music-finetunes
      summary: Update Music Finetune
      description: Update a music finetune.
      operationId: update_finetune
      parameters:
      - name: finetune_id
        in: path
        required: true
        schema:
          type: string
          title: Finetune Id
      - name: xi-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
          title: Xi-Api-Key
        description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMusicFinetuneRequestModel'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MusicFinetuneResponseModel'
        '403':
          description: Missing permissions to manage music finetunes.
        '404':
          description: Finetune not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - music
      - finetunes
      x-fern-sdk-method-name: update
    delete:
      tags:
      - music-finetunes
      summary: Delete Music Finetune
      description: Delete a music finetune
      operationId: delete_finetune
      parameters:
      - name: finetune_id
        in: path
        required: true
        schema:
          type: string
          title: Finetune Id
      - name: xi-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
          title: Xi-Api-Key
        description: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MusicFinetuneResponseModel'
        '403':
          description: Missing permissions to manage music finetunes.
        '404':
          description: Finetune not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - music
      - finetunes
      x-fern-sdk-method-name: delete
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MusicModelID:
      type: string
      enum:
      - music_v1
      - music_v2
      - music_v2_5
      title: MusicModelID
      x-fern-enum:
        music_v1:
          description: 'Deprecated: Deprecated.'
          deprecated: true
      default: music_v1
    MusicFinetuneResponseModel:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier of the finetune.
        name:
          type: string
          title: Name
          description: Name of the finetune.
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Tags associated with the finetune.
        primary_genre:
          anyOf:
          - type: string
          - type: 'null'
          title: Primary Genre
          description: Primary musical genre of the finetune.
        model_id:
          type: string
          title: Model Id
          description: The base music model the finetune was trained on.
          examples:
          - music_v1
          - music_v2
          - music_v2_5
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the finetune was created (UTC).
        visibility:
          $ref: '#/components/schemas/FinetuneVisibility'
          description: 'Who can access this finetune: `private` (only you), `workspace` (members of your workspace), `public` (ElevenLabs-curated, available to everyone).'
        created_by:
          $ref: '#/components/schemas/FinetuneCreatedBy'
          description: 'Who created the finetune: `self`, `workspace`, or `elevenlabs`.'
        status:
          $ref: '#/components/schemas/MusicFinetuneStatus'
          description: 'Training lifecycle status: pending, in_progress, completed, failed, and blocked.'
        training_progress:
          type: number
          title: Training Progress
          description: Training progress from 0.0 to 1.0.
        failure_reason:
          anyOf:
          - $ref: '#/components/schemas/MusicFinetuneFailureReason'
          - type: 'null'
          description: Reason the finetune failed or was blocked, if applicable.
      type: object
      required:
      - id
      - name
      - tags
      - model_id
      - created_at
      - visibility
      - created_by
      - status
      - training_progress
      title: MusicFinetuneResponseModel
    Body_Create_Music_Finetune_v1_music_finetunes_post:
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 5
          title: Name
          description: Name for the finetune (5-200 characters).
        primary_genre:
          type: string
          title: Primary Genre
          description: Primary musical genre of the finetune.
        files:
          items:
            type: string
            format: binary
          type: array
          maxItems: 50
          title: Files
          description: Audio files to train on.
          default: []
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Tags to associate with the finetune.
          default: []
        visibility:
          anyOf:
          - type: string
            enum:
            - private
            - workspace
          - type: 'null'
          title: Visibility
          description: Finetune visibility. Only 'private' and 'workspace' can be set.
        model_id:
          $ref: '#/components/schemas/MusicModelID'
          description: The model to create a finetune for.
          default: music_v1
      type: object
      required:
      - name
      - primary_genre
      title: Body_Create_Music_Finetune_v1_music_finetunes_post
    FinetuneCreatedBy:
      type: string
      enum:
      - self
      - workspace
      - elevenlabs
      title: FinetuneCreatedBy
    MusicFinetunePageResponseModel:
      properties:
        finetunes:
          items:
            $ref: '#/components/schemas/MusicFinetuneResponseModel'
          type: array
          title: Finetunes
          description: The finetunes in this page.
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Cursor to pass as `cursor` to fetch the next page; `null` when there are no more results.
        has_more:
          type: boolean
          title: Has More
          description: Whether more finetunes are available beyond this page.
      type: object
      required:
      - finetunes
      - next_cursor
      - has_more
      title: MusicFinetunePageResponseModel
    FinetuneVisibility:
      type: string
      enum:
      - private
      - workspace
      - public
      title: FinetuneVisibility
    UpdateMusicFinetuneRequestModel:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 200
            minLength: 5
          - type: 'null'
          title: Name
          description: Updated name for the finetune.
        tags:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 5
          - type: 'null'
          title: Tags
          description: Replacement set of tags.
        primary_genre:
          anyOf:
          - type: string
          - type: 'null'
          title: Primary Genre
          description: Updated primary musical genre.
        visibility:
          anyOf:
          - type: string
            enum:
            - private
            - workspace
          - type: 'null'
          title: Visibility
          description: Finetune visibility. Only 'private' and 'workspace' can be set.
      type: object
      title: UpdateMusicFinetuneRequestModel
    MusicFinetuneFailureReason:
      type: string
      enum:
      - audio_processing_failed
      - copyright_violation
      - training_failed
      title: MusicFinetuneFailureReason
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    MusicFinetuneStatus:
      type: string
      enum:
      - pending
      - in_progress
      - completed
      - failed
      - blocked
      title: MusicFinetuneStatus