{"openapi":"3.1.0","info":{"title":"沢渡雫 AI 声源 API","description":"GPT-SoVITS V2 同步文字转语音 API。支持中、日、英和自动语言识别，成功后返回 MinIO 私有对象的限时试听与下载链接。所有输出均为 AI 合成语音。","contact":{"name":"Shizuku Voice API"},"license":{"name":"使用前请确认模型、角色、作品、声优及训练素材相关权利与许可"},"version":"2.3.0"},"paths":{"/":{"get":{"summary":"Webui","operationId":"webui__get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/health":{"get":{"tags":["System"],"summary":"获取服务健康状态","description":"无需鉴权。返回模型加载状态、运行限制、实际设备和对象存储状态。","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Health Health Get"}}}}}}},"/api/metadata":{"get":{"tags":["Model"],"summary":"获取模型元数据","description":"返回支持的语言、参考风格、推荐风格和当前推理设备。","operationId":"metadata_api_metadata_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Metadata Api Metadata Get"}}}},"401":{"description":"Authorization 缺失或令牌无效。","content":{"application/json":{"example":{"detail":"missing or invalid Authorization header"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/device":{"post":{"tags":["Model"],"summary":"选择并预加载推理设备","description":"本地版本可切换 CPU/CUDA 与精度；当前公网实例锁定 CPU/FP32，因此请求值会被安全覆盖。","operationId":"select_device_api_device_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Select Device Api Device Post"}}}},"401":{"description":"Authorization 缺失或令牌无效。","content":{"application/json":{"example":{"detail":"missing or invalid Authorization header"}}}},"422":{"description":"请求参数不符合类型、枚举或取值范围。","content":{"application/json":{"examples":{"invalid_language":{"summary":"不支持的语言枚举","value":{"detail":[{"type":"literal_error","loc":["body","language"],"msg":"Input should be 'ja', 'zh', 'en' or 'auto'","input":"fr"}]}},"empty_text":{"summary":"文本为空","value":{"detail":"text cannot be empty"}}}}}},"503":{"description":"模型仍在加载，或请求的推理设备不可用。","content":{"application/json":{"example":{"detail":"model is still loading"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/tts":{"post":{"tags":["Speech"],"summary":"生成语音并返回下载链接","description":"同步生成 PCM 16-bit、单声道 WAV。成功后音频写入私有 MinIO 桶，响应返回限时 playback_url 和 download_url。建议生产集成使用 POST。","operationId":"tts_post_api_tts_post","security":[{"APIKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TTSRequest"}}}},"responses":{"200":{"description":"生成完成后的音频元数据与限时签名链接。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TTSResponse"}}}},"401":{"description":"Authorization 缺失或令牌无效。","content":{"application/json":{"example":{"detail":"missing or invalid Authorization header"}}}},"422":{"description":"请求参数不符合类型、枚举或取值范围。","content":{"application/json":{"examples":{"invalid_language":{"summary":"不支持的语言枚举","value":{"detail":[{"type":"literal_error","loc":["body","language"],"msg":"Input should be 'ja', 'zh', 'en' or 'auto'","input":"fr"}]}},"empty_text":{"summary":"文本为空","value":{"detail":"text cannot be empty"}}}}}},"429":{"description":"并发请求队列已满，请根据 Retry-After 稍后重试。","headers":{"Retry-After":{"description":"建议等待秒数。","schema":{"type":"integer","example":10}}},"content":{"application/json":{"example":{"detail":"service is busy; at most 6 requests may run or wait"}}}},"500":{"description":"语音合成过程中发生内部错误。","content":{"application/json":{"example":{"detail":"synthesis failed: internal inference error"}}}},"502":{"description":"音频已经生成，但上传对象存储失败。","content":{"application/json":{"example":{"detail":"audio was generated but object storage upload failed"}}}},"503":{"description":"模型仍在加载，或请求的推理设备不可用。","content":{"application/json":{"example":{"detail":"model is still loading"}}}}}},"get":{"tags":["Speech"],"summary":"通过查询参数生成语音","description":"与 POST /api/tts 等价的兼容接口。文本会出现在 URL 和访问日志中，不建议在生产环境使用。","operationId":"tts_get_api_tts_get","deprecated":true,"security":[{"APIKeyHeader":[]}],"parameters":[{"name":"text","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":300,"description":"要合成的文本。","title":"Text"},"description":"要合成的文本。"},{"name":"language","in":"query","required":false,"schema":{"enum":["ja","zh","en","auto"],"type":"string","description":"ja、zh、en 或 auto。","default":"ja","title":"Language"},"description":"ja、zh、en 或 auto。"},{"name":"style","in":"query","required":false,"schema":{"enum":["auto","neutral","gentle","sad","emotional","reflective"],"type":"string","description":"auto、neutral、gentle、sad、emotional 或 reflective。","default":"auto","title":"Style"},"description":"auto、neutral、gentle、sad、emotional 或 reflective。"},{"name":"speed","in":"query","required":false,"schema":{"type":"number","maximum":2.0,"minimum":0.5,"description":"语速倍率。","default":1.0,"title":"Speed"},"description":"语速倍率。"},{"name":"top_k","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"语义采样候选数量。","default":15,"title":"Top K"},"description":"语义采样候选数量。"},{"name":"top_p","in":"query","required":false,"schema":{"type":"number","maximum":1.0,"minimum":0.1,"description":"核采样阈值。","default":1.0,"title":"Top P"},"description":"核采样阈值。"},{"name":"temperature","in":"query","required":false,"schema":{"type":"number","maximum":1.5,"minimum":0.1,"description":"采样温度。","default":1.0,"title":"Temperature"},"description":"采样温度。"},{"name":"seed","in":"query","required":false,"schema":{"type":"integer","maximum":4294967295,"minimum":-1,"description":"随机种子；-1 表示随机。","default":-1,"title":"Seed"},"description":"随机种子；-1 表示随机。"},{"name":"device","in":"query","required":false,"schema":{"enum":["auto","cuda","cpu"],"type":"string","description":"推理设备。","default":"auto","title":"Device"},"description":"推理设备。"},{"name":"precision","in":"query","required":false,"schema":{"enum":["auto","fp16","fp32"],"type":"string","description":"计算精度。","default":"auto","title":"Precision"},"description":"计算精度。"}],"responses":{"200":{"description":"生成完成后的音频元数据与限时签名链接。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TTSResponse"}}}},"401":{"description":"Authorization 缺失或令牌无效。","content":{"application/json":{"example":{"detail":"missing or invalid Authorization header"}}}},"422":{"description":"请求参数不符合类型、枚举或取值范围。","content":{"application/json":{"examples":{"invalid_language":{"summary":"不支持的语言枚举","value":{"detail":[{"type":"literal_error","loc":["body","language"],"msg":"Input should be 'ja', 'zh', 'en' or 'auto'","input":"fr"}]}},"empty_text":{"summary":"文本为空","value":{"detail":"text cannot be empty"}}}}}},"429":{"description":"并发请求队列已满，请根据 Retry-After 稍后重试。","headers":{"Retry-After":{"description":"建议等待秒数。","schema":{"type":"integer","example":10}}},"content":{"application/json":{"example":{"detail":"service is busy; at most 6 requests may run or wait"}}}},"500":{"description":"语音合成过程中发生内部错误。","content":{"application/json":{"example":{"detail":"synthesis failed: internal inference error"}}}},"502":{"description":"音频已经生成，但上传对象存储失败。","content":{"application/json":{"example":{"detail":"audio was generated but object storage upload failed"}}}},"503":{"description":"模型仍在加载，或请求的推理设备不可用。","content":{"application/json":{"example":{"detail":"model is still loading"}}}}}}}},"components":{"schemas":{"DeviceRequest":{"properties":{"device":{"type":"string","enum":["auto","cuda","cpu"],"title":"Device","description":"目标设备：auto、cuda 或 cpu。","default":"auto"},"precision":{"type":"string","enum":["auto","fp16","fp32"],"title":"Precision","description":"目标精度：auto、fp16 或 fp32。","default":"auto"}},"type":"object","title":"DeviceRequest"},"TTSRequest":{"properties":{"text":{"type":"string","maxLength":300,"minLength":1,"title":"Text","description":"要合成的文本。公网实例当前最多允许 300 个 Unicode 字符；首尾空白会被移除。"},"language":{"type":"string","enum":["ja","zh","en","auto"],"title":"Language","description":"文本处理语言：ja=日语，zh=中文，en=英语，auto=逐段自动识别。语言不确定、文本混合或客户端不能保证标签正确时建议使用 auto。","default":"ja"},"style":{"type":"string","enum":["auto","neutral","gentle","sad","emotional","reflective"],"title":"Style","description":"参考语音风格：auto、neutral、gentle、sad、emotional、reflective。auto 会按语言选用推荐参考片段。","default":"auto"},"speed":{"type":"number","maximum":2.0,"minimum":0.5,"title":"Speed","description":"语速倍率。1.0 为原速，数值越小越慢，越大越快。","default":1.0},"top_k":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Top K","description":"语义采样候选数量。值越小越稳定，建议保持默认值 15。","default":15},"top_p":{"type":"number","maximum":1.0,"minimum":0.1,"title":"Top P","description":"核采样累计概率阈值。建议保持默认值 1.0。","default":1.0},"temperature":{"type":"number","maximum":1.5,"minimum":0.1,"title":"Temperature","description":"采样温度。越高变化越大；建议保持 0.8–1.0。","default":1.0},"seed":{"type":"integer","maximum":4294967295.0,"minimum":-1.0,"title":"Seed","description":"随机种子。-1 表示每次随机；固定非负整数可提高结果可复现性。","default":-1},"device":{"type":"string","enum":["auto","cuda","cpu"],"title":"Device","description":"推理设备：auto、cuda、cpu。当前公网实例锁定为 CPU，传入其他值也会按 CPU 执行。","default":"auto"},"precision":{"type":"string","enum":["auto","fp16","fp32"],"title":"Precision","description":"计算精度：auto、fp16、fp32。当前公网实例锁定为 CPU/FP32。","default":"auto"}},"type":"object","required":["text"],"title":"TTSRequest","examples":[{"device":"auto","language":"ja","precision":"auto","seed":-1,"speed":1.0,"style":"gentle","temperature":1.0,"text":"こんばんは。今日も一緒に帰ろうね。","top_k":15,"top_p":1.0}]},"TTSResponse":{"properties":{"status":{"type":"string","const":"completed","title":"Status","description":"任务状态；同步接口成功时固定为 completed。"},"generation_id":{"type":"string","title":"Generation Id","description":"本次生成的唯一 ID，可用于日志关联。"},"ai_generated":{"type":"boolean","title":"Ai Generated","description":"固定为 true，表示内容由 AI 合成。"},"model_id":{"type":"string","title":"Model Id","description":"实际使用的模型标识。"},"filename":{"type":"string","title":"Filename","description":"建议下载文件名。"},"content_type":{"type":"string","const":"audio/wav","title":"Content Type","description":"音频 MIME 类型。"},"size_bytes":{"type":"integer","minimum":1.0,"title":"Size Bytes","description":"WAV 文件字节数。"},"sample_rate":{"type":"integer","minimum":1.0,"title":"Sample Rate","description":"采样率，单位 Hz。"},"duration_seconds":{"type":"number","minimum":0.0,"title":"Duration Seconds","description":"生成音频时长，单位秒。"},"inference_seconds":{"type":"number","minimum":0.0,"title":"Inference Seconds","description":"模型推理耗时，单位秒。"},"total_server_seconds":{"type":"number","minimum":0.0,"title":"Total Server Seconds","description":"服务端排队和推理总耗时，单位秒。"},"inference_device":{"type":"string","title":"Inference Device","description":"实际推理设备。"},"inference_precision":{"type":"string","title":"Inference Precision","description":"实际计算精度。"},"model_reload_seconds":{"type":"number","minimum":0.0,"title":"Model Reload Seconds","description":"本次请求触发模型切换时的加载耗时。"},"storage":{"type":"string","const":"minio","title":"Storage","description":"对象存储类型。"},"object_key":{"type":"string","title":"Object Key","description":"MinIO 私有对象键；不能无签名直接访问。"},"playback_url":{"type":"string","title":"Playback Url","description":"限时在线播放 URL。"},"download_url":{"type":"string","title":"Download Url","description":"限时附件下载 URL。"},"download_url_expires_at":{"type":"string","format":"date-time","title":"Download Url Expires At","description":"两个签名 URL 的 ISO 8601 过期时间。"},"download_url_ttl_seconds":{"type":"integer","minimum":60.0,"title":"Download Url Ttl Seconds","description":"签名 URL 有效秒数。"}},"type":"object","required":["status","generation_id","ai_generated","model_id","filename","content_type","size_bytes","sample_rate","duration_seconds","inference_seconds","total_server_seconds","inference_device","inference_precision","model_reload_seconds","storage","object_key","playback_url","download_url","download_url_expires_at","download_url_ttl_seconds"],"title":"TTSResponse","examples":[{"ai_generated":true,"content_type":"audio/wav","download_url":"http://storage.example/private-signed-download-url","download_url_expires_at":"2026-08-05T04:38:26+00:00","download_url_ttl_seconds":86400,"duration_seconds":1.46,"filename":"shizuku_v2_ai_20260804_043826_53a955ac.wav","generation_id":"20260804_043826_53a955ac","inference_device":"cpu","inference_precision":"fp32","inference_seconds":4.925,"model_id":"shizuku-v2","model_reload_seconds":0.0,"object_key":"audio/2026/08/04/shizuku_v2_ai_example.wav","playback_url":"http://storage.example/private-signed-playback-url","sample_rate":32000,"size_bytes":93484,"status":"completed","storage":"minio","total_server_seconds":4.925}]}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"Authorization"}}},"tags":[{"name":"Speech","description":"文字转语音生成接口。"},{"name":"Model","description":"模型能力、参考风格和推理设备信息。"},{"name":"System","description":"服务健康状态与运行限制。"}]}