资讯 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

API接入AI翻译配音

本文档介绍如何快速使用API调用AI翻译配音服务。

前置条件

在使用API服务之前,请您确保:

接口列表

AI翻译配音统一前缀:https://aip.baidubce.com/rpc/2.0/speech/publiccloudspeech/v1/echo

# 接口 Path 作用 额度校验
1 素材上传 /footage/upload 获取 BOS 临时上传凭证(STS),客户端直传
2 素材管理 /footage/manage 素材增删改查(action_type 分发)
3 任务创建 /task/create 创建视频 / 任务(4 种模式)
4 任务管理 /task/manage 任务查询 / 更新 / 确认 / 删除 / 导出(6 种操作) confirm_task_result
5 任务重试 /task/retry 重试已有任务并可调整配置

通用约定

鉴权方式

属性 参数名称 类型 是否必填 说明
鉴权令牌 access_token string 二选一 鉴权令牌
鉴权API Key Authorization string 二选一 鉴权API Key

公共响应结构

{
  "log_id": "20250622150000XXXX",
  "error_code": 0,
  "error_message": "success",
  "data": {}
}

error_code = 0 为成功;非 0 时 error_message 为失败原因,data 通常为 null

错误码总表

error_code error_message 典型场景
0 success 成功
100001 请求体非法 JSON 解析失败
100002 系统内部错误,请稍后重试 内部异常
100003 无效的参数 参数缺失、枚举非法
100005 账户无效权限 操作非本账号资源
100006 名称重复 素材名 / 剧集名 / 视频名重复
100007 数据更新失败 更新写入失败
100008 数据保存失败 入库失败
100009 数据删除失败 删除失败
100010 数据查询失败 记录不存在
100012 重试次数超过限制 非 failed 任务累计重试达 3 次
100016 任务类型不支持 export_task 传入非 compose 任务
100017 任务状态不支持 任务处于 init/doing
100019 名称长度超限 名称超 50 字符
100025 重复请求过于频繁,请稍后重试 5 秒内重复提交
100026 资源配额剩余不足 前置额度校验未通过
100027 生成上传文件Token失败 STS / SRT token 申请失败
100028 上传文件失败 非 BOS 外链转存失败
100030 数据数量验证失败 删除 ID 数与实际不一致
100032 剧集记录不存在 series_id 不存在

枚举值

  • 任务类型(task_type),常驻链按序推进:analysis(分析/角色提取)→ subtitle(字幕提取+擦除)→ translation(翻译)→ dubbing(上屏/配音)→ compose(合成)
  • 任务状态(task_status)init 待执行、doing 处理中、failed 失败、done 完成待校验、checking 校验中、checked 已校验
  • 语言source_language 仅支持 zhtarget_language 支持 enid
  • 字幕提取器(extractor_type)advancesrtFile字幕擦除(subtitle_remove_mode)nonestandardadvanced
  • 人脸类型(face_type)normalanime

接口描述

一、素材上传

  • Method:全部 POST
  • Content-Typeapplication/json

获取 BOS 临时上传凭证,用于客户端直传文件到 BOS。凭证有效期固定 1 小时。本接口仅生成凭证,不存储素材记录

请求参数

字段 类型 必填 说明
file_name string 文件名,需带后缀(如 video.mp4),最大长度 50 字符

请求示例

curl --location 'https://aip.baidubce.com/rpc/2.0/speech/publiccloudspeech/v1/echo/footage/upload' \
--header 'authorization: Bearer xxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "file_name": "video_sample.mp4"
}'

响应字段(data)

字段 类型 说明
access_key_id string 临时 Access Key ID,用于 BOS 客户端鉴权
secret_access_key string 临时 Secret Access Key,用于 BOS 客户端鉴权
session_token string 临时 Session Token,STS 鉴权必填
expiration string 凭证过期时间,ISO 8601 格式(如 2025-06-22T16:00:00Z
resource string BOS 目标对象路径(不含 bucket),如 prefix/projects/12345/uuid/video_sample.mp4
bucket_name string BOS Bucket 名称
endpoint string BOS Endpoint 地址,如 https://bos.bj.bcebos.com

响应示例

{
  "log_id": "20250622150000XXXX",
  "error_code": 0,
  "error_message": "success",
  "data": {
    "access_key_id": "STSxxxxxxxxxxxx",
    "secret_access_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "session_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "expiration": "2025-06-22T16:00:00Z",
    "resource": "prefix/projects/100001/550e8400-e29b-41d4-a716-446655440000/video_sample.mp4",
    "bucket_name": "echo-prod",
    "endpoint": "https://bos.bj.bcebos.com"
  }
}

使用流程

  1. 调用本接口获取临时凭证;
  2. 使用 BOS SDK 或 HTTP PUT,将文件直传到 endpoint/bucket_name/resource,参考 BOS STS 文档
  3. 上传成功后,将 https://<endpoint>/<bucket_name>/<resource> 作为 video_url 传入任务创建接口。

备注

  • 凭证有效期 1 小时,超时需重新调用本接口获取新凭证。
  • 每次调用生成唯一 UUID 路径,避免多次上传覆盖同名文件。

二、素材管理

  • Method:全部 POST
  • Content-Typeapplication/json

对素材(Footage)进行统一管理:创建、更新、分页查询、详情、删除。通过 action_type 区分操作,同一接口承载多种语义。

请求参数(公共部分)

字段 类型 必填 说明
action_type string 操作类型,枚举:createupdatelistdetaildelete
create object 条件必填 action_type=create 时必填
update object 条件必填 action_type=update 时必填
list object 条件必填 action_type=list 时必填
detail object 条件必填 action_type=detail 时必填
delete object 条件必填 action_type=delete 时必填

create 对象

字段 类型 必填 说明
footage_name string 素材名称(同账号下唯一)
footage_url string 素材 URL。若 URL 包含平台 BOS bucket 则视为已有 BOS 对象;否则后端会拉取该 URL 并转存到 BOS(同步上传,大文件或外链较慢时可能超时,推荐先用素材上传接口直传 BOS)
footage_desc string 素材描述

update 对象

字段 类型 必填 说明
footage_id int64 素材 ID
footage_name string 新素材名称(同账号下唯一,空串表示不更新)
footage_desc string 新素材描述(空串表示不更新)

footage_namefootage_desc 至少传一项。

list 对象

字段 类型 必填 说明
page int 页码,从 1 开始(1–100)
page_size int 每页大小(1–1000)
sort string 排序方式:asc/desc,默认 desc

detail 对象

字段 类型 必填 说明
footage_id int64 素材 ID

delete 对象

字段 类型 必填 说明
footage_ids int64[] 待删除素材 ID 列表(不可为空,每个 ID 必须存在且归属当前账号)

请求示例

// 创建素材
{
  "action_type": "create",
  "create": {
    "footage_name": "角色A参考视频",
    "footage_url": "https://bucket.bj.bcebos.com/path/to/footage.mp4",
    "footage_desc": "角色A 的参考素材"
  }
}

// 更新素材
{
  "action_type": "update",
  "update": { "footage_id": 123456, "footage_name": "角色A参考视频-新版", "footage_desc": "更新后的描述" }
}

// 查询列表
{
  "action_type": "list",
  "list": { "page": 1, "page_size": 20, "sort": "desc" }
}

// 查询详情
{
  "action_type": "detail",
  "detail": { "footage_id": 123456 }
}

// 删除
{
  "action_type": "delete",
  "delete": { "footage_ids": [123456, 123457] }
}

响应字段(data)

data 中只包含与 action_type 对应的一个字段,其余省略:

action_type data 字段 内容
create create { "footage_id": 123456 }
update update { "footage_id": 123456 }
list list pagepage_sizetotallist(Footage 数组)
detail detail Footage 对象
delete delete 回显 footage_ids

Footage 对象

字段 类型 说明
footage_id int64 素材 ID
footage_name string 素材名称
footage_url string 素材的预签名访问 URL(带过期时间)
footage_desc string 素材描述
create_time string 创建时间,格式 yyyy-MM-dd HH:mm:ss

响应示例

// list
{
  "log_id": "20250622150000XXXX",
  "error_code": 0,
  "error_message": "success",
  "data": {
    "list": {
      "page": 1,
      "page_size": 20,
      "total": 35,
      "list": [
        {
          "footage_id": 123456,
          "footage_name": "角色A参考视频",
          "footage_url": "https://bucket.bj.bcebos.com/path/...?authorization=...",
          "footage_desc": "角色A 的参考素材",
          "create_time": "2025-06-22 15:00:00"
        }
      ]
    }
  }
}

// detail
{ "log_id": "...", "error_code": 0, "error_message": "success",
  "data": { "detail": { "footage_id": 123456, "footage_name": "角色A参考视频",
    "footage_url": "https://...", "footage_desc": "...", "create_time": "2025-06-22 15:00:00" } } }

// create / update
{ "log_id": "...", "error_code": 0, "error_message": "success", "data": { "create": { "footage_id": 123456 } } }

// delete
{ "log_id": "...", "error_code": 0, "error_message": "success", "data": { "delete": { "footage_ids": [123456, 123457] } } }

备注

  • 同一账号 5 秒内不允许提交完全相同请求,否则返回 100025
  • 返回的 footage_url 是带签名的临时 URL,适合短时间内下载 / 预览;长期请保存素材 ID,后续通过 detaillist 重新获取新的预签名 URL。
  • 删除时若传入 ID 数量与实际查到的数量不一致,返回 100030(不会部分删除)。

三、任务创建

  • Method:全部 POST
  • Content-Typeapplication/json

创建视频处理任务,支持四种模式,通过 action_type 切换:

action_type 说明 创建内容 使用模板
single_video 单视频创建 创建/复用剧集 + 视频 + 任务链首个任务 video_dubbing_standard
batch_video 批量视频创建 创建/复用剧集 + 多个视频 + 每个视频的首个任务(全成或全败) video_dubbing_standard
single_task 单任务创建 对已有视频追加单个阶段的任务

常驻任务链:analysissubtitletranslationdubbingcompose。单视频 / 批量创建只触发首个阶段,后续阶段由配置自动推进 / 用户确认后推进。

请求参数(公共部分)

字段 类型 必填 说明
action_type string 枚举:single_video/batch_video/single_task
single_video object 条件必填 action_type=single_video 时必填
batch_video object 条件必填 action_type=batch_video 时必填
single_task object 条件必填 action_type=single_task 时必填

single_video 对象

创建一个新视频并启动完整任务链。series_id 为 0 时自动创建剧集(名称取 series_name,未传则用 video_name + "(系列)"),剧集名重复会报错。

字段 类型 必填 说明
series_id int64 剧集 ID,不传或传 0 则自动创建
series_name string 新建剧集名称(≤50 字符)
series_desc string 剧集描述(≤50 字符)
footage_id int64 关联素材 ID。传入后 video_url 被忽略,使用素材的 BOS 地址(会校验素材归属)
video_url string 视频 URL(footage_id 未传时必填)。若包含平台 BOS bucket 且以 http 开头,后端自动转成 BOS 路径
video_name string 视频名称(≤50 字符,同剧集下唯一)
video_desc string 视频描述(≤50 字符)
source_language string 原始语言,当前仅支持 zh
target_language string 目标语言,当前支持 enid
analysis_config object 分析阶段配置
subtitle_config object 字幕提取阶段配置
translate_config object 翻译阶段配置
dubbing_config object 配音阶段配置
compose_config object 合成阶段配置(本接口一般不传,由后续阶段使用)

配置对象为空时按默认值处理,但传入的字段需通过各自校验。

batch_video 对象

字段 类型 必填 说明
series_id int64 剧集 ID。传 0 则用 series_name 创建新剧集
series_name string 新建剧集名称(≤50 字符)
series_desc string 剧集描述(≤50 字符)
source_language string 同 single_video
target_language string 同 single_video
video_list object[] 视频参数列表,至少 1 条
analysis_config / subtitle_config / translate_config / dubbing_config object 子任务配置(同 single_video,作用于列表内所有视频)

video_list 元素

字段 类型 必填 说明
video_url string 视频 URL
video_name string 视频名称(≤50 字符,列表内不可重复,且不可与剧集已有视频重名)
video_desc string 视频描述(≤50 字符)

列表内重复名称返回 名称重复;与剧集已有视频重名返回 名称重复,重复视频名称:xxx

single_task 对象

针对已有视频追加单个阶段的任务。

字段 类型 必填 说明
video_id int64 已有视频 ID
task_type string 任务阶段:analysis/subtitle/translation/dubbing/compose
对应阶段 config object 条件必填 task_type 匹配的阶段配置必填,其余可省略

任务配置子对象(接口 3 / 5 通用)

analysis_config

字段 类型 必填 默认值 说明
need_human_check bool false 是否需要人工审核
disable_face_detection bool false 是否禁用人脸检测
face_type string normal 人脸类型:真人 normal、动漫 anime

subtitle_config

字段 类型 必填 默认值 说明
need_human_check bool false 是否需要人工审核
extractor_type string advance 字幕提取器:advancesrtFile
srt_file_url string 条件必填 extractor_type=srtFile 时必填,需为合法 SRT 文件;其他模式不应传
subtitle_remove_mode string none 字幕擦除模式:nonestandardadvanced
language string 同 source_language 字幕语言

translate_config

字段 类型 必填 默认值 说明
need_human_check bool false 是否需要人工审核
target_lang string 同 target_language 目标语言代码

dubbing_config

字段 类型 必填 默认值 说明
need_human_check bool false 是否需要人工校验
with_original_vocal bool false 是否用原人声音频填补空白

请求示例

// 1) single_video
{
  "action_type": "single_video",
  "single_video": {
    "series_id": 0,
    "series_name": "我的剧集",
    "series_desc": "可选",
    "video_url": "https://bucket.bj.bcebos.com/path/input.mp4",
    "video_name": "第一集",
    "video_desc": "第一集",
    "source_language": "zh",
    "target_language": "en",
    "analysis_config": { "face_type": "normal" },
    "subtitle_config": { "extractor_type": "advance", "subtitle_remove_mode": "none" },
    "translate_config": {},
    "dubbing_config": { "with_original_vocal": false }
  }
}
// 2) batch_video
{
  "action_type": "batch_video",
  "batch_video": {
    "series_name": "我的剧集",
    "source_language": "zh",
    "target_language": "en",
    "video_list": [
      { "video_url": "https://.../01.mp4", "video_name": "第一集" },
      { "video_url": "https://.../02.mp4", "video_name": "第二集" }
    ],
    "analysis_config": {},
    "subtitle_config": { "extractor_type": "advance", "subtitle_remove_mode": "none" },
    "translate_config": {},
    "dubbing_config": {}
  }
}

// 3) single_task
{
  "action_type": "single_task",
  "single_task": {
    "video_id": 100001,
    "task_type": "subtitle",
    "subtitle_config": { "extractor_type": "advance", "subtitle_remove_mode": "none" }
  }
}

响应字段(data)

action_type 返回对应字段:

action_type data 字段 内容
single_task single_task video_id(恒为 0)、task_iderror_codeerror_message
single_video all_task series_idvideo_idtask_iderror_codeerror_message
batch_video batch_task series_id + list(元素结构同 all_task

字段 类型 说明
series_id int64 剧集 ID
video_id int64 视频 ID(single_task 场景后端未回填,为 0)
task_id int64 任务 ID(单/批量创建时为首个阶段任务 ID)
error_code int 单条结果的错误码(0 表示成功)
error_message string 单条结果的错误信息

响应示例

// single_video
{ "log_id": "...", "error_code": 0, "error_message": "success",
  "data": { "all_task": { "series_id": 1001, "video_id": 200001, "task_id": 3000001 } } }

// batch_video
{ "log_id": "...", "error_code": 0, "error_message": "success",
  "data": { "batch_task": { "series_id": 1001, "list": [
      { "series_id": 1001, "video_id": 200001, "task_id": 3000001 },
      { "series_id": 1001, "video_id": 200002, "task_id": 3000002 }
  ] } } }

// single_task
{ "log_id": "...", "error_code": 0, "error_message": "success",
  "data": { "single_task": { "video_id": 0, "task_id": 3000010 } } }

备注

  • 5 秒内不允许提交完全相同请求,否则返回 100025
  • single_video / batch_video 只创建首个阶段任务,后续阶段由系统自动推进。
  • single_video.footage_id 有值时会校验素材归属,并使用该素材的 BOS 地址;此时 video_url 不生效。
  • subtitle_config.extractor_type=srtFile 时,srt_file_url 必须指向合法 SRT 文件。

四、任务管理

  • Method:全部 POST
  • Content-Typeapplication/json

对已创建的任务进行统一管理,通过 action_type 区分操作:

action_type 说明
list_video 分页查询当前账号下的视频列表
detail_task 查询任务详情(按 video_idtask_id
update_task_result 更新任务结果(人工修改字幕 / 角色 / 翻译等)
confirm_task_result 确认任务结果(完成人工审核,推动进入下一阶段)
delete_task 删除任务(按 video_id 删除整个视频,或按 task_ids 批量删除任务)
export_task 导出合成任务(compose)的最终视频 URL

请求参数(公共部分)

字段 类型 必填 说明
action_type string 见上表枚举
list_video object 条件必填 page(1–100)、page_size(1–1000)、sortasc/desc,默认 desc
detail_task object 条件必填 video_id / task_id 二选一
update_task_result object 条件必填 见下
confirm_task_result object 条件必填 见下
delete_task object 条件必填 video_id / task_ids 二选一
export_task object 条件必填 task_id(必须是 compose 类型任务)

detail_task 参数

字段 类型 必填 说明
video_id int64 二选一 视频 ID:返回该视频下全部任务
task_id int64 二选一 任务 ID:返回单个任务

至少传一个;都传时以 video_id 为准。

update_task_result 参数

更新任务的人工审核结果,仅允许操作归属当前账号的任务。建议先用 detail_task 拉取当前结果,在本地修改后整体提交。提交内容会覆盖任务的审核结果(checked_result),任务状态不变

字段 类型 必填 说明
task_id int64 任务 ID,必须 >0
analyze_result object 条件必填 任务类型为 analysis 时必填,见 analyze_result 结构
subtitle_result object 条件必填 任务类型为 subtitle 时必填,见 subtitle_result 结构
translate_result object 条件必填 任务类型为 translation 时必填,见 translate_result 结构
  • task_status 字段:本接口不支持修改任务状态,状态流转由 confirm_task_result 与后台调度推进。
  • 与任务类型不匹配的结果对象会被忽略;匹配的结果对象缺失时返回 无效的参数
  • 同一账号 5 秒内提交完全相同的请求会被拦截(返回 重复请求过于频繁,请稍后重试)。

各任务类型的覆盖语义

任务类型 必填结果对象 覆盖方式
analysis analyze_result 以提交的 characters 全量替换原角色列表;按 character_id 匹配原角色以保留后端字段(人脸向量、关联字幕、音色配置)。未提交的角色等同删除
subtitle subtitle_result 以提交的 subtitles 全量替换原字幕列表;按 id 匹配原字幕以保留说话人信息。未提交的字幕项等同删除
translation translate_result id 逐条覆盖原译文的 textstart_timeend_timecharacter_idlanguageoriginal_text;不新增、不删除条目

confirm_task_result 参数

确认任务结果,完成人工审核并推动任务进入下一阶段。提交的结果处理方式与 update_task_result 完全一致,区别是确认成功后任务状态由 checking 变为 checked,并在同一事务中创建下一阶段任务。

字段 类型 必填 说明
task_id int64 任务 ID,必须 >0
analyze_result object 条件必填 任务类型为 analysis 时必填,结构见下
subtitle_result object 条件必填 任务类型为 subtitle 时必填,结构见下
translate_result object 条件必填 任务类型为 translation 时必填,结构见下
  • 任务必须处于 checking 状态,否则返回 任务状态不支持
  • 同一账号 5 秒内提交完全相同的请求会被拦截。

delete_task 参数

字段 类型 必填 说明
video_id int64 二选一 视频 ID:删除整个视频及其所有任务
task_ids int64[] 二选一 任务 ID 列表:批量删除指定任务

两者至少传一个;都不为空时优先按 video_id 删除。

任务结果对象结构(接口 4 请求与响应通用)

analyze_result 结构

字段 类型 必填 说明
characters object[] 角色列表,元素结构见 角色对象

subtitle_result 结构

字段 类型 必填 说明
subtitles object[] 字幕项列表,元素结构见 字幕项对象
characters map<string, object> 角色信息映射,key 为 character_id仅响应回显使用,提交时忽略

translate_result 结构

字段 类型 必填 说明
translated_subtitles object[] 译文字幕项列表,元素结构见 字幕项对象
characters map<string, object> 角色信息映射,key 为 character_id仅响应回显使用,提交时忽略

字幕项对象

subtitlestranslated_subtitles 的元素结构:

字段 类型 必填 说明
id string 字幕项 ID,用于与原字幕匹配,必须回传
text string 字幕文本(译文场景为译文)
start_time float 起始时间(秒)
end_time float 结束时间(秒)
character_id string 关联角色 ID,旁白固定为 __narrator__
language string 语言代码,如 zhen
original_text string 原始文本(翻译结果中保存译前原文)

角色对象(characters 元素)

analyze_result.characters 的元素结构,提交时需整体回传:

字段 类型 必填 说明
character_id string 角色唯一标识,用于与原角色匹配
name string 角色名称
description string 角色描述
intro_name string 角色介绍中的名字
intro_description string 角色介绍中的描述
avatar string 角色头像(base64)
images string[] 角色关联图片的 BOS 链接列表
merge_id string 合并后的角色 ID(角色被合并时使用)
series_merge_id string 剧集维度合并后的角色 ID
gender string 性别
age string 年龄

subtitle_result.characters / translate_result.characters / dubbing_result.characters 的 value 为精简角色对象,仅含 character_idnameavatarmerge_idseries_merge_id

请求示例

// 查询视频列表
{ "action_type": "list_video", "list_video": { "page": 1, "page_size": 20, "sort": "desc" } }

// 查询任务详情(按 video_id)
{ "action_type": "detail_task", "detail_task": { "video_id": 200001 } }

// 更新任务结果
{
  "action_type": "update_task_result",
  "update_task_result": {
    "task_id": 3000001,
    "task_status": "checked",
    "subtitle_result": {
      "subtitles": [
        { "id": "473e1c93-1b8c-46", "text": "直到死去5年的丈夫站在我面前的时候",
          "start_time": 0.3, "end_time": 2.7,
          "character_id": "1000261_ebee37e3-d9fe-48_cluster_0", "language": "zh" },
        { "id": "a238d69d-3d9e-43", "text": "我才知道原来他没死",
          "start_time": 2.9, "end_time": 4.83,
          "character_id": "1000261_ebee37e3-d9fe-48_cluster_0", "language": "zh" }
      ]
    }
  }
}

// 确认任务结果
{ "action_type": "confirm_task_result", "confirm_task_result": { "task_id": 3000001 } }

// 删除任务
{ "action_type": "delete_task", "delete_task": { "task_ids": [3000001, 3000002] } }

// 导出合成视频
{ "action_type": "export_task", "export_task": { "task_id": 3000100 } }

响应字段(data)

action_type 返回对应字段,其余省略:

action_type data 字段 内容
list_video list pagepage_sizetotallist(VideoDTO 数组)
detail_task detail video_idtask_id + 五个阶段的 TaskDTO 数组
update_task_result update_task_result { "task_id": 3000001 }
confirm_task_result confirm_task_result { "task_id": 3000001 }
delete_task delete 回显 video_id / task_ids
export_task export task_idfinal_url

VideoDTO

字段 类型 说明
video_id int64 视频 ID
name string 视频名称
video_url string 视频的预签名访问 URL
source_language string 原始语言
target_language string 目标语言
duration int32 视频时长(秒)
description string 视频描述
create_time string 创建时间,yyyy-MM-dd HH:mm
update_time string 更新时间,yyyy-MM-dd HH:mm

detail 响应结构

字段 类型 说明
video_id int64 视频 ID(按 task_id 查询时为任务所属视频 ID)
task_id int64 任务 ID(按 video_id 查询时为 0)
analysis TaskDTO[] 分析阶段任务列表
subtitle TaskDTO[] 字幕提取任务列表
translation TaskDTO[] 字幕翻译任务列表
dubbing TaskDTO[] 字幕上屏 / 配音任务列表
compose TaskDTO[] 视频合成任务列表

TaskDTO

字段 类型 说明
video_id int64 视频 ID
task_id int64 任务 ID
task_type string 任务类型(见枚举)
task_status string 任务状态(见枚举)
fail_reason string 失败原因
need_check bool 是否需要人工校验
url_info object 视频 / 音频相关的 URL 信息
created_time string 创建时间
updated_time string 更新时间
analysis_config / subtitle_config / translate_config / dubbing_config / compose_config object 任务创建时的配置信息
analyze_result / subtitle_result / translate_result / dubbing_result object 任务结果(含审核修改后的版本)

export

字段 类型 说明
task_id int64 任务 ID(export)
final_url string 最终合成视频的预签名 URL(export)

响应示例

// list_video
{ "log_id": "...", "error_code": 0, "error_message": "success",
  "data": { "list": { "page": 1, "page_size": 20, "total": 1, "list": [
    { "video_id": 200001, "name": "第一集",
      "video_url": "https://.../input.mp4?authorization=...",
      "source_language": "zh", "target_language": "en",
      "duration": 600, "description": "",
      "create_time": "2025-06-22 15:00", "update_time": "2025-06-22 15:05" }
  ] } } }

// detail_task
{ "log_id": "...", "error_code": 0, "error_message": "success",
  "data": { "detail": {
    "video_id": 200001,
    "task_id": 0,
    "analysis": [
      { "video_id": 200001, "task_id": 3000001, "task_type": "analysis",
        "task_status": "done", "need_check": false,
        "created_time": "2025-06-22 15:00:00", "updated_time": "2025-06-22 15:03:00" }
    ],
    "subtitle": [], "translation": [], "dubbing": [], "compose": []
  } } }

// update_task_result / confirm_task_result
{ "log_id": "...", "error_code": 0, "error_message": "success",
  "data": { "update_task_result": { "task_id": 3000001 } } }

// delete_task
{ "log_id": "...", "error_code": 0, "error_message": "success",
  "data": { "delete": { "task_ids": [3000001, 3000002] } } }

// export_task
{ "log_id": "...", "error_code": 0, "error_message": "success",
  "data": { "export": { "task_id": 3000100, "final_url": "https://.../final.mp4?authorization=..." } } }

备注

  • detail_task 并发拉取各任务的审核结果并按 task_id 升序返回;结果中包含 BOS 预签名 URL,请及时使用。
  • export_task 仅支持 compose 类型任务,且要求任务已完成(url_info 中存在 final_video_url),否则返回 100016
  • 删除视频(delete_task.video_id)会级联删除该视频下所有任务;批量删除任务(task_ids)不会删除视频本体。
  • update_task_result 只写入人工审核结果、不改变任务状态;状态流转由 confirm_task_result 与后台调度推进。
  • confirm_task_result 要求任务处于 checking 状态,且会做前置资源额度校验,额度不足时返回 资源配额剩余不足

五、任务重试

  • Method:全部 POST
  • Content-Typeapplication/json

适用场景:任务 failed 后修复配置重跑;任务已完成但对结果不满意,换参数重跑。

请求参数

字段 类型 必填 说明
task_id int64 任务 ID
analysis_config object 仅当任务类型为 analysis 时生效
subtitle_config object 仅当任务类型为 subtitle 时生效
dubbing_config object 仅当任务类型为 dubbing 时生效

可覆盖字段白名单

重试时只有以下字段会覆盖到原任务配置,其余字段保持不变:

配置 可覆盖字段 说明
analysis_config disable_face_detection 是否禁用人脸检测
analysis_config need_human_check 是否需要人工审核(同时更新任务 need_check
subtitle_config extractor_type advancesrtFile
subtitle_config subtitle_remove_mode nonestandardadvanced
subtitle_config need_human_check 同时更新任务 need_check
dubbing_config with_original_vocal 是否用原人声音频填补空白
dubbing_config need_human_check 同时更新任务 need_check

请求示例

// 重试字幕任务,并调整提取器与擦除模式
{
  "task_id": 3000002,
  "subtitle_config": { "extractor_type": "advance", "subtitle_remove_mode": "advanced", "need_human_check": false }
}

// 重试失败的分析任务(failed 状态不计重试次数)
{
  "task_id": 3000001,
  "analysis_config": { "disable_face_detection": true, "need_human_check": false }
}

// 仅重试,不调整配置
{ "task_id": 3000003 }

响应字段(data)

字段 类型 说明
video_id int64 视频 ID(当前实现未回填,可能为 0)
task_id int64 任务 ID(与请求一致)
error_code int 错误码(0 表示成功)
error_message string 错误信息

响应示例

{
  "log_id": "20250622150000XXXX",
  "error_code": 0,
  "error_message": "success",
  "data": {
    "task_id": 3000002
  }
}

备注

  • 同一账号 5 秒内不允许提交完全相同的重试请求,否则返回 100025
  • 重试成功后 task_id 不变,可直接复用原 task_id 查询进度。
  • failed 状态任务重试不计次;其他终态任务最多重试 3 次。
  • translation / compose 阶段的配置目前无法通过本接口修改,需要联系后端支持。

附录:通过 STS 凭证上传文件的 Python 示例

"""通过 BOS 的 STS 临时凭证上传文件并返回文件链接"""

import os
import sys
import time
from io import BytesIO
from baidubce.bce_client_configuration import BceClientConfiguration
from baidubce.auth.bce_credentials import BceCredentials
from baidubce.services.bos.bos_client import BosClient

# ===== 配置区域:填入 /footage/upload 返回的 STS 临时凭证 =====
STS_ACCESS_KEY_ID = "<access_key_id>"
STS_SECRET_ACCESS_KEY = "<secret_access_key>"
STS_SESSION_TOKEN = "<session_token>"
BOS_HOST = "http://bj.bcebos.com"      # 对应响应中的 endpoint
BUCKET_NAME = "<bucket_name>"          # 对应响应中的 bucket_name


def upload_file(local_file_path, object_key=None):
    if not os.path.exists(local_file_path):
        print(f"文件不存在: {local_file_path}")
        return None

    if object_key is None:
        object_key = os.path.basename(local_file_path)

    bos_config = BceClientConfiguration(
        credentials=BceCredentials(STS_ACCESS_KEY_ID, STS_SECRET_ACCESS_KEY),
        endpoint=BOS_HOST,
        security_token=STS_SESSION_TOKEN
    )
    bos_client = BosClient(bos_config)

    # 大于 1GB 用分块上传,否则用简单上传
    file_size = os.path.getsize(local_file_path)
    max_simple_size = 1 * 1024 * 1024 * 1024  # 1GB

    if file_size >= max_simple_size:
        part_size = 100 * 1024 * 1024  # 每块 100MB
        total_parts = (file_size + part_size - 1) // part_size
        upload_id = bos_client.initiate_multipart_upload(BUCKET_NAME, object_key).upload_id

        part_list = []
        with open(local_file_path, 'rb') as f:
            part_number = 1
            while True:
                data = f.read(part_size)
                if not data:
                    break
                response = bos_client.upload_part(
                    BUCKET_NAME, object_key, upload_id, part_number, len(data), BytesIO(data))
                part_list.append({"partNumber": part_number, "eTag": response.metadata.etag})
                print(f"  [{part_number}/{total_parts}] 分块上传完成")
                part_number += 1

        bos_client.complete_multipart_upload(BUCKET_NAME, object_key, upload_id, part_list)
    else:
        bos_client.put_object_from_file(BUCKET_NAME, object_key, local_file_path)

    # 生成预签名 URL(1 小时有效)
    timestamp = int(time.time())
    signed_url = bos_client.generate_pre_signed_url(
        BUCKET_NAME, object_key, timestamp, expiration_in_seconds=3600).decode('utf-8')
    print(f"上传成功,签名链接(1 小时有效):\n{signed_url}")
    return signed_url


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("用法: python upload_by_bos_sts.py <文件路径> [对象路径]")
        sys.exit(1)
上一篇
AI翻译配音使用说明
下一篇
API文档