openapi: 3.2.0
info:
  description: The LocalAI Rest API.
  title: LocalAI Voice Profiles API
  contact:
    name: LocalAI
    url: https://localai.io
  license:
    name: MIT
    url: https://raw.githubusercontent.com/mudler/LocalAI/master/LICENSE
  version: 2.0.0
servers:
- url: /
tags:
- name: voice-profiles
paths:
  /api/voice-profiles:
    get:
      description: List saved voice-cloning references without exposing filesystem paths.
      tags:
      - voice-profiles
      summary: List voice profiles
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/localai.VoiceProfileListResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schema.ErrorResponse'
    post:
      description: Save a consent-confirmed PCM WAV reference clip and exact transcript for voice cloning. Admin-only.
      tags:
      - voice-profiles
      summary: Create a voice profile
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voiceprofile.Profile'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schema.ErrorResponse'
        '413':
          description: Request Entity Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schema.ErrorResponse'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Display name
                description:
                  type: string
                  description: Optional description
                language:
                  type: string
                  description: Optional language tag
                transcript:
                  type: string
                  description: Exact transcript of the reference clip
                consent_confirmed:
                  type: boolean
                  description: Confirms authorization to clone the voice
                audio:
                  type: string
                  description: 16-bit PCM WAV, preferably mono 24 kHz, 1-120 seconds, up to 50 MiB
                  format: binary
              required:
              - name
              - transcript
              - consent_confirmed
              - audio
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Display name
                description:
                  type: string
                  description: Optional description
                language:
                  type: string
                  description: Optional language tag
                transcript:
                  type: string
                  description: Exact transcript of the reference clip
                consent_confirmed:
                  type: boolean
                  description: Confirms authorization to clone the voice
                audio:
                  type: string
                  description: 16-bit PCM WAV, preferably mono 24 kHz, 1-120 seconds, up to 50 MiB
                  format: binary
              required:
              - name
              - transcript
              - consent_confirmed
              - audio
  /api/voice-profiles/{id}:
    delete:
      description: Permanently remove a saved voice-cloning profile. Admin-only.
      tags:
      - voice-profiles
      summary: Delete a voice profile
      parameters:
      - description: Voice profile UUID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schema.ErrorResponse'
  /api/voice-profiles/{id}/audio:
    get:
      description: Stream the saved reference WAV for an authenticated TTS user.
      tags:
      - voice-profiles
      summary: Preview voice profile audio
      parameters:
      - description: Voice profile UUID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            audio/x-wav:
              schema:
                type: string
        '404':
          description: Not Found
          content:
            audio/x-wav:
              schema:
                $ref: '#/components/schemas/schema.ErrorResponse'
components:
  schemas:
    voiceprofile.AudioMetadata:
      type: object
      properties:
        bit_depth:
          type: integer
        channels:
          type: integer
        duration_ms:
          type: integer
        mime_type:
          type: string
        sample_rate:
          type: integer
        size_bytes:
          type: integer
    schema.ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/schema.APIError'
    schema.APIError:
      type: object
      properties:
        code: {}
        message:
          type: string
        param:
          type: string
        type:
          type: string
    voiceprofile.Profile:
      type: object
      properties:
        audio:
          $ref: '#/components/schemas/voiceprofile.AudioMetadata'
        consent_confirmed_at:
          type: string
        created_at:
          type: string
        description:
          type: string
        id:
          type: string
        language:
          type: string
        name:
          type: string
        transcript:
          type: string
        updated_at:
          type: string
        voice:
          type: string
    localai.VoiceProfileListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/voiceprofile.Profile'
  securitySchemes:
    BearerAuth:
      type: apiKey
      name: Authorization
      in: header