汛沛数字人 API 文档

本文档适用于第三方系统接入汛沛数字人及视频创作能力的完整技术说明。路由前缀：/api/v1

Base URL https://ucar.wang

📌 鉴权方式：所有接口采用 HMAC-SHA256 签名认证。请求头需携带 X-Api-Key、X-Timestamp、X-Sign。签名算法：sign = HMAC-SHA256(api_key + timestamp, api_secret)。请在密钥管理页面获取密钥对。

数字人克隆

POST /api/v1/avatar?action=create 视频克隆数字人 ▼

⚠️ video_url 与 file_id 二选一。相同URL视为同一个数字人。

参数	类型	说明
title可选	string	数字人名称，默认"未命名"
video_url可选	url string	视频URL，支持mp4/mov，H264编码，≤500MB，5秒~30分钟
image_url可选	url string	图片URL（图片克隆时使用）
aigc_flag可选	int	0=跟随设置，1=开启AIGC水印，2=关闭，默认0

cURL 请求示例

curl -k https://ucar.wang/api/v1/avatar?action=create \
  -H "X-Api-Key: ak-your-key" \
  -H "X-Timestamp: 1700000000" \
  -H "X-Sign: your-hmac-signature" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "我的数字人",
    "video_url": "https://example.com/my_video.mp4"
  }'

POST /api/v1/avatar?action=create 图片克隆数字人 ▼

参数	类型	说明
title可选	string	数字人名称，默认"未命名"
image_url必填	url string	图片URL，用于克隆数字人形象
model可选	int	模型版本，默认2

cURL 请求示例

curl https://ucar.wang/api/v1/avatar?action=create \
  -H "X-Api-Key: ak-your-key" \
  -H "X-Timestamp: 1700000000" \
  -H "X-Sign: your-hmac-signature" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "我的图片数字人",
    "image_url": "https://example.com/photo.jpg"
  }'

GET /api/v1/avatar?action=task 查询数字人克隆任务状态 ▼

参数	类型	说明
task_id必填	string	创建任务时返回的task_id

状态值：1=pending，2=processing，3=completed，4=failed。成功时返回avatar字段为数字人ID。

GET /api/v1/avatar?action=list 查询公共数字人列表 ▼

参数	类型	说明
page可选	int	页码，默认1
size可选	int	每页数量，默认20，最大50

声音克隆

POST /api/v1/voice?action=create 创建声音克隆 ▼

参数	类型	说明
title必填	string	声音名称
audio_url必填	url string	音频URL，建议15秒以上清晰人声
language可选	string	语言代码，默认zh

POST /api/v1/voice?action=edit 修改声音的参数 ▼

参数	类型	说明
voice_id必填	string	声音ID
rate可选	float	语速倍率，默认1.0
volume可选	float	音量倍率，默认1.0
pitch可选	float	音调倍率，默认1.0

GET /api/v1/voice?action=list 查询声音列表 ▼

参数	类型	说明
kind可选	int	声音类型，1=我的声音，默认1
page可选	int	页码，默认1
size可选	int	每页数量，默认20，最大50

GET /api/v1/voice?action=task 查询声音克隆任务状态 ▼

参数	类型	说明
task_id必填	string	创建任务时返回的task_id

视频创作

POST /api/v1/video?action=create_tts 文本驱动视频创作 ▼

参数	类型	说明
avatar_id必填	string	数字人ID
voice_id必填	string	声音ID
text必填	string	数字人台词文本
title可选	string	视频标题
subtitle_config可选	object	字幕配置，详见上游文档

POST /api/v1/video?action=create_audio 音频驱动视频创作 ▼

参数	类型	说明
avatar_id必填	string	数字人ID
audio_url必填	url string	驱动音频URL
title可选	string	视频标题

POST /api/v1/video?action=create_audio_tts 纯音频TTS创作 ▼

参数	类型	说明
voice_id必填	string	声音ID
text必填	string	合成文本
language可选	string	语言代码，默认zh

GET /api/v1/video?action=task 查询创作任务状态 ▼

参数	类型	说明
task_id必填	string	创建任务时返回的task_id

响应中 video_Url（注意大写U）为生成完成的视频地址。状态：1=pending，2=processing，3=completed，4=failed。

系统接口

POST /api/v1/account/upload_url 获取文件上传地址 ▼

参数	类型	说明
file_extension必填	string	文件扩展名，如 mp4、jpg、wav

返回upload_url可直接PUT上传文件，file_id用于后续接口引用。

GET /api/v1/account/credit 查询账户积分 ▼

查询当前API Key所属账户的汛沛平台积分余额。

消息回调

任务完成后，汛沛平台会主动向注册的回调地址推送任务结果。支持数字人克隆、声音克隆、视频创作三种回调。

POST /api/task/callback 事件回调地址 ▼

字段	类型	说明
type必填	int	1=视频创作完成，2=数字人克隆完成，3=声音克隆完成
task_id必填	string	任务ID
status必填	int	1=pending，2=processing，3=completed，4=failed
video_Url	string	（type=1时）视频下载地址
avatar	string	（type=2时）数字人ID
voice	string	（type=3时）声音ID

错误码

错误码	含义
401	认证失败——密钥无效或签名错误
400	参数错误——缺少必填参数或参数格式有误
429	调用频率超限——已达每日配额上限
2001	参数错误
2003	Token无效或过期
2004	余额不足
1001	系统繁忙，请稍后重试