VideoStudio 开放接口文档

生产环境 Base URL

https://video.livepartner.fans

所有接口统一使用该域名（HTTPS，nginx 反向代理至视频工厂服务），路径前缀为 /v1。文档中的「<你的域名>」占位符会自动替换为当前访问域名。

标准接入步骤（最小可跑通链路）

1. 获取 API Key：向平台方申请客户账户，获取客户连接码（API_KEY，格式示例 ck_live_xxxxxxxx）。
2. 查询模板：调用 GET /v1/templates 获取可用模板，记下目标模板的 code（作为后续 template_id）与 material_spec.required 素材清单。
3. 创建任务：调用 POST /v1/video/generations 提交 template_id（可带 external_task_id 做幂等），返回 task_id。若未携带素材包，任务进入 awaiting_materials 并返回 missing_materials 缺失清单。
4. 上传素材：按缺失清单逐类调用 POST /v1/video/materials（multipart 直传）或 POST /v1/video/materials/presign + confirm（OSS 预签名直传）。
5. 提交任务：素材齐全后调用 POST /v1/video/generations/{task_id}/commit 使任务进入 queued；也可不调用，素材齐全后任务会自动入队。
6. 轮询/回调：轮询 GET /v1/video/generations/{task_id}（或配置 callback 接收终态回调），等待 status 变为 done。
7. 下载成片：从任务详情读取 result.url 直接下载，或由平台直传至 delivery_url / result_upload 指定地址。

任务状态机

创建 → awaiting_materials（等待素材） → queued（排队中） → rendering（渲染中） → done（完成）
                                                         ├→ failed（失败，自动退款）
                                                         └→ cancelled（取消，自动退款）
素材齐全自动入队：awaiting_materials → queued
缺料提交被拒：      commit → 409 + missing_materials（不入队）
MV 缺镜头脚本被拒：  commit → 409 + missing_materials + declared_slots（不入队）
解析失败/超时打回：  自动回到 awaiting_materials，GET 返回 error，补齐后重新 commit
超时回收：          awaiting_materials 超 24h → 自动取消并退款

以下资源清单页与接入文档同域公开、无需登录，可直接发给甲方/接入方查阅选型：

以上页面数据与平台实时一致；转场/歌词清单随插件库自动更新，字体清单在字体库变更后由平台重建。

所有接口均通过 Authorization 请求头携带你的客户 API Key（即「连接码」）：

Authorization: Bearer <你的_API_KEY>

未携带或无效的 Key 将返回 401 authentication_error。你可以在「设置 → 客户设置」中查看每个客户的连接码。

连接码说明

• 格式：以 ck_live_ 开头，例如 ck_live_40af5b765f1b90789f4c0000。
• 发放：由平台方在管理后台为每个客户生成，需妥善保管，泄露可导致账户被盗刷（后台支持随时重置）。
• 额度：每次成功出片按模板定价扣减账户 quota（可用额度）；失败 / 取消自动全额退款。可通过 GET /v1/balance 实时查询。

错误响应结构（OpenAI 风格）

鉴权失败统一返回 401，响应体为 OpenAI 风格错误结构，请以 error.type 判断错误类型、error.code 判断 HTTP 状态码：

{ "error": { "type": "authentication_error", "code": "401",
             "message": "缺少 Authorization 请求头或格式不正确",
             "retryable": false, "request_id": "req-xxxxxxxx" } }

常见鉴权失败

• 401（type=authentication_error）：未携带 Authorization 请求头、格式不正确、Key 不存在 / 已被禁用 / 客户状态非正常。后端不再细分，统一以该错误类型返回。
• 409（type=invalid_request_error）：缺料提交（详见「创建生成任务」），响应体附带 missing_materials 缺失清单；MV 任务缺少镜头脚本时同样返回 409，并额外给出 declared_slots（实际收到的槽位，便于自查漏交项）。
• 任务失败/打回时 error_code 取值：MISSING_SHOT_SCRIPT（MV 缺镜头脚本）、MATERIAL_PARSE_TIMEOUT（素材解析超时 > 5 分钟）、MATERIAL_PARSE_FAILED（素材解析失败）、QUEUE_TIMEOUT（排队 30 分钟无人认领，自动退款）、MISSING_MATERIALS（素材不齐）。前两者属「可补件后重提交」，任务停在 awaiting_materials。

查询当前账户可用的视频生成模型（OpenAI 风格模型列表）。/models 为兼容别名，不同第三方客户端对 Base URL 拼接方式不同，两者效果一致。

请求示例

curl https://<你的域名>/v1/models \
  -H "Authorization: Bearer <API_KEY>"

响应示例

{
  "object": "list",
  "data": [
    {
      "id": "xinghe-cd-c1",
      "object": "model",
      "created": 0,
      "owned_by": "xinghe",
      "description": "星光1号 · 宣传片（CD）"
    },
    {
      "id": "xinghe-mv-m1",
      "object": "model",
      "created": 0,
      "owned_by": "xinghe",
      "description": "星光1号 · 音乐MV（MV）"
    }
  ]
}

查询当前账户可用的视频模板及其素材要求。创建任务时必须指定一个模板的 code 作为 template_id。支持查询参数：category（模板类别，如 cd / mv）、status（上架状态，默认 enabled，仅返回已上架模板）。

请求示例

curl https://<你的域名>/v1/templates \
  -H "Authorization: Bearer <API_KEY>"

curl https://<你的域名>/v1/templates/CD-2024-005 \
  -H "Authorization: Bearer <API_KEY>"

响应示例

{
  "object": "list",
  "data": [
    {
      "object": "template",
      "id": "CD-2024-005",
      "code": "CD-2024-005",
      "name": "星光 1 号",
      "category": "CD",
      "status": "enabled",
      "version": "1.0.0",
      "ratio": "16:9",
      "resolution": "1080P",
      "desc": "...",
      "description": "...",
      "materials": "...",
      "duration": "...",
      "cover": "https://<你的域名>/uploads/templates/starlight-1.png",
      "cover_url": "https://<你的域名>/uploads/templates/starlight-1.png",
      "thumbnail": "https://<你的域名>/uploads/templates/starlight-1.png",
      "sample": "https://<你的域名>/uploads/templates/sample.mp4",
      "sample_url": "https://<你的域名>/uploads/templates/sample.mp4",
      "preview": "https://<你的域名>/uploads/templates/sample.mp4",
      "default_plugin": "plugin-001",   // 可选：模板默认渲染插件编号，任务未指定 plugin_id 时使用
      "template_type": "generator",       // generator=生成式 / project=工程模板（含工程文件，可经 AI 翻译官适配）
      "renderer": "kdenlive",            // 渲染后端：kdenlive / ffmpeg（工作机按 capabilities.render_backends 匹配认领）
      "ai_mode": "template-direct",       // template-direct=模板直接渲染 / ai-assisted=AI 辅助
      "design_resolution": { "width": 1920, "height": 1080, "fps": 30 },
      "supported_resolutions": [ { "width": 1920, "height": 1080, "fps": 30 } ],   // 模板支持的分辨率列表：创建任务传 output_resolution 必须命中其中一项
      "decorations_schema": { "decorations": {}, "requires_plugins": [] },   // 模板装饰 schema（五项 intro/ending/watermark/corner_tl/corner_tr）
      "material_spec": {
        "version": "1.0.0",
        "ratio": "16:9",
        "default_resolution": "1080P",
        "required": [
          { "key": "poster", "name": "海报图", "desc": "主视觉海报", "constraints": { "format": ["jpg","png","webp"], "max_size_mb": 10, "min_dimension": "1000x1000", "count": 1, "order": 1 } },
          { "key": "original_vocal", "name": "原唱", "constraints": { "format": ["mp3","wav","flac"], "max_size_mb": 50, "count": 1, "order": 3 } },
          { "key": "album_images", "name": "相册图", "constraints": { "format": ["jpg","png"], "max_size_mb": 20, "count": { "min": 10 }, "order": 7 } }
        ]
      }
    }
  ]
}

请求体（JSON）

水印 / 片头片尾 / 播放器标签（均可经 API 独立开关）

片头、片尾、水印、左上角歌名标签（播放器1）、右上角会员卡标签（播放器2）都提供用户级独立开关，甲方通过 /v1/video/generations 的 intro / ending / watermark / labels 四个字段控制，无需后台介入。

{
  "watermark": {
    "enabled": true,                  // 独立开关：true=显示；false=关闭水印；省略默认 true（只要传了对象即启用）
    "type": "image",                   // "image"=图片水印 或 "text"=文字水印，二者选其一
    "image_url": "https://cdn.example.com/wm.png",  // type=image 必填：http(s) 地址，服务端下载并做安全策略校验，下载失败任务将报错
    "text": "星光音乐相册 · 版权所有",  // type=text 必填：水印主文字
    "sub_text": "video.livepartner.fans", // type=text 可选：次行文字（如网址），两行显示
    "position": "bottom-right",           // 可选：top-left/top-right/bottom-left/bottom-right 固定角位；省略=按模板漂浮动画
    "opacity": 0.6                        // 可选：0-1 透明度，省略=模板默认
  },
  "intro": { "enabled": true, "url": "https://cdn.example.com/intro.mp4", "type": "video" },  // 片头：enabled=false 关闭（用模板默认片头）；省略=按模板默认
  "ending": { "enabled": true, "url": "https://cdn.example.com/end.png", "type": "image" },  // 片尾：enabled=false 关闭（用模板默认片尾）
  "labels": {                            // 播放器标签独立开关 + 可选覆盖文本
    "player1": {                        // 左上角歌名标签（播放器1）
      "enabled": true,                  // false=隐藏该标签
      "title": "《星河入梦》",            // 可选覆盖：歌名主标题
      "author": "词：林晚 曲：陈默"       // 可选覆盖：作者行
    },
    "player2": {                        // 右上角会员卡标签（播放器2）
      "enabled": true,                  // false=隐藏该标签
      "user_name": "星晴",               // 可选覆盖：会员昵称
      "platform_name": "星光音乐",        // 可选覆盖：平台名
      "level": "一级音乐人"            // 可选覆盖：会员等级
    }
  },
  "song_info": {                          // 若不传 labels 覆盖，则播放器标签文本取此处
    "song_name": "《星河入梦》",          // 歌名（labels.player1.title 缺省时显示）
    "lyricist": "林晚",                 // 词作者 → 显示为"词：林晚"
    "composer": "陈默",                 // 曲作者 → 显示为"曲：陈默"
    "user_name": "星晴",                // 用户昵称（labels.player2.user_name 缺省时显示）
    "member_level": "一级音乐人",       // 会员等级
    "platform_name": "星光音乐"         // 平台名称
  }
}

说明：

• 水印开关：watermark 兼容旧布尔语义——省略或 false=无水印；true=使用客户默认水印（后台客户资料中配置的文本或图片 URL）；对象形式下 enabled:false 同样关闭。
• 水印类型（图片/文字二选一，默认图片）：type 省略时自动推断——有 image_url→图片，有 text→文字，都没有则默认图片水印（走后台客户默认水印的图片）。type=image 需 image_url（http(s)，服务端下载校验）；type=text 需 text（主文字）+ 可选 sub_text（次行）。position 固定角位生效；opacity 0-1 控制透明度。
• 水印图专用约束：甲方传入的图片水印（type=image 的 image_url）只用于水印叠加层，绝不会被当作封面、头像、平台 Logo 等其他用途；系统内部按素材槽位严格隔离（水印固定为 watermark.png，与封面 cover.png、头像 avatar.png 互不相干）。
• 片头/片尾开关：intro / ending 传 {enabled:true, url, type:"image"|"video"} 启用并指定资源；enabled:false 关闭（退回模板默认片头/片尾）；省略则按模板默认。
• 播放器标签开关与素材归属（固定规则，不可混用）：
  • 播放器1（左上角歌名标签）：图片 = 作品封面；上方文字 = 歌曲名（song_name）；下方文字 = 词作者 / 曲作者（lyricist→"词：X"、composer→"曲：Y"，词曲整体用 songwriter→"词曲：X"）。下方文字严格限定为作者信息，绝不显示演唱者/昵称。
  • 播放器2（右上角会员卡标签）：图片 = 该用户头像（avatar 素材，缺失时用模板占位头像，绝不用封面/海报/Logo 顶替）；上方文字 = 用户昵称（user_name）；下方文字 = 平台标识名（platform_name，如"星光音乐"）。
  labels.player1 / labels.player2 各自 enabled:false 即可单独隐藏对应标签；覆盖文本（player1.title/author、player2.user_name/platform_name/level）可选，不传则按上述固定归属取 song_info 对应字段。
• 字段白名单校验：非白名单字段忽略；类型非字符串返回 400 code=4008；labels 结构非法或对应必填项缺失均返回 4008。
• 水印、片头、片尾、标签开关随任务落库并写入 work 端渲染清单（customer_requirements），查询任务接口原样回显（watermark / intro / ending / labels 字段）。
• prompt 元数据兜底：若 song_info 缺省或字段不足，服务端会从 prompt 的 ```json 代码块中提取 params 自动填补（title→song_name、artist→user_name、platformName→platform_name、lyricist/composer/songwriter/memberLevel→同名或对应字段）。显式传入优先，仅缺失字段被填补；画面作品名/作者/平台名必须通过结构化字段下发。

歌词格式（支持标准 LRC 与 JSON，自动识别）

歌词可通过 song_info.lyrics 传入，也可作为素材上传（type=line_lyrics 逐行歌词 / type=word_lyrics 逐字歌词，见第 5 节）。服务端与渲染端自动识别以下三种格式，无需声明：

• ① 标准 LRC（推荐，含逐字时间增强）：[mm:ss.xx] 时间戳 + 文本，支持 <mm:ss.xx> 逐字时间标签。
• ② 行级 JSON 数组：每个元素 { "time": 秒, "end": 秒, "text": "..." }（时间单位为秒，浮点）。逐字时间缺失时按字均分。
• ③ 逐字 JSON 数组：每个元素 { "word": "字", "start_s": 秒, "end_s": 秒, "_yiqiLineBreakAfter": true }（_yiqiLineBreakAfter 可选，标记该字之后换行；缺省时按每行连续字自动断行）。

JSON 歌词示例（逐字，与甲方"逐字对齐 JSON"格式一致）：

[
  { "word": "那", "start_s": 16.197, "end_s": 16.277 },
  { "word": "年", "start_s": 16.277, "end_s": 16.4 },
  { "word": "夏", "start_s": 16.4, "end_s": 16.6, "_yiqiLineBreakAfter": true },
  { "word": "天", "start_s": 16.6, "end_s": 16.9 }
]

行级 JSON 歌词示例：

[
  { "time": 16.197, "end": 20.146, "text": "那年夏天蝉鸣声声，" },
  { "time": 20.146, "end": 24.3, "text": "风穿过旧时光" }
]

material_package / result_upload 字段结构（甲方对象存储契约）

当甲方通过自己的对象存储交换素材包与成品时，可传入以下结构。字段原样保存并透传返回，便于双方对账：

{
  "material_package": {
    "mode": "object_storage",
    "schema_version": "cd-material-package/1.0",
    "external_task_id": "admin_cd_video_test_xxx",
    "package_sha256": "<ZIP_SHA256>",
    "archive_sha256": "<ZIP_SHA256>",
    "manifest_sha256": "<MANIFEST_SHA256>",
    "package_bytes": 123456789,
    "expires_at": 1786900000000,
    "materials_zip": {
      "method": "GET",
      "object_key": "temp/cd-video/admin_cd_video_test_xxx/input/materials.zip",
      "url": "https://<SIGNED_GET_URL>",
      "sha256": "<ZIP_SHA256>",
      "content_type": "application/zip"
    },
    "manifest": {
      "method": "GET",
      "object_key": "temp/cd-video/admin_cd_video_test_xxx/input/manifest.json",
      "url": "https://<SIGNED_GET_URL>",
      "sha256": "<MANIFEST_SHA256>",
      "content_type": "application/json"
    },
    "objects": [
      {
        "slot": "poster",
        "object_key": "temp/cd-video/admin_cd_video_test_xxx/input/objects/poster.jpg",
        "url": "https://<SIGNED_GET_URL>",
        "sha256": "<FILE_SHA256>",
        "bytes": 245760,
        "content_type": "image/jpeg"
      }
    ]
  },
  "result_upload": {
    "method": "PUT",
    "object_key": "temp/cd-video/admin_cd_video_test_xxx/output/final.mp4",
    "url": "https://<SIGNED_PUT_URL>",
    "content_type": "video/mp4",
    "expires_at": 1786900000000
  }
}

material_package（直接兼容甲方嵌套契约）：ZIP 下载地址读取优先级固定为 materials_zip.url → url → download_url → object_url；ZIP SHA-256 按 materials_zip.sha256 → archive_sha256 → package_sha256 → sha256 强校验（不匹配则 material_package_status=failed）；manifest 独立从 manifest.url 下载（甲方 manifest.json 不在 ZIP 内），SHA 按 manifest.sha256 → manifest_sha256 校验；objects 原样保存透传（用于逐文件核验与单文件补取），不报未知字段错误；expires_at 为 Unix epoch 毫秒。也兼容旧的扁平写法 { "url": "...", "sha256": "..." }。
manifest 槽位映射：有 manifest 时以 materials[].slot 为准（poster / original_audio / accompaniment / album_image:{index} / platform_logo / intro_video / outro_video），album_image:{index} 按数值 index 排序；无 manifest 时才启用文件名智能推断作为人工应急兜底。
result_upload：PUT 上传地址，任务完成后成片直传该地址，PUT 请求头 Content-Type 取自 result_upload.content_type（默认 video/mp4），仅写入 url 指定的对象；HTTP 200/201/204 视为成功，回写 sha256/size/mime/width/height。进度经 result_upload_status（pending/delivering/done/failed）可查。
签名过期恢复：下载/上传的签名 URL 过期时，任务标记为「等待地址刷新」（addr_refresh），不判永久失败、不重新渲染、不重复扣费；甲方通过 POST /v1/video/generations/{task_id}/refresh 更新地址后，任务从原阶段续跑（素材下载过期只重下缺失对象，成片上传过期只重传成片）。

请求示例

curl -X POST https://<你的域名>/v1/video/generations \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f2b8c9a-4d1e-4f2a-9b3c-<唯一键>" \
  -d '{
    "template_id": "CD-2024-005",
    "prompt": "周年庆主题曲",
    "resolution": "1080P",
    "watermark": { "enabled": true, "type": "text", "text": "星光音乐相册 · 版权所有", "position": "bottom-right" },
    "intro": { "enabled": true, "url": "https://cdn.example.com/intro.mp4", "type": "video" },
    "ending": { "enabled": true, "url": "https://cdn.example.com/end.png", "type": "image" },
    "labels": { "player1": { "enabled": true }, "player2": { "enabled": true } },
    "song_info": { "song_name": "《星河入梦》", "lyricist": "林晚", "composer": "陈默", "user_name": "星晴", "member_level": "一级音乐人", "platform_name": "星光音乐" },
    "external_task_id": "PO-20260816-0001"
  }'

响应示例

{
  "object": "video.generation",
  "id": "JH3OOFVHYNQXN0K0",
  "display_id": 47,
  "created": 1786257420,
  "model": "xinghe-cd-c1",
  "status": "awaiting_materials",
  "status_version": 1,
  "template_id": "CD-2024-005",
  "plugin_id": "plugin-001",  // 可选：实际使用的渲染插件编号（任务级覆盖，否则为模板默认值）
  "resolution": "1080P",
  "watermark": { "enabled": true, "type": "text", "text": "星光音乐相册 · 版权所有", "position": "bottom-right" },
  "intro": { "enabled": true, "url": "https://cdn.example.com/intro.mp4", "type": "video" },
  "ending": { "enabled": true, "url": "https://cdn.example.com/end.png", "type": "image" },
  "labels": { "player1": { "enabled": true }, "player2": { "enabled": true } },
  "song_info": { "song_name": "《星河入梦》", "lyricist": "林晚", "composer": "陈默", "user_name": "星晴", "member_level": "一级音乐人", "platform_name": "星光音乐" },
  "callback": null,
  "external_task_id": "PO-20260816-0001",
  "delivery_url": null,
  "material_package": null,
  "result_upload": null,
  "missing_materials": [
    { "key": "poster", "name": "海报图", "desc": "" },
    { "key": "original_vocal", "name": "原唱音频", "desc": "" }
  ],
  "material_acceptance": {},
  "estimate_seconds": 420,
  "usage": { "quota": 5000, "used": 3403, "remaining": 1597, "balance": 1598.0 }
}

响应中的 model 字段

所有视频生成任务均由本平台大模型驱动，响应中通过 model 字段标识所使用的模型：

"model": "xinghe-cd-c1"

模型按模板类别拆分（与 /v1/models 返回的模型 ID 一致）：CD 类模板使用 xinghe-cd-c1，MV 类模板使用 xinghe-mv-m1。客户端可在请求中通过可选字段 model 指定模型；不传时服务端按所选模板的类别自动匹配。

为指定任务上传自定义素材（图片 / 音频 / 视频），multipart/form-data 上传。任务渲染时将完全使用该客户上传的素材，不再使用默认素材库。

表单字段

请求示例

curl -X POST https://<你的域名>/v1/video/materials \
  -H "Authorization: Bearer <API_KEY>" \
  -F "task_id=JH3OOFVHYNQXN0K0" \
  -F "type=poster" \
  -F "file=@/path/to/cover.png"

响应示例

{
  "object": "video.material",
  "id": "JH3OOFVHYNQXN0K0",
  "display_id": 47,
  "type": "poster",
  "filename": "poster_1786257420.png",
  "url": "/uploads/<cust_id>/tasks/47/materials/poster_1786257420.png",
  "size": 245760,
  "task_status": "awaiting_materials",
  "missing_materials": [
    { "key": "original_vocal", "name": "原唱音频", "desc": "" },
    { "key": "album_images", "name": "相册图片", "desc": "" }
  ],
  "message": "素材已接收；仍缺 original_vocal、album_images，补齐后任务自动进入队列"
}

素材上传有两条等价受理的路径（2026-09-27 口径统一）：
① POST /v1/video/materials（multipart 表单直传）—— 适合小文件、实现最简单；
② POST /v1/video/materials/presign + PUT + POST /v1/video/materials/confirm —— 大文件推荐：申请一个 对象存储预签名直传地址（PUT 方法），客户端拿到 put_url 后直接 PUT 上传，不经过服务器、不占服务器带宽，传完后调 confirm 登记。
两条最终都落到同一份任务素材目录与同一套验收规则上，任选其一即可。

请求参数（JSON body）

请求示例

curl -X POST https://<你的域名>/v1/video/materials/presign \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"JH3OOFVHYNQXN0K0","type":"poster","filename":"cover.png"}'

响应示例

{
  "object": "video.material.presign",
  "task_id": "JH3OOFVHYNQXN0K0",
  "type": "poster",
  "oss_key": "materials/<cust_id>/tasks/47/poster_1786257420_cover.png",
  "put_url": "https://longsir-singleaz-1304349840.cos.ap-guangzhou.myqcloud.com/materials/...?...&Signature=...",
  "content_type": "任意（签名不校验该请求头）",
  "expires_in": 86400,
  "expires_at": "2026-09-28T00:30:00.000Z"
}

直传步骤

curl -X PUT "<put_url>" \
  -H "Content-Type: video/mp4" \
  --data-binary "@/path/to/file.bin"

直传完成后，调用本接口登记素材。服务端会校验对象存在，并把素材拉取到任务素材目录、更新任务状态（awaiting_materials → queued）。

请求参数（JSON body）

请求示例

curl -X POST https://<你的域名>/v1/video/materials/confirm \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"JH3OOFVHYNQXN0K0","type":"poster","oss_key":"materials/<cust_id>/tasks/47/poster_1786257420_cover.png"}'

响应示例

{
  "object": "video.material",
  "id": "JH3OOFVHYNQXN0K0",
  "display_id": 47,
  "type": "poster",
  "filename": "poster_1786257420_cover.png",
  "url": "/uploads/<cust_id>/tasks/47/materials/poster_1786257420_cover.png",
  "size": 245760,
  "task_status": "awaiting_materials",
  "missing_materials": [
    { "key": "original_vocal", "name": "原唱音频", "desc": "" },
    { "key": "album_images", "name": "相册图片", "desc": "" }
  ],
  "message": "素材已登记；仍缺 original_vocal、album_images，补齐后任务自动进入队列"
}

task_id 使用创建任务返回的任务编号（如 JH3OOFVHYNQXN0K0）；为兼容历史数据，数字形式的历史任务内部 id 也仍可查询。

响应示例

{
  "object": "video.generation",
  "id": "JH3OOFVHYNQXN0K0",
  "created": 1786257420,
  "status": "done",
  "status_version": 3,
  "template_id": "CD-2024-005",
  "resolution": "1080P",
  "progress": 100,
  "external_task_id": "PO-20260816-0001",
  "missing_materials": [],
  "error": null,
  "error_code": null,
  "material_acceptance": { "poster": 1, "original_vocal": 1 },
  "retry_count": 0,
  "material_package_status": "ingested",
  "result_upload_status": "done",
  "callback_status": "sent",
  "result": {
    "url": "https://<你的域名>/uploads/CD-2024-005/47.mp4",
    "duration": "04:15",
    "size": 195035136,
    "sha256": "9f2c...（成片 SHA-256 十六进制）",
    "mime": "video/mp4",
    "width": 1920,
    "height": 1080,
    "expires_in": 604800
  },
  "created_at": "2026-08-09 09:00:00",
  "finished_at": "2026-08-09 09:07:00"
}

当 status 不为 done 时，result 为 null。

返回当前 API Key 所属账户下最近的任务。 limit 可选，1-100，默认 20。每条记录的 id 为任务编号。

{ "object": "list", "data": [ { "id": "JH3OOFVHYNQXN0K0", "object": "video.generation", "status": "done", "template_id": "CD-2024-005", "resolution": "1080P", "progress": 100 } ] }

显式提交：客户端声明素材已就绪，主动把 awaiting_materials 任务提交进入 queued。提交不绕过素材完整性校验——缺必需素材仍返回 409 并附 missing_materials，任务不得入队。

MV 模板额外校验：MV 任务必须有镜头脚本（每镜 durationMs + videoPrompt）。只提供镜头底图、没有时长与提示词的交付包无法开工，提交时会返回 409 + missing_materials，并在 declared_slots 里列出实际收到的槽位（便于自查漏交了什么）。详见 §15 MV 视频制作对接。

缺镜头脚本时的 409 响应示例：

{
  "error": {
    "type": "invalid_request_error",
    "code": "409",
    "message": "MV 素材不齐全：缺少「镜头脚本」（每镜时长与提示词）。仅提供镜头底图无法开工——每镜时长决定生成时长、提示词决定画面内容。",
    "retryable": false,
    "request_id": "req-xxxxxxxx"
  },
  "missing_materials": [
    { "key": "shot_script", "name": "镜头脚本",
      "desc": "mv-shots.json：每镜 segmentIndex / shotIndex / imageUrl / videoPrompt / durationMs" },
    { "key": "shot_script_csv", "name": "或 01-镜头图/ + 02-镜头脚本.csv",
      "desc": "每镜提示词 + 时长(秒)" }
  ],
  "declared_slots": ["poster", "cover", "original_audio", "mv_shot:1", "…", "edit_script"]
}

curl -X POST https://<你的域名>/v1/video/generations/JH3OOFVHYNQXN0K0/commit \
  -H "Authorization: Bearer <API_KEY>"

成功返回任务详情（含 status=queued、status_version、missing_materials）与 message。错误：404 任务不存在；409 任务已结束 / 已在处理中 / 必需素材不齐全（响应体含 missing_materials 清单）。

⚠️ MV 交付包：镜头脚本（mv-shots.json）格式规范与打包自查

现象：POST /v1/video/generations 返回 200（任务已创建、额度已扣），但任务随后被打回 awaiting_materials，查询接口返回 error_code=MISSING_SHOT_SCRIPT。任务不会开工，且 24 小时内未补齐会自动取消并退款。

原因：包里已有 manifest.json（其 materials[] 已声明 mv_shots_json 槽位、mv.shots_object 也写明路径 input/mv-shots.json），也有全套镜头底图 input/objects/shot/00N.jpg，但打包时漏掉了这个 JSON 文件本身。manifest 里的声明与 script_sha256 不会自动把文件补齐。

注意：edit-script.md（剪辑脚本，通常只有几行作品概述）不能替代镜头脚本——它不含每镜时长与提示词。

正确格式：input/mv-shots.json

{
  "timeline": { "frameRate": 30, "durationMs": 134000, "audioDurationMs": 133944, "shotCount": 52, "shotMaxSeconds": 15 },
  "script": {
    "type": "story",
    "tone": "暖橙与霓虹青蓝对撞，黄昏逆光加海雾柔化（全片风格锚，会作为前缀注入每一镜提示词）"
  },
  "shots": [
    {
      "segmentIndex": 1,
      "shotIndex": 1,
      "segmentType": "verse",
      "lyricLine": "",
      "imageUrl": "input/objects/shot/001.jpg",
      "videoPrompt": "女孩站在雨夜街头，霓虹灯牌倒映在积水里，她缓缓抬头看向镜头，发丝随风微动",
      "camera": "push",
      "startMs": 0,
      "endMs": 2576,
      "durationMs": 2576
    }
  ]
}

上面只列了 1 条示意，实际需按 manifest.mv.shot_count 给满（例如 52 条）。

字段说明

硬约束（不满足会被打回或生成错误成片）

• shots[] 顺序必须与 input/objects/shot/001.jpg ～ 0NN.jpg 一一对应（底图按顺序配对）
• Σ durationMs 应等于 timeline.durationMs（建议同时提供 timeline.audioDurationMs = 音频实测时长）
• max(shots[].endMs) 必须 ≤ 音频时长（任何镜头都不得越过音频终点）
• 单镜 durationMs ≤ shotMaxSeconds（默认 15 秒），超过请拆成多个镜头
• 镜头条数 = manifest.mv.shot_count = 包内分镜图张数
• 音轨必须是 原唱（vocalUrl / originalVocalUrl），不得只给伴奏

打包自查 5 步（提交前务必做）

1. 解压交付包，确认 input/mv-shots.json 文件真实存在（不能只有 manifest 里的声明）
2. 打开它，确认 shots 数组非空，且每条都带 videoPrompt 与 durationMs
3. 确认 shots 条数 = 镜头图张数 = timeline.shotCount，且顺序与文件名序号一致
4. 对账 Σ durationMs = timeline.durationMs（±200ms），且 max(endMs) ≤ 音频时长
5. 确认音轨是原唱（vocalUrl / originalVocalUrl），不是伴奏

若已被打回：按 error_code/message 补齐后重新提交（或调用 POST /v1/video/generations/{task_id}/commit）即可续跑；超过 24 小时任务会被自动取消并退款，重新提交即可。同一份物料包重推时，已完成的镜头成果会保留。

取消任务并自动退款（退回 1 次额度）。仅 awaiting_materials / queued / pending 状态可取消；已进入渲染阶段不可取消。

curl -X POST https://<你的域名>/v1/video/generations/JH3OOFVHYNQXN0K0/cancel \
  -H "Authorization: Bearer <API_KEY>"

响应示例

{
  "object": "video.generation",
  "id": "JH3OOFVHYNQXN0K0",
  "status": "cancelled",
  "message": "任务已取消，额度已退还",
  "usage": { "quota": 5000, "used": 3403, "remaining": 1597, "balance": 1598.0 }
}

错误：404 任务不存在；409 已进入处理阶段无法取消。

对失败或已取消任务退还额度（failed 任务失败时会自动退款，本接口用于手动补退款场景）。每个任务仅可退款一次，重复调用返回 409。

curl -X POST https://<你的域名>/v1/video/generations/JH3OOFVHYNQXN0K0/refund \
  -H "Authorization: Bearer <API_KEY>"

响应示例

{
  "object": "video.generation",
  "id": "JH3OOFVHYNQXN0K0",
  "display_id": 47,
  "status": "failed",
  "refunded": true,
  "message": "退款成功",
  "usage": { "quota": 5000, "used": 3403, "remaining": 1597 }
}

错误：404 任务不存在；409 已退款不可重复、或状态非失败/已取消。

对失败或已取消任务重新进入队列，并重新校验素材齐全度（齐全 → queued，否则 → awaiting_materials）。计费规则：已退款任务重跑重新扣费（额度不足返回 402，账单流水类型 retry_charge）；未退款任务重跑沿用原扣费（流水类型 retry、金额 0）。每次重跑 retry_count +1。

curl -X POST https://<你的域名>/v1/video/generations/JH3OOFVHYNQXN0K0/retry \
  -H "Authorization: Bearer <API_KEY>"

成功返回任务详情（含 retry_count）与 message（任务已重跑（原任务已退款，本次已重新扣费） 或 任务已重跑（沿用原扣费））。错误：404 任务不存在；409 状态非失败/已取消；402 已退款任务重跑时额度不足。

签名地址过期续跑：当素材包下载或成片回传的签名 URL 过期（任务详情 addr_refresh 非空、ingest_note 含「等待甲方刷新地址」），甲方用此接口更新原任务的 material_package 或 result_upload 地址后，任务从原阶段续跑——素材下载过期只重下缺失对象，成片上传过期只重传已渲染成片。不重新渲染、不重新扣费，task_id 与账单状态保持不变。

curl -X POST https://<你的域名>/v1/video/generations/JH3OOFVHYNQXN0K0/refresh \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "result_upload": { "method": "PUT", "object_key": "temp/cd-video/.../output/final.mp4", "url": "https://<NEW_SIGNED_PUT_URL>", "content_type": "video/mp4", "expires_at": 1786900000000 } }'

至少提供 material_package 或 result_upload 其一，二者可同时更新。成功返回刷新后的任务详情（addr_refresh 清空、对应状态回 pending）。

回调人工重放：按 event_id 重新投递一次终态回调（用于甲方漏收后的补投）。请求体：{ "event_id": "evt_xxx" }。

curl -X POST https://<你的域名>/v1/video/callbacks/replay \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "event_id": "evt_xxx" }'

secret 配置（建议必配，支持降级）：回调签名密钥使用账户的 api_secret（在平台客户配置中维护，可轮换）。平台采用「两层兜底 + 降级兼容」： 第 1 层（签名回调）——配置了 api_secret 时发送 HMAC-SHA256 签名回调（见下方签名算法）； 第 2 层（降级兼容）——若甲方未配置 api_secret，平台降级为无签名回调仍照常投递（带 X-Unsigned: 1 头明确标记，callback_status=sent_unsigned），保证甲方能收到作品回执，甲方可据此识别非签名投递并自行决定信任级别。 为安全防伪造，强烈建议甲方配置 api_secret 并校验签名。

签名算法：HMAC-SHA256(api_secret, timestamp + "\n" + nonce + "\n" + raw_body)，经请求头 X-Signature / X-Timestamp（秒级时间戳）/ X-Nonce 传递。甲方需校验：签名、时间戳新鲜度（过期拒绝）与 nonce 去重（重复拒绝）。

回调体（终态 done/failed/cancelled 触发，event_id 同一任务稳定不变，便于幂等去重）：

{
  "event_id": "evt_xxx",
  "event_type": "video.generation.done",
  "task_id": "JH3OOFVHYNQXN0K0",
  "external_task_id": "admin_cd_video_test_xxx",
  "status": "done",
  "status_version": 9,
  "occurred_at": "2026-08-16T20:08:00+08:00",
  "result": { "sha256": "...", "size": 12345678, "mime": "video/mp4", "width": 1920, "height": 1080, "url": "https://..." },
  "error": null
}

重试策略：回调失败采用退避重试 1m → 5m → 15m → 1h → 6h → 24h（超过后保持 24h），任务详情可查 callback_attempts（尝试次数）、callback_next_at（下次重试时间）、callback_last_code（最后 HTTP 状态）与 callback_last_error（错误摘要）。同一 event_id 重复投递不重复归档，甲方按 event_id 幂等去重。

素材打回事件：material_rejected（2026-10-07 新增）

素材包验收不通过被打回时（status=awaiting_materials），平台主动推送 event_type=video.generation.material_rejected —— 甲方无需轮询即可知道被打回及原因，按 issues 逐条整改后直接重新推送（24 小时内续跑不取消）。

{
  "event_id": "evt_rej_xxx",
  "event_type": "video.generation.material_rejected",
  "task_id": "5PTQYNVVWTATBOPD",
  "status": "awaiting_materials",
  "error_code": "MATERIAL_SPEC_REJECTED",
  "issues": {
    "invalid_materials": ["缺少主角定妆照（mv.dressImageUrl / mv.dressAvailable 均未就绪）..."],
    "missing_materials": [...],
    "ingest_note": "拉包/解压阶段备注，无则为 null",
    "deadline_hours": 24
  }
}

• event_id 幂等口径：evt_rej_* 按「任务 + 状态版本 + 错误摘要」生成 —— 同一次打回的重试投递同 id；整改后重推再次被打回内容变化 → 新 event_id；随后终态回调各自独立。
• 签名 / 重试 / 幂等：与终态回调完全一致（X-Signature 校验 + 退避重试）。
• 前提：推送任务时需带 callback.url（未带则无法主动通知，甲方以轮询查询接口兑底）。

查询当前账户的扣费 / 退款流水记录。limit 可选，1-200，默认 50。

响应示例

{
  "object": "list",
  "data": [
    {
      "id": 1001,
      "task_id": "JH3OOFVHYNQXN0K0",
      "display_id": 47,
      "type": "charge",
      "amount": 0,
      "balance_before": 1597,
      "balance_after": 1596,
      "note": "创建任务扣费",
      "created_at": "2026-08-16 10:00:00"
    },
    {
      "id": 1002,
      "task_id": "JH3OOFVHYNQXN0K0",
      "display_id": 47,
      "type": "cancel_refund",
      "amount": 0,
      "balance_before": 1596,
      "balance_after": 1597,
      "note": "取消任务退款",
      "created_at": "2026-08-16 10:05:00"
    }
  ],
  "has_more": false
}

视频渲染完成后存于平台存储，甲方按以下流程获取成品：

1. 轮询或回调获知任务 status = done；
2. 调用 GET /v1/video/generations/{task_id}，读取 result.url；
3. result.url 为平台同域名下的成品下载地址，直接用 HTTP GET 下载即可；
4. 下载后甲方应自行转存到自己的文件桶并长期留存。

{
  "object": "balance",
  "quota": 5000,
  "used": 3403,
  "remaining": 1597,
  "currency": "次"
}

/v1/me 返回账户整体信息（OpenAI Organizations 风格）：

{
  "object": "organization",
  "id": "<cust_id>",
  "name": "<账户名称>",
  "balance": { "quota": 5000, "used": 3403, "remaining": 1597 },
  "status": "active"
}

任务级 error_code（查询任务接口回传，配合 status=awaiting_materials / failed）

错误响应结构

{
  "error": {
    "type": "authentication_error",
    "code": "401",
    "message": "缺少 Authorization: Bearer <API_KEY> 请求头",
    "retryable": false,
    "request_id": "req-20260816-a1b2c3"
  }
}

• v3.16（2026-10-24）：新增星河字画（文字 PV）CD 模板 xinghe-cd-001 —— ① 歌词 + 原唱音频直接出文字 PV 成片，服务端浏览器内编码（不占渲染机队列，30s 成片实测约 2 分钟）； ② 素材只要 line_lyrics + original_vocal，歌词也可用 song_info.lyrics 内嵌传； ③ 成片 H.264 + AAC（引擎原生 Opus 自动转 AAC，兼容 iOS/Safari/微信）、16:9、720P/1080P/2K/4K@30fps； ④ 歌词由引擎按节拍自动排轴，LRC 时间戳不参与对时（与 §17.2 的逐句对时口径不同，逐句卡点仍走 CD-2024-005）； ⑤ 缺歌词 → awaiting_materials + MISSING_LYRICS，补料后自动回队；编码失败自动重试 2 次。 详见 §18。同版修复模板列表接口三处缺陷：status=all 此前返回空列表、 category 大小写敏感（传 cd 查不到 CD 模板）、样片地址被拼成 https://<域名>/oss://... 死链（现按对象存储现签返回，可直接播放）。
• v3.13（2026-10-14）：自带海报镜口径修正 + 甲方接入范例（一次接对） —— ① §15.4.2「甲方自带海报镜规则」③ 修正：timeline.durationMs 与 shotCount 必须包含海报镜（= Σ 全部镜头时长 / 总镜数；自检闸门②按甲方原值直接比对，少写海报时长会被 MV_SELFCHECK_FAILED 打回——此前文档写「无需修改」与闸门实际口径不符，已修正）； ② 新增可直接照抄的 mv-shots.json 接入范例：海报镜（segmentType=poster，0→5000）+ 歌曲镜（自 5000 起顺延）+ 成片时间轴对账表（0→5s 静音无字幕 / 5s→末尾 音画同步 / 总时长 = 海报段 + 音频实测）+ 推包前 60 秒自查清单； ③ 明确音画口径：海报镜期间静音、无歌词字幕，歌曲音频与歌词由平台自动整体后移海报时长，甲方音频/歌词文件零改动。 渲染端配套 scripts-patch v110（一致性校验按「歌曲镜总长 = 脚本总长 − 海报段」与音频比对，海报段不再造成误拦）。 机器可读规范同步：openapi.yaml v1.3.5（segmentType 枚举新增 poster 并写明音画口径）、 mv-shots.schema.json（枚举同步 + 新增海报镜完整范例）。
• v3.12（2026-10-14）：海报镜独立设计落地（渲染端兑现 §15.4.2 既有承诺） —— 海报分镜（segmentType=poster）实现为独立静音前置段：音轨整体延迟海报时长（adelay）、 平台歌词字幕层整体后移同长，海报镜期间无歌声、无歌词字幕（修复短前奏歌曲歌词压到海报画面的问题）。 成片总时长 = 音频实测 + 海报时长（+片尾）；歌曲部分逐镜时长与音画对齐关系不变；甲方推送格式零改动。 构建产物新增 metadata.poster_independent_seconds 可观测字段。
• v3.11（2026-10-14）：转场接口端到端核准 + 文档口径补全 —— 甲方声明的 shots[].transition = {type, duration} 已核准全链路落地（逐镜声明 → 交付包透传 → 构建解析 → 渲染端 xfade 执行）。 文档补齐：① 声明层级改为三级（补交付包全局默认 manifest.transitions.default/per_shot，per_shot 数组下标即镜头序号）； ② 转场目录数量修正为 49 项（ffmpeg 原生 46 + 预留/自研 3）；③ rectopen/rectclose/fx_sparkle 标注 「当前按 fade 呈现、变体就绪后自动生效」；④ 非法 type 与 duration 超限行为明确（忽略/截断，不报错）。详见 §15.4.3。
• v3.10（2026-10-14）：delivery.lutCode 取值口径统一（编号型） —— 本文档 §15 交付示例曾出现名称型 "TEAL_ORANGE_01"，与 §16 及实际实现（滤镜库按「编号.cube」存取）矛盾； 最终口径统一为三位数字编号（001–204，含前导零，如 007），名称型取值将因库中无同名文件 按「不调色」处理并记录告警（不阻断出片）。不填 lutCode = 保持原片色彩（合法状态）。 滤镜总览与编号清单见 LUT 调色滤镜库（附 CSV 清单）。详见 §16。
• v3.9（2026-10-10）：三项链路修复（不涉及契约字段，推送格式零改动） —— ① 尾帧保真：修复「短镜头尾帧被拼接截断」——模型有 124 帧下限（如 4.5s 镜头实际生成 ≈5.2s）， 此前按目标时长硬截断会把已注入的尾帧剪掉；现改为 setpts 轻微压缩保帧（压缩比 ≤1.5）， 成片最后一帧严格对齐甲方尾帧图（见 镜头脚本首尾帧）； ② 长镜头动态路由：≥8 秒的镜头派给当前在线机器中显存最大者（动态选机，机器掉线自动落到下一台）， 不再锚定固定机器——杜绝「专用机掉线 → 长镜头永久排队」； ③ 修复 CD 成片末尾混入平台 logo（案例 #429 实锤）：2026-10-01 起素材包内的 watermark.png（= 甲方 platform_logo 的水印副本）因文件名为英文、未被相册池排除逻辑命中， 会按字母序排在相册图之后被当成最后一张照片全屏轮播；已修复照片池排除逻辑并发布渲染补丁（v104）， 水印图只以左下角小水印形式出现，不再进相册轮播。受影响时段（10-01 之后带图片水印的 CD 单）如需重制可联系重跑。
• v3.8（2026-10-09）：海报分镜（镜头 0）+ 主体锁定提示词 —— ① MV 开场「海报 5 秒静态展示」升级为生成机生成的动态海报分镜（segmentType=poster，默认 5000ms）： 平台默认自动插入（首帧取包内海报/封面图做「海报动态化」，甲方包无需任何改动）， delivery.posterShot 可开关（enabled=false 禁用）与覆盖（durationMs / imageUrl / prompt）； 成片总时长 = 原时长 + 海报时长（音轨整体延迟海报时长开场，前奏为纯画面，歌词-音乐对齐关系不变）； ② 甲方也可在 mv-shots.json 自带海报镜：镜号必须顺延（海报镜占 (0,0)，原镜头 shotIndex 依次 +1，不得与原镜头撞号）、 durationMs 必填、timeline.durationMs 无需修改；平台检测到自带海报镜即不再自动插入（防双海报）； ③ 主体锁定（甲方口径「背景风景可以变化，主体不能变、不能出现新的人」）：每一镜提示词逐镜注入 5 处人物硬约束——最高优先级主体锁定前置（提示词开头）+ 正向构成声明 + 甲方 videoPrompt 原文约束保留 + 末尾完整版收束 + hasPerson=false 镜头全镜禁人（连影子/倒影/背景人影都不允许）；纯提示词约束，无任何检测环节。 详见 §15.4.2。
• v3.6（2026-10-06）：交付规格变更（经双方确认） —— MV 镜头生成降档为 960×544 @ 24fps，经 AI 超分回 1920×1080 后按 24fps 交付（此前契约 1920×1080@30）。 要点：① 分辨率不违约（交付仍 1080P）、全片 24fps 无 judder（不做 30fps 帧重采样）、 生成提速 50%+、交付最快；仅帧率偏离契约（30 → 24）； ② 物料包内 06-视频生成要求.txt / manifest.delivery 若声明 1920×1080@30，平台按本口径统一交付，不再按原文执行； ③ 镜头脚本 schema 的 timeline.frameRate 缺省值 30 → 24（见 mv-shots.schema.json）； ④ 回退通道：平台侧环境变量开关可整体恢复原文口径（需线下沟通）。
• v3.7（2026-10-07）：定妆照快速整改指引 + 打回主动通知 —— ① §15.4.1 顶部新增「推包前 30 秒自查清单」（定妆照三种给法 + 四环自查 + 打回原因查询）； ② 新增 material_rejected 打回主动回调：素材验收打回（status=awaiting_materials）时主动推送签名回调 （event_type=video.generation.material_rejected），payload 含 issues 结构化整改清单 （invalid_materials / missing_materials / deadline_hours=24），失败自动退避重试； ③ 查询接口 GET /v1/video/generations/{id} 的 error / invalid_materials / missing_materials 口径不变。
• v3.5（2026-10-03）：MV 一致性核验链（四环）+ mv 节点新增三个字段 —— ① 核验链（见 §15.4.1）：核验单覆盖完整链条「MV 脚本 → 主角定妆照 → MV 镜头表（含首帧）→ 镜头首尾帧」，四环任一不通过即打回 awaiting_materials（不消耗算力、不产出成片），备注以「【素材包不予受理，请整改后重新推送】」开头逐条列明； ② 新增字段（乙方拉包即可见）：mv.dressImageUrl / mv.dressAvailable（主角定妆照地址与可用性）—— 定妆照的用途是换脸依据（是否需要换脸由甲方的换脸开关决定，我方已支持 mv.faceSwap 系列字段与说明句两种形态）、mv.tailFrameReadyCount（尾帧就绪数，与 shots[].endImageUrl 对应）；包内定妆照（dress/·定妆/ 目录或图）会被转存为我方可下载地址； ③ 行为变化（请注意）：定妆照设为 required —— 未定妆的作品推送接单会被核验闸门拦下（提示先生成定妆照），已定妆的作品不受影响； ④ 尾帧链交叉核验：tailFrameReadyCount 与包内实际匹配到的尾帧数不一致 → 打回（堵住「声明有尾帧、包里缺图」的漏网）； ⑤ 可观测：作品详情接口新增 mv_consistency，镜头级明细每镜带 end_frame_status（'' 未声明／ok 可下发／blocked 地址不可下载）与 end_frame_used（生成机实际用上的尾帧字段）；本地自查脚本 validate-mv-shots.mjs 同步增加「⑥ 定妆照」「⑦ 尾帧完整性」两项（与平台闸门同口径）； ⑥ 机器可读规范同步：openapi.yaml 升 v1.3.3（MvMaterialResponse.mv 加上述三字段）。
• v3.4（2026-10-03）：首尾帧 shots[].endImageUrl 由「可选增强」升级为硬要求 —— zip 包必须包含每一镜尾帧图（input/objects/shot-end/NNN.jpg）；包内缺失、上传失败或仅给包内相对路径 → 任务直接打回报错，不再静默退化为单首帧；同时取消「下一镜首帧兜底」，严格按契约首尾帧生成。见 §15.3 镜头脚本。
• v3.3（2026-10-02）：镜头级状态查询增加双鉴权（§15.6.1）—— 甲方现有 API 凭据 Authorization: Bearer <api_key> 可直接调用，按作品归属隔离（仅能查询自己客户名下的作品）；原 worker 管理令牌 x-mv-admin-token 通道不变，仍可查全部作品。机器可读规范同步 openapi.yaml v1.3.2。
• v3.2（2026-10-01）：镜头脚本新增「尾帧」字段 shots[].endImageUrl（首尾帧生成，可选） —— ① 用途：与 imageUrl（首帧）配对，锚定本镜的结束画面，使相邻镜头接得更连贯，也进一步约束模型不得脱离分镜源图自由创作； ② 自适应（重要）：提供该字段才启用首尾帧模式；不提供则完全按现行单首帧管线生成，行为与本次改造前完全一致、不受任何影响 —— 甲方可按需逐步接入，不提供不会造成任何兼容性问题； ③ 包内图：若单独提供尾帧图，请放 end/ · shot-end/ · lastframe/ 目录（按镜号取值），必须与 shot/ 严格分开（尾帧文件也常命名为 NNN.jpg，混入首帧映射会导致首帧被尾帧覆盖）； ④ 机器可读规范同步：openapi.yaml 升 v1.3.1（MvShot 加 endImageUrl）、mv-shots.schema.json 同步。
  ⑤ 同日新增：镜头脚本风格参数 script.style（可选）—— 全片统一的画面制作风格约束（如「赛博朋克霓虹夜景，高对比低饱和暗部，胶片颗粒」），注入每一镜提示词最前（优先级最高）；平台并按它做生成后本地抽帧风格质检：镜头内风格跳动（相邻帧色度突变）、画面偏离首帧基准、上下黑边、过曝/欠曝，任一超标自动换 seed 重生成（阈值可调、指标全量留档 score_json）。不提供 style 则一切照旧（tone 与既有质检行为不变）。
  ⑥ 同日新增：镜头级状态查询通道（§15.6.1）—— 甲方凭乙方 worker 管理令牌（配置于甲方系统 mv_worker_admin_token）调用 GET /api/mv/works/{workId}/shots，查询任意作品的逐镜头生成状态、种子与质检指标（含风格抽帧检查）；只读、独立令牌、不与接单/回传凭据混用。
• v3.1（2026-09-24）：文档合并为单一入口——原《MV 视频制作对接文档 v1.4》的全部内容并入本文档新增的 §15 MV 视频制作对接（整改对照 R1–R9、三种交付方式与接单入口契约、物料包字段硬性要求、渲染前自检闸门、交付规格、状态与运维、错误码与整改、联调回归 752/757/683、哈希与回传口径、常见问题）；原地址 /mv-api-docs.html 保留为跳转页（旧锚点自动映射到 §15 对应小节），甲方只需保存本页一个 URL；§14 素材验收与 §15 相互交叉引用，不再出现两份文档口径不一致的情况。
• v3.1（续）· 机器可读规范与自助校验：openapi.yaml 升级 v1.3.0，补全 MV 契约 —— 新增 POST /api/mv/inbound（接单入口）与三个需甲方实现的接口（GET /v1/mv-video/materials/{workId}、returns/complete、returns/refresh，以 x-implemented-by: provider 标注、servers 用 {api_base} 变量，可直接生成服务端骨架）、10 个组件 schema（MvMaterialResponse / MvTimeline / MvShot / MvDelivery / MvProviderReturn / MvCompleteRequest 等），并给任务 schema 补齐 error_code / mv_stage / mv_shot_done / mv_shot_total 等字段、修正 invalid_materials 为字符串数组；新增 docs/mv-shots.schema.json（镜头脚本 JSON Schema）与 docs/validate-mv-shots.mjs（零依赖本地自查脚本，与自检闸门同口径），甲方可在打包环节提前发现问题，见 §15.3+。
• v3.0（2026-09-24）：MV 时间轴硬校验（渲染前自检闸门）+ 音轨基准 + 根治"素材错配"（详见 §14.4、§15 MV 视频制作对接）—— ① 自检闸门：MV 任务在任何生成动作之前校验四条件（shots.length == timeline.shotCount == 分镜图张数；|Σ shots[].durationMs − timeline.durationMs| ≤ 200ms；max(endMs) ≤ 音频实测时长；durationMs 与音频实测偏差仅告警），任一不通过即转 awaiting_materials + error_code=MV_SELFCHECK_FAILED（message 附四个实测数值），不消耗算力、不产出成片； ② 时间轴口径：全片时长以音频实测为准（新增字段 timeline.audioDurationMs 为首选基准），逐镜严格按 shots[].durationMs（±1 帧），不再使用模板默认时间轴/固定镜头节奏，Σ镜头 > 音频 + 2s 一律拦停打回； ③ 音轨基准：MV 只用原唱轨（media.vocalUrl / originalVocalUrl），不再与伴奏混播，音画同步以该轨为准； ④ 根治「素材错配」根因：素材包未就绪时禁止使用模板自带测试素材顶替（此前导致成片尾部 46.3s / 68.1s 冻结空帧：测试包 44 镜脚本覆盖了甲方 23/27 镜脚本）——现在一律打回等待； ⑤ 哈希口径（§14.6）：确认我方 ingest 会重新打包 materials.zip，双方验收统一改为逐素材 sha 比对。
• v2.9（2026-09-20）：素材验收硬标准 + 交付规格硬保证（详见 §14）——① 素材验收：CD 必须用照片、MV 必须用视频，在「素材入库」与「渲染出包」两个环节强制校验，不合规一律打回（任务转 awaiting_materials、error_code=MATERIAL_SPEC_REJECTED、message 给出可读原因），不出片、不交付；查询接口新增 invalid_materials（结构化整改问题项）、ingest_note、material_package_status 回传，便于甲方自查整改。② 交付规格：修复「登记 1080P、成片实际 720P」的链路缺陷（素材包清单未下发目标规格，且共享素材包长期复用旧包）；现在渲染前强制下发目标规格，渲染端交付前用 ffprobe 校验成片规格，不符即阻止交付并自动重跑，平台侧另做交付审计（delivery_spec_ok / delivery_spec_mismatch）。已实测：登记 1080P 的任务，成片实测 1920×1080 通过审计后才入库。
• v2.8（2026-09-18）：新增 MV 镜头脚本格式规范与打包自查 —— 针对近期最高频的打回：交付包已含 manifest.json 与全套 shot/00N.jpg，但漏打 input/mv-shots.json 文件本身（manifest 里声明了槽位与 script_sha256，容易误判为"已提供"）。本次明确：① edit-script.md（剪辑概述）不能替代镜头脚本；② 给出 mv-shots.json 完整字段、示例与硬约束（shots[] 非空、每镜 videoPrompt + durationMs、ΣdurationMs = timeline.durationMs、单镜 ≤ shotMaxSeconds、与 shot/NNN.jpg 顺序一一对应）；③ 附「打包自查 3 步」；④ 文档顶部与「任务管理」章节加醒目提示。后端同版本一并修复 mv-shots.json 解析路径的两个潜伏缺陷（videoPrompt 组装变量未定义、运镜描述二次归一化叠加重复）。
• v2.7（2026-08-21）：作品回执「两层兜底 + 降级兼容」——① 修复回调链路 callback_status 未初始化导致终态回调永不触发的缺陷（终态任务回调扫描放宽至 NOT IN ('sent','sent_unsigned','blocked')，兼容存量 none）；② 任务进入终态时主动立即回调（不再等 30s 扫描），接入 done/成片回传/最终失败/取消各路径；③ 降级兼容：甲方未配置 api_secret 时降级为无签名回调仍照常投递（带 X-Unsigned: 1 头，callback_status=sent_unsigned），不再 blocked 不发，保证甲方必能收到作品回执；④ callback 字段支持 URL 字符串或 {"url":...}，callback_status 状态扩展为 sent/sent_unsigned/failed/blocked；⑤ 回执投递失败按退避序列自动重试（1/5/15/60/360/1440 分钟），可用 POST /v1/video/callbacks/replay 重放 + GET /v1/video/generations/{id} 轮询双兜底。建议甲方创建任务时强制配置 callback + api_secret（签名防伪造）。
• v2.6（2026-08-19）：交付质量与等待预期优化——① estimate_seconds 由固定值改为动态估算（近 20 个已完成任务的中位纯处理时长 + 排队任务分摊并发槽位，创建任务响应同步新增 estimate_note），无人排队时不再虚报约 4400 秒；② 修复无时间戳歌词导致成品无歌词字幕的问题——纯文字歌词按歌曲总时长自动均分生成逐字卡拉OK字幕、歌词编码（GB18030/BOM）兼容、规范 .lrc 优先；③ CD 模板生成核验单移除「换脸」校验（换脸在生成海报时已完成），仅保留提示词生成校验；④ 修复用户头像兜底链路——用户头像仅采用 user_avatar 素材，缺失时使用模板内置占位头像（member.jpg），不再错误回退到封面/海报/平台 LOGO（避免平台 LOGO 被当成用户头像渲染）；平台 LOGO（platform_logo）仅用于品牌感位置，封面兜底同样排除 logo/水印/poster/海报 等品牌与版式文件。
• v2.5（2026-08-18）：新增「水印与歌曲元数据」契约——watermark 支持图片水印（type=image + image_url，服务端下载并安全策略校验）与文字水印（type=text + text/sub_text/position/opacity）二选一，兼容旧布尔语义（true=客户默认水印）；新增 song_info（歌名/词曲作者/歌词/用户昵称/会员等级/平台名）用于播放器卡片渲染；字段白名单校验 + 4008 错误码；随任务落库、查询回显、并写入 work 端渲染清单 customer_requirements。
• v2.4（2026-08-17）：正式部署上线——对外生产域名固定为 https://video.livepartner.fans（nginx 转发至 video-studio:8780）；新增「快速开始 / 接入指引」章节与任务状态机说明；联调回归全绿（SMOKE 27 项 / FULL 90 项），含「不带素材创建 → awaiting_materials + 缺失清单 → 补齐素材 → 排队 → 出片」全链路验证。
• v2.3（2026-08-16）：差异整改——兼容甲方真实嵌套 material_package（materials_zip.url + 独立 manifest.url + objects 透传，ZIP/manifest SHA 分别校验，下载地址按 materials_zip.url→url→download_url→object_url 优先级）；manifest 以 slot 为准、album_image:{index} 按数值 index 排序；成片 PUT 携带 result_upload.content_type、200/201/204 视为成功；签名 URL 过期标记 addr_refresh 等待刷新 + 新增 POST /v1/video/generations/{task_id}/refresh 原任务续跑（不重新渲染、不重复扣费）；回调增加稳定 event_id 幂等 + 标准回调体（event_type/status/status_version/occurred_at/result/error）+ 未配置 secret 不降级发送 + 退避重试（1m/5m/15m/1h/6h/24h）+ POST /v1/video/callbacks/replay 按 event_id 重放；远程下载 SSRF 与压缩包路径穿越/绝对路径/盘符/层级防护；账单类型补充 retry/retry_charge。
• v2.2（2026-08-16）：甲方「再次整改」落地——素材包拉取（下载 → SHA-256 → 解压 tar.gz/zip → manifest 验收 → 登记，material_package_status 全程可查）；成片回传（result_upload PUT + 回写 sha256/size/mime/width/height，result_upload_status 可查）；退款后重跑重新扣费（retry_charge）；commit 不得绕过素材校验（缺料 409）；签名回调（HMAC-SHA256 + timestamp + nonce 防重放，callback_status 可查）；429 限流 + Retry-After；poster_image/poster_images 合并为 poster；错误码 4004→4001 统一。
• v2.1（2026-08-16）：素材状态改为「按模板 material_spec.required 齐全才 queued」；新增取消 / 退款 / 重跑 / 账单流水接口；创建任务接收 material_package / result_upload；补齐 status_version / missing_materials / material_acceptance 等对账字段；模板目录补充 status / version / ratio / resolution；错误码细分 4001 / 4006 / 4007 / 4041 / 409。
• v2.0（2026-08）：开放 /v1/video/generations、/v1/video/materials、/v1/templates、/v1/billing 等接口；支持 multipart 上传与 OSS 预签名直传兜底。
• v1.0（2026-07）：首个对外接口版本，支持模板列表与创建任务。

14.1 标准

14.2 打回时查询接口会回传什么

任务状态变为 awaiting_materials，同时回传以下字段（均为可程序化处理的整改依据）：

14.3 整改后如何重新推送

1. 按备注整改素材包（补齐文件 / 换成正确的媒体类型 / 修正镜头脚本）
2. POST /v1/video/generations/{task_id}/refresh 刷新素材地址并按新包重新验收；或在创建任务时传入新的 material_package
3. 验收通过后任务自动进入 queued；已完成的镜头成果会保留，只补跑未完成的部分

14.4 MV 时间轴硬校验（渲染前自检闸门，v3.0 新增）

MV 任务在任何生成动作之前执行下列四条校验；任一不通过 → 任务转 awaiting_materials、error_code=MV_SELFCHECK_FAILED， error（message）内附四个实测数值（镜头数 / Σ镜头时长 / timeline.durationMs / max(endMs) / 音频实测）， 不消耗算力、不产出成片（对齐甲方整改报告 R2 / R5）。

成片保证：全片时长 = 音频实测（与 durationMs 偏差 ≤200ms，符合 R1 口径）；逐镜按 shots[].durationMs 排布（±1 帧）； Σ镜头 比音频短 ≤2s 由末镜铺满，Σ镜头 比音频长 >2s 直接打回；成片内不存在冻结段/空画面。

14.5 常见打回原因与整改对照

14.6 哈希验收口径（v3.0 确认）

我方 ingest 会重新打包 materials.zip（并可能改写清单），因此整包 sha256 不可复现； 我方对素材包的 SHA 校验仅用于「下载是否完整」，不作为拒收成片依据。双方验收统一以 逐素材 sha 比对 为准。

一句话说明：甲方提供 物料包（分镜图 + 镜头脚本 + 音乐）与 成片回传通道；我方负责把每张分镜图做成视频片段、严格按 shots[].durationMs 逐镜排布、以原唱轨合成音画，并把成片回传给甲方。

平台 Base URL：https://video.livepartner.fans（任务提交 / 查询接口见 §4、§6）

接入凭据（3 项）：

三种交付方式（任选其一）：

方式① 接单入口契约（甲方推送 → 我方自动拉物料并投产）：

# 请求头
x-mv-inbound-token: <接单令牌>        # 由我方提供（平台设置项 mv_inbound_token）

# 请求体
{
  "work_id": "757",                      // 必填（兼容 workId / id）
  "api_base": "https://api.example.com", // 可选：拉取物料用的甲方基址；省略时用双方约定的默认值
  "access_key": "mv_xxxxxxxx"            // 可选：同上；省略时用默认值
}

# 响应
{
  "code": 0,
  "data": {
    "work_id": "757",
    "duplicated": false,                 // true = 已登记（幂等，复用并更新凭据）
    "shot_total": 23,                    // 解析到的镜头数（0 = 物料未就绪或缺镜头脚本）
    "pull_error": null,                  // 拉物料失败原因（失败不抛错，我方记录并重试）
    "started": true,                     // 是否已自动进入生产管线
    "status": "ready"                    // registered（登记成功但物料未就绪）/ ready（已就绪）
  }
}

物料包下发（我方调用，必配）。返回结构：

{
  "ready": true,                       // false 时我方记录待就绪并在刷新后重试（不会用其它素材顶替）
  "work":    { "id": 757, "title": "燃烧的十月", "artist": "某某" },
  "media":   {
    "vocalUrl":         "https://.../original-audio.mp3",   // ★ 唯一音轨基准（R3）
    "originalVocalUrl": "https://.../original-audio.mp3",   //   二选一提供即可
    "bgmUrl":           "https://.../bgm.mp3"               //   仅参考，MV 不使用伴奏
  },
  "lyrics":  { "lrcUrl": "https://.../line-lyrics.lrc", "wordLrcUrl": "https://.../word-lyrics.json" },
  "mv": {
    "timeline": {
      "frameRate": 30,
      "durationMs": 122000,          // 甲方声明的全片时长（整秒取整常见）
      "audioDurationMs": 122376,     // ★ 建议提供：实测音频时长，供我方直接对轴（首选基准）
      "shotCount": 23,
      "shotMaxSeconds": 15
    },
    "shots": [
      {
        "segmentIndex": 0, "shotIndex": 0,
        "segmentType": "intro",          // intro / lyric / interlude / outro
        "lyricLine": "",
        "startMs": 0, "endMs": 8857, "durationMs": 8857,
        "camera": "front",
        "imageUrl": "https://.../shot-001.jpg",   // 图生视频输入（与包内 shot/NNN.jpg 同源同内容）
        "videoPrompt": "街灯下的空镜，光影缓慢流动"   // ★ 该镜视频提示词
      }
      // … 共 shotCount 条
    ]
  },
  "delivery": {
    "aspectRatio": "16:9", "resolution": "1920x1080", "frameRate": 30,
    "lutCode": "007",                    // ★ 2026-10-14 口径统一：滤镜编号（三位数字、含前导零，001–204，见 §16）
                                         //   历史示例 "TEAL_ORANGE_01"（名称型）已废弃——实现/滤镜库/校验均只认编号型，
                                         //   名称型取值会因库中无同名文件而不调色（记录告警）
    "watermarkUrl": "https://.../wm.png", "watermarkPosition": "bottom-right",
    "introEnabled": false, "outroUrl": "https://.../outro.mp4"
  },
  "providerReturn": {
    "returnToken": "rt-xxx",             // 回传票据（7 天有效）
    "completeEndpoint": "/v1/mv-video/materials/757/returns/complete",
    "allowedContentType": "video/mp4", "maxFileSizeBytes": 104857600
  }
}

字段硬性要求（缺一项即被打回，我方不猜测、不兜底）：

我方把 MP4 以 Content-Type: video/mp4 PUT 到甲方提供的预签名地址，随后调用 complete。

{
  "objectKey": "temp/mv-video/757/output/final.mp4",
  "sha256": "64位小写hex（与实际文件逐字节一致）",
  "bytes": 58741233,
  "eventId": "evt-20260924-0001"     // 幂等 ID，重复提交返回 idempotent
}

请求头需带 X-MV-Return-Token（取自物料包 providerReturn.returnToken）。

票据过期时我方调用，不新建任务。

甲方自助校验工具（提交前本地自查，建议接进打包流程）

# 本地自查（打包前跑一次，提前发现会被打回的包）
node validate-mv-shots.mjs input/mv-shots.json \
     --shots-dir=input/objects/shot \
     --audio=input/objects/original-audio.mp3
#   → 输出平台同款四数值 + 逐条问题清单；退出码 0=通过 / 1=会被打回 / 2=用法错误
#   已知音频时长时也可直接 --audio-ms=122376；加 --json 得到机器可读结果

# 生成客户端 SDK（平台接口：提交任务、查询进度）
openapi-generator-cli generate -i https://video.livepartner.fans/openapi.yaml -g python -o ./sdk

# 生成服务端骨架（甲方需实现的物料接口，含 DTO 与字段名）
openapi-generator-cli generate -i https://video.livepartner.fans/openapi.yaml -g python-flask -o ./mv-provider \
  --global-property apis=MvMaterials,MvReturns

闸门通过时我方会做什么

• 在任务时间轴写入一条可查记录：MV 自检闸门通过：镜头数=N Σ镜头=Xms timeline.durationMs=Yms maxEnd=Zms 音频实测=Wms(<音轨文件>)（可用 GET /v1/video/generations/{id} 的 material_package_status / 时间轴查证）；
• 全片时长 = 音频实测时长（优先 timeline.audioDurationMs，缺失时我方 probe 原唱轨，再缺失才用 durationMs）；
• 逐镜按 shots[].durationMs 排布（±1 帧），不循环、不重复、不重排、不按模板节奏；
• Σshots 比音频短（差值 ≤2s）时，由末镜铺满这点差值（观感连续，不产生空帧）；
• Σshots 比音频长超过 2s → 视为脚本与音频不同版，拦停打回，不会出现「镜头被挤到音频之外」的空画面。

node validate-mv-shots.mjs input/mv-shots.json --shots-dir=input/objects/shot --audio=input/objects/original-audio.mp3
#   退出码 0 = 通过（平台不会因此被拦）；1 = 会被打回（列出逐条问题）；2 = 用法错误

甲方自查伪代码（与闸门口径一致，可在提交前自跑）：

assert len(shots) == timeline.shotCount == len(shot/*.jpg)
assert abs(sum(s.durationMs for s in shots) - timeline.durationMs) <= 200
assert max(s.endMs for s in shots) <= audio_duration_ms        # 音频实测（或 timeline.audioDurationMs）
# ④ 仅提示：abs(timeline.durationMs - audio_duration_ms) 允许几百毫秒（整秒取整）

mv 节点新增字段（乙方拉包即可见）

主角定妆照的用途：换脸依据（是否需要换脸由甲方开关决定）

• 定妆照 ≠ 一定换脸：定妆照是换脸的基准人脸；是否需要换脸由甲方提供的开关决定 —— 换脸就用（以定妆照为目标脸），不换脸就不用；
• 开关当前形态：甲方目前多以任务说明句给出（例如任务名里的「未启用 AI 换脸。」，我方运营后台会把它单独提取展示）；若甲方改为结构化字段下发，我方已按「多别名 + 宽松取值」接住上表中的 mv.faceSwap 系列字段，字段名冻结后无需再改；
• 核验不受开关影响：不论是否换脸，定妆照都必须是就绪状态（前置定妆逻辑，防止漏网）—— 开关只决定我方是否使用它做换脸。

行为变化（请同步给生成侧）

• 定妆照已设为 required：未定妆的作品推送过来会被核验闸门拦下，打回原因写明「缺少主角定妆照（mv.dressImageUrl / mv.dressAvailable 均未就绪）：该作品尚未定妆，请先在甲方侧生成主角定妆照后再推送 —— 未定妆的作品不予接单」；
• 已定妆的作品不受影响（新核验项对已定妆包向后兼容）；
• 尾帧图必须每一镜都有：包内缺失、上传失败、或只给包内相对路径 → 一律打回（不静默退化为单首帧）；
• 我方在镜头派发前会再校验一次尾帧地址可用性：声明了尾帧但地址不可下载的镜头会被拦下并写明原因，不会按单首帧出片。

一、海报分镜（segmentType=poster，默认 5 秒）

对甲方的影响清单：

• 推送格式零改动，物料包无需任何调整；
• 成片总时长比音频实测长约 5 秒（海报开场）属正常；
• 镜头数 +1 属正常：镜头级状态接口（§15.6.1）会多一镜 segment_type=poster、段号 0，原镜头段号整体顺延；
• 歌词字幕（如甲方自行压字幕）需整体后移海报时长，平台成片内不带字幕层、无此问题。

三、甲方接入范例（自带海报镜，2026-10-14 新增 · 一次接对模板）

以下是一份可直接照抄的 mv-shots.json（海报 5s + 歌曲 3 镜示意，其余镜头同理顺延）。 核心口径一句话：海报镜排第 0 位且声明 segmentType:"poster"；timeline.durationMs = 全部镜头时长之和（含海报镜）；海报段静音无字幕，歌曲音画从海报结束后开始、相对关系与甲方声明完全一致。

{
  "timeline": {
    "durationMs": 36900,      // ★ = 5000 + 6200 + 6000 + 19700（全部镜头之和，闸门② ±200ms）
    "shotCount": 4,           // ★ 含海报镜
    "audioDurationMs": 31900, // 纯歌曲音频实测时长（不含海报段）
    "frameRate": 24
  },
  "shots": [
    {
      "segmentIndex": 0, "shotIndex": 0,
      "segmentType": "poster",                    // ★ 识别位：平台看到后不再自动插入海报镜
      "durationMs": 5000,
      "startMs": 0, "endMs": 5000,                // 海报镜占绝对时间轴 0 → 5000
      "imageUrl": "input/objects/shot/001.jpg",   // 海报图首帧（与包内 shot/001.jpg 同源同内容）
      "endImageUrl": "input/objects/shot-end/001.jpg", // ★ 2026-10-19 必填：海报镜尾帧（缺帧直接打回，平台不补齐）
      "videoPrompt": "海报动态化：缓慢推近，光效流动，氛围粒子；保持画面主体与构图不变" +
                     "；画面中央的标题文字『xxx』与右下角小字『xxx』随镜头缓慢推进保持清晰可读",
                                                  // ★ 文字内容直接写在提示词里，由模型生成；不要写「淡入/渐显」
      "hasPerson": true                           // 海报含人物如实声明；纯文字/风景海报写 false
    },
    {
      "segmentIndex": 1, "shotIndex": 1,          // ★ 自带海报镜后，原第一镜镜号顺延为 1
      "segmentType": "intro",
      "durationMs": 6200,
      "startMs": 5000, "endMs": 11200,            // 自海报结束后顺延（绝对时间轴）
      "imageUrl": "input/objects/shot/002.jpg",
      "endImageUrl": "input/objects/shot-end/002.jpg",   // 尾帧（硬要求，见 §15.3）
      "videoPrompt": "（本镜画面描述，含人物约束原文）",
      "hasPerson": false,
      "transition": { "type": "fadeblack", "duration": 0.6 }   // 与上一镜（海报镜）的衔接，见 §15.4.3
    }
    // … 其余歌曲镜同理：startMs/endMs 依次顺延，durationMs 建议落在 5.2~6.5s 甜点区（§15.4.4）
  ]
}

交付后成片时间轴（验收对账口径）：

推包前 60 秒自查（自带海报镜版，全过即一次接对）：

• shots[0].segmentType == "poster"，镜号 0/0，原镜头镜号已顺延、无撞号；
• timeline.durationMs == Σ shots[].durationMs（±200ms）、timeline.shotCount = 含海报镜的总镜数；
• timeline.audioDurationMs 填纯歌曲音频实测（不含海报段）；
• 每镜都有 endImageUrl 尾帧 —— 海报镜同样必带（§15.3 硬要求）；海报镜缺尾帧直接打回（MATERIAL_MISSING_END_FRAME），平台不自动补齐；durationMs 落在 5.2~6.5s 甜点区；
• 不想要海报前置段：不要声明 poster 镜，并在 delivery.posterShot.enabled=false 关闭平台自动插入；只要包内有海报图且未声明 poster 镜，平台默认自动插入 5s 海报镜（甲方包口径不变，见上表）。

二、主体锁定（所有镜头逐镜注入，纯提示词、无检测）

口径（甲方原话）：背景风景可以随镜头运动自然变化，但主体人物绝对不能变、不能出现新的人。

每镜下发给生成模型的提示词中，人物约束共 5 处、覆盖开头/中段/结尾：

一、声明方式（三级，优先级从高到低）

二、转场目录（49 项 = ffmpeg xfade 原生 46 + 预留/自研 3）

三、技术保障

一、时长对照表（实测口径：H3 模型 + 当前固化配方）

二、规则说明

• 下限 5.2s（124 帧）：H3 模型训练区间下限，短于此值不会更快——平台按 5.2s 生成再裁剪，算力白耗。
• 6.9s 阈值：超过即触发「分段续接」（上一段真实末帧作为下一段首帧，阿里官方长视频同款范式）。 分段后每段都在锚定力全覆盖区间，人物漂移窗口结构性消失；拼接后由平台变速对齐回脚本时长（压缩比 ≤1.5，动作略快）。
• 漂移背景：实测长镜头中后段，模型会漂移出「分镜里不存在的人物」（2026-10-12/13 两单实锤，首尾帧均无人仍出现同一张男主脸）。 平台已上线人脸质检硬门：首帧无人脸的镜头，生成片段检出人脸即自动换 seed 重做——甲方看到的成片干净，但重做会拉长交付时间。 因此分镜按甜点区设计 = 一次通过率最高 = 交付最快。
• 时长口径：转场（§15.4.3）消耗每镜尾部预留的 1s 重叠余量，不占用脚本时长——分镜时长规范与转场声明互不影响。

三、分镜设计建议（给甲方的脚本规范）

作品状态机（mv_works.status）：

registered → pulling → ready → processing → returning → completed
                             ↘ awaiting_materials（自检闸门/素材问题打回，补齐后可续跑，24h 未补齐自动取消退款）
                             ↘ failed（含失败原因，可修正后继续）

阶段明细：pulling / importing / ready / shots 3/23 / concat / lut:CODE / watermark / uploading / completed。

我方管理端接口（需管理员令牌 x-admin-token），供运营监控与问题处理：

15.6.1 镜头级状态查询（甲方接入，2026-10-02 新增）

甲方可凭乙方 worker 管理令牌（向星河索取后配置到甲方系统的 mv_worker_admin_token）直接查询任意作品的逐镜头生成状态与质检指标：

鉴权（二选一）：

未携带凭据返回 401；管理令牌未配置且无凭据返回 503。

响应（data.work 概要 + data.shots[] 逐镜明细，按段号→镜号排序）：

curl -H "x-mv-admin-token: <令牌>" \
     "https://video.livepartner.fans/api/mv/works/{workId}/shots"

MV 相关错误码与 §12「任务级 error_code」一致，这里给出 MV 场景下的整改动作：

按甲方要求，用甲方提供的测试作品走完整链路，并回报「自检闸门四个数值 + 成片实测总时长」。

{ 757 → 镜头数 23 = shotCount 23 = 包内分镜图 23；Σ=122000ms = durationMs 122000ms（偏差 0）
      max(endMs)=122000ms ≤ 原唱实测 122376ms  → 闸门通过，预期成片 122.376s
  752 → 镜头数 27 = shotCount 27 = 包内分镜图 27；Σ=100000ms = durationMs 100000ms（偏差 0）
      max(endMs)=100000ms ≤ 原唱实测 100536ms  → 闸门通过，预期成片 100.536s }

• Q：成片尾部出现一段静止画面/空画面？ A：这是本次已修复的问题类型。修复后此类包会在自检闸门被拦停（MV_SELFCHECK_FAILED，附四个数值），不再产出带空尾的成片。
• Q：成片时长和 durationMs 差了几百毫秒？ A：正常。甲方 durationMs 常为整秒取整（如 122000），实测音频为 122376；我方一律以音频实测对轴，偏差仍在 R1 允许的 ±200ms 口径内（以 audioDurationMs 为准）。
• Q：能不能只给伴奏轨？ A：不能。MV 必须以 vocalUrl（或 originalVocalUrl）为唯一基准轨；仅提供伴奏会导致音画/歌词落点对不上，我方会打回。
• Q：镜头数量对不上会怎样？ A：shots.length、timeline.shotCount、包内分镜图张数三者必须一致，否则闸门拦截（MV_SELFCHECK_FAILED），不会「按经验补」。
• Q：素材还没准备好怎么办？ A：任务会停在 awaiting_materials 等待（不会用任何其它素材顶替开工）；补齐后 refresh 或重推即可续跑，已完成的镜头成果保留。
• Q：分镜图需要什么规格？ A：公网可下载即可（建议 ≥1280px 长边），我方按交付分辨率缩放补边；底图是该镜的起始帧。
• Q：成片多久能好？ A：本地 GPU 约 5–15 分钟/镜头（多机并行更快）；使用 API 供应商约数十秒/镜头。
• Q：可以只重做某个镜头吗？ A：可以，用单镜头 reset 接口，完成后自动重新拼接回传，不影响其它镜头。
• Q：素材安全吗？ A：物料按作品隔离存储，成片通过甲方自有预签名地址回传，我方不对外分发。

2026-10-22 定版。本节把甲方最常问的三件事一次讲清楚：歌词怎么带、字体能不能指定、转场怎么声明。每项都标注了实现状态，请按状态列判断能否在本期使用。

17.1 速查表

17.2 歌词规范

① 三种给法（任选其一，不要重复上传互相矛盾的两份）：素材上传 line_lyrics（行级）/ word_lyrics（逐字）/ 创建任务时 song_info.lyrics 内嵌文本（纯文本，平台自行断句，无时间轴，只适合不需要精确对时的场景）。

② 优先级（同一包内多份并存时）：word_lyrics（逐字 JSON）＞ line_lyrics（行级 .lrc）＞ 文件名含 lrc 的其它文件 ＞ 纯文本兜底（含 song_info.lyrics —— 平台会把它落成 lyrics.txt，优先级最低）。建议同时给 line_lyrics 与 word_lyrics：行级管文案与断行，逐字管逐字高亮。

③ 时间基准（最高频的错，必看）：所有时间戳一律是歌曲音频自身的时间轴，从音频第 0 秒起算。平台负责把歌词整体后移到画面上对应位置：

④ 覆盖要求：LRC 时间戳须连续覆盖到音频结束。渲染口径：每句显示到下一句开始为止；最后一句按自身时长结束（≈ 每字 0.38s，「别急着」3 字 ≈ 1.5s），平台不会把末句延长到音频/片尾，之后到音频结束为空白无词区。中间缺行同理会出现空白窗。（实测案例：某 CD 单 LRC 仅 11 行、末句 [00:55.22]别急着 → 成片 61.7s 后到片尾 80.6s 全部无词；平台不补句。）若末尾空窗明显（> 3s），请甲方自查补齐。

⑤ 编码：UTF-8（可带 BOM）优先；GB18030 自动兜底。请勿用 UTF-16（会整包解析失败）。

⑥ 常见错误

17.3 字体规范（已定版：字体随歌词，不单独指定）

① 各产出的字体来源（固定）

② 平台字体库：内置 65 款（原始 51 + 开源替代 14），可按编号 / 平台 ID 查阅与下载，公开清单页：字体清单。字体库的用途是给歌词插件/模板用，不是给甲方按任务指定——同一作品所有集数的字体由所选歌词样式一致决定。

③ 想换字体怎么办：换歌词插件（MV）或换模板（CD），即「换整套歌词样式」。不支持只换字体（只换字体必然带字号/行距/描边一起变，属于新样式）。需要新样式走平台侧新增插件/模板，之后甲方按编号选择即可。

变更说明：v3.15 初稿曾给出 typography 任务级覆盖草案（font_family / font_id / size_px / 颜色 / 边距）。评估结论为不实现：自定义字体必须以 ASS [Fonts] 内嵌方式下发才能保证渲染机可用（仅靠文件名匹配时 libass 会回退），成本与稳定性都不划算，且会与插件样式规范冲突。该草案已删除，文档不再保留，避免甲方误以为可传。

17.4 转场规范

完整类型目录（49 项，含 fade / wipeleft / slideup / circleopen …）与各类型观感说明见 §15.4.3 转场系统，线上可搜版：转场库。

① 声明位置与优先级（高 → 低）

② 下标语义：per_shot[k] 是第 k 个镜头（图片）与它前面那个的衔接，下标从 1 开始有效（k=0 无前镜，忽略）。CD 的 k = 相册图序号；MV 的 k = 镜头序号（含海报镜）。

③ 取值规则（两端一致）：type 必须是目录内名称，写错/库中不存在 → 该处忽略并回落自定义，不阻断出片；duration 单位秒，夹取 0.2–1.0s；type 为 cut / none 或 duration ≤ 0 = 硬切（不重叠、不淡化）。

④ CD 与 MV 的能力差异（重要）

即：CD 只能控「转场多久、要不要硬切」，控不了「用什么花样」；需要 CD 使用真实 xfade 样式属后端切换事项，未在本期范围内。

⑤ 示例（CD，包级）

"transitions": {
  "default": { "type": "fade", "duration": 0.8 },
  "per_shot": [
    null,                                  // k=0 无前镜，忽略
    { "type": "wipeleft", "duration": 0.6 },   // 第 1→2 张
    { "type": "cut" },                          // 第 2→3 张：硬切
    { "type": "fade", "duration": 1.0 }         // 第 3→4 张
  ]
}

⑥ 示例（MV，逐镜）

{ "shots": [
  { "index": 0, "durationMs": 5000, "segmentType": "poster", "transition": { "type": "cut" } },
  { "index": 1, "durationMs": 6000, "transition": { "type": "fade",     "duration": 0.5 } },
  { "index": 2, "durationMs": 5000, "transition": { "type": "wipeleft", "duration": 0.6 } }
] }

17.5 状态与告警口径

17.6 推包前自查（这三件）

□ 歌词：包内有 line_lyrics（.lrc）或 word_lyrics（逐字 JSON），UTF-8
□ 歌词：时间戳从音频 0 秒起算（不加封面/海报偏移），且覆盖到音频结尾
□ 转场：manifest.json（或 MV 的 mv-shots.json）里 type 是目录内名称、duration 在 0.2–1.0s
□ 字体：不用管（字体随歌词，不单独指定）；确需换字体请换歌词插件/模板

一句话：给「歌词 + 原唱音频」，出一支歌词同步的文字 PV成片。模板编号 xinghe-cd-001，由服务端直接编码（不排队占渲染机），比 MV 快得多。

18.1 模板信息

18.2 素材要求

18.3 歌词怎么给（只关心一件事：一行一句）

编码：UTF-8（可带 BOM）；不要 UTF-16。 不要在歌词里加 [ti:] / [ar:] 之外的舞台指令（会当普通文本处理）。

18.4 分辨率怎么指定（output_resolution）

{
  "output_resolution": { "width": 1920, "height": 1080, "fps": 30 }
}

取值必须命中模板 supported_resolutions，否则返回 4008：

不传则按模板默认 1080P 输出。当前模板为 16:9；竖屏（9:16）等其它画幅需另开模板，未在本模板范围内。

18.5 状态流转与错误码

创建 → awaiting_materials（缺料，附 missing_materials）
     → queued（素材齐全，自动回队）
     → rendering（服务端编码，progress 1→100）
     → done（result.url 可下载）

18.6 完整接入示例（可直接照抄）

# ① 建单（先不给素材，返回 awaiting_materials + missing_materials）
curl -X POST https://<你的域名>/v1/video/generations \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -d '{
    "template_id": "xinghe-cd-001",
    "song_info": { "song_name": "作品名", "lyricist": "词", "composer": "曲" },
    "output_resolution": { "width": 1920, "height": 1080, "fps": 30 },
    "external_task_id": "your-order-0001"
  }'
# → { "id": "C6F8J1X1YBO45K11", "display_id": 547, "status": "awaiting_materials", ... }

# ② 歌词：申请直传地址 → PUT → 登记
curl -X POST https://<你的域名>/v1/video/materials/presign \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -d '{ "task_id": "C6F8J1X1YBO45K11", "type": "line_lyrics", "filename": "line.lrc" }'
# → { "oss_key": "materials/xh01/tasks/547/line_lyrics_..._line.lrc", "put_url": "https://...", ... }
curl -X PUT --upload-file ./line.lrc "<put_url>"
curl -X POST https://<你的域名>/v1/video/materials/confirm \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -d '{ "task_id": "C6F8J1X1YBO45K11", "type": "line_lyrics",
        "oss_key": "<上一步的 oss_key>", "filename": "line.lrc" }'
# → task_status 仍为 awaiting_materials，missing 只剩 original_vocal

# ③ 原唱音频：同上三步，type 换成 original_vocal
# → task_status = "queued"（必需素材齐全，自动进入渲染）

# ④ 轮询（建议 5 秒一次）
curl https://<你的域名>/v1/video/generations/C6F8J1X1YBO45K11 \
  -H "Authorization: Bearer <API_KEY>"
# → rendering 1% → 25% → 40% → done 100%，result.url 即成品下载地址（COS 签名，长期可重新查询获取）

18.7 常见问题