qianwen-video-generation

Qwen 视频生成

使用 Wan 和 HappyHorse 模型生成视频。所有任务均为异步任务——提交后轮询，直到完成。 此技能是 QianWen-AI/qianwen-ai 的一部分。

⚠️ 关键参数差异：

• kf2v（首帧+尾帧）：时长固定为 5 秒——其他值都会导致失败。输出仅包含静音。
• 分辨率参数因模型系列而异，并非仅取决于模式：选择 size、resolution 或 ratio 前，请查看当前模型目录。例如，happyhorse-1.1-t2v 使用 resolution + ratio，而 wan2.6-t2v 使用 size。

技能目录

使用此技能的内部文件来执行和学习。默认路径不可用或需要详细信息时，按需加载参考文件。

位置	用途
scripts/video.py	默认执行方式——自动检测模式、提交、轮询、下载
references/execution-guide.md	后备方案：所有 5 种模式的 curl 命令、代码生成
references/request-fields.md	按模式分类的字段表和音频处理
references/workflows.md	时长扩展、多镜头、VACE 流程
references/polling-guide.md	轮询模式和时间安排
references/merge-media.md	拼接、裁剪、音频叠加——ffmpeg/moviepy 示例
references/prompt-guide.md	各模式的提示词公式、声音描述、多镜头结构
references/examples.md	各模式的完整脚本示例
references/sources.md	官方文档 URL

安全

绝不要以明文形式输出任何 API 密钥或凭据。始终使用变量引用（Shell 中使用 $DASHSCOPE_API_KEY，Python 中使用 os.environ["DASHSCOPE_API_KEY"]）。任何凭据检查或检测都必须不显示明文：仅报告状态（例如“已设置”/“未设置”、“有效”/“无效”），绝不显示其值。绝不要显示可能包含机密的 .env 或配置文件内容。

**未配置 API 密钥时，绝不要要求用户直接提供。**应改为帮助用户创建带有占位符的 .env 文件（DASHSCOPE_API_KEY=sk-your-key-here），并指导用户从 QianWen Console 获取实际密钥后替换占位符。只有在用户明确要求时，才写入实际密钥值。

密钥兼容性

支持 PAYG（sk-ws-...；旧版 sk-...）和 Token Plan（sk-sp-...）密钥。检测 API 密钥类型时不得暴露密钥：

python3 -c "
import sys; sys.path.insert(0, 'scripts')
from qianwen_lib import detect_api_key_type
print(detect_api_key_type('scripts/qianwen_lib.py'))
"

输出	含义
token-plan	Token Plan 密钥——仅使用下方 Token Plan 目录中的模型。
payg	按量付费密钥——可使用完整模型目录。
not-set	未配置密钥。

对于 Token Plan，请获取并阅读当前的 Token Plan 模型目录，然后使用其中列出的确切模型。如果 CDN 访问失败，请使用本地后备文件。

Token Plan 不支持本地文件上传；对于 i2v/r2v/kf2v 模式，请提供可访问的 URL（https:// 或 oss://）作为参考图片/视频，而不要使用本地路径。

Token Plan 仅支持特定模型——请严格使用上述参考资料中列出的模型，不要猜测或探测模型是否可用。对于 PAYG，请继续阅读下文。

模式选择指南

用户需求	模式	关键字段
仅根据文本描述生成视频	t2v	仅 prompt
为单张图片添加动画	i2v	img_url 或 reference_image
wan2.7 统一 i2v：首帧、首帧 + 尾帧、视频续写、音频同步	i2v	media[]、first_frame_url、first_clip_url、driving_audio_url
在两张图片之间转场（⚠️ 固定 5s，仅静音）	kf2v	first_frame_url + last_frame_url
角色扮演：让角色演绎新剧本	r2v	reference_urls 或 media；请查看 CDN 模型目录，了解特定模型的限制
视频编辑：多图参考、重绘、局部编辑、延长、扩图	vace	function；请查看 CDN 模型目录，了解当前默认值
视频编辑（无 function 字段，使用媒体数组）	videoedit	model；请查看 CDN 模型目录，了解支持的模型

模型选择

1. 用户指定了模型 → 直接使用。
2. 当模型选择取决于能力、场景或价格时，请参考 qianwen-model-selector 技能。

在选择、推荐或默认使用模型之前，请获取并阅读当前的 Qwen 视频生成模型目录。其中包含模型列表、模型基本信息、模式推荐、兼容性说明和默认值。如果无法访问 CDN，请使用本地备用文件。

端点：/services/aigc/video-generation/video-synthesis。

⚠️ 重要：上方的模型列表是特定时间点的快照，可能已过时。模型可用性 经常变化。在作出模型决策之前，务必查看官方模型列表， 以获取权威且最新的目录。

模型详情：如需了解特定模型的更多信息，请引导用户访问 https://www.qianwenai.com/models/<model-name>。将 <model-name> 替换为准确的模型 ID；切勿修改或猜测该 ID。

动态模型查询：如果可以使用 qianwen-model-selector 技能或 QianWen CLI（qianwen models info <model>），请使用它获取实时模型数据。CLI 需要身份验证——登录流程请参阅 qianwen-usage 技能。

执行

⚠️ 多个制品：在单次会话中生成多个文件时，必须为每个文件名添加数字后缀（例如 out_1.mp4、out_2.mp4），以防止覆盖。

前提条件

• API Key：使用 Key Compatibility 中的非明文检测器；不要将其替换为检查变量是否存在。如果未找到 Key，请在可用时使用 qianwen-ops-auth，或指导用户在 .env 中配置 DASHSCOPE_API_KEY/QIANWEN_API_KEY。技能可以独立安装。
• Python 3.9+（仅标准库，无需安装 pip 包）
• 对于媒体合并（拼接、剪辑、音频叠加）：请参阅 merge-media.md，了解适合用户环境的 ffmpeg/moviepy 方案

环境检查

首次执行前，请确认 Python 可用：

python3 --version  # must be 3.9+

如果找不到 python3，请尝试 python --version 或 py -3 --version。如果 Python 不可用或版本低于 3.9，请跳至 execution-guide.md 中的路径 2（curl）。

默认：运行脚本

脚本路径：脚本位于此技能目录（包含此 SKILL.md 的目录）下的 scripts/ 子目录中。**必须先找到此技能的安装目录，然后始终使用绝对路径执行脚本。**不要假设脚本位于当前工作目录中。执行前不要使用 cd 切换目录。

执行说明：在前台运行所有脚本——等待标准输出；不要在后台运行。

**查找方式：**先运行 python3 <this-skill-dir>/scripts/video.py --help，查看所有可用参数。

python3 <this-skill-dir>/scripts/video.py \
  --request '{"model":"happyhorse-1.1-t2v","prompt":"A detective in a rainy city at night","resolution":"720P","ratio":"16:9","duration":5}' \
  --print-response

参数	说明
--request '{...}'	JSON 请求正文
--file path.json	从文件加载请求
--mode MODE	覆盖自动检测的模式（t2v/i2v/kf2v/r2v/vace）
--model ID	覆盖模型
--output path	目录或文件路径。如果路径以视频扩展名（.mp4/.mov/.webm/.mkv/.m4v 等）结尾，则将其用作输出文件名（自动创建父目录）。否则视为目录——视频将根据 OSS URL 的基本名称自动命名，以避免不同运行之间发生覆盖；不同调用请使用不同文件名，以免覆盖响应数据
--print-response	将响应 JSON 打印到标准输出
--submit-only	提交后退出（打印 task_id）
--task-id ID	操作现有任务
--poll-interval N	轮询间隔秒数（默认：15）
--timeout N	最大等待秒数（默认：600）

模型优先级：--model 命令行标志 > --request JSON 中的 "model" 字段 > 配置的默认模型。未指定模型时将使用配置的默认模型，该模型不一定是最新或最强的模型。

验证结果

• 退出代码为 0 且响应包含 output.task_id → 提交成功
• 轮询结果达到 task_status: SUCCEEDED → 生成完成
• 非零退出代码、HTTP 错误或 FAILED 状态 → 失败
• 执行后检查：确认输出视频文件存在且大小不为零（ls -la <output_dir>）
• 强制要求 — stderr 信号检查：确认结果后，检查命令的 stderr 输出中是否包含 [ACTION_REQUIRED] 或 [UPDATE_AVAILABLE]。如果出现任一信号，在回复用户之前，必须按照下方更新检查中的说明操作。

失败时

如果脚本运行失败，请将错误输出与下方诊断表进行匹配，以确定解决方法。如果没有匹配项，请阅读 execution-guide.md，了解其他路径：curl 命令（路径 2 — 全部 5 种模式）、代码生成（路径 3）和自主解决（路径 5）。

如果完全无法使用 Python → 直接跳到 execution-guide.md 中的路径 2（curl）。

错误模式	诊断	解决方法
command not found: python3	Python 不在 PATH 中	尝试 python 或 py -3；如果未安装，请安装 Python 3.9+
Python 3.9+ required	脚本版本检查失败	将 Python 升级到 3.9+
类型提示附近出现 SyntaxError	Python 版本低于 3.9	将 Python 升级到 3.9+
未找到 QIANWEN_API_KEY/DASHSCOPE_API_KEY	缺少 API 密钥	从 QianWen Console 获取密钥；添加到 .env：echo 'DASHSCOPE_API_KEY=sk-...' >> .env；或者在可用时运行 qianwen-ops-auth
HTTP 401	密钥无效或不匹配	运行 qianwen-ops-auth（仅进行非明文检查）；确认密钥有效
SSL: CERTIFICATE_VERIFY_FAILED	SSL 证书问题（代理/企业网络）	macOS：运行 Install Certificates.command；否则设置 SSL_CERT_FILE 环境变量
URLError / ConnectionError	网络不可达	检查互联网连接；如果使用代理，请设置 HTTPS_PROXY
HTTP 429	请求受到速率限制	等待后使用退避策略重试
HTTP 5xx	服务端错误	使用退避策略重试
ImportError: moviepy	未安装 moviepy	运行 pip install moviepy，或改用系统 ffmpeg（参见 merge-media.md）
PermissionError	无法写入输出	使用 --output 指定可写目录

请求字段摘要

所有模式都需要 prompt。有关各模式的完整字段表，请参见 request-fields.md。

⚠️ 按模型系列划分的分辨率参数（重要）

分辨率字段因模型系列而异。选择 size、resolution 和 ratio 之前，请先查看上方的模型目录；使用错误的字段可能导致 API 调用失败。

各模式的必填字段

• 必填字段因模型系列而异。有关负载结构，请参见 request-fields.md；有关当前各模型的兼容性，请参见上方的模型目录。

费用估算

🚨 绝不要猜测或编造任何价格。 请始终引导用户前往 官方定价页面查询确切费率。

费用按生成视频的秒数计费。价格因模型和分辨率而异。请获取 CDN 模型定价参考，并通过官方定价页面查询当前确切费率。部分模型可能提供有限的免费额度——不要假定任何调用都是免费的；请使用 qianwen-usage skill 检查剩余免费额度，或在用户的 QianWen 控制台中确认。如果 CDN 访问失败，请使用本地备用文件。

如需查看实际用量和账单，请使用 qianwen-usage skill，或访问控制台： 用量分析 | 按量付费账单 | Token 套餐订阅

绝不要编造、猜测或构造用量、账单或控制台 URL。 只能提供此 skill 中列出的确切链接。如果此处未列出某个 URL，就不要编造。

本地文件处理

当用户提供本地文件路径（图像、视频、音频）时，请直接传递给脚本。脚本会自动上传本地文件到 DashScope 临时存储（oss:// URL，TTL 为 48 小时），并注入 X-DashScope-OssResourceResolve: enable 请求头。无需手动上传。

生产环境：默认临时存储的 TTL 为 48 小时，且上传限额为 100 QPS——不适用于生产环境、高并发或负载测试。如需使用自己的 OSS 存储桶，请在 .env 中设置 QWEN_TMP_OSS_BUCKET 和 QWEN_TMP_OSS_REGION，安装 pip install alibabacloud-oss-v2，并通过 QWEN_TMP_OSS_AK_ID / QWEN_TMP_OSS_AK_SECRET 或标准变量 OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET 提供凭据。使用权限遵循最小权限原则的 RAM 用户（仅对目标存储桶授予 oss:PutObject 和 oss:GetObject 权限）。如果已安装 qianwen-ops-auth，请参阅其 references/custom-oss.md 获取完整设置指南。

跨技能链式调用

使用其他技能的输出作为输入时（例如，image-gen → i2v、audio-tts → 音频叠加）：

• 直接传递 URL（例如，"img_url": "<image_url from image-gen>"）——不要下载后再以本地路径重新传递
• 脚本会检测 URL 前缀（https://、oss://），并直接传递，不会重新上传
• 仅在向用户预览或执行非 API 操作时使用响应中的 local_path

将此技能的输出传递给其他技能时（例如，vace edit、vision analyze）：

• 传递响应中的 video_url——不要下载后再以本地路径重新传递

场景	使用
传递给其他技能	video_url / image_url（URL）
向用户展示 / 本地播放	local_path（本地文件）

重要说明

• 仅支持异步：所有视频 API 都需要 X-DashScope-Async: enable 请求头。
• kf2v：使用不同的 API 端点。时长固定为 5s，且仅支持静音。
• r2v：在提示词中使用 character1/character2/...。最多支持 5 个参考素材（最多 3 个视频）。
• vace：必须指定 function。仅支持静音，输出时长不超过 5s。
• 多镜头：设置 shot_type: "multi" 和 prompt_extend: true。
• 视频 URL 将在 24 小时后过期——脚本会自动将视频下载到 --output 目录。链式调用其他技能（例如 vace edit）时，直接传递 video_url——不要重新下载。
• 高级工作流 → 请参阅 workflows.md。

错误处理

错误	原因	操作
401 Unauthorized	API 密钥无效或缺失	如果可用，请运行 qianwen-ops-auth；否则提示用户设置密钥（仅检查是否为非明文）
current user api does not support synchronous calls	缺少异步请求头	添加 X-DashScope-Async: enable
429 / 5xx	速率限制或服务器错误	采用退避策略重试
The product is not activated / Model not subscribed	账户未启用第三方模型	访问 Model Market，找到该模型，然后点击“Enable” / “开通”
任务 FAILED	生成失败	检查轮询响应中的 output.message

输出位置

优先使用当前工作目录。默认子目录：./output/qianwen-video-generation/。

禁止写入：切勿将输出文件写入此技能的安装目录或任何 skills/ 层级。所有生成内容都必须写入当前工作目录下的 output/，或用户指定的路径。

更新检查（执行后必须进行）

脚本执行后，检查 stderr 中是否有操作信号。脚本会自动检测更新状态并发出结构化信号。必须根据这些信号采取操作。用户明确要求检查更新时，也适用本节。

信号：[ACTION_REQUIRED] qianwen-update-check skill is not installed

当 stderr 包含此信号时，你 MUST 向用户提供以下选项，并在继续操作前等待用户回复。请勿默默跳过。

尚未安装更新检查 skill。它会让你及时了解 QianWen-AI/qianwen-ai 的新功能和错误修复。

1. 立即安装 — 我会为你运行安装命令
2. 暂时跳过 — 本次不做任何操作
3. 不再提醒 — 永久隐藏此提示

用户回复后：

• 用户选择 1 → 运行：npx skills add QianWen-AI/qianwen-ai --skill qianwen-update-check -y，然后运行：python3 <this-skill-scripts-dir>/gossamer.py --dismiss
• 用户选择 2 → 运行：python3 <this-skill-scripts-dir>/gossamer.py --dismiss，然后正常继续
• 用户选择 3 → 运行：python3 <this-skill-scripts-dir>/gossamer.py --never-install，然后正常继续

信号：[UPDATE_AVAILABLE]

当 stderr 包含此信号时，必须在回复中附上一条简短的更新通知，其中包含版本信息以及 stderr 输出中显示的更新命令。

stderr 中没有信号

如果 stderr 中既不包含 [ACTION_REQUIRED]，也不包含 [UPDATE_AVAILABLE]，则无需采取任何操作——该 skill 已安装且为最新版本（或缓存时间未超过 24 小时）。

用户明确提出请求

当用户明确要求检查更新（例如“检查更新”或“检查版本”）时：

1. 在相邻的 skill 目录中查找 qianwen-update-check/SKILL.md。
2. 如果找到，则运行：python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response 并报告结果。
3. 如果未找到，则提供上述安装选项。

参考资料

• execution-guide.md — 后备路径（适用于所有模式的 curl、代码生成、自主模式）
• request-fields.md — 按模式划分的详细字段表及音频处理
• workflows.md — 时长扩展、音频变通方案、多镜头、VACE 流程
• polling-guide.md — 轮询模式和时间建议
• merge-media.md — 生成合并、剪辑和音频叠加代码的指南
• examples.md — 所有模式的完整脚本执行示例
• sources.md — 官方文档 URL