indextts.openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Aviary worker — indextts",
    "description": "TTS worker for the **indextts** engine, speaking the Aviary unified contract.\n\n- **Voice modes**: reference_audio\n- **Languages**: zh, en\n- **Native sample rate**: 24000 Hz\n- **Formats**: wav, mp3\n\nSuccessful synthesis responses are **raw audio bytes** (`audio/wav` or `audio/mpeg`) with `X-Audio-Duration` (seconds) and `X-Sample-Rate` headers; errors are plain text. Generation parameters are engine-specific — read `GET /capabilities` for the parameter schema this worker accepts.",
    "version": "0.1.0"
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Health check",
        "description": "Any 2xx response means the model is loaded and the worker is ready to synthesize.",
        "operationId": "health__get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/capabilities": {
      "get": {
        "summary": "Engine capabilities",
        "description": "Voice modes, preset voices, generation parameter schema (name/type/min/max/default), languages, output formats, native sample rate, and chunking hints. The Aviary WebUI renders its generation form from this document.",
        "operationId": "capabilities_capabilities_get",
        "responses": {
          "200": {
            "description": "This engine's capabilities",
            "content": {
              "application/json": {
                "schema": {},
                "example": {
                  "engine": "indextts",
                  "voice_modes": [
                    "reference_audio"
                  ],
                  "voices": [],
                  "languages": [
                    "zh",
                    "en"
                  ],
                  "params": [
                    {
                      "name": "emotion",
                      "type": "enum",
                      "choices": [
                        "none",
                        "happy",
                        "angry",
                        "sad",
                        "afraid",
                        "disgusted",
                        "melancholic",
                        "surprised",
                        "calm"
                      ],
                      "default": "none",
                      "label": {
                        "en": "Emotion",
                        "fr": "Émotion",
                        "zh": "情绪"
                      }
                    },
                    {
                      "name": "emo_alpha",
                      "type": "float",
                      "min": 0.0,
                      "max": 1.0,
                      "default": 0.6,
                      "step": 0.05,
                      "label": {
                        "en": "Emotion strength",
                        "fr": "Intensité de l'émotion",
                        "zh": "情绪强度"
                      }
                    },
                    {
                      "name": "temperature",
                      "type": "float",
                      "min": 0.1,
                      "max": 1.5,
                      "default": 0.8,
                      "step": 0.05,
                      "label": {
                        "en": "Temperature",
                        "fr": "Température",
                        "zh": "温度"
                      }
                    },
                    {
                      "name": "speed",
                      "type": "float",
                      "min": 0.5,
                      "max": 2.0,
                      "default": 1.0,
                      "step": 0.05,
                      "label": {
                        "en": "Speed",
                        "fr": "Vitesse",
                        "zh": "语速"
                      }
                    },
                    {
                      "name": "seed",
                      "type": "int",
                      "label": "Seed"
                    }
                  ],
                  "formats": [
                    "wav",
                    "mp3"
                  ],
                  "sample_rate": 24000,
                  "max_chunk_chars": 0
                }
              }
            }
          }
        }
      }
    },
    "/v1/audio/speech": {
      "post": {
        "summary": "Synthesize speech (OpenAI-style)",
        "description": "JSON body: `input` (required, the text), `response_format` (`wav` default | `mp3`), `voice` (preset id, when supported), `control` (voice description, when supported), `seed`, plus any engine parameter from `/capabilities` — values may be sent as strings, they are coerced leniently.",
        "operationId": "speech_v1_audio_speech_post",
        "responses": {
          "200": {
            "description": "Raw audio bytes. Headers: X-Audio-Duration (seconds, float), X-Sample-Rate (Hz).",
            "content": {
              "application/json": {
                "schema": {}
              },
              "audio/wav": {},
              "audio/mpeg": {}
            }
          },
          "400": {
            "description": "Bad request (e.g. empty text)",
            "content": {
              "text/plain": {}
            }
          },
          "500": {
            "description": "Generation failed",
            "content": {
              "text/plain": {}
            }
          }
        }
      }
    },
    "/clone": {
      "post": {
        "summary": "Synthesize with a cloned voice",
        "description": "Multipart form: `text` (required), `reference_audio` (required file — the voice to clone), `prompt_text` (its transcript; strongly recommended, required by some engines), `response_format`, plus engine parameters as string form fields. Reference uploads are cached by content hash, so resending the same voice for every chunk of a long text is cheap.",
        "operationId": "clone_clone_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_clone_clone_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Raw audio bytes. Headers: X-Audio-Duration (seconds, float), X-Sample-Rate (Hz).",
            "content": {
              "application/json": {
                "schema": {}
              },
              "audio/wav": {},
              "audio/mpeg": {}
            }
          },
          "400": {
            "description": "Bad request (e.g. empty text)",
            "content": {
              "text/plain": {}
            }
          },
          "500": {
            "description": "Generation failed",
            "content": {
              "text/plain": {}
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Body_clone_clone_post": {
        "properties": {
          "text": {
            "type": "string",
            "title": "Text"
          },
          "response_format": {
            "type": "string",
            "title": "Response Format",
            "default": "wav"
          },
          "reference_audio": {
            "type": "string",
            "contentMediaType": "application/octet-stream",
            "title": "Reference Audio"
          },
          "prompt_text": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Prompt Text"
          }
        },
        "type": "object",
        "required": [
          "text",
          "reference_audio"
        ],
        "title": "Body_clone_clone_post"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    }
  }
}