泥团 Seedance 2.5 / MiniMax-H3 视频
使用本 Skill 目录中的 scripts/generate_video.py，Python 3.10+，无需第三方依赖。先从当前 Agent 的技能信息或安装目录定位 Skill 根目录，再用绝对路径运行脚本，不依赖当前工作目录；输入素材、输出视频和任务记录应放在 Agent 可访问的用户工作区，不要放进技能安装目录。支持泥团的 seedance-2.5 和 MiniMax-H3 协议，不调用 Kongji 或旧的泥团固定 30 秒模型脚本。不同 Agent 的安装方式、Shell 权限和密钥设置见 Agent 安装与兼容说明。
选择模型
| 参数/能力 | Seedance 2.5（默认） | MiniMax-H3 |
|---|---|---|
--model |
seedance-2.5 |
MiniMax-H3（名称须准确） |
| 时长 | 4–30 秒；工具默认 10 秒 | 4–15 秒；工具默认 4 秒 |
--resolution |
480p/720p/1080p；默认 720p | 768P/2K；默认 768P |
| 比例 | 六种比例，默认 16:9 | 六种比例，默认 16:9 |
| 生成模式 | 文生、图生、独立首帧、首尾帧、多图、多模态 | 文生、图生、首尾帧、多图、多模态 |
| 声音开关 | --enable-audio true\|false，默认 true |
文档未定义，不传该参数 |
| 请求结构 | prompt、size 及各模式参考字段 | metadata.metaso_content 等专用参数 |
明确要求 H3 时使用 --model MiniMax-H3；不明确时沿用默认 Seedance。H3 不接受 --size、--enable-audio 或单独 --first-frame；单图用 --image，首尾帧须成对提供。H3 文档未给素材数量上限，不把 Seedance 的 30/10/10 当作其上限。H3 请求结构见 H3 参数参考。
执行
- 提取模型、提示词、时长、比例、分辨率及参考素材用途，按上表分别校验。缺提示词时询问；已有提示词则直接执行。Seedance 所有模式可用
--enable-audio true开启声音、--enable-audio false关闭声音，请求发送 JSON 布尔值，不发送字符串"false"。H3 不发送此开关，不能承诺其静音控制。复杂提示词用--prompt-file读取 UTF-8 文件，避免 shell 转义。 - 素材参数同时支持本地路径和已有公网 HTTP(S) URL：
--image、--video、--audio可逐项重复，保持用户顺序；Seedance 仅首帧用--first-frame。两种模型的首尾帧均用--first-frame和--last-frame，不允许只提供尾帧。Seedance 模式及尺寸、公共上传/状态/下载流程见 API 与参数参考。 - 本地素材自动匿名上传到临时公网托管，默认保留至少
1h并按uguu → tmpfiles → litterbox顺序故障切换；该顺序优先尝试本机已实测可上传并读取的渠道。可用--upload-hosts litterbox,tmpfiles,uguu自定义顺序。--expiry可选1h/12h/1d/3d，表示直链至少需要保持多久：Tmpfiles 最多 48 小时，Uguu 固定约 3 小时，因此期限不匹配的渠道会静态跳过，不会静默缩短素材公开时间。简短告知所用临时公网托管及有效期；用户要求自动上传已构成该工作流的授权，无需重复确认。支持 JPEG/PNG/WebP 图片、MP4 视频、MP3 音频，每份不超过 50 MiB；这些是本脚本护栏，不能说成泥团官方限制。相同本地路径只上传一次。 - 先用
create ... --dry-run校验并预览请求，再去掉该参数真实执行。预览不读取凭证、不解析 DNS、不上传、不创建文件、不访问网络；本地素材显示UPLOAD_PENDING_N占位符。 - 只从
NITUAN_API_KEY环境变量读取密钥，Windows 也支持当前用户环境变量。缺失时只提示配置变量；不索要聊天明文，不把密钥写入脚本、命令参数、日志、任务记录或 URL。创建请求不会自动重试；创建结果不明时先核查平台任务记录。 - 默认先离线校验输出路径并原子建立
.task.json，随后才上传和提交。素材按 SHA-256 去重，匿名 multipart 流式上传、最多 4 路并发；有效缓存会优先复用，缓存未命中后才按渠道顺序上传；每个渠道上传成功后先探测媒体签名，探测失败会继续下一个渠道；成功链接写入按渠道隔离的本地缓存与任务记录，供失败后续传。默认缓存目录在 Windows%LOCALAPPDATA%\nituan-seedance-video\uploads，其他系统为用户缓存目录；--cache-dir可覆盖。缓存只在未过期、期限匹配且重新探测成功时复用。可用--upload-workers 1..4调节并发。 - 建议
create ... --submit-only，立即记录video_id与.task.json路径；再用resume --task-file ... --wait-timeout 45查询并下载。可用--from-task恢复尚未提交或上传失败的记录；如果状态为submitting/uncertain，必须人工核查泥团平台，Skill 不会再次 POST。POST 最多一次。每次操作可加--timeout限定整体等待预算；--wait-timeout单独限制轮询窗口。.task.json不存密钥。 - 查询或下载已提交任务使用
query/resume/download --task-file ...，自动沿用输出位置；--output可覆盖。只有 ID 时用--video-id，需提供--output。长任务使用工具异步执行能力，不因工具超时重新create。 - 下载走泥团
/content路由，外部 HTTPS CDN 跳转不带 Bearer。拒绝把 JSON/HTML 错误页当视频，检查 MP4 签名和长度；通过 ETag/Last-Modified 及 SHA-256 检查点支持安全 Range 续传。输出默认不覆盖。--inspect-video auto用本机ffprobe检查视频流和时长，Seedance 另核对尺寸；H3 文档未给实际像素映射，不猜测 768P/2K 的宽高。未安装时明确标注跳过；required强制有 ffprobe，off关闭。 - 用户明确提供
--role image:1=主体、video:1=运镜或audio:1=配乐时，将用途附加到实际提示词；本地先检查编号是否存在。提示词里明确的“图片31/视频11/音频2”等引用也会对素材数量校验，时长如“视频10秒”不会当成索引。 - 交付绝对文件路径、任务 ID、完成状态，并用本地媒体语法展示成片：
。
创建 Skill、调试脚本、预览请求不代表授权真实付费生成；只有用户实际要求生成视频时才执行真实 create。
调用示例
以下命令展示参数用法。先将 SKILL_DIR 替换为 Agent 实际安装的 Skill 根目录，并使用所在系统可用的 Python 命令（Windows 可用 py -3 或 python，macOS/Linux 常用 python3）；素材、提示词和输出路径使用 Agent 运行环境可访问的路径。输出父目录需已存在。
# MiniMax-H3 文生：专用 metadata 请求，4–15 秒，768P 或 2K
python "<SKILL_DIR>/scripts/generate_video.py" create --model MiniMax-H3 --prompt "未来城市在日落时亮起灯光，镜头缓慢推进" --seconds 4 --resolution 2K --aspect-ratio 16:9 --dry-run
# MiniMax-H3 首尾帧：自动上传，按首帧/尾帧顺序发送两张 reference_image
python "<SKILL_DIR>/scripts/generate_video.py" create --model MiniMax-H3 --prompt "由首帧连续运镜过渡至尾帧" --first-frame "<工作区>/首帧.png" --last-frame "<工作区>/尾帧.png" --output "<工作区>/H3成片.mp4" --submit-only
# MiniMax-H3 多模态：同样支持 --image/--video/--audio 和 --role
python "<SKILL_DIR>/scripts/generate_video.py" create --model MiniMax-H3 --prompt-file "<工作区>/提示词.txt" --image "<工作区>/产品.png" --video "<工作区>/运镜.mp4" --audio "<工作区>/配乐.mp3" --resolution 768P --seconds 10 --output "<工作区>/H3成片.mp4" --submit-only
# 文生视频：先预览，再去掉 --dry-run 并用 --submit-only 提交
python "<SKILL_DIR>/scripts/generate_video.py" create --prompt "雨后古镇，白猫追逐萤火虫，平稳跟拍，无字幕" --seconds 10 --aspect-ratio 9:16 --dry-run
# 单图：自动上传，使用 input_reference
python "<SKILL_DIR>/scripts/generate_video.py" create --prompt "以参考图为首帧，人物自然微笑挥手" --image "<工作区>/人物.png" --output "<工作区>/成片.mp4" --submit-only
# 指明素材用途，并控制上传并发/整体等待时间
python "<SKILL_DIR>/scripts/generate_video.py" create --prompt "人物走进街景" --image "<工作区>/人物.png" --output "<工作区>/成片.mp4" --role "image:1=主角身份" --upload-workers 2 --timeout 180 --submit-only
# 默认至少保留一小时，依次尝试 Uguu、Tmpfiles、Litterbox
python "<SKILL_DIR>/scripts/generate_video.py" create --prompt "人物走进街景" --image "<工作区>/人物.png" --output "<工作区>/成片.mp4" --submit-only
# 首尾帧：两张图片具有明确角色
python "<SKILL_DIR>/scripts/generate_video.py" create --prompt "由首帧连续运镜过渡至尾帧" --first-frame "<工作区>/首帧.jpg" --last-frame "<工作区>/尾帧.jpg" --output "<工作区>/成片.mp4" --submit-only
# 仅首帧并关闭声音：发送 first_frame 和布尔值 enable_audio: false
python "<SKILL_DIR>/scripts/generate_video.py" create --prompt "以该画面为起点，镜头缓慢向前推进" --first-frame "<工作区>/首帧.jpg" --seconds 5 --enable-audio false --output "<工作区>/静音成片.mp4" --submit-only
# 多图：依次为图片1、图片2，不自动解释为首尾帧
python "<SKILL_DIR>/scripts/generate_video.py" create --prompt "图片1的人物走入图片2的场景" --image "<工作区>/人物.png" --image "https://example.com/scene.jpg" --output "<工作区>/成片.mp4" --submit-only
# 多模态：视频1参考运镜，音频1参考配乐
python "<SKILL_DIR>/scripts/generate_video.py" create --prompt-file "<工作区>/提示词.txt" --image "<工作区>/产品.png" --video "<工作区>/运镜.mp4" --audio "<工作区>/配乐.mp3" --size 1280x720 --output "<工作区>/成片.mp4" --submit-only
# 如果上传中断，继续准备并首次提交；不会为提交结果未知的任务重发 POST
python "<SKILL_DIR>/scripts/generate_video.py" create --from-task "<工作区>/成片.task.json" --submit-only
# 已有任务：不重新创建；--task-file 沿用任务记录中的输出位置
python "<SKILL_DIR>/scripts/generate_video.py" resume --task-file "<工作区>/成片.task.json" --wait-timeout 45
python "<SKILL_DIR>/scripts/generate_video.py" query --task-file "<工作区>/成片.task.json"
# 只有任务 ID 时显式指定输出位置；download 也支持 --task-file
python "<SKILL_DIR>/scripts/generate_video.py" query --video-id task_example
python "<SKILL_DIR>/scripts/generate_video.py" resume --video-id task_example --wait-timeout 45 --output "<工作区>/成片.mp4"
python "<SKILL_DIR>/scripts/generate_video.py" download --video-id task_example --output "<工作区>/成片.mp4"
两种模型均会把单张 --image 识别为图生、多张图识别为多图，出现视频或音频识别为多模态。Seedance 图生发送 input_reference，H3 图片发送 metadata.metaso_content 中的 image_url 对象。--mode multi 可强制单图走多图，--mode multimodal 可强制图片走多模态。首尾帧不可与普通参考素材混用。仅 Seedance 支持独立首帧、--mode first-frame 及 enable_audio；--audio 是音频参考，不等同于声音开关。--from-task 沿用保存的模型和请求参数，不能同时传 --enable-audio；Seedance 旧记录未保存开关时默认 true。H3 恢复时校验内容项、角色、顺序及已上传链接，避免发送被篡改的素材结构。不发送文档未确认的 generate_audio。
维护验证
python -m unittest discover -s scripts -p "test_*.py" -v
回归使用模拟传输，验证载荷、原子任务记录、提交不确定态、缓存复用/过期、部分上传恢复、链接签名探测、并发顺序、全局超时、Range 下载及 ffprobe 策略。真实托管的可达性仅用合成素材联调；它不能证明泥团机房可访问每个外部 URL、账户模型权限或生成质量。真实生成需用户单独提出，不会因 Skill 测试自动创建付费任务。
