{
    "openapi": "3.1.0",
    "info": {
        "title": "AutoTTS Agent API",
        "version": "1.0.1",
        "description": "Fast, intelligent Google Gemini Text-to-Speech API designed for AI Agents. Dynamic per-request voice and style switching supported."
    },
    "servers": [
        {
            "url": "https://audio.bulmano.com",
            "description": "Production AutoTTS Server"
        }
    ],
    "paths": {
        "/api.php": {
            "post": {
                "summary": "Synthesize Text to Speech (WAV)",
                "description": "Converts text into high-fidelity studio speech using Google Gemini 3.8 TTS. AI agents can dynamically customize the voice and style for every single request.",
                "operationId": "synthesizeSpeech",
                "security": [
                    {
                        "BearerAuth": []
                    },
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "text"
                                ],
                                "properties": {
                                    "text": {
                                        "type": "string",
                                        "description": "The verbatim text to synthesize into speech.",
                                        "example": "\u0645\u0631\u062d\u0628\u0627\u064b \u0628\u0643\u0645 \u0641\u064a \u062e\u062f\u0645\u0629 \u062a\u062d\u0648\u064a\u0644 \u0627\u0644\u0646\u0635 \u0625\u0644\u0649 \u0635\u0648\u062a."
                                    },
                                    "voice": {
                                        "type": "string",
                                        "enum": [
                                            "Despina",
                                            "Zephyr",
                                            "Puck",
                                            "Charon",
                                            "Kore",
                                            "Fenrir",
                                            "Leda",
                                            "Orus",
                                            "Aoede",
                                            "Callirrhoe",
                                            "Autonoe",
                                            "Enceladus",
                                            "Iapetus",
                                            "Umbriel",
                                            "Algieba",
                                            "Erinome",
                                            "Algenib",
                                            "Rasalgethi",
                                            "Laomedeia",
                                            "Achernar",
                                            "Alnilam",
                                            "Schedar",
                                            "Gacrux",
                                            "Pulcherrima",
                                            "Achird",
                                            "Zubenelgenubi",
                                            "Vindemiatrix",
                                            "Sadachbia",
                                            "Sadaltager",
                                            "Sulafat"
                                        ],
                                        "default": "Despina",
                                        "description": "Voice to speak with. Can be customized per request."
                                    },
                                    "character": {
                                        "type": "string",
                                        "description": "Alias for voice."
                                    },
                                    "style": {
                                        "type": "string",
                                        "description": "Turn-level vocal style/emotion/prosody (e.g. \"warm, conversational\", \"calm documentary\", \"energetic\", \"serious\"). Can be customized per request.",
                                        "example": "warm, confident, conversational"
                                    },
                                    "speaking_style": {
                                        "type": "string",
                                        "description": "Alias for style."
                                    },
                                    "model": {
                                        "type": "string",
                                        "enum": [
                                            "auto",
                                            "lite",
                                            "full"
                                        ],
                                        "default": "auto",
                                        "description": "Model tier: auto (tries flash-lite first, fallback to flash), lite (flash-lite-tts), full (flash-tts)."
                                    },
                                    "response": {
                                        "type": "string",
                                        "enum": [
                                            "json",
                                            "wav"
                                        ],
                                        "default": "json",
                                        "description": "Response format: \"json\" returns audio metadata and URLs; \"wav\" streams the raw binary audio/wav directly."
                                    },
                                    "filename": {
                                        "type": "string",
                                        "default": "audio",
                                        "description": "Custom filename prefix for generated WAV file."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful TTS synthesis",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "audio": {
                                            "type": "object",
                                            "properties": {
                                                "url": {
                                                    "type": "string",
                                                    "format": "uri"
                                                },
                                                "download_url": {
                                                    "type": "string",
                                                    "format": "uri"
                                                },
                                                "voice": {
                                                    "type": "string",
                                                    "example": "Despina"
                                                },
                                                "style": {
                                                    "type": "string",
                                                    "example": "warm, confident, conversational"
                                                },
                                                "model": {
                                                    "type": "string",
                                                    "example": "gemini-3.8-flash-lite-tts"
                                                },
                                                "duration_seconds": {
                                                    "type": "number",
                                                    "example": 4.25
                                                },
                                                "key_label": {
                                                    "type": "string",
                                                    "example": "Key 001"
                                                }
                                            }
                                        }
                                    }
                                }
                            },
                            "audio/wav": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid request parameters"
                    },
                    "401": {
                        "description": "Unauthorized - Invalid or missing API token"
                    },
                    "429": {
                        "description": "Rate limit encountered / Keys exhausted"
                    },
                    "500": {
                        "description": "Server error during speech synthesis"
                    }
                }
            }
        },
        "/api.php?action=health": {
            "get": {
                "summary": "Service Health and Key Pool Status",
                "operationId": "getHealth",
                "responses": {
                    "200": {
                        "description": "Current service health metrics",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "version": {
                                            "type": "string",
                                            "example": "1.0.1"
                                        },
                                        "total_keys": {
                                            "type": "integer",
                                            "example": 210
                                        },
                                        "usable": {
                                            "type": "integer",
                                            "example": 38
                                        },
                                        "working": {
                                            "type": "integer",
                                            "example": 12
                                        },
                                        "ready": {
                                            "type": "integer",
                                            "example": 8
                                        },
                                        "candidate": {
                                            "type": "integer",
                                            "example": 18
                                        },
                                        "cooldown": {
                                            "type": "integer",
                                            "example": 120
                                        },
                                        "rate_limited": {
                                            "type": "integer",
                                            "example": 120
                                        },
                                        "project_denied": {
                                            "type": "integer",
                                            "example": 17
                                        },
                                        "key_blocked": {
                                            "type": "integer",
                                            "example": 2
                                        },
                                        "invalid": {
                                            "type": "integer",
                                            "example": 1
                                        },
                                        "api_disabled": {
                                            "type": "integer",
                                            "example": 0
                                        },
                                        "forbidden": {
                                            "type": "integer",
                                            "example": 0
                                        },
                                        "server_location_unsupported": {
                                            "type": "integer",
                                            "example": 0
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api.php?action=voices": {
            "get": {
                "summary": "List Supported Voices",
                "operationId": "getVoices",
                "responses": {
                    "200": {
                        "description": "List of prebuilt studio voices",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        },
                                        "default_voice": {
                                            "type": "string",
                                            "example": "Despina"
                                        },
                                        "voices": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "name": {
                                                        "type": "string"
                                                    },
                                                    "gender": {
                                                        "type": "string"
                                                    },
                                                    "description": {
                                                        "type": "string"
                                                    },
                                                    "is_default": {
                                                        "type": "boolean"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "BearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Pass token via `Authorization: Bearer <TOKEN>` header"
            },
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-AutoTTS-Key",
                "description": "Pass token via `X-AutoTTS-Key: <TOKEN>` header"
            }
        }
    }
}