Logo

智能分屏布局生成

将 2-16 个视频片段按共享拼图模板合成为一个分屏视频。接口只负责视频布局与渲染，不执行人脸追踪、说话人检测或人物选择。

同一个 file_id 可以在 clips 中重复出现，并为每个条目设置不同裁剪框。例如，可以把同一段原片的左半边和右半边同时放入两个槽位。

布局选择建议

模式适用场景行为
auto默认推荐；调用方不维护模板编号根据素材比例、目标画幅和槽位数量自动选择已审核模板，并返回实际 layout_id 与 random_seed
template需要固定版式或复现历史任务严格使用指定 layout_id；模板槽位数必须与 clips 数量一致

如需固定自动任务的结果，可以先使用 auto，再保存返回的 layout.layout_id，后续改用 template。random_seed 用于复现自动模式中同类版式的空间变体；素材数量、裁剪参数或输出画幅变化后，即使种子相同，最终布局也可能不同。

layout_id 模板目录

以下目录覆盖 2-16 个槽位，并分别展示 1:1、16:9 和 9:16 输出比例下的实际版式。选择比例后，可点击任意图片放大查看并确定所需的 layout_id。

选择输出比例查看对应版式，点击任意图片可放大。

创建任务

基本信息

项目值
请求方法POST
请求路径/task/video_split_screen
Content-Typeapplication/json
鉴权方式Authorization 请求头（直接传 API Key）
计费按所有选取片段中的最短时长计费

请求参数

参数名类型必填默认值说明
clipsarray是—2-16 个视频片段，数组顺序用于稳定处理相同条件下的槽位分配
layout_modestring否autoauto 自动选模板；template 使用指定模板
layout_idinteger条件必填—layout_mode=template 时必填，模板槽位数必须等于 clips 数量
random_seedinteger否任务自动生成0-2147483647；用于复现裁剪等价模板中的随机空间变体
output_ratiostring否9:16输出画幅：9:16、16:9、1:1
qualitystring否1080p输出清晰度：720p、1080p
fit_modestring否covercover 填满槽位并居中裁剪；contain 保留完整画面并补背景
duration_modestring否shortest当前版本仅支持 shortest
audio_modestring否firstfirst、mix 或 mute
gap_rationumber否0.008槽位间距占画布比例，范围 0-0.05
background_colorstring否#000000背景颜色，格式为 #RRGGBB

输出尺寸

output_ratio720p1080p
9:16720 × 12801080 × 1920
16:91280 × 7201920 × 1080
1:1720 × 7201080 × 1080

clips 条目

字段类型必填默认值说明
file_idstring是—已上传的视频文件 ID，可在不同条目中重复
begin_time_msinteger否0选取片段开始时间，单位毫秒
end_time_msinteger否视频结尾选取片段结束时间；0 或缺省表示视频结尾
cropobject否完整画面固定归一化裁剪框 {x,y,width,height}，各边必须在 [0,1] 内

crop 使用相对于源视频的归一化坐标：左上角为 (0,0)，右下角为 (1,1)。例如左半幅为 {"x":0,"y":0,"width":0.5,"height":1}。该裁剪先于 fit_mode 生效；使用 cover 时，系统可能在这个区域内部继续裁剪以填满目标槽位。

音频模式

值行为
first使用按 clips 顺序找到的第一条有效音频；全部静音时输出无音轨视频
mix混合所有带音频的输入，不延长最短输出时长
mute输出无音轨视频

请求示例：同一视频左右分屏

curl -X POST https://api.ai-mcn.tv:10000/task/video_split_screen \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clips": [
      {
        "file_id": "537489015178246",
        "begin_time_ms": 0,
        "end_time_ms": 10000,
        "crop": {"x": 0, "y": 0, "width": 0.5, "height": 1}
      },
      {
        "file_id": "537489015178246",
        "begin_time_ms": 0,
        "end_time_ms": 10000,
        "crop": {"x": 0.5, "y": 0, "width": 0.5, "height": 1}
      }
    ],
    "layout_mode": "template",
    "layout_id": 21,
    "random_seed": 20260611,
    "output_ratio": "9:16",
    "quality": "1080p",
    "fit_mode": "cover",
    "audio_mode": "first"
  }'

创建成功响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178400",
    "task_type": "video_split_screen",
    "status": "queued",
    "estimated_duration": 12,
    "estimated_queue_wait_duration": 0,
    "estimated_total_duration": 12
  }
}

查询任务结果

项目值
请求方法GET
请求路径/task/video_split_screen/{task_id}
鉴权方式Authorization 请求头（直接传 API Key）

output_result 字段

字段类型说明
versionstring输出协议版本，当前为 video_split_screen.v1
file_idstring合成视频文件 ID
download_urlstring合成视频下载路径
duration_msinteger输出时长，等于最短选取片段时长
width / heightinteger输出视频像素尺寸
layout.layout_idinteger实际采用的模板 ID
layout.equivalence_keystring模板的裁剪等价类标识；槽位尺寸要求相同的空间变体共享同一标识
layout.random_seedinteger本次实际使用的随机种子，可用于复现模板变体
layout.slotsarray按目标槽位顺序返回的精确映射

layout.slots 字段

字段类型说明
slot_indexinteger模板槽位序号，从 0 开始
clip_indexinteger对应请求中 clips 的数组下标
file_idstring该槽位使用的源视频文件 ID
begin_time_ms / end_time_msinteger实际使用的源片段时间范围
source_cropobject实际源裁剪框，归一化坐标；cover 可能在请求裁剪框内继续居中裁剪
destination_rectobject实际目标槽位，归一化坐标，已计入 gap_ratio
fit_modestring该槽位使用的填充方式

source_crop 与 destination_rect 都包含 x、y、width、height：

  • source_crop 相对于源视频，用于说明最终读取了原片的哪个区域。
  • destination_rect 相对于输出画布，用于说明该区域最终放在成片的哪里。
  • 两者都是 0-1 归一化坐标，不是像素坐标。
  • clip_index 用于回查请求条目；同一 file_id 重复出现时，应依靠它区分两个输入。

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178400",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "version": "video_split_screen.v1",
      "file_id": "537489015178401",
      "download_url": "/download/c1/537489015178401.mp4",
      "duration_ms": 10000,
      "width": 1080,
      "height": 1920,
      "layout": {
        "layout_id": 21,
        "equivalence_key": "crop:0.5x1,0.5x1",
        "random_seed": 20260611,
        "slots": [
          {
            "slot_index": 0,
            "clip_index": 0,
            "file_id": "537489015178246",
            "begin_time_ms": 0,
            "end_time_ms": 10000,
            "source_crop": {"x": 0.171875, "y": 0, "width": 0.15625, "height": 1},
            "destination_rect": {"x": 0.003704, "y": 0.004167, "width": 0.490741, "height": 0.991667},
            "fit_mode": "cover"
          },
          {
            "slot_index": 1,
            "clip_index": 1,
            "file_id": "537489015178246",
            "begin_time_ms": 0,
            "end_time_ms": 10000,
            "source_crop": {"x": 0.671875, "y": 0, "width": 0.15625, "height": 1},
            "destination_rect": {"x": 0.503704, "y": 0.004167, "width": 0.490741, "height": 0.991667},
            "fit_mode": "cover"
          }
        ]
      }
    }
  }
}

使用限制

  • 一个任务使用固定布局，不会在播放过程中自动切换模板。
  • 当前版本只支持固定 crop，不支持随时间变化的裁剪关键帧。
  • 输出时长固定为最短选取片段时长，不循环、不定格、不补黑。
  • 最多 16 个输入，系统还会根据输入总分辨率限制解码负载。
  • gap_ratio 会从每个槽位边缘向内留白；contain 产生的补边以及槽位间距均使用 background_color。
  • 本文档提供完整的 layout_id 可视化目录；如不需要固定版式，仍建议使用 layout_mode=auto。
  • 本接口不自动识别人脸或说话人；需要人物驱动的动态分屏时，应由上层业务先生成片段与裁剪参数。

错误码

错误码HTTP 状态码说明
6013400缺少 clips 等必填参数
6016400片段、裁剪、模板或渲染参数非法
6004404某个 file_id 不存在
6014400某个输入不是支持的视频类型
6502401鉴权失败
6201 / 6202402配额或余额不足