CreateSpeechTask - 创建声影同传任务--视频直播-火山引擎

文档中心

导航

CreateSpeechTask - 创建声影同传任务

最近更新时间：2025.12.09 16:52:33首次发布时间：2025.12.09 16:52:33

调用 CreateSpeechTask 接口，创建声影同传任务。从任务开始到任务结束，当直播源开始推流时，同传任务会自动拉取该直播流进行同传处理，并将经过同传处理的新直播流推送到指定的转推地址，从而实现在转推地址上直播同传处理后的内容。例如，您可以使用 OBS 开播，创建同传任务后，在抖音上直播同传处理后的内容。

注意事项

请求频率：单用户请求频率限制为 10 次/秒。

请求说明

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

调试

API Explorer

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

去调试

请求参数

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

Query

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

Body

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

参数	类型	是否必选	示例值	描述
Name	String	是	`TaskA`	任务名称。该名称在所有运行中的任务中必须唯一。长度为 1-64 个字节。可包含以下字符：数字（0-9）大写字母（A-Z）小写字母（a-z）中文下划线（_）中划线（-）
Rule	Object of Rule	是	`-`	任务规则。

Name

String

是

TaskA

任务名称。该名称在所有运行中的任务中必须唯一。长度为 1-64 个字节。可包含以下字符：

数字（0-9）
大写字母（A-Z）
小写字母（a-z）
中文
下划线（_）
中划线（-）

Rule Object of Rule 是 - 任务规则。

Rule

参数	类型	是否必选	示例值	描述
Pipe	String	是	`si`	任务类型。取值如下： `si`：声影同传模式。适用于对同步性和沉浸感要求较高的会议直播等场景。 `mix`：仅字幕。 `realtime`：实时同传模式。适用于对延迟敏感的赛事直播等场景。
Delay	Integer	否	`20`	播出延迟时长，用于保证同传声音和字幕的翻译处理完成。取值范围为 `[0,60]`，单位为秒。不同任务类型（`Pipe`）下，建议取值如下： `si`： `LipSync` 取值为 `true` 时，建议取值 `20`。 `LipSync` 取值为 `false` 时，建议取值 `12`。 `mix`：`8`。 `realtime`：`2` 或 `3`。
Source	Object of Source	是	`-`	源流配置。
StartTime	String	否	`2025-11-17T11:30:06+08:00`	任务开始时间。遵循 RFC3339 格式的东八区（UTC+8）时间，精度为秒。如果未传该参数，任务会立即启动。
EndTime	String	否	`2025-11-17T12:11:06+08:00`	任务结束时间，必须晚于任务开始时间（`StartTime`），且两者之间的时间跨度不得超过 7 天。遵循 RFC3339 格式的东八区（UTC+8）时间，精度为秒。如果未传该参数，任务会在开始时间的 7 天后结束。说明当任务结束或拉流失败时，停止向转推地址推流。
Output	Object of Output	是	`-`	转推配置。
SI	Object of SI	否	`-`	声影同传模式配置。说明仅在 `Pipe` 取值为 `si` 时生效。
RealTime	Object of RealTime	否	`-`	实时同传模式配置。说明仅在 `Pipe` 取值为 `realtime` 时生效。
Extra	Object of Extra	否	`-`	额外配置。
Subtitle	Object of Subtitle	否	`-`	字幕配置。
GlossaryMap	JSON Map	否	`{"字节跳动":"ByteDance","视频直播":"MediaLive"}`	关键词库。格式为 `"Key":"Value"`，每个 `"Key":"Value"` 之间用英文逗号（,）隔开。其中，`"Key"` 为原文，`"Value"` 为译文。配置关键词库后，同传任务会严格按照词库进行翻译。

Source

参数	类型	是否必选	示例值	描述
Url	String	是	`https://xxx/live/xxx.flv`	源流地址，即需要拉取的原始流地址。支持 RTMP 或 FLV 格式。可通过地址生成器生成拉流地址，并确保域名、`AppName` 和 `StreamName` 与原始直播流的推流地址一致。说明原始直播流的推流地址可从直播平台获取，也可通过地址生成器生成。地址中不可直接包含多字节编码字符（如中文字符）。如需包含，必须对这些字符进行 URL 编码（URL-encode）。

Output

参数	类型	是否必选	示例值	描述
Url	Array of String	是	`rtmp://xxx`	转推地址，同传任务会将经过同传处理的新直播流推送到该地址。支持 RTMP 格式。最多支持传入 8 个转推地址。可从直播平台获取或通过地址生成器生成推流地址。说明如需拉取经过同传处理的新直播流，可通过地址生成器生成拉流地址，并确保域名、`AppName` 和 `StreamName` 与转推地址一致。地址中不可直接包含多字节编码字符（如中文字符）。如需包含，必须对这些字符进行 URL 编码（URL-encode）。

SI

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

参数	类型	是否必选	示例值	描述
LipSync	Boolean	否	`true`	是否开启数字人口型功能。默认值为 `false`。取值如下： `true`：开启。开启后，人物口型将与翻译后的语音同步，提升直播的沉浸感。 `false`：关闭。

LipSync

Boolean

否

true

是否开启数字人口型功能。默认值为 false。取值如下：

true：开启。开启后，人物口型将与翻译后的语音同步，提升直播的沉浸感。
false：关闭。

RealTime

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

参数	类型	是否必选	示例值	描述
VoiceShow	Boolean	否	`true`	是否开启同传声音功能。默认值为 `false`。取值如下： `true`：开启。开启后，将提供带有音色复刻效果的翻译语音。 `false`：关闭。

VoiceShow

Boolean

否

true

是否开启同传声音功能。默认值为 false。取值如下：

true：开启。开启后，将提供带有音色复刻效果的翻译语音。
false：关闭。

Extra

参数	类型	是否必选	示例值	描述
AMix	Object of AMix	否	`-`	混音配置。

Subtitle

参数	类型	是否必选	示例值	描述
Position	Object of Position	否	`-`	字幕位置。
Original	Object of Original	是	`-`	原文字幕配置。
Translation	Array of Translation	是	`-`	译文字幕配置。目前仅支持传入一个译文语种。

AMix

参数	类型	是否必选	示例值	描述
BGVolume	Float	否	`1.0`	原声音量，用于实现同传声音与原声的混合播放。默认值为 `0.2`。取值范围为 `[0, 1.0]`。说明仅在 `Pipe` 取值为 `realtime` 时生效。

Position

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

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

Relative

String

否

bottom

字幕在画面中的位置。默认值为 bottom。取值如下：

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

MarginTb

Float

否

0.05

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

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

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

Original

参数	类型	是否必选	示例值	描述
Language	String	是	`zh`	字幕语言。取值如下： `zh`：中文。 `en`：英文。
Font	String	否	`arial`	字体，默认值为 `arial`。可通过 GetSpeechConfig 获取当前账号下可使用的字体列表。
FontSize	Integer	否	`32`	字号。默认值为 `40`。取值范围为 [1,100]。
FontColor	String	否	`white`	字体颜色。默认白色。使用以下任一方式表示颜色值：颜色的英文名称，例如 `red` 表示红色。十六进制颜色代码，例如 `#FF0000` 表示红色。 R:G:B:A 颜色值，格式为`红:绿:蓝:透明度`，每个值的取值范围为 `[0,255]`，例如 `255:0:0:128` 表示半透明的红色。
Alignment	Integer	否	`0`	字幕对齐方式。默认值为 `0`。取值如下： `0`：居中对齐。 `1`：左对齐。 `2`：右对齐。
MaxRowNumber	Integer	否	`2`	原文字幕展示的最大行数，`0` 表示不限制行数。说明原文和译文的行数限制单独计算。
MaxCharNumber	Integer	否	`60`	每行字幕的最大字符数。默认值为 `60`。建议取值 `60`。
Hidden	Boolean	否	`false`	是否隐藏字幕。默认值为 `false`。取值如下： `true`：隐藏字幕。 `false`：显示字幕。
ShowPriority	Integer	否	`100`	展示优先级。默认原文字幕在上，译文字幕在下。取值越大，优先级越高。
Box	Object of Box	否	`-`	字体背景。
Border	Object of Border	否	`-`	字体阴影。

Translation

参数	类型	是否必选	示例值	描述
Language	String	是	`en`	字幕语言。取值如下： `zh`：中文。 `en`：英文。 `ja`：日语。 `es`：西班牙语。 `id`：印尼语。 `pt`：葡萄牙语。 `fr`：法语。 `de`：德语。
Font	String	否	`arial`	字体，默认值为 `arial`。可通过 GetSpeechConfig 获取当前账号下可使用的字体列表。
FontSize	Integer	否	`32`	字号。默认值为 `40`。取值范围为 [1,100]。
FontColor	String	否	`white`	字体颜色。默认白色。使用以下任一方式表示颜色值：颜色的英文名称，例如 `red` 表示红色。十六进制颜色代码，例如 `#FF0000` 表示红色。 R:G:B:A 颜色值，格式为`红:绿:蓝:透明度`，每个值的取值范围为 `[0,255]`，例如 `255:0:0:128` 表示半透明的红色。
Alignment	Integer	否	`0`	字幕对齐方式。默认值为 `0`。取值如下： `0`：居中对齐。 `1`：左对齐。 `2`：右对齐。
MaxRowNumber	Integer	否	`2`	译文字幕展示的最大行数，`0` 表示不限制行数。说明原文和译文的行数限制单独计算。
MaxCharNumber	Integer	否	`60`	每行字幕的最大字符数。默认值为 `60`。建议取值 `60`。
Hidden	Boolean	否	`false`	是否隐藏字幕。默认值为 `false`。取值如下： `true`：隐藏字幕。 `false`：显示字幕。
ShowPriority	Integer	否	`100`	展示优先级。默认原文字幕在上，译文字幕在下。取值越大，优先级越高。
Box	Object of Box	否	`-`	字体背景。
Border	Object of Border	否	`-`	字体阴影。

Box

参数	类型	是否必选	示例值	描述
W	Float	是	`1.0`	宽度。默认值为 `1.0`。单位为 px。
Color	String	是	`black@0.5`	颜色。格式为`颜色的英文名称@透明度`。透明度取值范围为 `[0,1]`，支持 2 位小数。默认值为 `black@0.5`。

Border

参数	类型	是否必选	示例值	描述
W	Float	是	`1.0`	宽度。单位为 px。
Color	String	是	`black@0.5`	颜色。格式为`颜色的英文名称@透明度`。透明度取值范围为 `[0,1]`，支持 2 位小数。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见返回结构。

参数	类型	示例值	描述
Code	Integer	`0`	状态码。
Message	String	`success`	状态信息。
Data	Object of Data	`-`	任务信息。

Data

参数	类型	示例值	描述
TaskID	String	`ab5d68****257f3f`	任务 ID。

请求示例

POST https://live.volcengineapi.com?Action=CreateSpeechTask&Version=2023-01-01
{
    "Name": "TaskA",
    "Rule": {
        "Pipe": "si",
        "Delay": 20,
        "Source": {
            "Url": "https://xxx/live/xxx.flv"
        },
        "EndTime": "2025-11-17T12:11:06+08:00",
        "StartTime": "2025-11-17T11:30:06+08:00",
        "Output": {
            "Url": [
                ""
            ]
        },
        "SI": {
            "LipSync": true
        },
        "RealTime": {
            "VoiceShow": true
        },
        "Extra": {
            "AMix": {
                "BGVolume": 1
            }
        },
        "Subtitle": {
            "Position": {
                "Relative": "bottom",
                "MarginTb": 0.05,
                "MarginLr": 0.2
            },
            "Original": {
                "Language": "zh",
                "Font": "arial",
                "FontSize": 32,
                "FontColor": "white",
                "Alignment": 0,
                "MaxRowNumber": 2,
                "MaxCharNumber": 60,
                "Hidden": false,
                "ShowPriority": 100,
                "Box": {
                    "W": 1,
                    "Color": "black@0.5"
                },
                "Border": {
                    "W": 1,
                    "Color": "black@0.5"
                }
            },
            "Translation": [
                {
                    "Language": "en",
                    "Font": "arial",
                    "FontSize": 32,
                    "FontColor": "white",
                    "Alignment": 0,
                    "MaxRowNumber": 2,
                    "MaxCharNumber": 60,
                    "Hidden": false,
                    "ShowPriority": 100,
                    "Box": {
                        "W": 1.0,
                        "Color": "black@0.5"
                    },
                    "Border": {
                        "W": 1.0,
                        "Color": "green@0.5"
                    }
                }
            ]
        },
        "GlossaryMap": {
            "字节跳动": "ByteDance",
            "视频直播": "MediaLive"
        }
    }
}

返回示例

{
    "ResponseMetadata": {
        "RequestID": "202511171128292187AC16BA39652EACFF",
        "RequestId": "20230604110420****100232280022D31",
        "Action": "CreateSpeechTask",
        "Version": "2023-01-01",
        "Service": "live",
        "Region": "cn-north-1"
    },
    "Result": {
        "Code": 0,
        "Message": "success",
        "Data": {
            "TaskID": "ab5d68****257f3f"
        }
    }
}

错误码

您可访问公共错误码，获取更多错误码信息。