Mai skill · 输入契约

video-pip-compose 怎么用、输入是什么

把两个视频合成一个画中画输出。本页讲清 agent 提交时该填哪些字段，以及透明数字人、白边这些点怎么走。

task_type = video_pip_compose_mai · 给 owner 看 · 本轮范围：先不加自动扣图、不加 per-user 计费

一句话

它做什么

用户给两段 Mai 视频，想合成一个：主画面 + 角落小窗浮窗(PIP)、或上下分屏、或左右分屏。agent 把需求写成一段自然语言 instruction，加上两个视频 id 和布局参数，提交给异步 Gateway/Tobatsu。

overlay

浮窗(默认)

split_v

上下分屏

split_h

左右分屏

数据流

两个视频怎么进来

main_video_id
主画面/游戏＋ pip_video_id
要叠的小窗 → Gateway 解析 id→URL → pip-compose 渲染

Mai 侧 agent 只填 file_id；Gateway 把它解析成 Tobatsu 侧的 main_video_url / pip_video_url。透明数字人视频走 pip_video_id（= pip_video_url）这一路。

字段

输入字段（agent 可见 payload）

必填

字段	说明
`instruction`required	一句自然语言，描述想要的合成效果。白边、扣像、位置语义都写在这里。
`main_video_id`required	主视频 Mai file_id（背景 / 游戏画面），如 `A1b2C3.mp4`。
`pip_video_id`required	小窗视频 file_id。透明数字人 URL 走这里，如 `D4e5F6.mp4`。

布局选择

字段	取值 / 默认	说明
`layout`	`overlay`(默认) / `split_v` / `split_h`	浮窗 / 上下分屏 / 左右分屏。

浮窗字段（layout=overlay 时）

字段	取值 / 默认	说明
`overlay_position`	`tl`/`tr`/`bl`/`br`/`custom`，默认 `tr`	四角预设。没有 `center`；居中用 `custom` + x/y=0.5。
`overlay_x` / `overlay_y`	float 0..1	仅 `custom` 时生效。相对输出画布的位置（0=左/上，1=右/下）。
`overlay_size`	0.12..0.80，默认 `0.34`	小窗短边 ÷ 输出画布短边（不是主视频宽）。
`overlay_shape`	`circle`(默认)/`square`/`vrect`(9:16)/`hrect`(16:9)	小窗形状。`circle` 直径= size×短边。
`overlay_margin`	0..0.1，默认 `0.02`	用角落预设时离边距离。

分屏字段（layout=split_v / split_h 时）

字段	取值 / 默认	说明
`split_pip_side`	`first`/`second`，默认 `second`	split_v：first=上, second=下。split_h：first=左, second=右。
`split_pip_ratio`	0.20..0.50，默认 `0.40`	小窗那侧占输出分屏维度的比例。

取景 / 音量 / 备注（可选）

字段	取值 / 默认	说明
`main_framing` / `pip_framing`	`{offset_x,offset_y,zoom}` 或 `null`	每个视频的裁切/缩放。offset −1..1，zoom 0.30..3.20。省略=居中 cover。
`main_volume`	0..1，默认 `1.0`	主视频音量。
`pip_volume`	0..1，默认 `1.0`	小窗音量。数字人小窗的声音若已从主视频抽出，设 `0` 避免双声。
`user_brief`	string	给审计日志的创意简述；渲染器不用。

关键点 ①

透明数字人 → pip_video_id

透明背景的数字人视频，作为要叠加的那一层，填进 pip_video_id。Gateway 把它解析成 Tobatsu 侧的 pip_video_url。主画面（游戏/背景）走 main_video_id。

数字人的声音如果已从主视频里抽出，记得 pip_volume=0，否则会和主音轨重叠成双声。

关键点 ②

白边 / 扣像 → 写在 instruction 里

本轮没有独立的白边/扣图参数字段。白边、描边、形状这些都用自然语言写进 instruction，由 agent + 渲染端按语义处理。

「数字人位置：右上角圆形 PIP 加白边」
「把 B 放右下角圆形小窗，小窗静音」
「B 放主画面正中央，圆形浮窗，小窗占短边 30%」 → custom + x/y=0.5 + size 0.30

关键点 ③

本轮范围

○自动扣图 / 抠像接口 —— 本轮不加，透明素材由调用方自带

○per-user 计费 —— 本轮不加，沿用现有计费

●当前能力 —— 两视频合成：浮窗 / 上下分屏 / 左右分屏，Rendi 主路 + ffmpeg 兜底

Envelope

Gateway 自动注入（agent 不填）

上面的字段表是 agent 唯一要填的 payload。下面这些由 Mai 的 tobatsu-gateway tool 在派发时自动注入 —— agent 看不到、也不要填。契约本体在 $mai-async-gateway，这里列出来只为让 owner 看到 Tobatsu workflow 收到的完整输入。

字段	必需	说明
`callback_url`	required	终态回调地址（Mai 收结果）。
`callback_token`	required · 机密 · ≥16	回调鉴权 token，跟 payload 同级注入。
`failed_callback_url`	—	失败回调。⚠️ 拼写是 `failed_callback_url`，不是 `callback_failed_url` —— 后者会被 Tobatsu task-actions 以 extra_forbidden 拒掉。
`platform_terminal_callback`	—	对象 `{url, token, caller:"mai", caller_run_id}`，平台终态回调。
`business_run_id`	—	= gateway_run_id，回调里带回来做关联。
`gateway_task_id` / `gateway_run_id`	—	身份关联（Mai 侧 id，不是 Tobatsu task/run id）。
`delivery`	—	`{schema_version:1, mode:"mai_platform_artifacts", gateway_task_id, gateway_run_id}`。
`main_video_url` / `pip_video_url`	—	由 agent 填的 `main_video_id` / `pip_video_id` 解析而来 —— agent 传 id，gateway 注入 url。透明数字人就在 `pip_video_url`。

注：callback_url 是 delivery 回调，与 payload 平级（在 callback_envelope 内）。callback_token 是机密，和它平级注入；agent / payload 里都不出现。

样例

提交一个任务

# new_task：主视频 + 右下角圆形小窗，小窗静音
{
  "action": "new_task",
  "task_type": "video_pip_compose_mai",
  "payload": {
    "instruction": "把 A1b2C3.mp4 作为主视频，把 D4e5F6.mp4 放右下角圆形小窗，主视频保留声音，小窗静音。",
    "main_video_id": "A1b2C3.mp4",
    "pip_video_id":  "D4e5F6.mp4",   // ← 透明数字人走这里
    "layout": "overlay",
    "overlay_position": "br",
    "overlay_size": 0.24,
    "overlay_shape": "circle",
    "main_volume": 1.0,
    "pip_volume": 0.0
  }
}

通过 skill_toolcall_curl 打 POST /tobatsu-gateway。envelope（callback / gateway_task_id / run_id 等）由 $mai-async-gateway 契约统一带上，这里只列 agent 可见的 payload。改布局/位置/音量用 continue_task + 同一个 gateway_task_id。