openapi: 3.0.1
info:
  title: Waves Voice Cloning API
  description: 'Unified voice cloning API. Create a voice clone in a single call by

    uploading a short audio sample. Defaults to the latest supported model

    (`lightning-v3.1`). Replaces the legacy two-step upload + create flow and

    the model-specific `/waves/v1/lightning-large/add_voice` endpoint.

    '
  version: 1.0.0
servers:
- url: https://api.smallest.ai
  description: Waves API server
  x-fern-server-name: waves
paths:
  /waves/v1/voice-cloning:
    post:
      tags:
      - Voice Cloning
      summary: Create a voice clone
      description: 'Create an instant voice clone in a single call. Defaults to `lightning-v3.1`.

        '
      operationId: createVoiceClone
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - displayName
              - file
              properties:
                displayName:
                  type: string
                  minLength: 1
                  maxLength: 500
                  description: Human-readable name for the voice clone.
                  example: my-custom-voice
                file:
                  type: string
                  format: binary
                  description: 'Audio file to clone from. Supported MIME types:

                    `audio/mpeg`, `audio/mpeg-3`, `audio/wav`, `audio/wave`,

                    `audio/webm`, `video/webm`, `audio/mp4`, `video/mp4`.

                    Maximum size: 5 MB.

                    '
                description:
                  type: string
                  description: Optional longer description for the voice clone.
                accent:
                  type: string
                  description: Optional accent tag (e.g. "general", "indian").
                tags:
                  type: string
                  description: 'Optional comma-separated list of tags. Server splits on

                    commas and trims whitespace (`"en, tone-test"` → `["en", "tone-test"]`).

                    '
                  example: english,friendly
                language:
                  type: string
                  description: 'Primary language the clone will be used for. Optional, but

                    **strongly recommended** — set it to the language of your

                    reference audio. The TTS request''s `language` should also

                    match this code; setting it now avoids silent language

                    mismatches at inference time.


                    Must be one of the languages supported by `lightning-v3.1`

                    (e.g. `en`, `hi`). The server validates and rejects

                    unsupported codes with a 400.

                    '
                  example: en
                model:
                  type: string
                  default: lightning-v3.1
                  enum:
                  - lightning-v3.1
                  description: 'Voice cloning model. Defaults to `lightning-v3.1`.

                    `lightning-v2` is accepted by the schema for historical

                    reasons but is deprecated — the server returns 400 with

                    `"Voice cloning for lightning-v2 is deprecated. Please use lightning-v3.1"`.

                    '
      responses:
        '200':
          description: Voice clone created. Includes pre-generated sample clips of the new voice.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Voice clone created successfully
                  data:
                    type: object
                    properties:
                      voiceId:
                        type: string
                        description: Unique voice ID. Pass this as `voice_id` in TTS requests.
                        example: voice_dLP5T67Qw7
                      displayName:
                        type: string
                      model:
                        type: string
                        description: Internal model document for the cloned voice.
                      status:
                        type: string
                        enum:
                        - pending
                        - processing
                        - completed
                        - failed
                      language:
                        type: string
                      audioFileNames:
                        type: array
                        items:
                          type: string
                      createdAt:
                        type: string
                        format: date-time
                      organizationId:
                        type: string
                      samples:
                        type: array
                        description: Pre-generated sample audio clips in the cloned voice.
                        items:
                          type: object
                          properties:
                            text:
                              type: string
                              description: Text that was synthesized.
                            audioUrl:
                              type: string
                              description: Signed URL to the generated sample audio.
        '400':
          description: 'Validation error. Common causes: no file provided, invalid MIME type,

            file too large, clone limit exceeded, invalid language, or

            `model=lightning-v2` (deprecated).

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message.
                    example: clone limit exceeded, consider upgrading
        '401':
          description: Unauthorized — missing or invalid API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Server error. The `error_code` field may be populated for known failure modes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  error_code:
                    type: string
                    enum:
                    - voice_clone_timeout
                    - voice_clone_error
                    description: Present when a known failure mode occurred.
    get:
      tags:
      - Voice Cloning
      summary: List voice clones
      description: 'Retrieve all voice clones in your organization.

        '
      operationId: listVoiceClones
      security:
      - BearerAuth: []
      responses:
        '200':
          description: List of voice clones.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        voiceId:
                          type: string
                          example: voice_dLP5T67Qw7
                        displayName:
                          type: string
                        description:
                          type: string
                        accent:
                          type: string
                        tags:
                          type: array
                          items:
                            type: string
                        language:
                          type: string
                        status:
                          type: string
                          enum:
                          - pending
                          - processing
                          - completed
                          - failed
                        cloningType:
                          type: string
                          enum:
                          - instant
                          - professional
                        modelIds:
                          type: array
                          description: 'Models this clone is compatible with. `lightning-v3.1`

                            is the current default. Older entries may list

                            `lightning-large`.

                            '
                          items:
                            type: string
                        createdAt:
                          type: string
                          format: date-time
        '401':
          description: Unauthorized.
        '500':
          description: Server error.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'API key passed as `Authorization: Bearer <SMALLEST_API_KEY>`.'