数字人服务API接口文档

文本转动画服务，支持输入文本，实时返回音视频&视频生产的功能，TTA服务与2D&3D服务间以websocket协议进行交互。
新增语音转动画功能，支持音频URL或音频流式输入，驱动数字人进行播报
新增推流至ByteRTC房间功能，实现1v1实时交互 ByteRTC介绍
新增推流至RTMP地址功能，实现数字人实时直播 视频云直播服务介绍

针对在控制台下单的数字人资产，在调用TTA接口时，

• 数字分身、精品形象定制：形象id填入role
• 形象租赁：在形象库中找到形象对应的role、clothes_type、pose_type
• 声音复刻：声音id填入voice_type

2.1 Client-Side

2.1.1 自定义配置字段说明

2.1.2 动作库说明

• 支持静默作为单个动作（例如3s）。支持<action type="LISTENING" time="3s" />或者<action type="LISTENING" time="3000ms" />两种格式，time最长为100s。使用该动作时time字段必填。（3D暂不支持）

• 所有动作都支持：播放动作时不播报。支持通过<action type="OK" is_silence="true" />控制动作单独呈现，is_silence默认值为false，即默认边播报边做动作。（3D暂不支持）

2.1.3 插入图片/视频说明

<speak>
    <image url='url_1' left='100' top='100' height='100' width='100' level='1'>
        这是图片内的文本
    </image>
</speak> <!-- 单张图片显示-->


<speak>
    <image mode='opening' track_id='1' url='url_1' left='100' top='100' height='100' width='100' level='1'/>
        这是图片内的文本
    <image mode='closing' track_id='1'/>
</speak> <!-- 效果等同于第一个-->


<speak>
    <image mode='opening' track_id='1' url='url_1' left='100' top='100' height='100' width='100' level='1'/>
    <image mode='opening' track_id='2' url='url_2' left='200' top='200' height='200' width='200' level='2'/>
        这是图片内的文本
    <image mode='closing' track_id='2'/>
    <image mode='closing' track_id='1'/>
</speak> <!-- 多张图片显示-->


<speak>
    <image mode='opening' track_id='2' url='url_2' left='200' top='200' height='200' width='200' level='2'/>
    <image url='url_1' left='100' top='100' height='100' width='100' level='1'>
        这是图片内的文本
    </image>
    <image mode='closing' track_id='2'/>
</speak> <!--混合使用-->

<speak>
    <image url='url_1' left='100' top='100' height='100' width='100' level='1'>
        <image mode='opening' track_id='2' url='url_2' left='200' top='200' height='200' width='200' level='2'/>
        这是图片内的文本
        <image mode='closing' track_id='2'/>
    </image>
</speak> <!--混合使用-->

2.1.4 词条精修

当前支持在传入文本时通过标签进行词条精修，具体支持的标签为

2.1.5 切换镜头 （仅3D支持）

支持3种镜头切换：3dCameraFrontAll、3dCameraFrontHalf、3dCameraFrontFace
例：那就让我们赶快看看今天有哪些<camera mode='Camera3D' scene='3dCameraFrontFace' sensor_height='36.0'/>好物，首先给大家介绍的这款手机。<camera mode='Camera3D' scene='3dCameraFrontHalf' sensor_height='36.0'/>哈喽，直播间的宝宝们，小琦刚跑完5公里，元气满满的跟大家见面啦，我可是一个很烫很烫的科技发烧友，对智能产品<camera mode='Camera3D' scene='3dCameraFrontAll' sensor_height='36.0'/>非常懂行的呦。

2.1.6 切换背景 （仅3D支持）

支持在ssml文本中控制背景图切换
例：<background type='image' url='https://lf3-speech.bytetos.com/obj/speech-tts-external/ec-live/xiaomi_whole_body.jpeg' transition_effect='shutters' scene_levelmap='0'/>那就让我们赶快看看今天有哪些好物。

2.2 Server-Side

2.2.1 消息帧字段描述

2.2.1.1 错误码

2.2.1.2 消息类型

2.2.2 支持I帧调整

调整I帧间隔通过在初始化参数中通过I_frame_interval指定。

示例

{
    "video":{
        "video_width":1080,
        "video_height":1920,
        "I_frame_interval":25
    },
    "role":"XiaoYu",
    "role_conf":{
        "voice_type":"BV009_DPE_ParaTaco"
    },
    "input_mode":"text"
}

2.2.3 支持码率调整

在交互过程中需要调整bitrate时通过chat接口指定。
原chat接口格式形如

|CTL|02|"今天天气真不错"

通过扩展chat接口支持bitrate调整。扩展后chat接口为|CTL|02|{json_string}，json格式为

{
  "bitrate": 400, //int类型，单位为kbps，为空时不设置，合法范围是([400，5000]）
}

即交互时使用原接口格式，调整bitrate时使用json格式。

2.2.4 支持视频创作场景添加字幕

2.2.4.1 使用方法

• 当前仅支持在视频创作场景下添加字幕，实时流场景暂不支持

• 添加字幕时需要在初始化参数指定video["subtitle_control"]=true

• 文本驱动模式下（input_mode=text），字幕信息均从传入文本中获得

• 音频驱动模式下（input_mode=audio），字幕信息需要在传入音频通过subtitle标签传入，示例如|CTL|02|<speak><audio url="http://xxxx/test.mp3" format="mp3"/><subtitle text="今天天气真不错"/></speak>

• 当前仅在文本驱动模式下支持设置多种字幕效果，通过扩展chat接口传入。支持的效果设置及其字段说明如下：

json示例如

{
    "text":"<speak>今天天气真不错</speak>",
    "subtitle": {
        "global_style": {
            "fontname": "Source Han Serif CN",
            "fontsize": 18,
            "bold": true,
            "italic": true,
            "underline": true,
            "primary_colour": "0000ff00",
            "outline_colour": "0000ff00",
            "back_colour": "0000ff00",
            "margin_l": 100,
            "margin_r": 100,
            "margin_v": 140
        }
    }
}

传入的字幕效果是全局生效的，不针对单句字幕生效

2.2.4.2 支持的字幕字体

• 文本驱动场景下，可以通过传递fontname设置不同的字幕字体，当前支持的所有字幕字体包括：

2.2.4.3 支持输出字幕及其时间信息

• 视频创作的字幕场景下，可以在输出视频获得所有字幕事件回调信息，包括：voice_start、subtitle_on、subtitle_off、voice_end、all_subtitles 五种

• 事件通过|DAT|02|传递，可通过type字段区分是哪种类型事件，消息格式为：

示例：

• 传入文本为<speak>今天天气真不错，好想出去玩。玩什么呐？钓钓鱼，看看花享受大自然。</speak>

• 对应的字幕事件：

{
    "callback_info": {
        "data": {
            "subtitles": [
                {
                    "end_time_ms": 2880,
                    "start_time_ms": 0,
                    "text": "今天天气真不错，好想出去玩。"
                },
                {
                    "end_time_ms": 4000,
                    "start_time_ms": 2880,
                    "text": "玩什么呐？"
                },
                {
                    "end_time_ms": 6760,
                    "start_time_ms": 4000,
                    "text": "钓钓鱼，看看花享受大自然。"
                }
            ]
        },
        "type": "all_subtitles" 
    }
}

• 字段信息说明：

• 文本驱动模式下（input_mode=text）时句维度的字幕时间信息均从文本中获得

• 音频驱动模式下字幕信息需要在传入音频通过subtitle标签传入，且音频驱动模式暂不支持获得每句播报音频的准确时间信息，只能输出单句传入字幕的开始、结束时间信息，且字幕结束时间为实际获得的音频时长。

2D

协议：WebSocket
接口地址：wss://openspeech.bytedance.com/api/v1/volc_virtual_human/tta/2d?appid={appid}&access_token={token}
使用接口前需要申请appid和具体使用的形象

3D

协议：WebSocket
接口地址：wss://openspeech.bytedance.com/api/v1/volc_virtual_human/tta/3d?appid={appid}&access_token={token}
使用接口前需要申请appid和具体使用的形象

视频生产

适合仅同步生产数字人视频使用，支持mp4/mov/webm等格式，生产耗时约为视频时长*0.7左右。

实时交互

• 适合实时交互场景，数字人服务直接将数字人实时音视频流推送至ByteRTC房间

• 使用RTC作为链路传输协议，链路延迟较低，在数字人接收到驱动命令至端上音视频展示延迟<1s

• 客户端RTC SDK自带播放功能，客户侧需要根据场景，集成不同的ByteRTC客户端(web/windows/android/iOS)，可以将数字人的音视频流进行渲染和播放。火山引擎侧RTC介绍

• 请求中不能配置codec字段

• 请求中必须携带rtc的相关配置，示例如下：

|CTL|00|{"role":"xx","rtc":{"app_id":"xxx","room":"xxx","uid":"xx","token":"xxx"}}

• 由于RTC同一个房间内不能使用相同的uid，因此客户在拉流时，使用的uid不能与数字人请求中rtc参数中的uid一样

实时直播

• 适合直播场景，数字人服务直接将数字人实时音视频流推送至RTMP地址

• 使用RTMP作为传输链路协议，链路延迟相对较大，在数字人接收到驱动命令至拉流地址展示延迟在5s左右

• 客户端通过RTMP拉流地址获取数字人音视频流，进行展示和播放。VePlay具备拉取RTMP地址&播放功能

• 推拉流地址可以从火山视频云产品上申请

• 请求中不能配置codec字段

• 请求中必须携带rtmp的相关配置，示例如下：

|CTL|00|{"role":"xx","rtmp":{"addr":"rtmp://xxxxx","live_id":"xxx"}}

5.1 视频生产

5.1.1 Python

# coding=utf-8

import websockets
import asyncio
import json

SUCC_CODE = 1000
ILLEGAL_PARAM_CODE = 1001
SRV_BUSY_CODE = 1002
INNER_ERR_CODE = 1003
OTHER_ERR_CODE = 1004

AUDIO_DATA_HEADER = "|DAT|00|"
VIDEO_DATA_HEADER = "|DAT|01|"
JSON_DATA_HEADER = "|DAT|02|"
SELF_DATA_HEADER = "|DAT|03|"
SELF_DATA_END_HEADER = "|DAT|04|"

MSG_HEADER = "|MSG|00|"

OPEN_SESSION_HEADER = "|CTL|00|"
CLOSE_SESSION_HEADER = "|CTL|01|"
CHAT_HEADER = "|CTL|02|"

VOICE_START = "voice_start"
VOICE_END = "voice_end"
VIDEO_URL = "video_url"

conn_header = {"Resource-Id": "volc.avatar.2d"}

# 这部分需要授权下发，根据实际值进行替换
appid = "xxxx"
token = "xxxx"

uri = f"wss://openspeech.bytedance.com/api/v1/volc_virtual_human/tta/2d?appid={appid}&access_token={token}"
uid = "avatar_py_demo"
codec = "mp4"

# 使用说明：测试前替换为具体使用的形象
role = "xxx"
pose = ""
clothes = ""

param = json.dumps({
    "uid": uid,
    "role": role,
    "codec": codec,  # 视频生产需要传codec，实时场景不需要传codec
    "role_conf": {
        "pose_type": pose,
        "clothes_type": clothes
    },
    "output_url": True
})


def parse_event(data):
    obj = json.loads(data)
    info = obj["callback_info"]
    return info["type"], info["data"]


async def generate_video(text):
    try:
        # 建立连接
        print("start to connect {}".format(uri))
        async with websockets.connect(uri, extra_headers=conn_header) as ws:
            # 开启session
            data = OPEN_SESSION_HEADER + param
            print(f"<- {data}")
            await ws.send(data)
            data = await ws.recv()
            print(f"-> {data}")
            # 发送需要播报的文本
            data = CHAT_HEADER + text
            print(f"<- {data}")
            await ws.send(data)
            while True:
                data = await ws.recv()
                header = data[0:8]
                if type(data) is str:
                    print(f"-> {data}")
                # 事件相关回调
                if header == JSON_DATA_HEADER:
                    event, event_data = parse_event(data[8:])
                    if event == VOICE_END:
                        # 关闭session，等待视频合成
                        print(f"<- {CLOSE_SESSION_HEADER}")
                        await ws.send(CLOSE_SESSION_HEADER)
                    elif event == VIDEO_URL:
                        url = event_data["video_url"]
                        print(f"\n Video produce success, url: {url}")
                        break
                # 控制指令相关回调
                elif header == MSG_HEADER:
                    msg = json.loads(data[8:])
                    if msg["code"] != 1000:
                        break
    except websockets.exceptions.ConnectionClosed as e:
        print(f"Connection closed, code: {e.code}, reason: {e.reason}")


async def generate_stream(text):
    audio_file = open("test.pcm", "wb")
    video_file = open("test.h264", "wb")
    try:
        # 建立连接
        async with websockets.connect(uri, extra_headers=conn_header) as ws:
            # 开启session
            data = OPEN_SESSION_HEADER + param
            print(f"<- {data}")
            await ws.send(data)
            data = await ws.recv()
            print(f"-> {data}")
            # 发送需要播报的文本
            data = CHAT_HEADER + text
            print(f"<- {data}")
            await ws.send(data)
            while True:
                data = await ws.recv()
                header = data[0:8]
                if type(data) is str:
                    print(f"-> {data}")
                # 事件相关回调
                if header == JSON_DATA_HEADER:
                    event, _ = parse_event(data[8:])
                    # 开始播报的事件
                    if event == VOICE_START:
                        pass
                    # 结束播报的事件
                    elif event == VOICE_END:
                        # 关闭session
                        print(f"<- {CLOSE_SESSION_HEADER}")
                        await ws.send(CLOSE_SESSION_HEADER)
                        break
                # 控制指令相关回调
                elif header == MSG_HEADER:
                    msg = json.loads(data[8:])
                    if msg["code"] != 1000:
                        break
                # 二进制相关数据回调
                else:
                    # 获取pcm格式音频数据
                    if bytes.decode(header) == AUDIO_DATA_HEADER:
                        audio_file.write(data[8:])
                    # 获取h264格式视频数据
                    elif bytes.decode(header) == VIDEO_DATA_HEADER:
                        video_file.write(data[8:])
    except websockets.exceptions.ConnectionClosed as e:
        print(f"Connection closed, code: {e.code}, reason: {e.reason}")
    finally:
        audio_file.close()
        video_file.close()


if __name__ == '__main__':
    asyncio.get_event_loop().run_until_complete(generate_video("今天天气真不错。"))

5.1.2 Java