使用清晰的音频样本（AVI/MP3/MP4/M4A/WAV，不超过 30MB）克隆声音，获得可复用的 voice_id。克隆同步执行，可能耗时较长，请设置足够长的请求超时时间。允许保留的有效克隆声音数量取决于订阅方案。
请求头
X-API-Keystring必填你的 VisionStory API Key（sk-vs-...），请仅保存在服务端。可在 API Key 管理 中创建或管理，需要 Pro 或更高方案。
请求体
application/json必填audio_urlstring | null可为空清晰声音样本的公开可访问 URL。此字段与 inline_data 二选一。支持 AVI/MP3/MP4/M4A/WAV，文件不超过 30MB。
inline_dataInlineDataModel | null可为空以内嵌 base64 数据提供的声音样本。此字段与 audio_url 二选一。
datastring必填文件原始字节编码后的 base64 字符串，不包含 data: URI 前缀。
mime_typestring必填内嵌数据的 MIME 类型，网关据此区分图像、音频和视频。可接受的类型取决于具体接口，请参阅包含此对象的字段说明。数字人视频接受音频 ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav'] 和图像 ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic']。
preview_textstring | null可为空克隆声音试听片段中朗读的文本。默认使用内置短句，最多 100 个字符。
响应
200请求成功
application/json
dataCloneVoiceResponse | null必填可为空当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。
genderstring从音频样本识别的声音性别；尚未完成识别时为空。
languagestring从音频样本识别的主要语言，例如 english；尚未完成识别时为空。
localestring为克隆声音识别的 BCP 47 语言区域标记（例如 en-US），与 GET /api/v1/voices 的 locale 字段和 POST /api/v1/tts 的 locale 参数使用相同格式；无法识别时为空。
preview_audio_urlstring使用克隆声音合成的试听片段 URL；尚未就绪时为空。
voice_idstring必填克隆声音的唯一标识符。在文本脚本中将其作为 voice_id 传入，即可使用此声音朗读。
messagestring便于阅读的状态消息；调用成功时为 "success"。
server_timestring · date-time必填服务端生成响应时的时间戳，使用 ISO 8601 格式（UTC）。
default错误响应。所有失败均使用统一结构：error 对象包含数字错误码 code、便于阅读的 message、可选的 details 字符串，以及提供后续处理建议的可选 hint（便于 AI Agent 使用）。
application/json
errorErrorDetail必填codeinteger必填机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。
detailsstring | null可为空可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。
hintstring | null可为空供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。
messagestring必填便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。