[{"data":1,"prerenderedAt":154},["ShallowReactive",2],{"reference-detail-zh-clone_voice_api_v1_voice_post":3,"developer-code-1b5i8vu":152,"developer-code-m4wzi8":153},{"tag":4,"sourceTag":4,"tagSlug":5,"method":6,"path":7,"slug":8,"summary":9,"description":10,"operationId":11,"groupOrder":12,"descriptionHtml":13,"parameters":14,"requestBody":22,"responses":54,"security":139,"codeSamples":142},"Voices","voices","POST","\u002Fapi\u002Fv1\u002Fvoice","clone-voice","克隆声音","使用清晰的音频样本（AVI\u002FMP3\u002FMP4\u002FM4A\u002FWAV，不超过 30MB）克隆声音，获得可复用的 `voice_id`。克隆同步执行，可能耗时较长，请设置足够长的请求超时时间。允许保留的有效克隆声音数量取决于订阅方案。","clone_voice_api_v1_voice_post",30,"\u003Cp>使用清晰的音频样本（AVI\u002FMP3\u002FMP4\u002FM4A\u002FWAV，不超过 30MB）克隆声音，获得可复用的 \u003Ccode>voice_id\u003C\u002Fcode>。克隆同步执行，可能耗时较长，请设置足够长的请求超时时间。允许保留的有效克隆声音数量取决于订阅方案。\u003C\u002Fp>",[15],{"name":16,"in":17,"required":18,"description":19,"type":20,"example":21},"X-API-Key","header",true,"你的 VisionStory API Key（`sk-vs-...`），请仅保存在服务端。可在 [API Key 管理](\u002Fapi-keys) 中创建或管理，需要 Pro 或更高方案。","string","sk-vs-your-api-key",{"required":18,"contentType":23,"schema":24,"example":51},"application\u002Fjson",{"type":25,"description":26,"nullable":27,"properties":28},"CloneVoiceRequest","",false,[29,34,47],{"name":30,"required":27,"type":31,"description":32,"nullable":18,"properties":33},"audio_url","string | null","清晰声音样本的公开可访问 URL。此字段与 `inline_data` 二选一。支持 AVI\u002FMP3\u002FMP4\u002FM4A\u002FWAV，文件不超过 30MB。",[],{"name":35,"required":27,"type":36,"description":37,"nullable":18,"properties":38},"inline_data","InlineDataModel | null","以内嵌 base64 数据提供的声音样本。此字段与 `audio_url` 二选一。",[39,43],{"name":40,"required":18,"type":20,"description":41,"nullable":27,"properties":42},"data","文件原始字节编码后的 base64 字符串，不包含 `data:` URI 前缀。",[],{"name":44,"required":18,"type":20,"description":45,"nullable":27,"properties":46},"mime_type","内嵌数据的 MIME 类型，网关据此区分图像、音频和视频。可接受的类型取决于具体接口，请参阅包含此对象的字段说明。数字人视频接受音频 ['audio\u002Favi', 'audio\u002Fmpeg', 'audio\u002Fmp3', 'audio\u002Fmp4', 'audio\u002Fm4a', 'audio\u002Fwav'] 和图像 ['image\u002Fjpeg', 'image\u002Fjpg', 'image\u002Fpng', 'image\u002Fwebp', 'image\u002Fheic']。",[],{"name":48,"required":27,"type":31,"description":49,"nullable":18,"properties":50},"preview_text","克隆声音试听片段中朗读的文本。默认使用内置短句，最多 100 个字符。",[],{"audio_url":52,"preview_text":53},"https:\u002F\u002Fexample.com\u002Fmedia\u002Fvoice-sample.mp3","Welcome to VisionStory.",[55,109],{"status":56,"description":57,"contentType":23,"schema":58,"example":95,"examples":103,"headers":108},"200","请求成功",{"type":59,"description":26,"nullable":27,"properties":60},"BaseSuccessResponse_CloneVoiceResponse_",[61,85,90],{"name":40,"required":18,"type":62,"description":63,"nullable":18,"properties":64},"CloneVoiceResponse | null","当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。",[65,69,73,77,81],{"name":66,"required":27,"type":20,"description":67,"nullable":27,"default":26,"properties":68},"gender","从音频样本识别的声音性别；尚未完成识别时为空。",[],{"name":70,"required":27,"type":20,"description":71,"nullable":27,"default":26,"properties":72},"language","从音频样本识别的主要语言，例如 `english`；尚未完成识别时为空。",[],{"name":74,"required":27,"type":20,"description":75,"nullable":27,"default":26,"properties":76},"locale","为克隆声音识别的 BCP 47 语言区域标记（例如 `en-US`），与 GET \u002Fapi\u002Fv1\u002Fvoices 的 `locale` 字段和 POST \u002Fapi\u002Fv1\u002Ftts 的 `locale` 参数使用相同格式；无法识别时为空。",[],{"name":78,"required":27,"type":20,"description":79,"nullable":27,"default":26,"properties":80},"preview_audio_url","使用克隆声音合成的试听片段 URL；尚未就绪时为空。",[],{"name":82,"required":18,"type":20,"description":83,"nullable":27,"properties":84},"voice_id","克隆声音的唯一标识符。在文本脚本中将其作为 `voice_id` 传入，即可使用此声音朗读。",[],{"name":86,"required":27,"type":20,"description":87,"nullable":27,"default":88,"properties":89},"message","便于阅读的状态消息；调用成功时为 `\"success\"`。","success",[],{"name":91,"required":18,"type":92,"description":93,"nullable":27,"properties":94},"server_time","string · date-time","服务端生成响应时的时间戳，使用 ISO 8601 格式（UTC）。",[],{"data":96,"message":88,"server_time":102},{"gender":97,"language":98,"locale":99,"preview_audio_url":100,"voice_id":101},"female","english","en-US","https:\u002F\u002Fexample.com\u002Fclone.mp3","example_cloned_voice_id","2026-09-04T00:00:00Z",[104],{"name":88,"description":105,"summary":57,"value":106},"示例仅用于说明响应结构，不代表实时账户数据或实际报价。ID 和 URL 均为占位内容。请调用模型查询及费用估算接口，获取当前可用模型和价格。",{"data":107,"message":88,"server_time":102},{"gender":97,"language":98,"locale":99,"preview_audio_url":100,"voice_id":101},[],{"status":110,"description":111,"contentType":23,"schema":112,"example":135,"headers":138},"default","错误响应。所有失败均使用统一结构：`error` 对象包含数字错误码 `code`、便于阅读的 `message`、可选的 `details` 字符串，以及提供后续处理建议的可选 `hint`（便于 AI Agent 使用）。",{"type":113,"description":26,"nullable":27,"properties":114},"ErrorResponse",[115],{"name":116,"required":18,"type":117,"description":26,"nullable":27,"properties":118},"error","ErrorDetail",[119,124,128,132],{"name":120,"required":18,"type":121,"description":122,"nullable":27,"properties":123},"code","integer","机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。",[],{"name":125,"required":27,"type":31,"description":126,"nullable":18,"properties":127},"details","可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。",[],{"name":129,"required":27,"type":31,"description":130,"nullable":18,"properties":131},"hint","供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。",[],{"name":86,"required":18,"type":20,"description":133,"nullable":27,"properties":134},"便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。",[],{"error":136},{"code":137,"message":20,"details":20,"hint":20},1,[],[140],{"APIKeyHeader":141},[],[143,146,149],{"lang":144,"source":145},"SDK","from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nvoice = client.clone_voice(\n    audio_url=\"https:\u002F\u002Fexample.com\u002Fmedia\u002Fvoice-sample.mp3\",\n    preview_text=\"Welcome to VisionStory.\",\n)\nprint(voice)",{"lang":147,"source":148},"REST","import os\nimport requests\nimport base64\n\ndef encode_base64(file_path):\n    with open(file_path, 'rb') as file:\n        encoded_string = base64.b64encode(file.read()).decode('utf-8')\n    return encoded_string\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\n\n# payload = {\n#     \"audio_url\": \"https:\u002F\u002Fstorage.googleapis.com\u002Feleven-public-prod\u002Fpremade\u002Fvoices\u002FXb7hH8MSUJpSbSDYk0k2\u002Fd10f7534-11f6-41fe-a012-2de1e482d336.mp3\",\n#     \"preview_text\": \"How are you doing guys, this is my voice\"\n# }\n\naudio_file_path = '\u002Fpath\u002Fto\u002Faudio.mp3'\npayload = {\n    \"inline_data\": {\n        \"mime_type\": \"audio\u002Fmp3\",\n        \"data\": encode_base64(audio_file_path)\n    },\n    \"preview_text\": \"How are you doing guys, this is my voice\"\n}\n\n# wait for about 15 seconds\nresponse = requests.post(\n    'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvoice',  json=payload, headers=headers\n)\nresp_data = response.json()\nprint(resp_data['data']['voice_id'])",{"lang":150,"source":151},"cURL","curl -X 'POST' \\\n      'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvoice' \\\n      -H 'accept: application\u002Fjson' \\\n      -H 'content-type: application\u002Fjson' \\\n      -H 'X-API-Key: $VISIONSTORY_API_KEY' \\\n      --data '\n{\n    \"audio_url\": \"https:\u002F\u002Fstorage.googleapis.com\u002Feleven-public-prod\u002Fpremade\u002Fvoices\u002FXb7hH8MSUJpSbSDYk0k2\u002Fd10f7534-11f6-41fe-a012-2de1e482d336.mp3\",\n    \"preview_text\": \"How are you doing guys, this is my voice\"\n}\n'","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">from\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> visionstory \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient.from_env()\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">voice \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> client.clone_voice(\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    audio_url\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fexample.com\u002Fmedia\u002Fvoice-sample.mp3\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    preview_text\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"Welcome to VisionStory.\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(voice)\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">{\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"gender\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"female\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"language\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"english\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"locale\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"en-US\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"preview_audio_url\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fexample.com\u002Fclone.mp3\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"voice_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"example_cloned_voice_id\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">  },\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"message\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"success\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"server_time\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"2026-09-04T00:00:00Z\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">}\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1788547144475]