配置项目

1.接口说明

项目创建成功后，可以调用该接口更新项目，配置制作视/音频时需要的属性，包括人像、声音、背景、贴纸、音频和字幕等。

1.4.0版本起，项目场景中使用以下类型素材时，支持使用素材链接做为参数。

音频驱动：驱动音频
图片数字人
图片背景
视频背景
图片贴纸

注：使用素材链接参数时，需要保障链接可以正常访问下载，若素材链接无效，会导致作品合成失败。

2.请求地址

https://digitbot.bokecc.com/api/project/update

3.请求方式

POST application/json

4.请求参数

(1).公共参数，参考服务说明。

(2).接口参数

①.Query参数：通过URL参数传递。

参数名	类型	必需	说明
version	String	是	接口版本号，当前支持版本：1.0.0、1.1.0、1.3.0、1.4.0、1.5.0
projectId	String	是	项目ID，创建项目时返回的唯一身份标识。

②.Body参数：通过请求Body传递，JSON格式。

参数名	类型	必需	说明	版本变更
name	String	否	项目名称，最长支持20个字符。无参数值时，不更新项目名称。
videoWidth	Integer	否	视频宽度，像素值，正偶数值。无参数值时，不更新视频宽度。
videoAspect	String	否	视频比例，宽高比，w:h格式。无参数值时，不更新视频比例。
scenes	Array	否	项目中的场景(scene)列表，按先后顺序排列。无参数值时，使用默认属性构造一个场景。
subtitlesStyle	Object	否	字幕样式。无参数值时，表示不开启字幕功能。
tailFrameUrl	String	否	视频结尾帧图片链接。支持jpg、jpeg、png等图片格式。无参数值时，表示不设置结尾帧。	2025-12-24：新增

videoWidth、videoAspect：视频宽度和视频比例，在制作视频时有效，用于指定输出视频的尺寸。
- 制作视频时，根据videoWidth和videoAspect计算出videoHeight。
- videoHeight和videoWidth一样要求是正偶数值，videoHeight计算结果不是偶数时，采用+1的方式补齐为偶数。
scenes：项目中允许包含多个场景，每个场景可独立设置属性，合成视/音频片段，最终合并成一个完整的视/音频文件。
- 更新项目时，要求一次性传递所有场景的参数，会根据参数中传递的场景属性，重新构建项目中的全部场景。
- 无参数值，或传递空列表时，会清除项目中已存在的所有场景，使用默认属性构造一个场景。
subtitlesStyle：制作视频时，支持字幕功能，可以设置字幕样式，包括字体、字号、颜色、位置等。
- 更新项目时，会根据参数中传递的属性，重新构建字幕样式。
- 无参数值时，表示不开启字幕功能，会清除之前已经设置过的字幕样式。
tailFrameUrl：设置视频结尾的帧图像，仅支持URL链接形式。
- 结尾帧设置，仅在只有一个场景，且场景中使用图文数字人时生效。

scene参数说明

参数名	类型	必需	说明
driverType	Integer	是	驱动类型，枚举值。0=文本驱动；1=音频驱动。0：文本驱动，提供文本数据，生成声音内容，制作视/音频。1：音频驱动，上传音频文件，作为声音内容，制作视/音频。
textDriver	Object	否	文本驱动内容。driverType=0时有效，此项为必需。
audioDriver	Object	否	音频驱动内容。driverType=1时有效，此项为必需。
portraitModel	Object	否	场景中应用的人像模型信息。无参数值时，表示没有使用人像模型。
voiceModel	Object	否	场景中应用的声音模型信息，文本驱动场景时为必需项。无参数值时，表示没有使用声音模型。
background	Object	否	场景背景信息。无参数值时，使用默认颜色背景。
stickers	Array	否	场景中应用的贴纸信息(sticker)列表，包括图片、PPT贴纸、线条。
coordinates	Array	否	场景中应用的部件坐标信息(coordinate)列表，包括人像、贴纸等。按由远及近顺序排列。
subtitles	Array	否	场景中应用的字幕信息(subtitle)列表，按字幕先后顺序排列。

coordinates：描述场景中应用部件的坐标属性，包括各部件的坐标位置、大小、文本标记位置等。
- 可设置坐标属性的部件包括：人像、图片贴纸、PPT贴纸、线条贴纸等。
- 关于排列顺序，场景中应用的每一个部件各自属于一个层级，层级越深，部件距离观看者越远。
- 参数中的部件按由远到近的顺序排列。
单个场景中各种部件应用数量的限制
- 人像：1个。
- 背景：1个，颜色、图片背景、视频背景，三选一。
- 贴纸：20个，图片贴纸和线条贴纸共计20个。
- PPT贴纸：1个。

scene.textDriver参数说明

参数名	类型	必需	说明	版本说明
text	String	是	文本内容，最少1个字符，最多支持20000个字符。JSON格式文本，参考附2.JSON格式文本说明。	1.5.0之前：只支持纯文本，输入的所有内容当作纯文本内容处理。1.5.0起：使用JSON格式文本，支持多音字标记、插入停顿、数值标记等。
speed	Float	否	文本合成声音内容时的语速倍数。取值在[0.6, 1.5]区间内，支持两位小数。1.00表示标准语速。默认值：1.00。
volume	Float	否	文本合成声音内容时的音量。取值在[1.0, 2.0]区间内，支持一位小数。1.0表示正常音量，2.0表示最大音量。默认值：1.0。

scene.audioDriver参数说明

参数名	类型	必需	说明	版本说明
audioId	String	否	用户上传的驱动音频ID。详见音频和字幕管理模块的创建驱动音频接口。useUrl=false时有效，该参数必需。	1.4.0之前：该参数必需
useUrl	Boolean	否	是否使用驱动音频素材链接。true时表示使用。默认值：false。	1.4.0：新增参数
audioUrl	String	否	驱动音频素材链接，支持mp3、wav、flac、wma、aac等常见音频格式。useUrl=true时有效，该参数必需。	1.4.0：新增参数

scene.portraitModel参数说明

参数名	类型	必需	说明	版本说明
type	Integer	是	场景中应用的人像模型类型，枚举值。0=模特人像；1=自定义人像。
modelId	String	否	人像数字人ID。type=0：模特人像，该参数必需。参考数字人管理模块的查询模特人像列表接口。type=1：自定义人像，useUrl=false时，该参数必需。参考数字人管理模块的查询定制人像列表接口。	1.0.0、1.1.0：自定义人像指专属口型人像数字人1.3.0起：自定义人像支持以下类型：专属口型人像、通用口型人像、图片数字人1.4.0之前：该参数必需
useUrl	Boolean	否	是否使用数字人素材链接，支持图片数字人和图文数字人。true时表示使用。type=1时有效。默认值：false。	1.4.0：新增参数。2025-11-17：变更。
modelUrl	String	否	数字人素材链接，支持jpg、jpeg、png等图片格式。type=1且useUrl=true时有效，该参数必需。	1.4.0：新增参数。
urlType	Integer	否	链接数字人类型，枚举值。2=图片数字人；7=图文数字人。type=1且useUrl=true时有效。默认值：2。	2025-11-17：新增。
facialFeature	Integer	否	链接图片数字人面部特征，枚举值。1=真人；2=卡通。type=1，useUrl=true且urlType=2（默认）时有效，该参数必需。	1.4.0：新增参数。2025-11-17：更新。
promptType	Integer	否	链接图文数字人模型提示词类型。枚举值。0=自定义提示词；1=系统内置说话模式提示词；2=系统内置唱歌模式提示词。type=1，useUrl=true且urlType=7时有效（暂不支持图文数字人上传训练）。默认值：1=说话模式。	2025-11-17：新增。
promptText	String	否	链接图文数字人自定义模型提示词。promptType=0时有效，且该参数必需。	2025-11-17：新增。
negativePrompt	String	否	链接图文数字人负面提示词，描述不想出现的内容，用来避免出现不希望的效果。type=1，useUrl=true，且urlType=7时有效。	2025-11-17：新增。
matting	Integer	否	图文数字人是否抠图，枚举值。0=不抠图；1=绿幕抠图；2=实景抠图。默认值：0	2025-12-24：新增。

matting：如输入图片是带有alpha通道的PNG，我们会直接用alpha通道作为抠图的结果。

scene.voiceModel参数说明（1.0.0）

参数名	类型	必需	说明	版本说明
type	Integer	是	场景中应用的声音模型类型，枚举值。0=AI声音；1=自定义声音。	1.0.0：自定义声音指多语言版声音模型
modelId	String	是	声音数字人ID。type=0：AI声音，系统预置的AI声音模型，参考数字人管理模块的查询AI声音列表接口。type=1：自定义声音，参考数字人管理模块的查询定制声音列表接口。
voiceStyleId	String	否	声音风格ID。参考数字人管理模块的查询声音风格列表接口。driverType=0且voiceModel.type=1时，需要选择声音风格，此项为必需。

scene.voiceModel参数说明（1.1.0起）

参数名	类型	必需	说明	版本说明
type	Integer	是	场景中应用的声音模型类型，枚举值。0=AI声音；1=多语言版模型声音；2=专属定制版模型声音。注：专属定制版模型声音只适用于文本驱动。	1.1.0起：定制声音区分多语言模型和专属定制版模型
modelId	String	是	声音数字人ID。type=0：AI声音，系统预置的AI声音模型，参考数字人管理模块的查询AI声音列表接口。type=1：多语言版模型声音，参考数字人管理模块的查询定制声音列表接口。type=2: 专属定制版模型声音, 参考数字人管理模块的查询定制声音列表接口。
voiceStyleId	String	否	声音风格ID。参考数字人管理模块的查询声音风格列表接口。driverType=0且voiceModel.type=1时有效，需要选择声音风格，此项为必需。

scene.background参数说明

参数名	类型	必需	说明	版本说明
type	Integer	是	背景类型，枚举值。0=颜色；1=图片；2=视频。默认值：0。
color	String	否	背景颜色，值为十六进制RGB颜色代码，支持RRGGBB或#RRGGBB格式。type=0时有效，默认：#FFFFFF。
backgroundId	String	否	背景ID。type!=0且useUrl=false时有效，该参数必需。type=1：使用图片背景。可以是预置图片背景，参考背景管理模块中查询预置图片背景列表接口。可以是自定义图片背景，参考背景管理模块中查询自定义图片背景列表接口。type=2：使用视频背景。参考背景管理模块中查询自定义视频背景列表接口。	1.4.0之前：type!=0时必需
useUrl	Boolean	否	是否使用背景素材链接。true时表示使用。默认值：false。	1.4.0：新增参数。
backgroundUrl	String	否	背景素材链接。type!=0且useUrl=true时有效，该参数必需。type=1时，表示图片背景素材链接，支持jpg、jpeg、png等图片格式。type=2时，表示视频背景素材链接，支持mp4格式。	1.4.0：新增参数。

scene.stickers.sticker参数说明

参数名	类型	必需	说明	版本说明
type	Integer	是	贴纸类型，枚举值。0=图片；1=PPT；2=线条。
stickerId	String	否	贴纸ID。type=0：使用图片贴纸。useUrl=false时有效，该参数必需。可以是预置的图片贴纸，参考贴纸管理模块中查询预置图片贴纸列表接口。可以是自定义图片贴纸，参考贴纸管理模块中查询自定义图片贴纸列表等接口。type=1：使用PPT贴纸。参考PPT(贴纸)管理模块中查询PPT图片(贴纸)列表接口。该参数必需。type=2：使用线条贴纸。参考贴纸管理模块中查询预置线条贴纸列表接口。该参数必需。	1.4.0之前：该参数必需
useUrl	Boolean	否	是否使用图片贴纸素材链接。true时表示使用。默认值：false。	1.4.0：新增参数。
stickerUrl	String	否	图片贴纸素材链接，支持jpg、jpeg、png等图片格式。type=0且useUrl=true时有效，该参数必需。	1.4.0：新增参数。

scene.coordinate参数说明

参数名	类型	必需	说明	版本说明
type	Integer	是	部件类型，枚举值。1=人像；21=图片贴纸；22=PPT贴纸；23=线条贴纸。
entityId	String	否	部件ID。type=1：人像模型数字人ID，和 portraitModel中的modelId关联，useUrl=false时，该参数必需。type=21：图片贴纸ID，和sticker中的stickerId关联，useUrl=false时，该参数必需。type=22：PPT贴纸ID，和sticker中的stickerId关联，该参数必需。type=23：线条贴纸ID，和sticker中的stickerId关联，该参数必需。	1.4.0之前：该参数必需
useUrl	Boolean	否	部件是否使用素材链接。true时表示使用。默认值：false。	1.4.0：新增参数。
entityIndex	Integer	否	部件索引编号。useUrl=true时，该参数必需。type=1：场景中只有一个人像，使用固定值0。type=21，对应图片贴纸在scene.stickers数组中的下标索引，从0开始计算。	1.4.0：新增参数。
width	Integer	是	部件宽度，像素值。指在输出视频中，部件经过缩放后的宽度。
height	Integer	是	部件高度，像素值。指在输出视频中，部件经过缩放后的高度。
x	Integer	是	部件坐标x，像素值。指在输出视频中，部件的水平方向位置。以视频左上角为原点，部件左上角顶点定位，即部件左上角到视频左上角的水平距离。
y	Integer	是	部件坐标y，像素值。指在输出视频中，部件的垂直方向位置。以视频左上角为原点，部件左上角顶点定位，即部件左上角到视频左上角的垂直距离。
position	Integer	否	文本驱动场景中，部件在文本中标记的位置，即标记前的字符数。默认值：0。

部件大小：由width、height指定部件在输出视频中的大小。
- 允许部件缩放后，超过视频画布边界，超出边界的部分在制作视频时会被截取掉。
- 人像、PPT贴纸仅支持保持原图比例缩放，当接口传入的width、htight值比例与原图比例不一致时，按如下策略处理：
  - 原图比例的宽>高：以参数width值为准，按原图比例计算height值。实际效果，输出视频中，人像的高度和传入参数不一致。
  - 原畋比例的宽<=高：以参数height值为准，按原图比例计算width值。实际效果，输出视频中，人像的宽度和传入参数不一致。
- 图片贴纸、线条贴纸支持自由缩放，以接口传入的width、height值为准。实际效果，输出视频中，贴纸的宽高和参数传入一致，图像可能变形。
部件坐标：以视频画布左上角为坐标系原点(0, 0)。向右、向下为正坐标，即使用第四象限坐标系。
文本标记：文本驱动场就中，允许标记部件在文本内容中的位置，表示在文本内容播报到指定位置时开始出现该贴纸。

scene.subtitle参数说明

参数名	类型	必需	说明
startTimestamp	Long	是	字幕开始时间戳，单位：毫秒。
endTimestamp	Long	是	字幕结束时间戳，单位：毫秒。
text	String	是	字幕内容。

音频驱动场景中，使用用户上传的驱动音频素材做为播报内容，制作视/音频。
- 上传驱动音频素材成功时，会触发音频语音转写任务，根据音频内容，生成字幕数据。
- 用户可以查询生成的字幕，对字幕内容进行校准，编辑后，通过该接口更新到项目场景中。
文本驱动场景中，使用文本内容生成字幕，不需要额外传递字幕数据。

subtitlesStyle参数说明

参数名	类型	必需	说明
status	Integer	否	是否启用字幕，枚举值。0=不启用；1=启用。默认值：0。
fontname	String	否	字体名称。参考音频和字幕管理模块中查询字体列表接口，使用alias值。默认值：Source Han Sans CN。
fontsize	Integer	否	字体大小，像素值，取值范围为[12, 100]区间。默认值：50。
primaryColor	String	否	文字颜色，值为十六进制RGB颜色代码，支持RRGGBB或#RRGGBB格式。默认值：#FFFFFF。
outlineColor	String	否	文字边框颜色，值为十六进制RGB颜色代码，支持RRGGBB或#RRGGBB格式。默认字幕文字没有边框。
backgroundColor	String	否	文字背景颜色，值为十六进制RGB颜色代码，支持RRGGBB或#RRGGBB格式。默认字幕文字没有背景。
backgroundAlpha	Integer	否	文字背景透明度，取值范围为[0, 100]区间，0表示透明；100表示不透明。backgroundColor有值时有效。
alignment	Integer	否	文字对齐方式，枚举值。1=左对齐；2=居中；3=右对齐。默认值：2。
marginLeft	Integer	否	字幕左边距，像素值。第一个文字到视频画布左边界的水平距离。alignment=1时有效，其他无效。默认值：40。
marginRight	Integer	否	字幕右边距，像素值。最后一个文字到视频画布右边界的水平距离。alignment=3时有效，其他无效。默认值：40。
marginBottom	Integer	否	字幕下边距，像素值。字幕区域底部到视频画布下边界的垂直距离。默认值：100。

单行字幕内容过长时，会自动向下换行显示。超长字幕会因为换行太多，导致超出视频下边界，而显示不全。

5.请求示例

POST https://digitbot.bokecc.com/api/project/update?projectId=xxxx&accountId=xxx&version=1.1.0&hash=xxx&time=xxx HTTP/1.1

{
    "name": "更新演示项目",
    "videoWidth": 1920,
    "videoAspect": "16:9",
    "scenes": [
        {
            "driverType": 0,
            "textDriver": {
                "text": "这是一段测试文本，welcome to HuoDe digitbot。",
                "speed": 1.00,
                "volume": 1.0
            },
            "audioDriver": {
                "useUrl": true,
                "audioId": ""
            },
            "portraitModel": {
                "type": 1,
                "useUrl": true,
                "modelId": "",
                "modelUrl": "https://xxxxxxx.xxxx/xxx.png",
                "urlType": 7,
                "prompt": "你是一位著名的歌唱家，能够完美演译流行歌曲。xxxxx"
            },
            "voiceModel": {
                "type": 1,
                "modelId": "xxx",
                "voiceStyleId": "xxx"
            },
            "background": {
                "type": 2,
                "useUrl": true,
                "color": "",
                "backgroundId": ""
            },
            "stickers": [
                {
                    "type": 1,
                    "stickerId": "xxx"
                },
                {
                    "type": 0,
                    "useUrl": true,
                    "stickerId": ""
                }
            ],
            "coordinates": [
                {
                    "type": 1,
                    "useUrl": true,
                    "entityId": "",
                    "entityIndex": 0,
                    "width": 376,
                    "height": 999,
                    "x": 30,
                    "y": 50,
                    "position": 0
                },
                {
                    "type": 21,
                    "useUrl": false,
                    "entityId": "xxxxx",
                    "width": 376,
                    "height": 999,
                    "x": 30,
                    "y": 50,
                    "position": 0
                },
                {
                    "type": 21,
                    "useUrl": true,
                    "entityId": "",
                    "entityIndex": 1,
                    "width": 376,
                    "height": 999,
                    "x": 30,
                    "y": 50,
                    "position": 0
                }
            ],
            "subtitles": [
                {
                    "startTimestamp": 1029,
                    "endTimestamp": 3091,
                    "text": "这是一行示例字幕，由上传的音频驱动素材转写生成。"
                }
            ]
        }
    ],
    "subtitlesStyle": {
        "status": 1,
        "fontname": "PangMenZhengDao",
        "fontsize": 65,
        "primaryColor": "#9326FA",
        "outlineColor": "#D0EEFF",
        "backgroundColor": "#FFDE00",
        "backgroundAlpha": 35,
        "alignment": 2,
        "marginLeft": 40,
        "marginRight": 40,
        "marginBottom": 130
    }
}

请求示例中举例使用了所有参数项，实际使用中根据需求选择使用。

6.响应示例

{
    "result": "OK"
}

7.响应说明

字段名	类型	说明
result	String	配置更新成功时的响应结果，字符串"OK"不区分大小写。

1.接口说明​

2.请求地址​

3.请求方式​

4.请求参数​

(1).公共参数，参考服务说明。​

(2).接口参数​

①.Query参数：通过URL参数传递。​

②.Body参数：通过请求Body传递，JSON格式。​

scene参数说明​

scene.textDriver参数说明​

scene.audioDriver参数说明​

scene.portraitModel参数说明​

scene.voiceModel参数说明（1.0.0）​

scene.voiceModel参数说明（1.1.0起）​

scene.background参数说明​

scene.stickers.sticker参数说明​

scene.coordinate参数说明​

scene.subtitle参数说明​

subtitlesStyle参数说明​

5.请求示例​

6.响应示例​

7.响应说明​

1.接口说明

2.请求地址

3.请求方式

4.请求参数

(1).公共参数，参考服务说明。

(2).接口参数

①.Query参数：通过URL参数传递。

②.Body参数：通过请求Body传递，JSON格式。

scene参数说明

scene.textDriver参数说明

scene.audioDriver参数说明

scene.portraitModel参数说明

scene.voiceModel参数说明（1.0.0）

scene.voiceModel参数说明（1.1.0起）

scene.background参数说明

scene.stickers.sticker参数说明

scene.coordinate参数说明

scene.subtitle参数说明

subtitlesStyle参数说明

5.请求示例

6.响应示例

7.响应说明