KugelAudio Text to Speech API

openapi: 3.2.0
info:
  description: 'The public REST API of KugelAudio text to speech: synthesis, models, voices, pronunciation dictionaries, projects, and the ElevenLabs-compatible endpoints. Streaming over WebSocket (`/ws/tts`, `/ws/tts/stream`, `/ws/tts/multi`) is described in the API reference, not here. Guides and examples: https://docs.kugelaudio.com/api-reference/introduction'
  title: KugelAudio Text to Speech API
  version: v1
servers:
- description: Default, geo-routed
  url: https://api.kugelaudio.com
- description: Direct EU endpoint
  url: https://api.eu.kugelaudio.com
tags:
- externalDocs:
    url: https://docs.kugelaudio.com/api-reference/tts/generate
  name: Text To Speech
paths:
  /v1/tts/generate:
    post:
      description: 'Reference: https://docs.kugelaudio.com/api-reference/tts/generate'
      operationId: generate_v1_tts_generate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SynthesizeRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - BearerAuth: []
      - ApiKeyHeader: []
      summary: Generate
      tags:
      - Text To Speech
components:
  schemas:
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    SynthesizeRequest:
      additionalProperties: false
      description: One-shot synthesis request (REST and single-request WebSocket).
      properties:
        cfg_scale:
          default: 2
          description: Classifier-free guidance scale (clamped to 1.2–2.5)
          title: Cfg Scale
          type: number
        dictionary_ids:
          anyOf:
          - items:
              type: integer
            maxItems: 50
            type: array
          - type: 'null'
          description: Per-request dictionary selection. Omit for the default behavior (all active dictionaries of the project apply, filtered by language). An empty list disables dictionaries for this request. A list of dictionary IDs applies exactly those dictionaries — including inactive ones — bypassing the language filter.
          title: Dictionary Ids
        language:
          anyOf:
          - maxLength: 10
            type: string
          - type: 'null'
          description: Language code (e.g., 'en', 'de')
          title: Language
        max_new_tokens:
          default: 2048
          description: Maximum tokens to generate
          maximum: 2048
          minimum: 1
          title: Max New Tokens
          type: integer
        model_id:
          anyOf:
          - type: string
          - type: 'null'
          description: Model to use
          title: Model Id
        normalize:
          default: true
          description: Enable text normalization
          title: Normalize
          type: boolean
        output_format:
          anyOf:
          - type: string
          - type: 'null'
          description: Combined codec+rate token (e.g. 'pcm_8000', 'ulaw_8000', 'alaw_8000'). Opt-in; when set it is authoritative and must not contradict 'sample_rate'. Absent ⇒ legacy 'sample_rate' path (linear PCM16).
          title: Output Format
        project_id:
          anyOf:
          - type: integer
          - type: 'null'
          description: Project ID for custom dictionary lookup
          title: Project Id
        sample_rate:
          default: 24000
          description: Output sample rate in Hz
          title: Sample Rate
          type: integer
        speed:
          default: 1
          description: Playback speed multiplier (0.8 = slower, 1.2 = faster)
          maximum: 1.2
          minimum: 0.8
          title: Speed
          type: number
        temperature:
          anyOf:
          - maximum: 1
            minimum: 0
            type: number
          - type: 'null'
          description: Sampling variance. 0 = most stable, 1 = most variance. Omit to use the engine default.
          title: Temperature
        text:
          description: Text to synthesize
          maxLength: 10000
          minLength: 2
          title: Text
          type: string
        voice_id:
          anyOf:
          - type: integer
          - type: string
          - type: 'null'
          description: Voice handle or legacy numeric ID for cloning
          title: Voice Id
      required:
      - text
      title: SynthesizeRequest
      type: object
  securitySchemes:
    ApiKeyHeader:
      description: Your API key in the `X-API-Key` header.
      in: header
      name: X-API-Key
      type: apiKey
    BearerAuth:
      description: 'Your API key as `Authorization: Bearer YOUR_API_KEY`.'
      scheme: bearer
      type: http
    ElevenLabsApiKey:
      description: Your KugelAudio API key in the ElevenLabs `xi-api-key` header.
      in: header
      name: xi-api-key
      type: apiKey
externalDocs:
  url: https://docs.kugelaudio.com/api-reference/introduction
x-provenance:
  method: harvested
  publisher: KugelAudio
  source: https://docs.kugelaudio.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)