文档中心

视频直播

声影同传和字幕配置

UpdateSubtitleTranscodePreset - 更新字幕配置

调用 UpdateSubtitleTranscodePreset 接口，更新已添加的字幕配置。

使用说明

根据使用场景，选择合适的功能。

使用场景	推荐功能	参数配置	说明
为直播提供基础字幕，方便静音或嘈杂环境下观看。	原文 ASR 字幕	整句出字方式（字幕会一句一句地完整显示）：`SIConfig` 下的 `Enable` 取值为 `true`、`Pipe` 取值为 `mix`（纯字幕）且仅配置 `SourceLanguage`（原文字幕），不配置 `TargetLanguage`（译文字幕）。实时流式出字方式（字幕会逐字或逐词地显示出来，而不会等待一句话结束）：`SIConfig` 下的 `Enable` 取值为 `true`、`Pipe` 取值为 `realtime` 且仅配置 `SourceLanguage`（原文字幕），不配置 `TargetLanguage`（译文字幕）。	通过语音识别，在视频画面叠加原文字幕。说明目前实时流式出字方式仅支持中文和英文字幕，整句出字方式则支持更多语言。
进行跨语言文字交流，触达全球观众。	字幕翻译	声影同传模式：`SIConfig` 下的 `Enable` 取值为 `true`、`Pipe` 取值为 `mix`（纯字幕），并配置 `SourceLanguage`（原文字幕）和 `TargetLanguage`（译文字幕）。纯字幕模式：`SIConfig` 下的 `Enable` 取值为 `false`，并配置 `SourceLanguage`（原文字幕）和 `TargetLanguage`（译文字幕）。说明推荐选择声影同传模式，翻译效果更佳。	通过语音识别，在视频画面叠加翻译字幕，但保留原声音频。
提供配音式翻译体验，如同观看译制片。	同传声音	`SIConfig` 下的 `Enable` 取值为 `true`、`Pipe` 取值为 `si`（声影同传）、`SpeakerRecognition` 取值大于 `0`，并配置 `SourceLanguage`（原文字幕）和 `TargetLanguage`（译文字幕）的 `Language`（语言）。	提供同传声音，并替换原声。
追求沉浸式真人翻译体验，提升专业性。	同传声音 + 数字人口型	`SIConfig` 下的 `Enable` 取值为 `true`、`Pipe` 取值为 `si`（声影同传）、`SpeakerRecognition` 取值大于 `0`、`DigitalHumanMouthShape` 取值为 `true`，并配置 `SourceLanguage`（原文字幕）和 `TargetLanguage`（译文字幕）的 `Language`（语言）。	在同传声音的基础上，通过 AI 技术驱动说话人口型与翻译音频同步，效果以假乱真。

注意事项

请求频率：单用户请求频率限制为 10 次/秒。
计费说明：
- 字幕费用：按字幕任务的实际运行时长计费。详见字幕计费。
- 转码费用：如果您拉取的是转码流，则会产生转码费用。转码按实际转码时长计费。详见转码计费。
前提条件
如需生成字幕 SRT 文件，请确保：
- 已开通火山引擎对象存储服务，并创建 TOS 桶。详见对象存储文档。
- 为视频直播服务授权跨服务访问角色，授权视频直播使用对象存储资源。
直播延迟：为保证字幕的稳定和完整，会给关联的转码流或添加字幕后缀的源流带来 15 到 30 秒的额外直播延迟。
生效时间：添加、编辑或删除字幕配置后，必须等待 3-5 分钟并重新推流，变更后的字幕配置才会生效。

请求说明

请求方式：POST
请求地址：https://live.volcengineapi.com?Action=UpdateSubtitleTranscodePreset&Version=2023-01-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`UpdateSubtitleTranscodePreset`	接口名称。当前 API 的名称为 `UpdateSubtitleTranscodePreset`。
Version	String	是	`2023-01-01`	接口版本。当前 API 的版本为 `2023-01-01`。

Body

参数	类型	是否必选	示例值	描述
Vhost	String	是	`push.example.com`	域名空间，您可以调用 ListVhostSubtitleTranscodePreset 接口，获取待更新字幕配置的 `Vhost` 取值。
App	String	是	`live`	应用名称，您可以调用 ListVhostSubtitleTranscodePreset 接口，获取待更新字幕配置的 `App` 取值。
PresetName	String	是	`OriginPreset`	字幕配置的名称，您可以调用 ListVhostSubtitleTranscodePreset 接口，获取待更新字幕配置的 `PresetName` 取值。
Description	String	否	`subtitleconfig0001`	字幕配置的描述信息。
Suffixes	Array of String	否	`["_hd","_bd"]`	当前 `AppName` 下的一个或多个转码后缀，为转码流添加字幕、同传声音等效果。这样，观众在切换清晰度时，也能体验到字幕、同传声音等效果。您可以调用 ListVhostTransCodePreset，并通过 `Suffixes` 参数获取转码后缀。注意 `AppName` 下的每个转码后缀，仅能绑定一个字幕配置。示例：源流地址：`rtmp://pull.example.com/live/test` 转码流（包含字幕、同传声音等效果）地址：`rtmp://pull.example.com/live/test_hd`
Delay	Integer	否	`8`	播出延迟时长，以保证同传声音和字幕的翻译处理完成。取值范围为 `[0,60]`，单位为秒。不同功能的建议取值如下： `si`：同时开启数字人口型、同传声音、字幕时：`20`。同时开启同传声音、字幕时：`12`。 `mix`：整句出字方式原文 ASR 字幕：`15`。字幕翻译：`8`。 `realtime`（实时流式原文 ASR 字幕）：`2` 或 `3`。有关具体功能的参数配置，详见使用说明。说明如果字幕出现的时间要早于原声或画面，可适当降低播出延迟时长，让字幕与原声或画面对齐，反之亦然。该参数仅当 `SIConfig` 下的 `Enable` 取值为 `true` 时生效。
DisplayPreset	String	否	`small`	（不推荐使用）预设效果，用于快速配置。传入该参数后，系统将自动对 `Font`（字体）、`MaxRowNumber`（字幕行数）、`MaxCharNumber`（每行最大字符数）、`Position`（左右边距和底部边距）进行智能化适配，且 `MaxRowNumber`、`MaxCharNumber` 和 `Position` 参数不再生效。取值如下： `small` ：小字幕。 `medium`：中字幕。 `large`：大字幕。
MaxRowNumber	Integer	否	`0`	每种语言字幕最多显示的行数。取值如下： `0`：根据字幕总字数和每行最大字符数自动换行，确保内容完整显示。 `1`：每种语言的字幕最多显示一行，内容可能被截断。 `2`：每种语言的字幕最多显示两行，内容可能被截断。说明如传入 `DisplayPreset`（预设效果配置），该参数取值固定为 `0`。该参数分别应用于原文和译文。原文和译文的行数限制单独计算。
Position	Object of Position	否	`-`	字幕位置。说明如传入 `DisplayPreset`（预设效果配置），该参数配置不生效，如未传入 `DisplayPreset`，该参数必选。
SIConfig	Object of SIConfig	否	`-`	声影同传模式配置。
SIOutput	Object of SIOutput	否	`-`	输出相关配置。
SourceLanguage	Object of SourceLanguage	是	`-`	原文字幕配置。说明 `SIConfig` 下的 `Enable` 取值为 `true` 时，原文与译文必须配置不同的语言。
TargetLanguage	Array of TargetLanguage	否	`-`	译文字幕配置。说明目前每次调用仅支持传入一种语言的字幕。 `SIConfig` 下的 `Enable` 取值为 `true` 时，原文与译文必须配置不同的语言。
HotWordList	Array of String	否	`["视频直播","赛事直播","智能家居"]`	热词列表。默认为空。热词需与原文语言一致，总字符数不超过 3 万。传入热词（如产品名、流行语）供语音识别模型参考，有助于提升识别准确率，但不保证每次均能准确识别。如果使用热词后仍出现识别错误，可通过 `ReplaceMap` 逐一配置可能出现的识别错误及其正确写法，对原文 ASR 字幕进行强制纠正。注意仅对原文 ASR 字幕生效。有关原文 ASR 字幕的相关参数配置，详见使用说明。
GlossaryWordList	Array of String	否	`["字节跳动:ByteDance","视频直播:MediaLive"]`	关键词列表。默认为空。每个数组元素的格式为`"原文:译文"`。例如`["字节跳动:ByteDance","视频直播:MediaLive"]`。总字符数不超过 3 万。传入专有词汇及其期望译法，如品牌名、人名、产品名或功能名，供翻译模型参考，有助于提升专有词汇的翻译准确率，但不保证每次均采用配置的译法。如果使用关键词后仍出现错译，可通过 `ReplaceMap` 逐一配置可能出现的错译及其正确译法，对生成的译文进行强制纠正。注意原文或译文本身不可包含英文逗号（,）。仅在配置译文字幕（`TargetLanguage`）时生效，且仅作用于译文字幕。
ReplaceMap	JSON Map	否	`{"蒂姆":"Tim","提姆":"Tim"}`	易错词列表。默认为空。配置需要强制纠正的字幕文字。需逐一枚举可能出现的错译或识别错误及其正确写法。格式为`"目标词":"替换词"`，每个`"目标词":"替换词"`之间用英文逗号（,）隔开。每个目标词或替换词长度为 1-50 个字符，最多可传入 500 对`"目标词":"替换词"`。系统匹配到目标词后，会将其强制替换为替换词。原文 ASR 字幕：纠正识别错误。例如，当`视频直播`被错误识别为`视屏直播`时，您可以传入`{"视屏直播":"视频直播"}`。译文字幕：纠正错译，仅修改译文，不修改原文或同传声音。例如，当 `Tim` 被错译为`蒂姆`或`提姆`时，您可以传入`{"蒂姆":"Tim","提姆":"Tim"}`。注意目标词和替换词本身不可包含英文逗号（,）。 `ReplaceMap` 只按文字匹配，不判断上下文，因此仅适用于目标词本身可以明确判定为错误的场景，例如`{"视屏直播":"视频直播"}`。请勿将目标词替换为包含该目标词的文本。例如，配置`{"颗粒":"颗粒感"}`后，模型输出`颗粒`时会被替换为`颗粒感`。如果模型已输出正确的`颗粒感`，其中的`颗粒`仍会被替换，结果变为`颗粒感感`。
SubtitleTosConfig	Object of SubtitleTosConfig	否	`-`	TOS 配置，用于生成字幕 SRT 文件。

Position

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
Relative	String	否	`top`	字幕在画面中的位置。取值如下： `top`：字幕展示在画面顶部。 `bottom`：字幕展示在画面底部。
MarginVertical	Float	否	`0.5`	字幕的上下边距，即字幕距离画面顶部或底部的距离。取值为画面高度的百分比，取值范围为 `(0, 0.5]`。当 `Relative` 取值为 `top` 时，表示上边距。当 `Relative` 取值为 `bottom` 时，表示下边距。
MarginHorizontal	Float	否	`0.2`	字幕的左右边距，即字幕距离画面左右边缘的距离。取值为画面宽度的百分比，取值范围为 `(0, 0.3]`。

Relative

String

否

top

字幕在画面中的位置。取值如下：

top：字幕展示在画面顶部。
bottom：字幕展示在画面底部。

MarginVertical

Float

否

0.5

字幕的上下边距，即字幕距离画面顶部或底部的距离。取值为画面高度的百分比，取值范围为 (0, 0.5]。

当 Relative 取值为 top 时，表示上边距。
当 Relative 取值为 bottom 时，表示下边距。

MarginHorizontal Float 否 0.2 字幕的左右边距，即字幕距离画面左右边缘的距离。取值为画面宽度的百分比，取值范围为 (0, 0.3]。

SIConfig

参数	类型	是否必选	示例值	描述
Enable	Boolean	否	`false`	是否开启声影同传模式。取值如下： `true`：开启声影同传模式。支持生成字幕、生成同传声音替换原声，以及驱动数字人口型与同传声音同步，提供沉浸式体验。 `false`：关闭声影同传模式，开启纯字幕模式。关闭后，`SIConfig` 中的其他参数均不生效。
Pipe	String	否	`mix`	声影同传类型。取值如下： `si`：字幕、同传音频与画面完全同步，支持数字人口型功能。适用于对同步性和沉浸感要求较高的会议直播等场景。 `mix`：仅字幕，包含整句出字方式原文 ASR 字幕。 `realtime`：实时流式原文 ASR 字幕。
SpeakerRecognition	Integer	否	`1`	是否开启同传声音功能。取值如下：大于 `0`：开启。开启后，将使用带有音色复刻效果的翻译语音替换直播原声。等于 `0`：关闭。说明仅在 `Pipe` 取值为空或 `si` 时生效。
DigitalHumanMouthShape	Boolean	否	`false`	是否开启数字人口型功能。取值如下： `true`：开启。开启后，说话人口型将与同传声音同步，提升直播的沉浸感。 `false`：关闭。说明仅在 `Pipe` 取值为空或 `si` 时生效。取值为 `true` 时，默认开启同传声音。
PipeExtra	String	否	`{"Separator":{"HandleType":1},"Amix":{"AudioEnhance":false}}`	额外配置，为 JSON 格式的字符串，包含音量均衡、降噪、原声音量等信息。详见 CreateSpeechTask 接口的 `Extra` 参数。说明建议仅在开启同传声音时传入该参数。有关同传声音的相关参数配置，详见使用说明。

SIOutput

参数	类型	是否必选	示例值	描述
Sei	Array of String	否	`["subtitle"]`	如需将字幕内容写入直播流的 SEI 消息，将参数值设置为 `["subtitle"]`。说明仅当 `Pipe` 取值为 `si` 或 `mix` 时，该参数生效。视频直播将字幕内容写入 SEI 消息时，SEI `type` 取值为 `100`。如果您的推流工具或应用也会向直播流写入自定义 SEI 消息，请避免使用相同的 SEI `type` 取值，否则播放器可能会将自定义数据识别为字幕。
Callback	Object of Callback	否	`-`	回调配置。

SourceLanguage

参数	类型	是否必选	示例值	描述
Display	Boolean	是	`true`	是否展示原文字幕，取值如下： `true`：展示，此时将展示原文和译文双语字幕。 `false`：不展示，此时将仅展示译文字幕。
Language	String	否	`zh`	原文字幕语言。当 `SIConfig` 下的 `Enable` 取值为 `true` 使用声影同传模式时，可通过 GetSubtitleTranscodePresetConfig 的 `OriginalLang` 获取当前账号字幕翻译和同传声音可使用的原文字幕语言，或通过该接口的`AsrLang` 获取当前账号可使用的原文 ASR 字幕语言，并传入 `Key` 值。当 `SIConfig` 下的 `Enable` 取值为 `false` 使用纯字幕模式时，取值如下： `zh`：中英混合。 `en`：英语。 `ko`：韩语。 `ja`：日语。
ShowPriority	Integer	否	`2`	原文字幕的展示优先级。取值越大，优先级越高。例如原文字幕的 `ShowPriority` 为 `1`，译文字幕的 `ShowPriority` 为 `2`，则译文字幕在上，原文字幕在下。
MaxCharNumber	Integer	否	`60`	原文每行字幕的最大字符数。建议取值 `60`。说明系统会综合您传入的该参数取值以及 `MarginLr`（左右边距）、`Font`（字体）、`FontSize`（字号）和屏幕分辨率等因素，计算出每行最终可显示的最大字符数。每个文字、字母、符号或数字均为一个字符。当 `MaxRowNumber` 取值为 `1` 或 `2` 时，如果原文的字幕总字数超出显示范围，内容将会被截断。例如每行字幕的最大字符数为 10，`MaxRowNumber` 取值 `2`，则当原文字幕总字数超出 20 时，20 字后的内容会被截断。如传入 `DisplayPreset`（预设效果配置），该参数配置不生效，如未传入 `DisplayPreset`，该参数必选。
Font	String	是	`siyuanheiti`	原文字幕字体。当 `SIConfig` 下的 `Enable` 取值为 `true` 使用声影同传模式时，可通过 GetSubtitleTranscodePresetConfig 的 `Font` 获取当前账号下可使用的字体列表，并传入 `Key` 值。当 `SIConfig` 下的 `Enable` 取值为 `false` 使用纯字幕模式时，具体取值如下。原文字幕语言（`Language` 取值）不同，原文字幕字体也随之不同。当原文字幕的语言是 `zh` 时，支持以下字体取值。 `siyuanheiti`：思源黑体。 `songtixi`：宋体细。 `songticu`：宋体粗。 `heitifan`：黑体繁。 `kaiti`：楷体。当原文字幕的语言是 `en` 时，支持以下字体取值。 `inter`：Inter。 `roboto`：Roboto。 `opposans`：OPPOSans。 `siyuansongti`：思源宋体。 `montserrat`：Montserrat。当原文字幕的语言是 `ko` 或 `ja` 时，支持 `notosans`（Noto Sans) 字体。
FontSize	Integer	否	`18`	原文字幕字号。单位为 px。说明如传入 `DisplayPreset`（预设效果配置），该参数配置不生效，如未传入 `DisplayPreset`，该参数必选。
FontColor	String	否	`0xFF0000@0.5`	原文字幕的字体颜色。使用以下任一方式表示颜色值：以 `0x` 或 `#` 开头，后面跟十六进制 RGB 颜色值，再通过 `@` 符号附加透明度，透明度支持十六进制（如 `0x80`）或小数（如 `0.5`）两种表示方式。例如，设置 RGB 值为 `FF0000`，透明度为 50% 的颜色时，可以传入 `0xFF0000@0x80`、`0xFF0000@0.5`、`#FF0000@0x80` 或 `#FF0000@0.5`。使用 FFmpeg 规定的颜色关键字，再通过 `@` 符号附加透明度，透明度支持用小数（如 `0.5`）表示。例如，设置 RGB 值为 `0xF0F8FF`，透明度为 50% 的颜色时，可以传入 `AliceBlue@0.5`。说明颜色定义方法及更多颜色关键字，详见 FFmpeg 的颜色定义语法。透明度数值越大，越不透明。用小数表示透明度时，取值范围为 `[0,1]`，支持 2 位小数。
Box	Object of Box	否	`-`	原文字幕字体背景。
Border	Object of Border	否	`-`	原文字幕字体阴影。

TargetLanguage

参数	类型	是否必选	示例值	描述
Language	String	否	`en`	译文字幕语言。当 `SIConfig` 下的 `Enable` 取值为 `true` 使用声影同传模式时，可通过 GetSubtitleTranscodePresetConfig 的 `Lang` 获取当前账号下可使用的译文字幕语言，并传入 `Key` 值。当 `SIConfig` 下的 `Enable` 取值为 `false` 使用纯字幕模式时，取值如下： `zh`：中英混合。 `en`：英语。 `ko`：韩语。 `ja`：日语。
ShowPriority	Integer	否	`1`	译文字幕的展示优先级。取值越大，优先级越高。例如原文字幕的 `ShowPriority` 为 `1`，译文字幕的 `ShowPriority` 为 `2`，则译文字幕在上，原文字幕在下。
MaxCharNumber	Integer	否	`60`	译文每行字幕的最大字符数。建议取值 `60`。说明系统会综合您传入的该参数取值以及 `MarginLr`（左右边距）、`Font`（字体）、`FontSize`（字号）和屏幕分辨率等因素，计算出每行最终可显示的最大字符数。每个文字、字母、符号或数字均为一个字符。当 `MaxRowNumber` 取值为 `1` 或 `2` 时，如果译文的字幕总字数超出显示范围，内容将会被截断。例如每行字幕的最大字符数为 10，`MaxRowNumber` 取值 `2`，则当译文字幕总字数超出 20 时，20 字后的内容会被截断。如传入 `DisplayPreset`（预设效果配置），该参数配置不生效，如未传入 `DisplayPreset`，该参数必选。
Hidden	Boolean	否	`false`	是否隐藏译文字幕。取值如下： `true`：隐藏。 `false`：显示。
Font	String	是	`inter`	译文字幕的字体。当 `SIConfig` 下的 `Enable` 取值为 `true` 使用声影同传模式时，可通过 GetSubtitleTranscodePresetConfig 的 `Font` 获取当前账号下可使用的字体列表，并传入 `Key` 值。当 `SIConfig` 下的 `Enable` 取值为 `false` 使用纯字幕模式时，具体取值如下。译文字幕语言（`Language` 取值）不同，译文字幕字体也随之不同。当译文字幕的语言是 `zh` 时，支持以下字体取值。 `siyuanheiti`：思源黑体。 `songtixi`：宋体细。 `songticu`：宋体粗。 `heitifan`：黑体繁。 `kaiti`：楷体。当译文字幕的语言是 `en` 时，支持以下字体取值。 `inter`：Inter。 `roboto`：Roboto。 `opposans`：OPPOSans。 `siyuansongti`：思源宋体。 `montserrat`：Montserrat。当译文字幕的语言是 `ko` 或 `ja` 时，支持 `notosans`（Noto Sans) 字体。
FontSize	Integer	否	`18`	译文字幕字号。单位为 px。说明如传入 `DisplayPreset`（预设效果配置），该参数配置不生效，如未传入 `DisplayPreset`，该参数必选。
FontColor	String	否	`0xFF0000@0.5`	译文字幕的字体颜色。使用以下任一方式表示颜色值：以 `0x` 或 `#` 开头，后面跟十六进制 RGB 颜色值，再通过 `@` 符号附加透明度，透明度支持十六进制（如 `0x80`）或小数（如 `0.5`）两种表示方式。例如，设置 RGB 值为 `FF0000`，透明度为 50% 的颜色时，可以传入 `0xFF0000@0x80`、`0xFF0000@0.5`、`#FF0000@0x80` 或 `#FF0000@0.5`。使用 FFmpeg 规定的颜色关键字，再通过 `@` 符号附加透明度，透明度支持用小数（如 `0.5`）表示。例如，设置 RGB 值为 `0xF0F8FF`，透明度为 50% 的颜色时，可以传入 `AliceBlue@0.5`。说明颜色定义方法及更多颜色关键字，详见 FFmpeg 的颜色定义语法。透明度数值越大，越不透明。用小数表示透明度时，取值范围为 `[0,1]`，支持 2 位小数。
Box	Object of Box	否	`-`	译文字幕字体背景。
Border	Object of Border	否	`-`	译文字幕字体阴影。

SubtitleTosConfig

参数	类型	是否必选	示例值	描述
Enable	Boolean	否	`true`	是否生成字幕 SRT 文件。默认值为 `false`。取值如下： `true`：生成。 `false`：不生成。
Bucket	String	否	`bucketa`	存储字幕 SRT 文件的 TOS 桶名称。长度为 3-63 个字符，只能包含小写字母（a-z）、数字（0-9）和连字符（-），且必须以小写字母（a-z）或数字（0-9）开头和结尾。
Region	String	否	`cn-beijing`	存储字幕 SRT 文件的 TOS 桶区域。取值如下： `cn-beijing`：华北2（北京） `cn-guangzhou`：华南1（广州） `cn-shanghai`：华东2（上海）
StorageDir	String	否	`FolderA`	存储字幕 SRT 文件的 TOS 桶文件夹名称。长度为 1-255 个字符，支持中文、英文（a-z，A-Z）、数字（0-9）及常见字符。不能以 `..` 作为目录名。可使用 `/` 表示子文件夹层级，例如 `a/b/c`。不能以 `/` 或 `\` 开头，也不能包含连续的 `/`。

Callback

参数	类型	是否必选	示例值	描述
Url	String	是	`https://xxx`	用于接收回调消息的地址。该地址需支持 HTTP 或 HTTPS 协议，并可通过公网访问。长度为 1 到 100 个字符。有关声影同传回调消息，详见声影同传回调消息。

Box

参数类型是否必选示例值描述

W Float 是 1.0 宽度。单位为 px。建议取值范围为 [1,10]。

参数	类型	是否必选	示例值	描述
W	Float	是	`1.0`	宽度。单位为 px。建议取值范围为 [1,10]。
Color	String	是	`0xFF0000@0.5`	颜色。使用以下任一方式表示颜色值：以 `0x` 或 `#` 开头，后面跟十六进制 RGB 颜色值，再通过 `@` 符号附加透明度，透明度支持十六进制（如 `0x80`）或小数（如 `0.5`）两种表示方式。例如，设置 RGB 值为 `FF0000`，透明度为 50% 的颜色时，可以传入 `0xFF0000@0x80`、`0xFF0000@0.5`、`#FF0000@0x80` 或 `#FF0000@0.5`。使用 FFmpeg 规定的颜色关键字，再通过 `@` 符号附加透明度，透明度支持用小数（如 `0.5`）表示。例如，设置 RGB 值为 `0xF0F8FF`，透明度为 50% 的颜色时，可以传入 `AliceBlue@0.5`。说明颜色定义方法及更多颜色关键字，详见 FFmpeg 的颜色定义语法。透明度数值越大，越不透明。用小数表示透明度时，取值范围为 `[0,1]`，支持 2 位小数。

Color

String

是

0xFF0000@0.5

颜色。
使用以下任一方式表示颜色值：

以 0x 或 # 开头，后面跟十六进制 RGB 颜色值，再通过 @ 符号附加透明度，透明度支持十六进制（如 0x80）或小数（如 0.5）两种表示方式。例如，设置 RGB 值为 FF0000，透明度为 50% 的颜色时，可以传入 0xFF0000@0x80、0xFF0000@0.5、#FF0000@0x80 或 #FF0000@0.5。
使用 FFmpeg 规定的颜色关键字，再通过 @ 符号附加透明度，透明度支持用小数（如 0.5）表示。例如，设置 RGB 值为 0xF0F8FF，透明度为 50% 的颜色时，可以传入 AliceBlue@0.5。

说明

颜色定义方法及更多颜色关键字，详见 FFmpeg 的颜色定义语法。
透明度数值越大，越不透明。
用小数表示透明度时，取值范围为 [0,1]，支持 2 位小数。

Border

参数类型是否必选示例值描述

Width Float 是 2 宽度。单位为 px。建议取值范围为 [1,10]。

参数	类型	是否必选	示例值	描述
Width	Float	是	`2`	宽度。单位为 px。建议取值范围为 [1,10]。
Color	String	是	`0xFF0000@0.5`	颜色。使用以下任一方式表示颜色值：以 `0x` 或 `#` 开头，后面跟十六进制 RGB 颜色值，再通过 `@` 符号附加透明度，透明度支持十六进制（如 `0x80`）或小数（如 `0.5`）两种表示方式。例如，设置 RGB 值为 `FF0000`，透明度为 50% 的颜色时，可以传入 `0xFF0000@0x80`、`0xFF0000@0.5`、`#FF0000@0x80` 或 `#FF0000@0.5`。使用 FFmpeg 规定的颜色关键字，再通过 `@` 符号附加透明度，透明度支持用小数（如 `0.5`）表示。例如，设置 RGB 值为 `0xF0F8FF`，透明度为 50% 的颜色时，可以传入 `AliceBlue@0.5`。说明颜色定义方法及更多颜色关键字，详见 FFmpeg 的颜色定义语法。透明度数值越大，越不透明。用小数表示透明度时，取值范围为 `[0,1]`，支持 2 位小数。

Color

String

是

0xFF0000@0.5

颜色。
使用以下任一方式表示颜色值：

以 0x 或 # 开头，后面跟十六进制 RGB 颜色值，再通过 @ 符号附加透明度，透明度支持十六进制（如 0x80）或小数（如 0.5）两种表示方式。例如，设置 RGB 值为 FF0000，透明度为 50% 的颜色时，可以传入 0xFF0000@0x80、0xFF0000@0.5、#FF0000@0x80 或 #FF0000@0.5。
使用 FFmpeg 规定的颜色关键字，再通过 @ 符号附加透明度，透明度支持用小数（如 0.5）表示。例如，设置 RGB 值为 0xF0F8FF，透明度为 50% 的颜色时，可以传入 AliceBlue@0.5。

说明

颜色定义方法及更多颜色关键字，详见 FFmpeg 的颜色定义语法。
透明度数值越大，越不透明。
用小数表示透明度时，取值范围为 [0,1]，支持 2 位小数。

返回参数

本接口无特有的返回参数。更多信息请见返回结构。

请求示例 1

原文 ASR 字幕（整句出字）

POST https://live.volcengineapi.com?Action=UpdateSubtitleTranscodePreset&Version=2023-01-01
{
    "Vhost": "push.example.com",
    "App": "live",
    "PresetName": "PresetA",
    "Description": "原文 ASR 字幕（整句出字）",
    "Suffixes": [
        "_hd",
        "_bd"
    ],
    "Delay": 15,
    "MaxRowNumber": 2,
    "Position": {
        "Relative": "bottom",
        "MarginVertical": 0.05,
        "MarginHorizontal": 0.2
    },
    "SIConfig": {
        "Enable": true,
        "Pipe": "mix"
    },
    "SIOutput": {
        "Sei": [
            "subtitle"
        ],
        "Callback": {
            "Url": "https://example.com/callback"
        }
    },
    "SourceLanguage": {
        "Display": true,
        "Language": "zh",
        "Font": "siyuanheiti",
        "FontSize": 18,
        "FontColor": "0xFFFFFF@1",
        "ShowPriority": 2,
        "MaxCharNumber": 60,
        "Box": {
            "W": 1.0,
            "Color": "0x000000@0.5"
        },
        "Border": {
            "Width": 2,
            "Color": "0x000000@0.5"
        }
    },
    "HotWordList": [
        "视频直播",
        "赛事直播",
        "智能家居"
    ],
    "ReplaceMap": {
        "视屏直播": "视频直播"
    }
}

返回示例 1

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "UpdateSubtitleTranscodePreset",
        "Version": "2023-01-01",
        "Service": "live",
        "Region": "cn-north-1"
    }
}

请求示例 2

原文 ASR 字幕（实时流式出字）

POST https://live.volcengineapi.com?Action=UpdateSubtitleTranscodePreset&Version=2023-01-01
{
    "Vhost": "push.example.com",
    "App": "live",
    "PresetName": "PresetB",
    "Description": "原文 ASR 字幕（实时流式出字）",
    "Suffixes": [
        "_hd",
        "_bd"
    ],
    "Delay": 2,
    "MaxRowNumber": 2,
    "Position": {
        "Relative": "bottom",
        "MarginVertical": 0.05,
        "MarginHorizontal": 0.2
    },
    "SIConfig": {
        "Enable": true,
        "Pipe": "realtime"
    },
    "SIOutput": {
        "Callback": {
            "Url": "https://example.com/callback"
        }
    },
    "SourceLanguage": {
        "Display": true,
        "Language": "zh",
        "Font": "siyuanheiti",
        "FontSize": 18,
        "FontColor": "0xFFFFFF@1",
        "ShowPriority": 2,
        "MaxCharNumber": 60,
        "Box": {
            "W": 1.0,
            "Color": "0x000000@0.5"
        },
        "Border": {
            "Width": 2,
            "Color": "0x000000@0.5"
        }
    },
    "HotWordList": [
        "视频直播",
        "赛事直播",
        "智能家居"
    ],
    "ReplaceMap": {
        "视屏直播": "视频直播"
    }
}

返回示例 2

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "UpdateSubtitleTranscodePreset",
        "Version": "2023-01-01",
        "Service": "live",
        "Region": "cn-north-1"
    }
}

请求示例 3

字幕翻译（声影同传模式）

POST https://live.volcengineapi.com?Action=UpdateSubtitleTranscodePreset&Version=2023-01-01
{
    "Vhost": "push.example.com",
    "App": "live",
    "PresetName": "PresetC",
    "Description": "字幕翻译（声影同传模式）",
    "Suffixes": [
        "_hd",
        "_bd"
    ],
    "Delay": 8,
    "MaxRowNumber": 2,
    "Position": {
        "Relative": "bottom",
        "MarginVertical": 0.05,
        "MarginHorizontal": 0.2
    },
    "SIConfig": {
        "Enable": true,
        "Pipe": "mix"
    },
    "SIOutput": {
        "Sei": [
            "subtitle"
        ],
        "Callback": {
            "Url": "https://example.com/callback"
        }
    },
    "SourceLanguage": {
        "Display": true,
        "Language": "en",
        "Font": "inter",
        "FontSize": 18,
        "FontColor": "0xFFFFFF@1",
        "ShowPriority": 2,
        "MaxCharNumber": 60,
        "Box": {
            "W": 1.0,
            "Color": "0x000000@0.5"
        },
        "Border": {
            "Width": 2,
            "Color": "0x000000@0.5"
        }
    },
    "TargetLanguage": [
        {
            "Language": "zh",
            "Font": "siyuanheiti",
            "FontSize": 18,
            "FontColor": "0xFFFFFF@1",
            "Hidden": false,
            "ShowPriority": 1,
            "MaxCharNumber": 60,
            "Box": {
                "W": 1.0,
                "Color": "0x000000@0.5"
            },
            "Border": {
                "Width": 2,
                "Color": "0x000000@0.5"
            }
        }
    ],
    "GlossaryWordList": [
        "ByteDance:字节跳动",
        "MediaLive:视频直播"
    ],
    "ReplaceMap": {
        "蒂姆": "Tim",
        "提姆": "Tim"
    }
}

返回示例 3

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "UpdateSubtitleTranscodePreset",
        "Version": "2023-01-01",
        "Service": "live",
        "Region": "cn-north-1"
    }
}

请求示例 4

同传声音 + 译文字幕

POST https://live.volcengineapi.com?Action=UpdateSubtitleTranscodePreset&Version=2023-01-01
{
    "Vhost": "push.example.com",
    "App": "live",
    "PresetName": "PresetD",
    "Description": "同传声音 + 译文字幕",
    "Suffixes": [
        "_hd",
        "_bd"
    ],
    "Delay": 12,
    "MaxRowNumber": 2,
    "Position": {
        "Relative": "bottom",
        "MarginVertical": 0.05,
        "MarginHorizontal": 0.2
    },
    "SIConfig": {
        "Enable": true,
        "Pipe": "si",
        "SpeakerRecognition": 1,
        "DigitalHumanMouthShape": false,
        "PipeExtra": "{\"Separator\":{\"HandleType\":1},\"Amix\":{\"AudioEnhance\":false}}"
    },
    "SIOutput": {
        "Sei": [
            "subtitle"
        ],
        "Callback": {
            "Url": "https://example.com/callback"
        }
    },
    "SourceLanguage": {
        "Display": false,
        "Language": "en",
        "Font": "inter",
        "FontSize": 18,
        "FontColor": "0xFFFFFF@1",
        "ShowPriority": 2,
        "MaxCharNumber": 60,
        "Box": {
            "W": 1.0,
            "Color": "0x000000@0.5"
        },
        "Border": {
            "Width": 2,
            "Color": "0x000000@0.5"
        }
    },
    "TargetLanguage": [
        {
            "Language": "zh",
            "Font": "siyuanheiti",
            "FontSize": 18,
            "FontColor": "0xFFFFFF@1",
            "Hidden": false,
            "ShowPriority": 1,
            "MaxCharNumber": 60,
            "Box": {
                "W": 1.0,
                "Color": "0x000000@0.5"
            },
            "Border": {
                "Width": 2,
                "Color": "0x000000@0.5"
            }
        }
    ],
    "GlossaryWordList": [
        "ByteDance:字节跳动",
        "MediaLive:视频直播"
    ],
    "ReplaceMap": {
        "蒂姆": "Tim",
        "提姆": "Tim"
    }
}

返回示例 4

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "UpdateSubtitleTranscodePreset",
        "Version": "2023-01-01",
        "Service": "live",
        "Region": "cn-north-1"
    }
}

请求示例 5

同传声音 + 数字人口型 + 译文字幕

POST https://live.volcengineapi.com?Action=UpdateSubtitleTranscodePreset&Version=2023-01-01
{
    "Vhost": "push.example.com",
    "App": "live",
    "PresetName": "PresetE",
    "Description": "同传声音 + 数字人口型 + 译文字幕",
    "Suffixes": [
        "_hd",
        "_bd"
    ],
    "Delay": 20,
    "MaxRowNumber": 2,
    "Position": {
        "Relative": "bottom",
        "MarginVertical": 0.05,
        "MarginHorizontal": 0.2
    },
    "SIConfig": {
        "Enable": true,
        "Pipe": "si",
        "SpeakerRecognition": 1,
        "DigitalHumanMouthShape": true,
        "PipeExtra": "{\"Separator\":{\"HandleType\":1},\"Amix\":{\"AudioEnhance\":false}}"
    },
    "SIOutput": {
        "Sei": [
            "subtitle"
        ],
        "Callback": {
            "Url": "https://example.com/callback"
        }
    },
    "SourceLanguage": {
        "Display": false,
        "Language": "en",
        "Font": "inter",
        "FontSize": 18,
        "FontColor": "0xFFFFFF@1",
        "ShowPriority": 2,
        "MaxCharNumber": 60,
        "Box": {
            "W": 1.0,
            "Color": "0x000000@0.5"
        },
        "Border": {
            "Width": 2,
            "Color": "0x000000@0.5"
        }
    },
    "TargetLanguage": [
        {
            "Language": "zh",
            "Font": "siyuanheiti",
            "FontSize": 18,
            "FontColor": "0xFFFFFF@1",
            "Hidden": false,
            "ShowPriority": 1,
            "MaxCharNumber": 60,
            "Box": {
                "W": 1.0,
                "Color": "0x000000@0.5"
            },
            "Border": {
                "Width": 2,
                "Color": "0x000000@0.5"
            }
        }
    ],
    "GlossaryWordList": [
        "ByteDance:字节跳动",
        "MediaLive:视频直播"
    ],
    "ReplaceMap": {
        "蒂姆": "Tim",
        "提姆": "Tim"
    }
}

返回示例 5

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "UpdateSubtitleTranscodePreset",
        "Version": "2023-01-01",
        "Service": "live",
        "Region": "cn-north-1"
    }
}

错误码

下表仅列出本接口特有的错误码。更多信息请参见公共错误码获取详细信息。

状态码	错误码	错误信息	说明
200	CommonErr	-	未分类错误。建议重试，如果仍返回该错误码，请联系技术支持。
400	InvalidParam	-	输入的参数无效或不符合要求，请参照请求参数说明进行检查。
400	InvalidParam.BindError	Request parameter error, please check input data	参数未通过校验，请检查参数类型是否正确。
403	RequestForbidden	-	请求被拒绝，当前账号下无请求的资源（域名空间、域名、应用、配置模版、证书）。
403	RequestForbidden.AccountIDNotAllow	this AccountID does not have permission to access the corresponding resource, please check the request parameters	请求被拒绝，当前账号下无请求的资源（域名空间、域名、应用、配置模版、证书）。
403	RequestForbidden.BillingStatus	Billing status is not available for the AccountID, please activate the service or recharge.	未开通视频直播服务或账号欠费，造成账单不可用，请检查服务开通情况和账号欠费情况。
404	ResourceNotFound	-	未找到资源（域名空间、域名、应用、配置模版、证书）。建议重试，如果仍返回该错误码，请联系技术支持。
500	InternalError	an internal error occurred, please contact the administrator.	出现内部错误，请联系技术支持。
500	InternalError.Preset	an internal error related to preset occurred, please contact the administrator.	出现与功能配置相关的内部错误，请联系技术支持。
502	InternalServiceError	an internal error occurred, please contact the administrator.	服务间出现错误，请联系技术支持。
502	InternalServiceError.BadResponse	an internal error occurred, please contact the administrator.	服务间出现错误，请联系技术支持。
504	InternalServiceTimeout	Internal Service is timeout. please contact the administrator.	内部服务超时，请联系技术支持。

SDK

视频直播提供了配套的开发工具集 SDK，支持多种编程语言，帮助您更方便的调用 API。

最近更新时间：2026.10.23 16:25:04

这个页面对您有帮助吗？

有用

无用

视频直播

使用说明 #

注意事项 #

请求说明 #

调试 #

请求参数 #

Query #

Body #

Position #

SIConfig #

SIOutput #

SourceLanguage #

TargetLanguage #

SubtitleTosConfig #

Callback #

Box #

Border #

返回参数 #

请求示例 1 #

返回示例 1 #

请求示例 2 #

返回示例 2 #

请求示例 3 #

返回示例 3 #

请求示例 4 #

返回示例 4 #

请求示例 5 #

返回示例 5 #

错误码 #

SDK #

使用说明

注意事项

请求说明

调试

请求参数

Query

Body

Position

SIConfig

SIOutput

SourceLanguage

TargetLanguage

SubtitleTosConfig

Callback

Box

Border

返回参数

请求示例 1

返回示例 1

请求示例 2

返回示例 2

请求示例 3

返回示例 3

请求示例 4

返回示例 4

请求示例 5

返回示例 5

错误码

SDK