meijiaka-zy/docs/vidu-tts-api.md

Vidu TTS API 开发文档

来源：https://platform.vidu.cn/docs/text-to-speech
更新时间：2026-04-21

一、概述

Vidu（生数科技）提供语音合成（TTS）和声音复刻能力，所有接口均为同步接口，直接返回结果，无需轮询。

• Base URL: https://api.vidu.cn
• 认证方式: Authorization: Token {your_api_key}
• Content-Type: application/json

---

二、语音合成 TTS

端点

POST /ent/v2/audio-tts

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Token {your_api_key}	API Key 认证

请求体

参数名称	类型	必填	描述
text	String	是	待合成文本，< 10000 字符。支持 <#x#> 停顿标记，x 为停顿时长（秒），范围 [0.01, 99.99]
voice_setting_voice_id	String	是	音色 ID
voice_setting_speed	Float	否	语速，默认 1.0，范围 [0.5, 2]
voice_setting_volume	Int	否	音量，默认 0（正常音量），范围 [0, 10]，值越大音量越高
voice_setting_pitch	Int	否	语调，默认 0（原音色），范围 [-12, 12]
voice_setting_emotion	String	否	情绪控制：happy/sad/angry/fearful/disgusted/surprised/calm。一般无需手动指定，模型自动匹配
pronunciation_dict_tone	list	否	多音字发音定义，如 ["燕少飞/(yan4)(shao3)(fei1)"]
payload	String	否	透传参数，最多 1048576 字符

响应体

{
  "task_id": "your_task_id_here",
  "state": "success",
  "file_url": "https://...",
  "credits": 10,
  "payload": "",
  "created_at": "2025-01-01T15:41:31.968916Z"
}

字段	类型	描述
task_id	String	Vidu 生成的任务 ID
state	String	queueing / success / failed
file_url	String	音频文件 URL
credits	Int	本次调用消耗的积分数
payload	String	透传参数
created_at	String	任务创建时间

Curl 示例

curl -X POST https://api.vidu.cn/ent/v2/audio-tts \
  -H "Authorization: Token {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "你好，欢迎使用vidu开放平台",
    "voice_setting_voice_id": "female-tianmei"
  }'

---

三、声音复刻

端点

POST /ent/v2/audio-clone

请求体

参数名称	类型	必填	描述
audio_url	String	是	原音频 URL（需可访问）。格式：mp3/m4a/wav；时长：10秒~5分钟；大小：≤20MB
voice_id	String	是	自定义声音 ID。长度 [8, 256]；首字符必须为英文字母；允许数字、字母、横线、下划线；末位不可为 -、_；不可与已有 ID 重复
prompt_audio_url	String	否	音色复刻示例音频（< 8秒），可增强音色相似度和稳定性
prompt_text	String	否	示例音频对应文本，需与音频内容一致，句末需有标点
text	String	是	复刻试听文本，≤1000 字符。使用复刻后的音色朗读，返回试听音频
payload	String	否	透传参数

响应体

{
  "task_id": "your_task_id_here",
  "state": "success",
  "voice_id": "vidu01",
  "demo_audio": "https://...",
  "payload": "",
  "created_at": "2025-01-01T15:41:31.968916Z"
}

字段	类型	描述
task_id	String	任务 ID
state	String	queueing / success / failed
voice_id	String	用户自定义的 voice_id（任务失败时不返回）
demo_audio	String	试听音频链接（仅当请求传入 text 时返回）
payload	String	透传参数
created_at	String	创建时间

Curl 示例

curl -X POST https://api.vidu.cn/ent/v2/audio-clone \
  -H "Authorization: Token {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "your_audio_url",
    "voice_id": "vidu01",
    "text": "你好，欢迎使用vidu开放平台"
  }'

---

四、预设音色列表

共 **16 个中文（普通话）**音色，分标准版和 Beta（精品）版。

标准版

voice_id	音色名称
male-qn-qingse	青涩青年音色
male-qn-jingying	精英青年音色
male-qn-badao	霸道青年音色
male-qn-daxuesheng	青年大学生音色
female-shaonv	少女音色
female-yujie	御姐音色
female-chengshu	成熟女性音色
female-tianmei	甜美女性音色

Beta（精品）版

voice_id	音色名称
male-qn-qingse-jingpin	青涩青年音色-beta
male-qn-jingying-jingpin	精英青年音色-beta
male-qn-badao-jingpin	霸道青年音色-beta
male-qn-daxuesheng-jingpin	青年大学生音色-beta
female-shaonv-jingpin	少女音色-beta
female-yujie-jingpin	御姐音色-beta
female-chengshu-jingpin	成熟女性音色-beta
female-tianmei-jingpin	甜美女性音色-beta

音色试听示例 URL 格式：https://scene.vidu.zone/media-asset/{id}.mp3（见飞书表格原始链接）

---

五、与 MiniMax 对比（接入参考）

维度	Vidu	MiniMax
Base URL	https://api.vidu.cn	https://api.minimaxi.com
认证	Token {key}	Bearer {key}
TTS 端点	POST /ent/v2/audio-tts	POST /v1/t2a_v2
同步/异步	同步	同步 + 异步
文本上限	10000 字符	10000 字符（同步）
语速范围	0.5 ~ 2.0 (Float)	需传 Int
音量范围	0 ~ 10 (Int，0=正常)	需传 Int
语调范围	-12 ~ 12 (Int)	需传 Int
情绪控制	7 种情绪可选	不支持
多音字	支持 pronunciation_dict_tone	不支持
声音复刻	同步，自定义 voice_id	异步，系统分配 voice_id
复刻音频要求	10秒~5分钟，≤20MB	约 10秒~5分钟
预设音色	16 个中文	6 个中文
响应音频字段	file_url	audio

---

六、对口型（Lip Sync）

端点

POST /ent/v2/lip-sync

⚠️ 异步接口，创建后返回 task_id，需要通过查询接口轮询或使用 callback_url 接收回调。

请求体

参数名称	类型	必填	描述
video_url	String	是	原视频 URL（需可访问）。格式：mp4/mov/avi；时长：1600秒（建议 10120秒）；大小：≤5G；分辨率：360p~4096p；编码：H.264
audio_url	String	否	音频文件 URL。格式：wav/mp3/wma/m4a/aac/ogg；时长：>1s 且 <600s；大小：≤100MB
text	String	否	文本内容，4~2000 字符。与 audio_url 同时有值时，以 audio_url 为准
speed	Float	否	语速，默认 1.0，范围 [0.5, 2]。仅文字生成时生效
voice_id	String	否	音色 ID。仅文字生成时生效
volume	Int	否	音量，默认 0（正常音量），范围 [0, 10]。仅文字生成时生效
ref_photo_url	String	否	人脸参考图 URL（jpg/jpeg/png/bmp/webp，192~4096px，≤10MB）。视频中有多张人脸时，用于指定对口型目标人物
callback_url	String	否	回调地址，任务状态变化时 POST 回调

视频素材规范

• 真人出镜（卡通人物需五官比例接近真人）
• 人脸正对镜头，水平转动不超过 45°，俯仰不超过 15°
• 人脸尽量不遮挡，面部光线稳定

创建响应

{
  "task_id": "your_task_id_here",
  "state": "created",
  "payload": "",
  "created_at": "2025-01-01T15:41:31.968916Z"
}

查询任务状态

GET /ent/v2/tasks/{task_id}/creations

响应体：

字段	类型	描述
id	String	任务 ID
state	String	created/queueing/processing/success/failed
err_code	String	错误码
credits	Int	消耗的积分数
payload	String	透传参数
bgm	Bool	是否使用 BGM
off_peak	Bool	是否使用错峰模式
creations	Array	生成物结果列表
creations[].id	String	生成物 ID
creations[].url	String	生成物 URL（24小时有效期）
creations[].cover_url	String	生成物封面 URL（24小时有效期）
creations[].watermarked_url	String	带水印的生成物 URL

Curl 示例（音频驱动）

curl -X POST https://api.vidu.cn/ent/v2/lip-sync \
  -H "Authorization: Token {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "your_video_url",
    "audio_url": "your_audio_url"
  }'

Curl 示例（文字驱动）

curl -X POST https://api.vidu.cn/ent/v2/lip-sync \
  -H "Authorization: Token {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "your_video_url",
    "text": "你好，欢迎使用vidu开放平台",
    "voice_id": "female-tianmei",
    "speed": 1.0
  }'

---

七、接入建议

1. Vidu 优势：情绪控制、多音字标注、16 个音色（含精品版）、同步复刻、对口型
2. Vidu 劣势：没有独立的"查询音色列表"API，音色通过飞书表格维护
3. 接口类型差异：
   • TTS / 声音复刻：同步接口，直接返回结果
   • 对口型：异步接口，需轮询 GET /tasks/{id}/creations 或使用 callback
4. 速度/音量/音调类型：Vidu 的速度是 Float，音量和音调是 Int（和 MiniMax 不同，MiniMax 三者都要求 Int）
5. 前端适配：语速 slider 范围改为 0.52.0；音量改为 010；音调改为 -12~12