AnimaCore API介绍

1 min read

概述 #

本接口用于连接UE端和AnimaCore服务器，实现UE端和服务端的双向通信。客户端可以发送文本、音频等消息，服务器将返回对应的Metahuman角色面部动画曲线数据。

您可以使用本接口构建完整的本地客户端，也可以将其嵌入到您的工作流中。例如您可能已经实现了llm交互或者语音交互，那么您只需要调用特定的功能或者模式即可。

您无法通过API直接获取在UE引擎中可播放的动画/实时动画/动画序列，服务器端只返回动画/音频/文本的原始数据。如果您需要直接获取动画，可以使用我们的UE插件MHC Talker。

💡 本接口面向有一定开发能力的个人/团队，需要对UE引擎有较为深入的了解。

💡 本项目处于开发阶段，逻辑和功能上并不完善。API可能随时更改，我们会尽量同步更新本文档。

如果您需要第一时间获取API变动信息，可以加入我们的微信交流群。

连接信息 #

服务器客户端之间使用websocket协议进行通信

URL #

wss://yxintv.top:9876/ws/{session_id}

💡 session_id目前需要客户端实现一个12位的随机字符串，同一个session id会被视为同一次会话（同一个websocket连接）。

查询参数 #

参数	类型	值	说明
`token`	`String`		验证令牌在账户中获取
`interact_type`	`String`	`'chat'`: 聊天模式,返回的文本由语言模型生成`'read'`: 阅读模式，返回的文本是用户输入本身	缺省值为`'chat'`，您可以在后续的每一轮对话中随时修改
`msg_type`	`String`	`'text'`: 文本交互`'bytes'`: 声音交互	缺省值为`'text'`，您可以在后续的每一轮对话中随时修改
`ani`	`String`	`'JESSE'`: `'SHIYAO'`: `'SHIYAO_V2''SHIYAO_EMO'`	`'SHIYAO'`模型包含头部运动`'JESSE'`模型不包含头部运动`'SHIYAO_V2'`为原始SHIYAO模型在更大的数据集上重新训练的模型`'SHIYAO_EMO'`为情绪模型的测试版本
`tts`	`String`	`'AZURETTS'`: 微软语音合成服务`'COSYVOICE'`: 阿里云语音合成服务`'GPTSOVITS'`: 服务器端本地语音合成	缺省值为`'GPTSOVITS'`，本地tts模型目前只做测试用，不具备商业项目的能力。您可以在后续的每一轮对话中随时修改。
`llm_model`	`String`	`'qwen-turbo'`: 通义千问大模型接口	目前只有一个语言模型接口，会陆续添加更多，缺省即可。
`role`	`String`	目前支持微软azure和阿里云dashscope语音合成服务中的角色名称，例如’zh-CN-XiaoxiaoNeural’，需要选择对应的`tts`服务。	`tts`值为`'AZURETTS'`时缺省值为’zh-CN-XiaoxiaoNeural’，即微软“晓晓”。您可以在后续的每一轮对话中随时修改。完整的角色支持列表参见azure文档:Azure AI services `tts`值为`'COSYVOICE'`时缺省值为’longxiaochun’，即阿里“龙小淳”。您可以在后续的每一轮对话中随时修改。完整的角色支持列表参见dashscope文档:阿里云帮助中心
`is_greeting`	`String`	`'true'` `'false'`	首次连接服务端是否返回欢迎语。
`prmpt`	`String`		llm的系统提示词，或者角色人设。base64编码。
`emo`	`Int`	`-1`：自动`0`：不满`1`：兴奋`2`：平静	角色动画的面部情绪，这个字段目前只在`'SHIYAO_EMO'`模型中起效值为`-1`时，服务端会尝试分析文本和音频的情感类别。
`emo_s`	`Float`	`0.0-1.0`	情绪强度，1为最高。

💡 音频消息目前仅支持16k采样，单声道，16bit的wav格式的音频。

示例： #

连接服务器并将交互模式设为阅读模式，消息类型设为音频

wss://yxintv.top:9876/ws/h6ssd23t34e8?token=123456&interact_type=read&msg_type=bytes

收发消息 #

一旦建立连接，客户端会收到服务器发送的欢迎语“你好，……..”，包含的全部字段见下文。

之后客户端可以向服务端发送消息。

客户端消息和服务器消息均为json格式。

客户端消息发送 #

字段： #

字段	类型	值	说明
`token`	`String`		验证令牌
`message_id`	`String`	长度为12位的随机字符串	需要客户端实现。同一个`message_id`会被视为同一轮（一问一答）对话
`interact_type`	`String`	`'chat''read'`	覆盖查询参数中对应的值
`msg_type`	`String`	`'text''bytes'`	覆盖查询参数中对应的值
`text`	`String`		(`msg_type`值为`'text'`时)用于交互的文本
`bytes`	`String`		(`msg_type`值为`'bytes'`时)用于交互的音频，base64编码
`ani`	`String`	`'JESSE'`: `'SHIYAO'`: `'SHIYAO_V2''SHIYAO_EMO'`	`'SHIYAO'`模型包含部运动`'JESSE'`模型不包含头部运动`'SHIYAO_V2'`为原始SHIYAO模型在更大的数据集上重新训练的模型`'SHIYAO_EMO'`为情绪模型的测试版本
`tts`	`String`	`'AZURETTS''GPTSOVITS''COSYVOICE'`	覆盖查询参数中对应的值
`role`	`String`		覆盖查询参数中对应的值
`is_greeting`	`String`	`'true'` `'false'`	首次连接服务端是否返回欢迎语。
`prmpt`	`String`		llm的系统提示词，或者角色人设。base64编码。
`emo`	`Int`	`-1`：自动`0`：不满`1`：兴奋`2`：平静	角色动画的面部情绪，这个字段目前只在`'SHIYAO_EMO'`模型中起效值为`-1`时，服务端会尝试分析文本和音频的情感类别。
`emo_s`	`Float`	`0.0-1.0`	情绪强度，1为最高。

💡 音频消息目前仅支持16k采样，单声道，16bit的wav格式的音频。

示例： #

{
    "token": "123456",
    "message_id":"d8rt653gh8gh",
    "interact_type": "chat",
    "msg_type": "text",
    "text": "现在是文本聊天模式。",
    "tts": "AZURETTS",
    "role": "zh-CN-XiaoxiaoNeural"
    
}

服务端消息返回 #

收到客户端请求时，服务端会返回一个json，表示任务开始处理。在低延迟环境下，也可以忽略这个消息：

{
    "task_id": message_id,
    "status": "pending"
}

然后服务端开始处理，当产生处理结果时，会陆续发送处理结果。目前服务端会将结果逐句处理、逐句发送。

字段： #

字段	类型	值	说明
`message_id`	`String`		客户端发送的`message_id`
`text`	`String`		文本内容
`audio`	`String`		文本内容对应的音频，base64编码
`animation`	`Json`		文本和音频对应的面部动画。json格式
`user_id`	`String`		用户名
`emo`	`String`		情绪信息，测试阶段，目前返回的值没有具体意义
`is_first`	`Bool`	`TrueFalse`	是否为一轮对话的第一句
`is_end`	`Bool`	`TrueFalse`	该轮对话是否结束
`duration`	`Float`		该句动画实际时长，30帧/秒
`X_time`	`Json`		服务端处理用时
`status`	`String`	`'pending''processing''done'`	消息处理状态
`remaining_time`	`int`		用户账户剩余生成动画时长，秒
`remaining_day`	`int`		用户账户过期剩余时长，天

💡 目前服务器端返回的音频为16k，单声道，16bit的不包含格式头的原始字节(raw)。需要客户端自行处理音频格式问题。

💡 微软的东亚服务器在高峰期可能遇到非常高的延迟，导致整体的回复速度变慢。我们也在解决这个问题，近期可能会添加更多的TTS引擎进行测试。

💡 2024/08/08 增加了阿里云tts引擎。

💡 2024/09/ 更新微软TTS为国内服务器（之前为亚洲服务器），大幅度降低了推理延迟。

animation字段 #

animation字段中的数据基本上是按照UE引擎中Curve Table数据类型的格式要求进行构建的，其中每一条曲线代表了一个Metahuman控制器，曲线的值代表了该控制器的运动状态。附件”UE_curve_table.json”可以直接转化为一个UE引擎中的Curve Table。您可以下载之后将其拖入UE编辑器即可。

UE_curve_table 下载

UE的Curve Table要求每一个曲线有一个”name”字段来标识曲线名称，在实际传输过程中，我们将”name”字段替换为了”ID”，并使用一个int类型的编号来区分不同的曲线，然后在客户端中重新将”ID”映射为”name”，这么做的初衷是为了减少传输数据量，因为曲线名称通常比较长。但是随着项目进行，使用”ID”所减少的数据量几乎可以忽略，我们计划在将来修改它，服务器端可以直接传输曲线名称而不需要客户端再做映射。

但是目前仍然需要在客户端中将”ID”映射为”name”，您可以在这里下载需要用到的键值对json文件：

ID_to_curve_name 下载

这个json文件包含了Metahuman中用于控制头部运动的全部276根曲线的名称和对应的ID。

示例： #

下面是一个完整的服务器端返回json的示例文件。

（你好！有什么我可以帮助你的吗？）

response 下载

下面是经过简化的服务器返回json示例，省略了audio和animation字段：

{
    "text": "\u4f60\u597d\uff01\u6709\u4ec0\u4e48\u6211\u53ef\u4ee5\u5e2e\u52a9\u4f60\u7684\u5417\uff1f",
    "audio": "AQAAAAAAAAA....",
    "animation": {
      "AnimArray": [
          {
              "ID": 0,
              "0.0": 0.0,
              "0.0333": 0.0,
          },
          {
              "ID": 1,
              "0.0": 0.0,
              "0.0333": 0.0,
          }
      ]
    },
    "user_id": "Onlooker",
    "message_id": "123456aaa",
    "emo": [],
    "is_end": false,
    "is_first": true,
    "duration": 5,
    "status": "processing",
    "remaining_time": 192273,
    "x_time": {
        "llm_infer": 0.5445709228515625,
        "asr_process": 0,
        "vc_process": null,
        "tts_process": 1.1153051853179932,
        "ani_process": 0.2299818992614746,
        "all_time": 1.6371128559112549
    }
}

服务器会逐句返回处理结果，直到本轮对话结束。

对话结束 #

一轮对话结束时，服务器端会额外发送一个json用于将动画的结束状态过渡到默认状态，json的字段格式与上面的示例相同。在这个json中，status字段的值为’done’，is_end字段的值为True。

该json文件中的text字段和audio字段的值为空。

更新日志： #

2025/03/31

新增了新模型字段

新增了新的查询参数

新增了新的请求字段

更新了新的微软AZURE和阿里云百炼的文档地址

更新了部分描述

2024/08/08

增加了对话结束json的描述

增加了新tts字段的描述

增加了新role字段的描述

增加了新animation模型的描述

2024/08/05

首次提交文档

更新 2025年10月19日

服务端

您的感觉是什么

快乐
常规
悲哀

MHC Talker-UE

AnimaCore服务端

AnimaCore API介绍

概述 #

连接信息 #

URL #

查询参数 #

示例： #

收发消息 #

客户端消息发送 #

字段： #

示例： #

服务端消息返回 #

字段： #

animation字段 #

示例： #

对话结束 #

更新日志： #

概述 #

连接信息 #

URL #

查询参数 #

示例： #

收发消息 #

客户端消息发送 #

字段： #

示例： #

服务端消息返回 #

字段： #

animation字段 #

示例： #

对话结束 #

更新日志： #

分享这篇文章 ：

分享这篇文章：