VisionStory 文本转语音 API 可使用任意公共或克隆声音，将文本转换为自然的 MP3 音频。请求同步处理，成功后直接返回生成的音频字节。
Beta。 只要账户拥有有效的 Pro 或更高等级订阅，其 API Key 即可调用此接口，无需额外申请能力白名单。
文本转语音接口
| 方法 | 路径 | 功能 |
|---|---|---|
POST | /api/v1/tts | 根据文本合成语音，返回 MP3 音频 |
将文本转换为 MP3 语音
传入 text 和从 GET /api/v1/voices 获取的 voice_id。可以指定 BCP 47 locale，如 en-GB 或 zh-TW，以引导多语言声音的发音和口音。不同语音引擎会尽力应用该设置，但效果可能不同；省略时使用声音原生的语言地区。
Shell
curl -s -X POST -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"text": "Hello from VisionStory.", "voice_id": "YOUR_VOICE_ID", "locale": "en-GB"}' https://openapi.visionstory.ai/api/v1/tts --output speech.mp3
响应体是原始 MP3 音频（audio/mpeg，44.1 kHz）。用量和计费信息放在响应头中，而不是响应体：
| 响应头 | 含义 |
|---|---|
X-Audio-Duration-Sec | 生成音频的时长，单位为秒 |
X-Usage-Characters | 计费字符数 |
X-Cost-Credit | 本次调用消耗的点数 |
Python
import requests, os
resp = requests.post(
"https://openapi.visionstory.ai/api/v1/tts",
headers={"X-API-Key": os.environ["VISIONSTORY_API_KEY"]},
json={"text": "Hello from VisionStory.", "voice_id": "YOUR_VOICE_ID", "locale": "en-GB"},
timeout=240,
)
resp.raise_for_status()
with open("speech.mp3", "wb") as f:
f.write(resp.content)
print("credits charged:", resp.headers.get("X-Cost-Credit"))
调整语速
可选参数 speech_rate 接受 slow、normal 或 fast。省略或传入 null 时使用正常语速。公共和克隆声音均支持语速调整，但实际时长变化因声音而异，应以 X-Audio-Duration-Sec 为准，不要假设固定时长。调整语速不改变音高，计费方式也不变。
Python
from visionstory import VisionStoryClient
from pathlib import Path
speech = VisionStoryClient.from_env().create_speech(
text="Hello from VisionStory.", voice_id="YOUR_VOICE_ID",
locale="en-GB", speech_rate="slow",
)
Path("speech.mp3").write_bytes(speech["audio"])
Shell
visionstory tts --text "Hello from VisionStory." --voice-id YOUR_VOICE_ID --speech-rate slow --output speech.mp3
本地和远程 MCP 的 create_speech 同样支持可选的 speech_rate。REST 调用将该字段与 text、voice_id、locale 一起放入 JSON 请求体。不传此字段的原有调用无需修改。
计费、限制与存储
- 同步返回，不在服务端保存。 音频直接随响应返回，服务端不会保存。请自行保存字节数据；重复请求会重新生成并再次计费。
- 计费： 每 1,000 个字符 2 点，不足 1,000 个字符按 1,000 个计算，仅成功时收费，没有免费额度。
- 字符限制： 支持长文本，但有单次请求上限；超出时返回
400。 - 并发： Beta 期间，每个 API Key 的同步生成并发数较低；超出限制的请求会被拒绝，不会排队。