{"openapi":"3.1.0","info":{"title":"Doubao TTS Wrapper + Speaker Manager","description":"封装火山豆包异步长文本TTS + 音色库管理 + 声音复刻训练；提供可视化管理页。","version":"1.1.0"},"paths":{"/health":{"get":{"tags":["系统"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Health Get"}}}}}}},"/tts/synthesize":{"post":{"tags":["TTS"],"summary":"一站式文本转语音（同步返回audio_url）","description":"适合 社创/扣子/Dify 自定义工具调用。speaker 可传 nick_name。","operationId":"synthesize_tts_synthesize_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesizeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Synthesize Tts Synthesize Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tts/submit":{"post":{"tags":["TTS"],"summary":"仅提交任务","operationId":"submit_only_tts_submit_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitOnlyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Submit Only Tts Submit Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tts/query":{"post":{"tags":["TTS"],"summary":"查询任务状态","operationId":"query_only_tts_query_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Query Only Tts Query Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tts/create":{"post":{"tags":["TTS"],"summary":"【v2550782】同步音频生成（≤3000字，支持参考音/图+音调）","description":"文档：https://docs.volcengine.com/docs/6561/2550782\n注意：这是「豆包音频生成」接口（seed-audio-1.0），与 /tts/synthesize（豆包语音合成大模型）是两个不同的产品。\n  - 同步返回，无需 submit+query 两阶段\n  - 上限 3000 字 / 120 秒\n  - ✨ 支持 pitch_rate 音调调节 [-12, 12]\n  - ✨ 支持 references 参考音频/图片（最多3条音频或1张图片）\n  - 默认采样率 40000（更高音质）\n  - 使用 X-Api-Key 单头鉴权（旧双头也兼容）\n  - speaker 字段：豆包语音合成 2.0 音色 / 复刻音色 / 与 audio_data/audio_url 互斥","operationId":"tts_create_tts_create_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Tts Create Tts Create Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/speakers":{"get":{"tags":["音色库"],"summary":"音色库：官方 + 本地克隆","operationId":"list_speakers_api_speakers_get","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","description":"分类：all / official_v2 / official_v1 / emotion / multilingual / cloned","default":"all","title":"Type"},"description":"分类：all / official_v2 / official_v1 / emotion / multilingual / cloned"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"关键词搜索（名字/ID/标签）","title":"Search"},"description":"关键词搜索（名字/ID/标签）"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Speakers Api Speakers Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/speakers/cloned":{"post":{"tags":["音色库"],"summary":"手动添加克隆音色（已拿到S_xxx）","operationId":"add_cloned_speaker_api_speakers_cloned_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddClonedSpeakerRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Add Cloned Speaker Api Speakers Cloned Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/speakers/cloned/{pk}":{"delete":{"tags":["音色库"],"summary":"删除克隆音色","operationId":"delete_cloned_speaker_api_speakers_cloned__pk__delete","parameters":[{"name":"pk","in":"path","required":true,"schema":{"type":"integer","title":"Pk"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Cloned Speaker Api Speakers Cloned  Pk  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/preview":{"get":{"tags":["音色库"],"summary":"试听：指定speaker+文本，直接返回audio_url","description":"试听接口：内部走完整 synthesize 流程，快速返回 audio_url 供前端 <audio> 播放。","operationId":"preview_api_preview_get","parameters":[{"name":"speaker","in":"query","required":true,"schema":{"type":"string","title":"Speaker"}},{"name":"text","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":500,"default":"这是一段试听音频，用来感受音色风格。","title":"Text"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Preview Api Preview Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/clone/upload":{"post":{"tags":["声音复刻"],"summary":"上传1-N段样本音频，提交火山ICL训练得到克隆音色","description":"上传样本音频并启动训练。克隆任务在后台异步完成，返回 task_id。\n可用 GET /api/clone/tasks 轮询，或直接看 /api/speakers?type=cloned。","operationId":"clone_upload_api_clone_upload_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_clone_upload_api_clone_upload_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Clone Upload Api Clone Upload Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/clone/tasks":{"get":{"tags":["声音复刻"],"summary":"查看最近200条克隆任务及进度（自动刷新状态）","operationId":"list_clone_tasks_api_clone_tasks_get","parameters":[{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","description":"是否向火山侧刷新最新状态并自动入库成功音色","default":true,"title":"Refresh"},"description":"是否向火山侧刷新最新状态并自动入库成功音色"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Clone Tasks Api Clone Tasks Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AddClonedSpeakerRequest":{"properties":{"speaker_id":{"type":"string","minLength":3,"title":"Speaker Id","description":"火山控制台或训练返回的 S_xxx/saturn_xxx/train_id"},"nick_name":{"type":"string","minLength":1,"title":"Nick Name","description":"友好别名，如'我的声音'，TTS时可直接传此名"},"language":{"type":"string","title":"Language","description":"语言代码 zh/en/ja/ko/...","default":"zh"},"gender":{"type":"string","title":"Gender","description":"M/F/U","default":"U"},"age":{"type":"string","title":"Age","description":"Children / Youth / Adults / Seniors","default":"Adults"},"description":{"type":"string","title":"Description","default":""},"resource":{"type":"string","title":"Resource","description":"默认 seed-icl-2.0（2.0复刻音色）","default":"seed-icl-2.0"}},"type":"object","required":["speaker_id","nick_name"],"title":"AddClonedSpeakerRequest"},"AdditionsParams":{"properties":{"disable_markdown_filter":{"type":"boolean","title":"Disable Markdown Filter","description":"True=只读Markdown内容，False=连符号一起读","default":true},"silence_duration":{"type":"integer","maximum":30000.0,"minimum":0.0,"title":"Silence Duration","description":"结尾追加静音毫秒数 [0, 30000]","default":0},"use_cache":{"type":"boolean","title":"Use Cache","description":"相同文本命中缓存可加速","default":true}},"type":"object","title":"AdditionsParams"},"AudioParams":{"properties":{"format":{"type":"string","title":"Format","description":"音频格式：mp3 / wav / pcm / ogg_opus","default":"mp3"},"sample_rate":{"type":"integer","title":"Sample Rate","description":"采样率：8000/16000/22050/24000/32000/44100/48000","default":24000},"speech_rate":{"type":"integer","maximum":100.0,"minimum":-50.0,"title":"Speech Rate","description":"语速 [-50, 100]，100=2倍速，-50=0.5倍速","default":0},"loudness_rate":{"type":"integer","maximum":100.0,"minimum":-50.0,"title":"Loudness Rate","description":"音量 [-50, 100]","default":0},"emotion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Emotion","description":"情感（仅多情感音色生效）：happy/angry/sad/surprise/gentle…"},"emotion_scale":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Emotion Scale","description":"情感强度 1~5","default":4},"enable_timestamp":{"type":"boolean","title":"Enable Timestamp","description":"是否返回句级+字级时间戳（做字幕）","default":false}},"type":"object","title":"AudioParams"},"Body_clone_upload_api_clone_upload_post":{"properties":{"nick_name":{"type":"string","title":"Nick Name","description":"克隆音色别名，如'我的声音'"},"language":{"type":"string","title":"Language","description":"语言代码（zh/en/ja/ko…）","default":"zh"},"gender":{"type":"string","title":"Gender","description":"M / F / U","default":"U"},"age":{"type":"string","title":"Age","description":"Children/Youth/Adults/Seniors","default":"Adults"},"files":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Files","description":"1~5段样本音频(wav/mp3/mp4)，单段5-60秒，总时长>30s"}},"type":"object","required":["nick_name","files"],"title":"Body_clone_upload_api_clone_upload_post"},"CreateAudioConfig":{"properties":{"format":{"type":"string","title":"Format","description":"音频格式：wav/mp3/pcm/ogg_opus","default":"mp3"},"sample_rate":{"type":"integer","maximum":48000.0,"minimum":8000.0,"title":"Sample Rate","description":"采样率默认 40000","default":40000},"speech_rate":{"type":"integer","maximum":100.0,"minimum":-50.0,"title":"Speech Rate","description":"语速 [-50, 100]","default":0},"pitch_rate":{"type":"integer","maximum":12.0,"minimum":-12.0,"title":"Pitch Rate","description":"音调 [-12, 12]（create接口独有）","default":0},"loudness_rate":{"type":"integer","maximum":100.0,"minimum":-50.0,"title":"Loudness Rate","description":"音量 [-50, 100]","default":0},"enable_subtitle":{"type":"boolean","title":"Enable Subtitle","description":"是否返回字级时间戳字幕","default":false}},"type":"object","title":"CreateAudioConfig"},"CreateReference":{"properties":{"audio_data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audio Data","description":"参考音频 base64（与 audio_url/speaker 互斥）"},"audio_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audio Url","description":"参考音频 URL（与 audio_data/speaker 互斥）"},"image_data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Data","description":"参考图片 base64（与 image_url 互斥）"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"参考图片 URL（与 image_data 互斥）"}},"type":"object","title":"CreateReference"},"CreateRequest":{"properties":{"text":{"type":"string","maxLength":3000,"minLength":1,"title":"Text","description":"合成文本或Prompt，最多 3000 字"},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Speaker","description":"音色ID或克隆别名（与 audio_data/audio_url/image_* 互斥）","default":"zh_female_vv_uranus_bigtts"},"model":{"type":"string","title":"Model","description":"模型版本：seed-audio-1.0-multilingual（多语种，推荐）/ seed-audio-1.0（中英）","default":"seed-audio-1.0-multilingual"},"references":{"anyOf":[{"items":{"$ref":"#/components/schemas/CreateReference"},"type":"array"},{"type":"null"}],"title":"References","description":"参考资源列表（最多3条音频/1张图片）"},"audio_config":{"$ref":"#/components/schemas/CreateAudioConfig"},"uid":{"type":"string","title":"Uid","default":"社创-user"}},"type":"object","required":["text"],"title":"CreateRequest","description":"文档：https://docs.volcengine.com/docs/6561/2550782\n特点：同步返回；最大 3000字/120秒；支持音效 text_prompt；支持参考音频/图片；新增 pitch_rate 音调。\n和 /tts/synthesize 完全不同接口（syntheesize 是异步长文本 TTS）。"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"QueryRequest":{"properties":{"task_id":{"type":"string","title":"Task Id","description":"submit 返回的 task_id"}},"type":"object","required":["task_id"],"title":"QueryRequest"},"SubmitOnlyRequest":{"properties":{"text":{"type":"string","maxLength":100000,"minLength":1,"title":"Text"},"speaker":{"type":"string","title":"Speaker","default":"zh_female_vv_uranus_bigtts"},"audio_params":{"$ref":"#/components/schemas/AudioParams"},"additions":{"$ref":"#/components/schemas/AdditionsParams"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id"},"uid":{"type":"string","title":"Uid","default":"社创-user"}},"type":"object","required":["text"],"title":"SubmitOnlyRequest","description":"仅 submit，不等待。返回 task_id 给调用方自己轮询。"},"SynthesizeRequest":{"properties":{"text":{"type":"string","maxLength":100000,"minLength":1,"title":"Text","description":"要合成的文本，最多 10 万字符"},"speaker":{"type":"string","title":"音色","description":"音色 ID / 克隆音色别名（nick_name）。可传官方音色ID（如 zh_female_vv_uranus_bigtts / 小禾），也可传自己克隆音色的 nick_name（如 '我的声音'），后端自动映射并切 resource_id。常用官方音色：vv(灵动)/小禾(港台腔)/云洲(清爽男)/小天(磁性男)/爽快思思/温暖阿虎/婉婉小禾/川塑客。完整列表 GET /api/speakers 查看。","default":"zh_female_vv_uranus_bigtts"},"audio_params":{"$ref":"#/components/schemas/AudioParams"},"additions":{"$ref":"#/components/schemas/AdditionsParams"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id","description":"临时覆盖模型版本（通常不用传，后端会根据speaker自动选）"},"max_wait_sec":{"type":"integer","maximum":3600.0,"minimum":5.0,"title":"Max Wait Sec","description":"同步接口最长等待秒数","default":300},"uid":{"type":"string","title":"Uid","description":"业务侧用户标识","default":"社创-user"}},"type":"object","required":["text"],"title":"SynthesizeRequest"},"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"}}}}