曜幕（MLS）openApi 接口文档

Base URL：

• 生产环境：http://{PROD_DOMAIN}

所有 openApi 接口路径统一为：

POST /mls/mlsOpenApi/{接口名}

{接口名} 即下文各章节标题中的接口名（如 uploadMlsPart、addMlsTask）。

0. 概览

0.1 鉴权方式

openApi 全部接口使用 AK 签名鉴权，通过请求头传递 X-AccessId、X-TimeStamp、X-SignatureNonce、X-Signature（计算规则见 1.2）。

• 操作人身份由 AK 决定：调用方无需、也无法在入参中指定用户身份（uin、userId 等由服务端依据 AK 解析）。
• 不需要 token，接口也不接受登录态。
• 以下接口清单为可调用的完整集合。调用清单外的接口名将返回 flag=1007。

本文档只描述 openApi 开放的接口。控制台接口（登录态）使用不同的入口与鉴权方式，不在本文档范围内。

0.2 接口清单

不在本清单中的接口无法通过 openApi 调用，详见 附录 A。

1. 鉴权与返回约定（请先阅读）

1.1 Header 鉴权参数

缺失任一 Header 返回：

{"flag":1004,"flagString":"X-AccessId参数不能为空"}

AK 不存在、已停用或签名不匹配，返回：

{"flag":101,"flagString":"验证失败"}

1.2 X-SIGNATURE 计算规则

将以下字段按顺序拼接，中间以换行符 \n 连接：

1. accessId（即 X-AccessId）
2. accessKey（用户 AK 的 accessSecret）
3. signatureNonce（即 X-SignatureNonce）
4. timeStamp（即 X-TimeStamp）
5. body（HTTP 请求原始 Body 字符串；无 Body 时为空字符串）

stringToSign = accessId + "\n" + accessKey + "\n" + signatureNonce + "\n" + timeStamp + "\n" + body
X-SIGNATURE  = md5(stringToSign)

注意事项

• body 是未经解析的原始 Body 文本。签名必须在序列化 JSON 之后计算，任何空格、换行、字段顺序差异都会导致签名不一致。
• timeStamp 仅参与签名，服务端不做时效校验，请调用方自行控制重放风险（配合 signatureNonce 唯一化）。
• 建议使用 POST + application/json；签名按 POST 原始 Body 计算。

签名参考实现

$body  = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$nonce = (string)mt_rand(10000000, 99999999);
$ts    = time();
$sign  = md5($accessId . "\n" . $accessKey . "\n" . $nonce . "\n" . $ts . "\n" . $body);

// Header
// Content-Type: application/json
// X-AccessId: $accessId
// X-TimeStamp: $ts
// X-SignatureNonce: $nonce
// X-Signature: $sign

String body  = objectMapper.writeValueAsString(payload);
String nonce = String.valueOf(ThreadLocalRandom.current().nextLong(10000000L, 100000000L));
String ts    = String.valueOf(Instant.now().getEpochSecond());
String raw   = accessId + "\n" + accessKey + "\n" + nonce + "\n" + ts + "\n" + body;
String sign  = DigestUtils.md5Hex(raw.getBytes(StandardCharsets.UTF_8));

1.3 返回码约定

• flag = 100：请求成功
• flag != 100：请求失败，具体原因见 flagString

常用 flag：

分页字段的位置分两种，请以各接口示例为准：

• total 与 data 同级：getUserMlsList、getMlsAmountRunList；
• count 位于 data 内：getMlsTimbreList、getMlsResourceGroups、getMlsResourceGroupFiles、getMlsDramaList、getMlsEpisodeList、getMyMlsFeedbackList。

1.4 请求格式约定

• 所有接口统一使用 application/json 作为请求体格式。
• 请在请求 Header 中设置 Content-Type: application/json。
• 接口名大小写敏感，须与本文档完全一致。

1.5 用户身份如何确定

调用方无需也无法在入参中指定用户身份，服务端依据 X-AccessId 对应的账号解析出请求归属的「当前用户」。

请在请求体中不要传 uin、parentUin、userId 等身份字段；即使传入也会被服务端忽略并按 AK 绑定账号处理。

1.6 前置条件：手机号绑定

以下接口要求 AK 绑定账号满足「渠道用户免绑，非渠道用户须绑定手机号」，否则返回 flag=110 且 flagString 为提示信息：

addMlsTask、addMlsDrama、addMlsDramaVideo、submitMlsDramaTasks、uploadMlsPart、completeMlsUpload、saveMlsTaskResource、deleteMlsTaskResource、copyMlsTaskResourceVersion

2. 分片上传

2.1 上传接口测试样例视频

为便于联调「分片上传 → 完成上传」流程，可使用下方公开测试视频作为本地源文件：下载后按接口要求将各分片做 Base64 编码，再依次调用 上传文件分片、完成分片上传 两个接口即可完整走通。

该文件仅用于接口功能验证与联调，请勿作为生产业务素材依赖；实际分片时请遵守单分片小于 10M 等下文参数约束。

2.2 POST /mls/mlsOpenApi/uploadMlsPart

上传文件分片。

请求参数

分片序号从 1 开始连续递增，completeMlsUpload 前不可有缺号。

请求示例

{
  "fileName": "test.mp4",
  "part": "base64_encode('xxxxxxx')",
  "partNum": 1
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "partSize": 2097152,
    "partName": "1-test.mp4.part"
  }
}

data 中字段以上传服务的实际返回为准；上例为常见返回。

常见错误

2.3 POST /mls/mlsOpenApi/completeMlsUpload

完成分片上传；成功后返回可播放的视频地址与封面。

请求参数

请求示例

{
  "fileName": "test.mp4"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "fileName": "test.mp4",
    "size": 38112078,
    "location": "https://vod.example.com/u/1000/mp4/0x0/9c259c15483898854dad9938736a6c78.mp4",
    "thumbnail": "https://cdn.example.com/pic/g-dvr/u/1000/images/9c259c15483898854dad9938736a6c78/0/0"
  }
}

2.4 POST /mls/mlsOpenApi/getMaterialAccess

获取素材直传所需的签名参数，用于客户端直传素材到对象存储。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "signatureNonce": 54321,
    "accessId": "xxxxxxxx",
    "expireTime": 1771214133,
    "signature": "14224ad83a75b14b349300868161d726",
    "filePrefix": "mls-1000",
    "diyParam": "{\"platform\":\"apaas\",\"service\":\"private-upload\",\"classify\":\"video\",\"groupID\":\"01\",\"subUser\":\"\",\"subCode\":\"subId\",\"subService\":\"mls\"}"
  }
}

3. 基础配置（只读）

3.1 POST /mls/mlsOpenApi/getSupportLanguageList

获取当前账号可用的语言配置列表。

返回范围由账号的语种配置决定，共三种模式：

未配置时按 basic 处理。

请求参数

无。

早期文档提到的 enable 入参已不再生效：本接口固定只返回启用中的语种。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "list": [
      {
        "id": 2,
        "language_name": "英文",
        "language_code": "english",
        "enable": 1,
        "is_open": 1,
        "model_name": "english",
        "create_time": 1770444003,
        "uptime": 1770444003
      }
    ]
  }
}

data.list[] 字段说明：

列表条数按账号配置变化，请勿硬编码语言数量或 ID 范围。

3.2 POST /mls/mlsOpenApi/getMlsModeTypeList

获取可创建的任务类型（服务端有缓存，配置变更约 1 小时生效）。创建任务前先调此接口，用于渲染类型下拉、控制是否展示语种/源片选择。

请求参数

无。

出参 data[]

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "mode_type": "full_pipeline",
      "mode_name": "全流程",
      "mode_type_index": "full_pipeline",
      "billing_mode": "stage",
      "requires_language": true,
      "requires_origin": true,
      "allow_coexist": false,
      "is_internal": false,
      "execution_mode": "legacy",
      "stages": [],
      "remark": "多语言全流程输出：前置+语种叠加"
    },
    {
      "mode_type": "demo_stages_pipeline",
      "mode_name": "示例阶段流水线",
      "mode_type_index": "demo_stages",
      "billing_mode": "stage",
      "requires_language": true,
      "requires_origin": true,
      "allow_coexist": true,
      "is_internal": false,
      "execution_mode": "stages",
      "stages": [
        {"stageId": "subtitle_translate", "policy": "complete"},
        {"stageId": "tts", "policy": "complete"},
        {"stageId": "compose", "policy": "complete"}
      ],
      "remark": "下发时转为 mode_type=custom + stages"
    }
  ]
}

类型以服务端配置为准，不要在前端硬编码 mode_type 与单价；阶段单价一律取 3.3 getMlsStageList。

3.3 POST /mls/mlsOpenApi/getMlsStageList

获取阶段计费价目（服务端有缓存，配置变更约 1 小时生效），供展示单价。

虚拟阶段 storage（成片存储）、source_upload（源视频上传）会出现在列表中，但不会下发给处理流程。

请求参数

无。

出参 data[]

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "stage_id": "audio_separate",
      "stage_name": "音频分离",
      "price_per_second": 1,
      "bill_scope": "once",
      "sort": 20,
      "remark": "一条视频一次，多语种不重复"
    }
  ]
}

3.4 POST /mls/mlsOpenApi/getMlsTimbreList

获取音色库，供选用配音音色。

请求参数

出参 data

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "女声-温柔",
        "fileUrl": "https://xxx/timbre/1.mp3",
        "fileExt": "mp3",
        "fileSize": 204800,
        "enable": 1,
        "createTime": 1770444003,
        "updateTime": 1770444003
      }
    ],
    "count": 1
  }
}

3.5 POST /mls/mlsOpenApi/getMlsTranslationSceneList

获取启用的翻译场景列表（服务端有缓存，配置变更约 1 小时生效）。

用户选择场景后，将 scene_code 作为 job_param.sceneCode 传给创建任务接口；服务端会为该场景装配对应的翻译提示词。

请求参数

无。

出参 data

⚠️ 本接口 data 直接是数组，不是 {list: [...]}。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "id": 1,
      "scene_code": "news",
      "scene_name": "新闻",
      "enable": 1,
      "remark": "新闻类内容翻译"
    }
  ]
}

缓存说明：场景列表有约 1 小时缓存，修改后最多 1 小时生效。

4. 任务（多语言输出）

任务即「一条源视频 → 一个或多个目标语种成片」，主键为 episodeId。

4.1 POST /mls/mlsOpenApi/getUserMlsList

分页查询当前账号的多语言输出任务列表（仅未删除）。

请求参数

请求示例

{
  "page": 1,
  "num": 15,
  "resStatus": -1,
  "title": "工程1",
  "episodeId": ""
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "episodeId": 26,
      "dramaId": 14,
      "drama_video_id": 0,
      "source_type": "single",
      "uin": 1000,
      "parentId": "01",
      "userId": 1000,
      "title": "工程1",
      "duration": 32,
      "origin_url": "https://vod.example.com/u/1000/mp4/0x0/mls-1000a1b2c3d4e5f6a7b8c9d0e1f2a3b4.mp4",
      "origin_ready": 1,
      "thumbnail": "https://cdn.example.com/pic/xxx",
      "languages": "italian",
      "mode_type": "full_pipeline",
      "mode_type_index": "full_pipeline",
      "resStatus": 0,
      "results": "[{\"language\":\"italian\",\"status\":0,\"uptime\":1776133477,\"url\":\"\"}]",
      "job_id": "mls-xxxxxxxx",
      "param": {},
      "job_param": {},
      "stages": ["audio_separate", "subtitle_translate"],
      "is_pay": 0,
      "is_del": 0,
      "create_time": 1776133477,
      "uptime": 1776133477,
      "complete_time": 0,
      "jobResource": {}
    }
  ],
  "total": 3
}

主要出参字段说明

列表按 episodeId 倒序返回。无数据时返回 {"flag":100,"flagString":"success","data":[],"total":0}。

4.2 POST /mls/mlsOpenApi/getMlsDetail

获取单条任务详情。出参字段与 4.1 单条结构一致，额外返回 jobResource 明细。

请求参数

请求示例

{
  "episodeId": 26
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "episodeId": 26,
    "title": "工程1",
    "resStatus": 0,
    "results": "[{\"language\":\"italian\",\"status\":0,\"uptime\":1776133477,\"url\":\"\"}]",
    "jobResource": {}
  }
}

常见错误

4.3 POST /mls/mlsOpenApi/addMlsTask

创建多语言任务。

请求参数

resources[] 项：

resources 中 language + fileType 不可重复；resources 也可传 JSON 字符串。

请求示例

{
  "title": "工程1",
  "origin_url": "https://vod.example.com/u/1000/mp4/0x0/mls-1000a1b2c3d4e5f6a7b8c9d0e1f2a3b4.mp4",
  "languages": "italian",
  "mode_type": "full_pipeline"
}

无源片（如仅字幕翻译）示例：

{
  "title": "字幕任务",
  "mode_type": "subtitle_only",
  "languages": "english",
  "resources": [
    {"language": "original", "fileType": "subtitle", "fileUrl": "https://xxx/1.srt"}
  ]
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "episodeId": 30,
    "job_id": "mls-xxxxxxxx",
    "mode_type": "full_pipeline",
    "mode_type_index": "full_pipeline",
    "dramaId": 0,
    "drama_video_id": 0
  }
}

常见错误

4.4 POST /mls/mlsOpenApi/updateMlsTask

编辑任务。

请求参数

行为说明

• resStatus = 1（处理中）时不允许修改，返回 处理中不允许修改。
• languages：
  • 当 mode_type 的 requires_language = false 时不允许修改，返回 当前任务类型不允许修改语种；
  • 传入的语种若包含新语种，会写入 results（status=0）并把 resStatus 重置为 0、重新生成 job_id；
  • 若所有传入语种都已存在，则只更新标题等字段，不重置状态。
• 语种编码非法返回 flag=110（flagString 为具体原因）。

请求示例

{
  "episodeId": 26,
  "title": "222",
  "languages": "indonesian"
}

返回示例

{
  "flag": 100,
  "flagString": "success"
}

常见错误

4.5 POST /mls/mlsOpenApi/deleteMlsTask

删除任务（软删），同时软删该任务下素材。

请求参数

请求示例

{
  "episodeId": 27
}

返回示例

{
  "flag": 100,
  "flagString": "success"
}

常见错误

4.6 POST /mls/mlsOpenApi/retryMlsTask

失败重试。若任务因视频预处理未完成/失败导致未就绪，会先自动重试预处理。

请求参数

行为说明

• resStatus = 3（全部完成）返回 任务已完成无需重试。
• 不传 languages：把 results 中 status != 2 且 status != 4 的语种重置为 0（即重跑未成功/未完成的）。
• 传 languages：仅重置这些语种中未成功的；若全部已成功，返回 所选语言已完成。
• 重试会重新生成 job_id，并把 resStatus 置 0、complete_time 置 0。
• 若集下存在互斥任务（allow_coexist = false），返回冲突提示。

请求示例

{
  "episodeId": 26,
  "languages": "italian"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "job_id": "mls-xxxxxxxx",
    "preprocess_retry": {
      "job_no": "PP202609290001",
      "retry_mode": "pull"
    }
  }
}

preprocess_retry 仅在本次同时触发了预处理重试时返回。

常见错误

5. 任务素材与资源

5.1 POST /mls/mlsOpenApi/saveMlsTaskResource

在已有任务上新增或编辑素材。

• 新增/编辑：均插入新版本；同一「语种 + 资源类型」的旧版本仅降级为历史版本，历史版本保留。
• resStatus = 1（处理中）不允许操作，返回 处理中不允许修改素材。
• 素材会自动关联任务所属的集。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "id": 88,
    "version": "v3-20260929",
    "versionSeq": 3
  },
  "uptime": 1776133477
}

resStatus = 1 时会被拒绝；任务不存在时返回 任务不存在。

5.2 POST /mls/mlsOpenApi/deleteMlsTaskResource

软删指定历史素材版本。

当前最新版本不可删除；如需替换请用 5.1 上传新地址或 5.3 从历史版本创建副本。resStatus = 1 处理中不允许删除。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "deletedId": 12
  }
}

常见错误

5.3 POST /mls/mlsOpenApi/copyMlsTaskResourceVersion

基于选中历史版本的内容生成新版本并升为最新版本；版本号形如 v3-20260929-copy。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "id": 90,
    "version": "v4-20260929-copy",
    "versionSeq": 4,
    "url": "https://xxx/replaced.srt",
    "sourceId": 10
  }
}

5.4 POST /mls/mlsOpenApi/getMlsResourceGroups

按语种 + fileType 查询分组摘要（不含文件明细）。用于 TTS 候选等「一类型多文件、按 ID 分组」的资源；jobResource 默认不返回这类数据。

按集（drama_video_id）聚合查询：可传 drama_video_id 直接按集查，或传 episodeId 由服务端解析所属集。二者至少传一，都传时以 drama_video_id 为准；无剧集的孤立任务回退按任务查。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "list": [
      {
        "groupKey": "timbre",
        "groupValue": "12345",
        "fileCount": 3,
        "uptime": 1776133477
      }
    ],
    "count": 1
  }
}

分页时额外返回 page / pageSize。

常见错误

5.5 POST /mls/mlsOpenApi/getMlsResourceGroupFiles

查询某分组下文件列表。平铺返回该分组下全部版本（含历史），不嵌套 versions。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "groupKey": "timbre",
    "groupValue": "12345",
    "count": 1,
    "list": [
      {
        "id": 88,
        "episodeId": 26,
        "drama_video_id": 0,
        "fileName": "1.mp3",
        "groupKey": "timbre",
        "groupValue": "12345",
        "url": "https://xxx/1.mp3",
        "source": "backend",
        "uptime": 1776133477,
        "version": "v2-20260929",
        "versionSeq": 2,
        "isLatest": true
      }
    ]
  }
}

常见错误

6. 剧集与集管理

层级关系：剧集（drama）→ 集 / 视频（drama_video）→ 任务（task）。

• 剧集通过 dramaId 标识；
• 集（视频）通过 id 标识（在其它接口中称 drama_video_id）；
• 一条集可提交多种 mode_type 的任务。

6.1 POST /mls/mlsOpenApi/addMlsDrama

新增剧集。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "dramaId": 15,
    "name": "短剧A",
    "mode_types": "",
    "languages": "",
    "source_type": "batch",
    "remark": ""
  }
}

新建剧集的 mode_types / languages 为空，会在首次 submitMlsDramaTasks 时写入并锁定。

常见错误

6.2 POST /mls/mlsOpenApi/updateMlsDrama

更新剧集名称 / 备注。

任务类型与输出语种不可通过本接口修改，由 submitMlsDramaTasks 首次提交时写入。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "dramaId": 15,
    "name": "短剧A-改",
    "mode_types": "full_pipeline",
    "languages": "english",
    "source_type": "batch",
    "remark": "备注"
  }
}

常见错误

6.3 POST /mls/mlsOpenApi/getMlsDramaList

剧集列表。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "list": [
      {
        "dramaId": 15,
        "name": "短剧A",
        "mode_types": "full_pipeline",
        "languages": "english",
        "source_type": "batch",
        "remark": "",
        "create_time": 1776133477,
        "uptime": 1776133477,
        "video_count": 12
      }
    ],
    "count": 1
  }
}

常见错误

6.4 POST /mls/mlsOpenApi/getMlsDramaDetail

剧集详情，含各集及其下属任务摘要。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "dramaId": 15,
    "name": "短剧A",
    "remark": "",
    "mode_types": "full_pipeline",
    "mode_type_list": ["full_pipeline"],
    "mode_types_configured": true,
    "languages": "english",
    "source_type": "batch",
    "create_time": 1776133477,
    "uptime": 1776133477,
    "videos": [
      {
        "id": 101,
        "dramaId": 15,
        "title": "第1集",
        "origin_url": "https://xxx/1.mp4",
        "thumbnail": "https://xxx/1.jpg",
        "duration": 120,
        "origin_ready": 1,
        "preprocess_status": 2,
        "preprocess_fail_msg": "",
        "sort": 1,
        "source_type": "batch",
        "list_type": "default",
        "task_count": 1,
        "tasks": [],
        "jobResource": {}
      }
    ]
  }
}

常见错误

6.5 POST /mls/mlsOpenApi/deleteMlsDrama

删除剧集：级联删除各集及其下属任务（软删）。

剧集下存在处理中任务（resStatus = 1）时拒绝删除。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "dramaId": 15,
    "deleted_task_count": 12
  }
}

deleted_task_count 为被级联软删的任务数。

常见错误

6.6 POST /mls/mlsOpenApi/addMlsDramaVideo

向剧集添加视频（集）。新增后服务端会按需启动该集的视频预处理。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "id": 102,
    "dramaId": 15,
    "title": "第2集",
    "origin_url": "https://xxx/2.mp4",
    "thumbnail": "",
    "duration": 0,
    "origin_ready": 0,
    "preprocess_status": 0,
    "sort": 2,
    "source_type": "batch",
    "list_type": "default",
    "task_count": 0,
    "tasks": [],
    "jobResource": {}
  }
}

origin_ready = 0 表示预处理进行中；处理完成后才会变为 1（此时才可提交任务）。

常见错误

6.7 POST /mls/mlsOpenApi/getMlsEpisodeList

集（视频）列表，返回各集及其下属任务摘要。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "list": [
      {
        "id": 101,
        "dramaId": 15,
        "drama_name": "短剧A",
        "title": "第1集",
        "origin_url": "https://xxx/1.mp4",
        "origin_ready": 1,
        "preprocess_status": 2,
        "duration": 120,
        "sort": 1,
        "task_count": 1,
        "tasks": [],
        "jobResource": {}
      }
    ],
    "count": 1
  }
}

6.8 POST /mls/mlsOpenApi/getMlsEpisodeDetail

集（视频）详情，额外返回 drama_name。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "id": 101,
    "dramaId": 15,
    "drama_name": "短剧A",
    "title": "第1集",
    "origin_url": "https://xxx/1.mp4",
    "origin_ready": 1,
    "task_count": 1,
    "tasks": [],
    "jobResource": {}
  }
}

常见错误

6.9 POST /mls/mlsOpenApi/updateMlsEpisode

更新集（视频）名称。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "id": 101,
    "title": "第1集-改"
  }
}

常见错误

6.10 POST /mls/mlsOpenApi/deleteMlsDramaVideo

删除集（视频）：级联软删该集下的任务。

该集存在处理中任务（resStatus = 1）时拒绝删除。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "id": 101,
    "deleted_task_count": 1
  }
}

常见错误

6.11 POST /mls/mlsOpenApi/submitMlsDramaTasks

批量提交剧集下未提交的视频任务（事务：全成功或全失败）。

请求参数

行为说明

• 首次提交：写入剧集的 mode_types / languages 并锁定，之后不可修改（改了返回 任务类型已确定，不可修改 / 输出语种已确定，不可修改）。
• 按「集 + 类型」去重，已存在且未完成（resStatus IN (0,1)）的组合会跳过。
• 存在预处理失败的集时整体拒绝：视频「xxx」预处理失败，请重试预处理或删除后重新上传。
• 提交前整体预估额度，可用积分不足时整体拒绝：额度不足，不允许提交。
• 若无待提交组合，返回 created: [] 且 message 为 没有待提交的任务。

请求示例

{
  "dramaId": 15,
  "mode_types": "full_pipeline",
  "languages": "english,italian"
}

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "created": [
      {
        "videoId": 101,
        "videoTitle": "第1集",
        "mode_type": "full_pipeline",
        "episodeId": 31,
        "job_id": "mls-xxxxxxxx"
      }
    ],
    "created_count": 1,
    "mode_types": "full_pipeline",
    "languages": "english,italian",
    "first_submit": true
  }
}

常见错误

7. 视频预处理

7.1 POST /mls/mlsOpenApi/retryMlsVideoPreprocess

视频预处理失败重试。三种定位方式任选其一，优先级：job_no > videoId/id > episodeId。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "job_no": "PP202609290002",
    "retry_mode": "pull",
    "ref_type": "drama_video",
    "ref_id": 101,
    "message": "预处理已重新提交（仅网络上传）"
  }
}

常见错误

说明：本接口只重跑预处理（源片转码/上传），不会重置任务；若要重跑任务请用 4.6 retryMlsTask（其内部会在需要时自动触发预处理重试）。

8. 额度（积分）

8.1 POST /mls/mlsOpenApi/getMlsAmount

获取当前账号额度。

请求参数

无。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "last_amount": 10000,
    "reserved": 1200,
    "available": 8800,
    "invite_reward_total": 0
  }
}

8.2 POST /mls/mlsOpenApi/getMlsAmountRunList

额度（积分）使用记录。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "id": 1,
      "uin": 1000,
      "trade_amount": -12,
      "last_amount": 9988,
      "trade_type": 2,
      "trade_desc": "全流程-英语 翻译费用",
      "episodeId": 26,
      "uptime": 1776133477,
      "task_title": "工程1"
    }
  ],
  "total": 1
}

8.3 POST /mls/mlsOpenApi/checkMlsAmount

创建任务前判断额度是否充足。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "sufficient": true,
    "required": 1200,
    "last_amount": 10000,
    "reserved": 0,
    "available": 10000,
    "billable_seconds": 120,
    "language_count": 2,
    "mode_type": "full_pipeline",
    "base_price_per_second": 3,
    "lang_price_per_second": 1,
    "timestamp_check": false
  }
}

base_price_per_second / lang_price_per_second 仅为参考，真实单价请以 3.3 getMlsStageList 为准。

常见错误

9. 反馈工单

工单状态：pending 待受理 → processing 处理中 → replied 已回复 → closed 已关闭（不可重开）。

9.1 POST /mls/mlsOpenApi/getMlsFeedbackCategoryTree

反馈分类树（仅启用）。为两级结构。

请求参数

无。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "功能异常",
        "sort": 1,
        "children": [
          {"id": 11, "name": "无法上传", "sort": 1}
        ]
      }
    ]
  }
}

9.2 POST /mls/mlsOpenApi/submitMlsFeedback

提交反馈工单，初始状态 pending。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "id": 1001
  }
}

常见错误

9.3 POST /mls/mlsOpenApi/appendMlsFeedbackMessage

关单前追评。

已回复（replied）的工单追评后回到 processing；已关闭（closed）不可追评。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "id": 1001
  }
}

常见错误

9.4 POST /mls/mlsOpenApi/getMyMlsFeedbackList

我的反馈列表。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "list": [
      {
        "id": 1001,
        "title": "无法上传视频",
        "feedbackSource": "web",
        "categoryId": 1,
        "categoryName": "功能异常",
        "subCategoryId": 11,
        "subCategoryName": "无法上传",
        "status": "pending",
        "userUnread": 0,
        "createTime": 1776133477,
        "updateTime": 1776133477,
        "closeTime": 0
      }
    ],
    "count": 1
  }
}

列表按 userUnread 倒序、id 倒序返回。

9.5 POST /mls/mlsOpenApi/getMyMlsFeedbackDetail

我的反馈详情，仅返回对用户可见的消息；打开后会自动清除未读标记。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "id": 1001,
    "title": "无法上传视频",
    "status": "replied",
    "userUnread": 0,
    "content": "上传一直失败",
    "images": ["https://xxx/1.png"],
    "pageUrl": "https://xxx/upload",
    "clientVersion": "1.2.0",
    "deviceInfo": "iPhone 15",
    "relatedType": "task",
    "relatedId": "26",
    "messages": [
      {
        "id": 1,
        "senderType": "user",
        "msgType": "user",
        "content": "上传一直失败",
        "images": ["https://xxx/1.png"],
        "adminName": "",
        "createTime": 1776133477
      }
    ]
  }
}

9.6 POST /mls/mlsOpenApi/closeMyMlsFeedback

用户关闭工单（不可重开）。

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "id": 1001,
    "closeTime": 1776133477
  }
}

常见错误

附录 A：接口可用范围

openApi 的可用范围以本文档「0.2 接口清单」为准。调用清单之外的接口名，一律返回：

{"flag":1007,"flagString":"请求接口不存在,请参照文档说明"}

部分能力（如账号注册登录、控制台会话、渠道对接、支付回调、内部运维与各类回调通知等）不通过 openApi 提供，请按各自的对接方式处理。

如需新增开放接口，请联系对接负责人评估后开通。

附录 B：典型调用时序

B.1 单条任务（有源片）

1. POST /mls/mlsOpenApi/getSupportLanguageList   → 取可用 language_code
2. POST /mls/mlsOpenApi/getMlsModeTypeList       → 取 mode_type / requires_origin / requires_language
3. POST /mls/mlsOpenApi/uploadMlsPart            → 分片上传（partNum 从 1 递增）
4. POST /mls/mlsOpenApi/completeMlsUpload        → 取 location
5. POST /mls/mlsOpenApi/checkMlsAmount           → 预估额度是否充足
6. POST /mls/mlsOpenApi/addMlsTask               → 取 episodeId
7. POST /mls/mlsOpenApi/getMlsDetail             → 轮询 resStatus / results
8. POST /mls/mlsOpenApi/retryMlsTask             → 失败时重试
9. POST /mls/mlsOpenApi/deleteMlsTask            → 清理

B.2 剧集批量任务

1. POST /mls/mlsOpenApi/addMlsDrama              → 取 dramaId
2. POST /mls/mlsOpenApi/addMlsDramaVideo         → 逐集添加（origin_ready 初始为 0）
3. POST /mls/mlsOpenApi/getMlsDramaDetail        → 轮询各集 origin_ready，全部为 1 后才可提交
4. POST /mls/mlsOpenApi/retryMlsVideoPreprocess  → 预处理失败时重试
5. POST /mls/mlsOpenApi/submitMlsDramaTasks      → 首次提交须传 mode_types / languages，提交后锁定
6. POST /mls/mlsOpenApi/getMlsDramaDetail        → 查看各任务进度

B.3 查询进度建议

• 优先轮询 4.1 getUserMlsList（可一次按 drama_video_id 或 resStatus 过滤多条），比逐条 getMlsDetail 更省请求。
• 传 brief=1 可显著减小响应体（不返回 results / param / job_param / stages / jobResource）；确认全部完成后，再对需要的任务单独取详情。

附录 C：任务级环境变量 param

param 为任务级环境变量对象，随任务写入并在下发处理流程时透传。常用字段：

param 会原样透传给下游，新增字段请与业务确认，避免与既有约定冲突。

附录 D：结构化业务参数 job_param

job_param 描述「怎么做」，服务端会对字段做校验后透传给下游处理流程。常用字段：

附录 E：变更记录