1. 数字人插件-接口文档/调用测试
萝卜AI直播
  • 系统介绍
  • 联系方式(交流群and主包wx)
  • 安装教程
  • 各平台直播间公屏抓取使用帮助
  • 版本下载/更新
    • 萝卜主程序
    • 数字人组件
    • 声音组件-Omnivoice
    • 声音组件-bertvits
    • 声音组件-VoxCPM2
    • 声音组件-GPTSovits
  • 常见问题
    • GPT模型怎么查找三个参数
  • 语音模型训练教程
    • BertVits语音模型训练教程
    • GPT-SoVITS2 语音模型训练教程
  • 数字人插件-接口文档/调用测试
    • 实时数字人 API 对接文档
    • 音频驱动
      POST
  1. 数字人插件-接口文档/调用测试

实时数字人 API 对接文档

本文档适用于第三方系统接入本地实时数字人软件,包含接口含义、请求参数、返回示例、curl 示例和 Python 调用代码。

通用说明#

后端地址#

本地默认地址:
http://127.0.0.1:9090
如果在软件界面或启动参数里修改过 API 端口,请把 9090 换成实际端口。
局域网访问示例:
http://运行数字人电脑的IP:9090

启动方式#

1.
双击打开已交付的软件程序。
2.
在软件首页选择数字人项目、数字人形象、窗口尺寸和 API 端口。
3.
点击“启动窗口”,等待实时数字人窗口显示出来。
4.
窗口启动完成后,再调用本文档中的接口。
注意:只打开主界面还不够,必须启动实时数字人窗口后,播报、切换形象、设置窗口等接口才会正常工作。

认证方式#

当前本地 FastAPI 接口没有 token、签名或登录鉴权。
如果部署在局域网或公网,请自行增加防火墙、网关鉴权、反向代理鉴权或内网访问限制。

请求格式#

POST 接口统一使用 JSON:

响应格式#

当前本地 API 没有统一的 code/message/data 包装格式。成功时直接返回业务 JSON,失败时 FastAPI 通常返回:
{
  "detail": "错误原因"
}

在线接口页面#

启动服务后可打开:
http://127.0.0.1:9090/docs

一、基础模块#

1.1 健康检查#

检查 FastAPI 服务是否启动。
接口地址
GET /health
请求参数
无
响应参数
参数类型描述
statusstring服务状态,正常时为 ok
Python 示例
cURL 示例
curl.exe -X GET "http://127.0.0.1:9090/health"
返回示例
{
  "status": "ok"
}

1.2 查询运行状态#

查询实时数字人当前是否运行、当前使用的处理器、当前形象和视频尺寸。
接口地址
GET /api/status
请求参数
无
响应参数
参数类型描述
statusstringrunning 运行中,stopped 已停止,not_initialized 未初始化
processorstring当前处理器,例如 heygem 或 wav2lip
character_namestring当前数字人形象 ID
current_video_dimensionsarray当前视频尺寸,格式通常为 [宽, 高]
Python 示例
cURL 示例
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"
}

二、播报模块#

2.1 音频驱动数字人播报#

使用音频驱动当前实时数字人播报。
接口地址
POST /api/process_audio
音频地址支持两种形式:
远程音频 URL:例如 https://example.com/demo.wav
运行数字人软件电脑上的本地路径:例如 D:\audios\demo.wav
如果业务系统和数字人软件不在同一台电脑上,本地路径必须是“运行数字人软件的电脑”能访问的路径,不是业务系统电脑上的路径。
请求参数
参数类型必填描述
audio_urlstring是音频 URL 或服务端本机音频路径,支持 mp3、wav 等常见音频格式
sr_origint否原始音频采样率,默认 44100
device_idxint/null否音频输出设备索引,不指定传 null
scaling_factorfloat否音频缩放系数,默认 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
}
响应参数
参数类型描述
statusstring成功时为 success
messagestring响应说明
qsizeint推入音频队列后的队列长度
push_statsobject最近一次音频推入统计信息,不同处理器字段可能不同
Python 示例:远程音频 URL
Python 示例:本机音频路径
cURL 示例:远程音频 URL
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 示例:本机音频路径
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"
}
说明:接口返回成功只表示音频已经进入处理队列,不代表数字人已经播报完成。如果需要知道播报结束,建议使用 WebSocket 接收 ActionId=1002。

三、数字人模块#

3.1 切换数字人形象#

切换当前实时数字人形象。
接口地址
POST /api/change_character
请求参数
参数类型必填描述
character_namestring是数字人形象 ID,通常为 项目类型/形象名
数字人形象示例
heygem/example
wav2lip/1080p(测试流畅度使用)
素材目录对应关系
avatars/heygem/example
avatars/wav2lip/1080p(测试流畅度使用)
Python 示例
cURL 示例
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"
}
注意:接口返回成功表示切换请求已提交到内部队列,不一定表示新形象已经完全加载完成。

3.2 获取数字人列表#

获取运行时维护的数字人列表。
接口地址
GET /api/characters
请求参数
无
响应参数
参数类型描述
statusstring成功时为 success
charactersarray数字人列表
Python 示例
cURL 示例
curl.exe -X GET "http://127.0.0.1:9090/api/characters"
返回示例
{
  "status": "success",
  "characters": []
}
注意:该接口返回当前运行时维护的数字人列表。如果接口返回空数组,请以软件界面中可选择的数字人形象为准。

3.3 训练数字人#

当前构建中该接口保留但禁用。
接口地址
POST /api/train_character
请求参数
参数类型必填描述
video_pathstring是视频文件路径,必须是运行数字人电脑可访问的路径
cyclebool否保留字段,默认 false
Python 示例
cURL 示例
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"
}

四、窗口模块#

4.1 设置实时窗口大小#

设置或取消固定实时数字人窗口尺寸。
接口地址
POST /api/set_window
请求参数
参数类型必填描述
widthint否窗口宽度,默认 720,必须大于 0
heightint否窗口高度,默认 1280,必须大于 0
flagbool否true 固定尺寸,false 取消固定
Python 示例
cURL 示例
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
  }
}

五、Python 调用脚本#

以下脚本可直接复制到你的业务系统中使用。使用前请先安装依赖:
pip install requests
使用步骤:
1.
先打开实时数字人软件,并启动实时数字人窗口。
2.
确认脚本中的 BASE_URL = "http://127.0.0.1:9090" 和软件界面中的 API 端口一致。
3.
将下方脚本保存到你的业务系统中,或直接复制其中的函数使用。
最小调用示例
使用本机音频路径
完整函数列表
函数作用
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()获取数字人列表
完整脚本源码

六、WebSocket 说明#

当前项目还包含 WebSocket 客户端逻辑。它不是等待别人连接,而是主动连接外部 WebSocket 服务:
ws://127.0.0.1:30003/human
ws://127.0.0.1:30004/human
...
ws://127.0.0.1:30012/human
外部系统如果需要接收播报结束通知,或使用 base64 音频数据推送,可以实现一个 WebSocket 服务。
常用 ActionId
ActionId方向说明
1010本项目 -> 外部服务通知当前数字人形象和处理器
1001外部服务 -> 本项目推送 base64 音频数据
1002本项目 -> 外部服务播报结束通知
1003外部服务 -> 本项目切换数字人形象
1004双向获取或返回数字人列表
1011外部服务 -> 本项目设置窗口尺寸
WebSocket 音频推送示例
{
  "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实时流服务未初始化或切换队列已满

常见问题#

1.
/health 正常,但 /api/process_audio 返回 503
说明 FastAPI 已启动,但实时流引擎或 DataLoader 还没准备好。请确认实时数字人窗口已经启动完成。
2.
传了本地路径,但提示 No audio file found
请确认路径是运行数字人程序那台电脑上的路径。如果业务系统在另一台机器,不能传业务系统本机路径。
3.
传远程 URL 失败
当前远程音频下载只支持 http 和 https,并且会拦截内网、回环、本地链路等地址,避免服务端请求伪造风险。
4.
请求体字段不符合模型
请对照本文档的参数表,只传接口支持的字段。音频播报请求体示例:
{
  "audio_url": "https://example.com/demo.wav"
}
5.
PowerShell 里 curl 表现奇怪
Windows PowerShell 里的 curl 可能是别名,建议使用:
curl.exe
修改于 2026-05-27 05:37:51
上一页
GPT-SoVITS2 语音模型训练教程
下一页
音频驱动
Built with