hanvis-15s

概述

概述

基于 Hanvis 统一 AI 算力网关（https://hanvis.cn）的 15 秒短视频定向创作技能。完整继承 hanvis-create 的底层能力模块，复用原有调用接口、参数、返回格式，不改动底层实现，仅做上层业务编排：

• 图片生成：Seedream 5.0 Flash 文生图（hanvis.py image）
• 文生音频：CosyVoice2 0.5B（hanvis.py tts）
• 音色克隆：IndexTTS 2.5（hanvis.py clone，需参考音频）
• 视频生成：Minimax H3（hanvis.py video，768P / 2K 两档）

新增编排逻辑：15s 定向流程、宽高比 / 分辨率问询、视频品质评价标准、分镜脚本、专业运镜、BGM 专项设计。

关键约定

• 附件统一走 URL，不使用 Base64：所有本地文件（图片/音频/视频）作为 API 附件时，一律先上传换取公网 URL 再传参：
  • 通用上传接口 POST /v1/files/upload（返回腾讯 COS 公网 URL），脚本命令：

python "<SKILL_DIR>/scripts/hanvis.py" upload --file "<本地文件>" → data.url 即公网 URL。

• image --ref-image、video --ref-image/--ref-video/--ref-audio 传本地路径时脚本会自动上传换 URL，传公网 URL 则直接透传；最终进 API 的全是 URL。
• 技能根目录：即本 SKILL.md 所在目录。调用脚本时用该目录拼绝对路径，例如

python "<SKILL_DIR>/scripts/hanvis.py" image --prompt "..."。

• API Key 存储：脚本读取 环境变量 HANVIS_API_KEY → ~/.hanvis/config.json；

Key 无效引导注册 https://hanvis.cn/register，余额不足引导 https://hanvis.cn/login 充值（与 hanvis-create 完全一致，详见下文「错误处理」）。

• 脚本输出：每次只向 stdout 输出一行 JSON：
  • 成功：{"status":"ok","type":...,"data":{...}}
  • 失败：{"status":"error","error_code":...,"code":...,"message":...,"action":...}

前置交互规则（强制优先执行）

1. 收到用户请求后，优先主动问询 2 项参数，必须拿到用户明确答复后再进入后续流程：
   • 宽高比：9:16 竖版 / 16:9 横版 / 1:1 方形
   • 视频分辨率：768P 或 2K 高清
   • ✅ 特殊：如果用户消息里已经直接写明宽高比 + 分辨率，跳过问询，直接读取参数。
2. 解析用户全部输入信息：文字描述、上传附件（图片 / 文档等），综合理解用户创作意图、使用场景、风格、受众、情绪基调、核心表达信息。对用户上传的图片 / 视频 / 音频素材，必须逐一分析其内容（画面主体、风格、色调、与主题的关联度），并判断该素材对生成视频是否有用（可作为画面主体、风格参考、首帧、运镜参考、BGM 基底等），为步骤7 的附件取舍提供依据。
3. 本技能固定产出视频时长：15 秒。所有脚本、镜头、音频、BGM 严格对齐 15s 时长。

执行步骤（严格按顺序执行）

步骤1：意图解析

整理用户需求，输出【用户创作意图文档】，包含：核心主题、风格调性、目标受众、想要传递的信息、画面偏好、禁忌内容、是否已有脚本。

步骤2：生成《视频品质评价标准》

先做目标观众群体分析，再编写标准：

1. 目标观众群体分析：基于步骤1解析出的用户意图，明确本条视频的目标观众是谁（如年龄段、性别倾向、身份场景、观看渠道、审美偏好、内容消费习惯），并输出简要分析结论；后续所有标准的松紧、侧重点都依据该群体的情况来定（例如面向年轻短视频用户的节奏要快、卡点要密；面向商务人群的画面要稳、信息要清晰）。
2. 基于观众分析定制本条 15s 视频专属验收标准，维度包含：

• 画面维度：构图、光影、色彩一致性、主体清晰度、画面无畸变、无闪烁、连贯性
• 镜头维度：运镜流畅度、节奏匹配、镜头切换卡点、无突兀跳切
• 音频维度：人声清晰度、BGM 音量配比、音色匹配、音频无爆音、卡点适配画面
• 叙事维度：15s 内信息传递完整、重点突出、开篇前 3~5 秒必须有勾子（Hook）——用悬念、冲突、视觉冲击或利益点抓住观众，让其有兴趣看下去，并对勾子强度设定可检验的标准；结尾有记忆点
• 合规维度：无违规画面、水印、杂乱文字

该标准作为后续脚本、运镜、BGM、视频生成的约束依据；生成视频后也对照该标准自检。

步骤3：生成分镜脚本

• 分支A（用户没有提供分镜/脚本）：从零创作适配 15s 短视频的分镜脚本，按时间轴切分（0~3s、3~7s、7~11s、11~15s），每镜标注：时间区间、画面内容、画面主体、字幕、音效。
• 分支B（用户已提供脚本/分镜）：在用户原稿基础上优化，保留用户核心想法，修正节奏、卡点、画面逻辑，适配 15s 时长，补齐缺失信息。

步骤4：运镜方案优化（行业最佳实践）

为每一个分镜单独设计运镜描述，优先选用短视频、商业宣传片成熟运镜方案，可选：缓慢推镜、横移、环绕、轻微跟焦、固定机位、微摇、渐拉、滑动运镜等；禁止过度花哨、抖动剧烈的运镜；运镜节奏贴合 BGM 节拍，写清楚运镜强度、速度、起止效果，写入分镜对应条目。

步骤5：BGM 背景音乐专项设计

独立输出 BGM 设计描述，包含：曲风、速度 BPM、情绪基调、乐器组合、音量曲线、卡点位置、起止淡入淡出；区分：BGM 主旋律、铺垫段落、高潮卡点段落；标注人声（如有）和 BGM 的音量配比，避免背景音乐盖过人声。人声 / 音效需要时调用音频能力：

• 文生音频：hanvis.py tts
• 参考音频音色复刻：hanvis.py clone（沿用 hanvis-create 音频模块）

步骤6：图片素材生成（复用 hanvis-create 图生图/文生图）+ 用户确认

模型为 Seedream 5.0 Flash (Ark)（doubao-seedream-5-0-flash-260915，35 积分/张），支持图片输入：文本 + 一张或多张参考图（单图、多图参考均可，通常 2~10 张），可完成图像编辑、风格迁移、物体替换、组合生成等操作。

根据分镜画面描述，批量生成对应画面素材，分辨率、宽高比严格匹配用户选定参数：

# 纯文生图
python "<SKILL_DIR>/scripts/hanvis.py" image --prompt "<分镜画面描述>" --size <匹配宽高比与分辨率> --n <所需张数> [--save ./素材.png]

# 图生图 / 多图参考（把有用的用户素材作为参考图传入）
python "<SKILL_DIR>/scripts/hanvis.py" image 
  --prompt "<分镜画面描述 + 各参考图的用法说明>" 
  --ref-image "<用户素材URL或本地路径>" [--ref-image "<更多参考图>" ...] 
  --size <匹配宽高比与分辨率> --n <所需张数> [--save ./素材.png]

用户素材作为生图参考（强制规则）：

1. 基于步骤1 对用户上传素材的内容分析：对生图有用的用户素材（人物形象、场景、风格、产品图等），在生成对应分镜图时必须通过 --ref-image 传入，作为 Seedream 的输入参考图（≤10 张），并在 prompt 中说明各参考图的用途（如"参考图1 的人物形象保持一致，参考图2 的场景氛围迁移到分镜画面"）。
2. 参考图支持对话中输入的图片本地路径（脚本自动上传 /v1/files/upload 换公网 URL）或公网 URL（直接透传），最终统一以 URL 形式传给 API，不使用 Base64。
3. 无用的素材不传入（沿用步骤7 第5条的取舍口径：与主题无关、质量差、干扰风格的不用）。
4. 用户素材与分镜的结合方式要与用户确认过的意图一致；不确定时在展示图片环节一并说明参考图的用法，让用户确认。

并行生成规则（多张图时必须遵守）：

• 需要生成多张不同分镜的素材图时，必须并行发起：在同一次回复中并行调用多个 image 命令（每个分镜一个命令、各用自己的提示词），禁止串行逐张等待——串行生成会成倍拉长等待时间。
• 各图的提示词相互独立、分别对应各自分镜；生成后按分镜编号整理归档（如 镜1.png、镜3.png），便于后续确认与对应。
• 必须记录每张图脚本返回的 data.urls（公网 URL），并与分镜编号一一对应存好（如"镜1 → https://…png"）。视频生成引用附件直接用这些公网 URL（本地文件脚本会自动上传换 URL）；图片 URL 24 小时有效，需在有效期内完成视频生成。
• 若某一张并行任务失败，单独重跑该张即可，不影响其他已成功的素材。

用户确认环节（强制）：

1. 图片生成后，必须把本次生成的全部图片一次性都显示在对话中给用户确认：
   • 将每一张图片的本地文件路径都列出来，并在一次回复中全部呈现（逐张列出路径，全部作为附件/预览展示）——严禁只展示其中一张或部分图片，有几张就展示几张，缺一张都不算完成展示。
   • 每张图标注它对应哪个分镜（如"镜1：0~3s 桃林水榭舞剑"）。
   • 展示前先做画质自检，然后请用户过目，话术参考：

> "两张关键帧已生成，先自检画质再请您确认：两张质量都不错——镜1 还原了参考图的构图，镜3 回眸特写眼神灵动、面部无畸变。请您过目："

• 若一次回复无法保证全部图片都展示成功，必须分多条回复补齐，直到所有图片都实际显示给用户为止。

1. 用户明确同意后，才能进入步骤7生成视频，不得跳过确认直接生成视频。
2. 用户对某张图片不满意的：只重新生成用户指定的那一张（其余已确认的素材不动），按用户意见调整该分镜的提示词后重跑 image 命令，重新生成后同样要把新图（连同其余已确认图片）全部展示出来，再次确认，直至用户满意。
3. 全部素材获得用户认可后，方可进入下一步。

步骤7：视频生成（复用 hanvis-create 视频模块）

输入：分镜脚本、运镜参数、BGM 音频、图片素材、宽高比、分辨率（768P / 2K）、品质评价标准作为约束提示，生成 15 秒短视频：

python "<SKILL_DIR>/scripts/hanvis.py" video 
  --prompt "<整合分镜+运镜+品质约束的提示词，≤500字>" 
  --model minimax-h3-93-768p | minimax-h3-93-2k 
  --ratio 16:9 | 9:16 | 1:1 
  --duration 15 
  --ref-image "<步骤6生成的图片URL1>" [--ref-image "<URL2>" ...] 
  [--save ./out.mp4]

附件引用规则（H3 V1 接口，强制）：

1. 必须通过 --ref-image 把步骤6生成的图片公网 URL 传给视频接口（可多次，每张一次），让视频内容真正基于已确认的素材图生成——这是保证成片与分镜/文字一致的关键，禁止只靠 prompt 文字描述而不用参考图。
2. 统一 URL 方案：优先直接传步骤6记录的 data.urls（公网 URL）；其他本地文件（用户素材等）脚本会自动经 POST /v1/files/upload 上传换取公网 URL 后再传参——全程不使用 Base64。
3. API 附件限制：
   • 总量：图片 ≤9 张、视频 ≤3 段、音频 ≤3 段，附件合计 ≤12 个。
   • 图片：单张 ≤20MB；格式 JPG / JPEG / PNG / WEBP / HEIC / HEIF；生成视频的宽高范围需在 [256, 5760] 像素内、宽高比 [0.4, 2.5]。
   • 视频：单段 ≤30MB、单段 2~15 秒、所有视频合计 ≤15 秒；格式 H.264/AVC、H.265/HEVC；分辨率宽高 [256, 5760] 像素、宽高比 [0.4, 2.5]、帧率 23.976~60fps。
   • 音频：单段 ≤10MB、单段 2~15 秒、所有音频合计 ≤15 秒；格式 WAV、MP3。
   • 分镜素材图超过 9 张时，挑选最关键的镜头图传入（优先级：勾子镜 → 转折/高潮镜 → 结尾镜），其余镜头靠 prompt 描述衔接。
4. prompt 中要写明每张参考图的用途与出场顺序（如"参考图1作为开场画面，参考图2用于中段转场……"），让模型正确理解图与分镜的对应关系；整段提示词 ≤500 字。
5. 用户自备素材的取舍规则（强制）：基于步骤1 对用户上传素材的内容分析结果执行——
   • 有用 → 必须传入：若素材（用户上传的图片 / 视频 / 音频）对生成视频有用（如作画面主体、风格参考、首帧、运镜参考、BGM 基底等），且传入后附件总数不超过上限（图片≤9、视频≤3、音频≤3、合计≤12），则生成视频时必须用 --ref-image / --ref-video / --ref-audio 传进去，并在 prompt 中对每个附件的内容与用途逐一说明（如"–ref-video 是用户提供的运镜参考，请参考其镜头节奏"）。
   • 无用 → 不传入：若素材与主题无关、质量差（模糊 / 畸变 / 带水印）或会干扰成片风格，则不放进去，也不在 prompt 中提及；同时向用户简要说明不采用的原因。
   • 超限 → 按优先级裁剪：传入后超过附件上限时，先保证步骤6 的关键分镜图（勾子镜 → 转折/高潮镜 → 结尾镜），再视余量纳入用户素材；被舍弃的素材告知用户。
6. 可选参考：--ref-video <URL>、--ref-audio <URL>（均可多次，用于 BGM / 运镜参考）。

视频参数约束：

• 768P → --model minimax-h3-93-768p（短边 768）
• 2K → --model minimax-h3-93-2k（2K 高清标准）
• --duration 强制锁定 15
• --ratio 使用用户选定的宽高比

输出返回格式（依次输出）

1. 用户创作意图总结
2. 视频品质评价标准
3. 15s 分镜脚本（带时间轴 + 运镜说明）
4. BGM 配乐详细设计方案
5. 素材 & 视频生成结果

输出文案简洁专业，适合直接给到视频生成模型；内部调用沿用 hanvis-create 的接口调用格式，参数透传。

错误处理（与 hanvis-create 一致）

边界约束

1. 底层图片、音频、视频生成能力完全复用 hanvis-create，不重新实现底层模型调用逻辑，只做上层编排。
2. 所有生成内容必须遵守内容安全规范。
3. 若用户中途修改分辨率 / 宽高比，从步骤2重新迭代全部内容。
4. 固定时长 15s，不支持用户修改时长。如用户要求别的时长，告知：本技能为 hanvis-15s，专门用于 15 秒短视频。

参考文档

详细接口参数、字段说明、错误码见 references/api_reference.md（仅在需要核对字段时加载）。