VisionStory 声音克隆 API 将音频样本转换为可复用的 voice_id。你可以选择公共声音或克隆自己的声音，再用于文本转语音和口型同步的数字人视频生成。
声音克隆接口
| 方法 | 路径 | 功能 |
|---|---|---|
GET | /api/v1/voices | 列出公共声音和你克隆的声音 |
POST | /api/v1/voice | 通过音频样本克隆声音 |
DELETE | /api/v1/voice | 删除你克隆的一个声音 |
查询公共声音与克隆声音
列表响应分为 public_voices 和 my_voices。每个声音包含机器可读的 BCP 47 locale、便于阅读的 language，以及结构化的 provider、gender、age、accent、use_cases 字段和试听 URL。旧版 tags 字段仍保留，以兼容现有调用。
使用 locale 和供应商筛选公共声音库，再通过 limit 和返回的 next_cursor 分页。基础语言标记（如 es）匹配所有西班牙语地区变体；完整语言地区标记（如 es-MX、en-GB、zh-TW 或 zh-HK）只匹配对应地区：
curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" \
"https://openapi.visionstory.ai/api/v1/voices?locale=es-MX&provider=minimax&limit=50"
import os
import requests
headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]}
response = requests.get(
"https://openapi.visionstory.ai/api/v1/voices",
headers=headers,
params={"locale": "es-MX", "provider": "minimax", "limit": 50},
timeout=10,
)
resp_data = response.json()
print(len(resp_data["data"]["public_voices"]))
print(len(resp_data["data"]["my_voices"]))
print(resp_data["data"]["next_cursor"])
不传 limit 时，接口保持原有行为，返回筛选后的完整声音库。分页时，my_voices 仅在第一页返回。locale 和 provider 的匹配不区分大小写。请始终使用接口返回的 voice_id，不要自行编造。
通过音频克隆 AI 声音
提交声音样本后，接口会返回 voice_id。音频来源必须二选一：可公开访问的 HTTPS URL，或包含 Base64 数据的 inline_data。可选的 preview_text 会使用新声音合成试听音频，方便立即检查效果。请求同步返回，约需 15 秒：
curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"audio_url": "https://your.site/sample.mp3", "preview_text": "How are you doing guys, this is my voice"}' https://openapi.visionstory.ai/api/v1/voice
使用本地文件时，先将其编码为 Base64，再放入 inline_data：
import base64
import os
import requests
headers = {"X-API-Key": os.environ["VISIONSTORY_API_KEY"]}
with open("/path/to/audio.mp3", "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
payload = {
"inline_data": {"mime_type": "audio/mp3", "data": encoded},
"preview_text": "How are you doing guys, this is my voice"
}
response = requests.post("https://openapi.visionstory.ai/api/v1/voice", json=payload, headers=headers) # takes ~15 s
voice = response.json()["data"]
print(voice["voice_id"], voice["locale"], voice["gender"], voice["preview_audio_url"])
样本要求： 提供单人、清晰的录音。支持 AVI、MP3、MP4、M4A 和 WAV，文件不超过 30 MB。可同时保留的克隆声音数量取决于订阅方案。
在视频中使用克隆声音
创建视频时，声音可用于以下两种场景：
文本脚本 — 使用所选声音朗读文本：
{
"model_id": "vs_character_v4",
"avatar_id": "YOUR_AVATAR_ID",
"text_script": { "text": "Hello!", "voice_id": "YOUR_VOICE_ID", "speech_rate": "normal" }
}
音频脚本换声 — 提供音频，并设置 voice_change: true，即可用所选 voice_id 对音频换声：
{
"model_id": "vs_character_v4",
"avatar_id": "YOUR_AVATAR_ID",
"audio_script": { "audio_url": "https://your.site/narration.mp3", "voice_change": true, "voice_id": "YOUR_VOICE_ID", "denoise": true }
}
删除专属声音
只能删除你自己的克隆声音；删除不会影响此前已使用该声音生成的视频：
curl -s -X DELETE -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/voice?voice_id=YOUR_VOICE_ID"