http://127.0.0.1:90909090 换成实际端口。http://运行数字人电脑的IP:9090code/message/data 包装格式。成功时直接返回业务 JSON,失败时 FastAPI 通常返回:{
"detail": "错误原因"
}http://127.0.0.1:9090/docsGET /health| 参数 | 类型 | 描述 |
|---|---|---|
| status | string | 服务状态,正常时为 ok |
curl.exe -X GET "http://127.0.0.1:9090/health"{
"status": "ok"
}GET /api/status| 参数 | 类型 | 描述 |
|---|---|---|
| status | string | running 运行中,stopped 已停止,not_initialized 未初始化 |
| processor | string | 当前处理器,例如 heygem 或 wav2lip |
| character_name | string | 当前数字人形象 ID |
| current_video_dimensions | array | 当前视频尺寸,格式通常为 [宽, 高] |
curl.exe -X GET "http://127.0.0.1:9090/api/status"{
"status": "running",
"processor": "heygem",
"character_name": "heygem/example",
"current_video_dimensions": [1080, 1920]
}{
"status": "not_initialized"
}POST /api/process_audiohttps://example.com/demo.wavD:\audios\demo.wav| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| audio_url | string | 是 | 音频 URL 或服务端本机音频路径,支持 mp3、wav 等常见音频格式 |
| sr_orig | int | 否 | 原始音频采样率,默认 44100 |
| device_idx | int/null | 否 | 音频输出设备索引,不指定传 null |
| scaling_factor | float | 否 | 音频缩放系数,默认 1.0 |
{
"audio_url": "https://example.com/demo.wav",
"sr_orig": 44100,
"device_idx": null,
"scaling_factor": 1.0
}{
"audio_url": "D:\\audios\\demo.wav",
"sr_orig": 44100,
"device_idx": null,
"scaling_factor": 1.0
}| 参数 | 类型 | 描述 |
|---|---|---|
| status | string | 成功时为 success |
| message | string | 响应说明 |
| qsize | int | 推入音频队列后的队列长度 |
| push_stats | object | 最近一次音频推入统计信息,不同处理器字段可能不同 |
curl.exe -X POST "http://127.0.0.1:9090/api/process_audio" `
-H "Content-Type: application/json" `
-d "{\"audio_url\":\"https://example.com/demo.wav\",\"sr_orig\":44100,\"device_idx\":null,\"scaling_factor\":1.0}"curl.exe -X POST "http://127.0.0.1:9090/api/process_audio" `
-H "Content-Type: application/json" `
-d "{\"audio_url\":\"D:\\audios\\demo.wav\",\"sr_orig\":44100,\"device_idx\":null,\"scaling_factor\":1.0}"{
"status": "success",
"message": "Audio data processed successfully",
"qsize": 8,
"push_stats": {}
}audio_url:{
"detail": "Need audio_url"
}{
"detail": "Only http and https audio URLs are supported"
}{
"detail": "No audio file found"
}{
"detail": "Stream service not available"
}ActionId=1002。POST /api/change_character| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| character_name | string | 是 | 数字人形象 ID,通常为 项目类型/形象名 |
heygem/example
wav2lip/1080p(测试流畅度使用)avatars/heygem/example
avatars/wav2lip/1080p(测试流畅度使用)curl.exe -X POST "http://127.0.0.1:9090/api/change_character" `
-H "Content-Type: application/json" `
-d "{\"character_name\":\"heygem/example\"}"{
"status": "success",
"message": "Character changed to heygem/example successfully",
"character_name": "heygem/example",
"processor": "heygem"
}GET /api/characters| 参数 | 类型 | 描述 |
|---|---|---|
| status | string | 成功时为 success |
| characters | array | 数字人列表 |
curl.exe -X GET "http://127.0.0.1:9090/api/characters"{
"status": "success",
"characters": []
}POST /api/train_character| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| video_path | string | 是 | 视频文件路径,必须是运行数字人电脑可访问的路径 |
| cycle | bool | 否 | 保留字段,默认 false |
curl.exe -X POST "http://127.0.0.1:9090/api/train_character" `
-H "Content-Type: application/json" `
-d "{\"video_path\":\"D:\\videos\\input.mp4\",\"cycle\":false}"{
"detail": "Character training is disabled in the HeyGem-only build"
}POST /api/set_window| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| width | int | 否 | 窗口宽度,默认 720,必须大于 0 |
| height | int | 否 | 窗口高度,默认 1280,必须大于 0 |
| flag | bool | 否 | true 固定尺寸,false 取消固定 |
curl.exe -X POST "http://127.0.0.1:9090/api/set_window" `
-H "Content-Type: application/json" `
-d "{\"width\":450,\"height\":800,\"flag\":true}"curl.exe -X POST "http://127.0.0.1:9090/api/set_window" `
-H "Content-Type: application/json" `
-d "{\"width\":450,\"height\":800,\"flag\":false}"{
"status": "success",
"message": "Window size updated successfully",
"details": {
"width": 450,
"height": 800,
"fixed": true
}
}pip install requestsBASE_URL = "http://127.0.0.1:9090" 和软件界面中的 API 端口一致。| 函数 | 作用 |
|---|---|
health() | 健康检查 |
get_status() | 查询运行状态 |
process_audio(audio_url, sr_orig=44100, device_idx=None, scaling_factor=1.0) | 音频驱动播报 |
change_character(character_name) | 切换数字人 |
set_window(width=450, height=800, fixed=True) | 设置窗口尺寸 |
get_characters() | 获取数字人列表 |
ws://127.0.0.1:30003/human
ws://127.0.0.1:30004/human
...
ws://127.0.0.1:30012/human| ActionId | 方向 | 说明 |
|---|---|---|
| 1010 | 本项目 -> 外部服务 | 通知当前数字人形象和处理器 |
| 1001 | 外部服务 -> 本项目 | 推送 base64 音频数据 |
| 1002 | 本项目 -> 外部服务 | 播报结束通知 |
| 1003 | 外部服务 -> 本项目 | 切换数字人形象 |
| 1004 | 双向 | 获取或返回数字人列表 |
| 1011 | 外部服务 -> 本项目 | 设置窗口尺寸 |
{
"ActionId": 1001,
"audio_data": "base64编码后的音频内容",
"tts_type": "Bert-Vits2",
"device_idx": null,
"text": "这句话对应的文本",
"scaling_factor": 1.0,
"verbal_type": "MasterVerbal"
}{
"ActionId": 1002,
"Text": "这句话对应的文本"
}| HTTP 状态码 | 常见原因 |
|---|---|
| 200 | 请求成功 |
| 400 | 参数不合法、远程音频 URL 不合法、远程地址无法解析 |
| 413 | 远程音频文件过大 |
| 422 | 请求体字段不符合模型 |
| 500 | 未传音频、音频路径不存在、内部处理异常 |
| 501 | 当前构建禁用了数字人训练 |
| 503 | 实时流服务未初始化或切换队列已满 |
/health 正常,但 /api/process_audio 返回 503No audio file foundhttp 和 https,并且会拦截内网、回环、本地链路等地址,避免服务端请求伪造风险。{
"audio_url": "https://example.com/demo.wav"
}curl 可能是别名,建议使用:curl.exe