openapi: 3.0.1
info:
  title: Smallest AI Waves API
  description: >-
    The Smallest AI Waves text-to-speech API. Generates natural speech from text
    using the Lightning family of models with sub-100ms latency, streams audio in
    realtime over Server-Sent Events, lists prebuilt voices, and clones custom
    voices from short audio samples. All endpoints are authenticated with a Bearer
    API key. The realtime bidirectional WebSocket transport for streaming TTS is
    modeled in the companion AsyncAPI document
    (asyncapi/smallest-ai-asyncapi.yml).
  termsOfService: https://smallest.ai/terms
  contact:
    name: Smallest AI Support
    url: https://smallest.ai/
    email: support@smallest.ai
  version: '1.0'
servers:
  - url: https://waves-api.smallest.ai/api/v1
    description: Waves production API
security:
  - bearerAuth: []
tags:
  - name: Text to Speech
    description: Synthesize speech from text.
  - name: Streaming
    description: Realtime streaming speech synthesis.
  - name: Voices
    description: List prebuilt voices and manage cloned voices.
paths:
  /lightning/get_speech:
    post:
      operationId: getSpeech
      tags:
        - Text to Speech
      summary: Synthesize speech from text.
      description: >-
        Generates an audio file from the input text using a Lightning TTS model
        and the specified voice. Returns the synthesized audio as a binary
        response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetSpeechRequest'
      responses:
        '200':
          description: Synthesized audio.
          content:
            audio/wav:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /lightning-v2/get_speech/stream:
    post:
      operationId: streamSpeech
      tags:
        - Streaming
      summary: Stream synthesized speech (SSE).
      description: >-
        Streams synthesized speech in realtime using the Lightning v2 model. The
        response is an HTTP Server-Sent Events stream whose `data:` frames each
        carry a JSON object containing a base64-encoded audio chunk; a final
        frame signals completion. The same path is also available as a
        bidirectional WebSocket (wss) endpoint - see the AsyncAPI document.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StreamSpeechRequest'
      responses:
        '200':
          description: Server-Sent Events stream of base64 audio chunks.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AudioStreamChunk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /lightning/get_voices:
    get:
      operationId: getVoices
      tags:
        - Voices
      summary: List available voices.
      description: >-
        Returns the catalog of prebuilt voices available for synthesis, including
        each voice's identifier and metadata such as language, gender, and accent.
      responses:
        '200':
          description: A list of available voices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /lightning/add_voice:
    post:
      operationId: addVoice
      tags:
        - Voices
      summary: Clone a voice.
      description: >-
        Creates a new cloned voice from a short reference audio sample. The
        resulting voice identifier can be used as the `voice_id` in synthesis
        requests.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AddVoiceRequest'
      responses:
        '200':
          description: The created cloned voice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Voice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /lightning/get_cloned_voices:
    get:
      operationId: getClonedVoices
      tags:
        - Voices
      summary: List cloned voices.
      description: Returns the voices that the authenticated account has cloned.
      responses:
        '200':
          description: A list of cloned voices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /lightning/delete_voice/{voiceId}:
    delete:
      operationId: deleteVoice
      tags:
        - Voices
      summary: Delete a cloned voice.
      description: Permanently deletes a previously cloned voice owned by the account.
      parameters:
        - name: voiceId
          in: path
          required: true
          description: Identifier of the cloned voice to delete.
          schema:
            type: string
      responses:
        '200':
          description: The voice was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: The voice was not found.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Pass your Waves API key as a Bearer token in the Authorization header:
        `Authorization: Bearer <SMALLEST_API_KEY>`.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request body failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests; the account rate limit was exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    GetSpeechRequest:
      type: object
      required:
        - text
        - voice_id
      properties:
        text:
          type: string
          description: The text to convert to speech.
          example: Modern problems require modern solutions.
        voice_id:
          type: string
          description: Identifier of the voice to synthesize with.
          example: meher
        model:
          type: string
          description: The Lightning TTS model pool to use.
          default: lightning
          example: lightning-v2
        sample_rate:
          type: integer
          description: Output audio sample rate in Hz.
          default: 24000
          example: 24000
        speed:
          type: number
          format: float
          description: Speech rate multiplier; 1.0 is normal speed.
          default: 1.0
          minimum: 0.5
          maximum: 2.0
        language:
          type: string
          description: Language code for synthesis.
          default: en
          example: en
        output_format:
          type: string
          description: Encoding of the returned audio.
          default: wav
          enum:
            - wav
            - pcm
            - mp3
        add_wav_header:
          type: boolean
          description: >-
            Whether to prepend a WAV header to the returned audio. Set false to
            receive raw PCM.
          default: true
    StreamSpeechRequest:
      type: object
      required:
        - text
        - voice_id
      properties:
        text:
          type: string
          description: The text to stream as speech.
        voice_id:
          type: string
          description: Identifier of the voice to synthesize with.
          example: meher
        model:
          type: string
          description: The Lightning streaming model pool.
          default: lightning-v2
        sample_rate:
          type: integer
          description: Output audio sample rate in Hz.
          default: 24000
        speed:
          type: number
          format: float
          description: Speech rate multiplier; 1.0 is normal speed.
          default: 1.0
        language:
          type: string
          description: Language code for synthesis.
          default: en
    AudioStreamChunk:
      type: object
      description: >-
        JSON payload carried in each SSE `data:` frame. Frames carry a base64
        audio chunk until a final frame sets `done` to true.
      properties:
        audio:
          type: string
          format: byte
          description: Base64-encoded raw PCM audio chunk.
        done:
          type: boolean
          description: True on the final frame to indicate the stream has completed.
    AddVoiceRequest:
      type: object
      required:
        - displayName
        - file
      properties:
        displayName:
          type: string
          description: Human-readable name for the cloned voice.
          example: My Brand Voice
        file:
          type: string
          format: binary
          description: Reference audio sample (e.g. WAV/MP3) to clone the voice from.
    Voice:
      type: object
      properties:
        voiceId:
          type: string
          description: Unique identifier used as `voice_id` in synthesis requests.
        displayName:
          type: string
          description: Human-readable voice name.
        language:
          type: string
          description: Primary language of the voice.
        gender:
          type: string
          description: Voice gender, when available.
        accent:
          type: string
          description: Voice accent, when available.
        tags:
          type: array
          description: Descriptive tags for the voice.
          items:
            type: string
    VoiceList:
      type: object
      properties:
        voices:
          type: array
          items:
            $ref: '#/components/schemas/Voice'
    DeleteResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
    Error:
      type: object
      properties:
        status:
          type: string
          description: Error status indicator.
        message:
          type: string
          description: Human-readable error message.
        error:
          type: string
          description: Error code or detail, when present.