openapi: 3.0.3
info:
  title: Kits AI Stem Splitter Vocal Separation API
  version: v1
  description: 'The Kits AI API (operated by Arpeggi Labs) provides studio-quality AI music and audio tools as asynchronous inference jobs: voice conversion, vocal separation, stem splitting, and voice-model blending, plus a catalog of royalty-free artist voice models. All create endpoints enqueue a job and return its status; poll the corresponding fetch endpoint for the signed output file URLs. This specification was generated by API Evangelist from the published Kits AI documentation (https://docs.kits.ai/); the provider lists an openapi.json in its llms.txt but the file was not retrievable at generation time.'
  contact:
    name: Kits AI Support
    url: https://help.kits.ai/
  x-generated-by: api-evangelist-enrichment
  x-source: https://docs.kits.ai/api-reference
servers:
- url: https://arpeggi.io/api/kits/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Vocal Separation
  description: Isolate vocals from a mixed audio track.
paths:
  /vocal-separations:
    post:
      tags:
      - Vocal Separation
      operationId: createVocalSeparation
      summary: Create a new vocal separation job
      description: Creates a vocal separation job and adds it to the separator queue. All requests must be made as multipart form requests.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - inputFile
              properties:
                inputFile:
                  type: string
                  format: binary
                  description: Input audio. Supports wav, webm, mp3 or flac. Max 50MB.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeparationJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      tags:
      - Vocal Separation
      operationId: listVocalSeparations
      summary: Fetch vocal separation jobs
      description: Returns a paginated list of vocal separation jobs.
      parameters:
      - $ref: '#/components/parameters/Order'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSeparationJobs'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /vocal-separations/{id}:
    get:
      tags:
      - Vocal Separation
      operationId: getVocalSeparation
      summary: Fetch a vocal separation job by ID
      description: Returns a single vocal separation job by id.
      parameters:
      - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeparationJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    JobId:
      name: id
      in: path
      required: true
      schema:
        type: integer
    PerPage:
      name: perPage
      in: query
      description: Page size (default 10).
      schema:
        type: integer
        default: 10
    Page:
      name: page
      in: query
      description: Page offset (default 1).
      schema:
        type: integer
        default: 1
    Order:
      name: order
      in: query
      description: Sort order, asc (default) or desc.
      schema:
        type: string
        enum:
        - asc
        - desc
        default: asc
  schemas:
    PaginatedSeparationJobs:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SeparationJob'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        perPage:
          type: integer
        currentPage:
          type: integer
        lastPage:
          type: integer
        firstPage:
          type: integer
        firstPageUrl:
          type: string
        lastPageUrl:
          type: string
        nextPageUrl:
          type: string
          nullable: true
        previousPageUrl:
          type: string
          nullable: true
    SeparationJob:
      type: object
      description: A vocal separation or stem splitter job.
      properties:
        id:
          type: integer
        createdAt:
          type: string
        type:
          type: string
          enum:
          - separate
        status:
          type: string
          enum:
          - running
          - success
          - error
          - cancelled
        jobStartTime:
          type: string
          nullable: true
        jobEndTime:
          type: string
          nullable: true
        vocalAudioFileUrl:
          type: string
          nullable: true
        lossyVocalAudioFileUrl:
          type: string
          nullable: true
        backingAudioFileUrl:
          type: string
          nullable: true
          deprecated: true
          description: DEPRECATED. Use stemFileUrls or lossyStemFileUrls with instrument "backing" instead.
        stemFileUrls:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/StemFile'
        lossyStemFileUrls:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/StemFile'
    StemFile:
      type: object
      properties:
        instrument:
          type: string
        url:
          type: string
  responses:
    Forbidden:
      description: Attempted to fetch a resource that does not belong to the requesting user.
      content:
        text/plain:
          schema:
            type: string
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        text/plain:
          schema:
            type: string
    Unauthorized:
      description: Authentication was not provided or was invalid.
      content:
        text/plain:
          schema:
            type: string
    UnprocessableEntity:
      description: Request body or query params are invalid.
      content:
        text/plain:
          schema:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key issued from the Kits AI API access page (https://app.kits.ai/api-access), sent as `Authorization: Bearer <api-key>`.'