qwencloud-video-generation

Qwen 视频生成

使用 Wan 模型生成视频。所有任务均为异步任务——提交后轮询，直至完成。 此技能属于 qwencloud/qwencloud-ai。

⚠️ 关键参数差异：

• kf2v（首帧 + 尾帧）：时长固定为 5 秒——其他值都会导致失败。输出仅包含静音视频。
• 分辨率参数因模型系列而异，不单由模式决定：选择 size、resolution 或 ratio 前，请获取当前模型目录。

技能目录

使用此技能的内部文件来执行任务和了解相关信息。默认路径无法使用或需要详细信息时，按需加载参考文件。

位置	用途
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 中使用 $QWENCLOUD_API_KEY，Python 中使用 os.environ["QWENCLOUD_API_KEY"]）。脚本会依次接受 QWENCLOUD_API_KEY、QWEN_API_KEY、DASHSCOPE_API_KEY。对凭据进行任何检查或检测时，必须采用非明文方式：仅报告状态（例如“已设置”/“未设置”、“有效”/“无效”），绝不可显示其值。绝不要显示可能包含机密的 .env 或配置文件内容。

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

密钥兼容性

脚本支持标准 QwenCloud API 密钥（sk-...）和 Token Plan 密钥（sk-sp-...）。对于受支持的视频模型，Token Plan 密钥会自动路由到 Token Plan 端点——请参阅下文的 Token Plan 支持。

Token Plan：不要使用 curl；始终使用随附的 Python 脚本。

Coding Plan 密钥（也使用 sk-sp- 前缀，但通过 Coding Plan 订阅购买）不可用——Coding Plan 不提供视频生成模型。使用标准密钥时，视频生成按秒计费。脚本会在启动时检测密钥类型并进行相应路由。如果已安装 qwencloud-ops-auth，请查看其 references/codingplan.md 了解完整详情。

检测 API 密钥类型，但不暴露密钥：

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

输出	含义
token-plan	检测到 Token Plan 密钥（sk-sp- 前缀）
payg	检测到标准 PAYG 密钥
not-set	环境中未找到 API 密钥

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

模式选择指南

用户需求	模式	关键字段
仅根据文本描述生成视频	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 模型目录，了解当前默认值
通过媒体协议编辑视频	videoedit	--model + media 或 video_url；请查阅 CDN 模型目录，了解支持的模型
将参考视频中人物的动作 / 表情迁移到角色图片上	animate	--model + image_url + video_url + mode；请查阅 CDN 模型目录，了解支持的模型

模型选择

🚫 重要：绝不要覆盖用户指定的参数。 如果用户明确指定了模型（在提示词或请求 JSON 中），你必须使用该确切模型。不要：

• 将其替换为“更适合”或更新的模型（例如，因为任务“看起来像一体化作业”，就把用户指定的 wan2.6-t2v 换成 wan3.0-video）
• 替换或重组用户的输入字段（例如转换用户指定的 img_url / media 排列），除非所选模型的文档格式要求这样做；如果必须转换，请保持用户媒体的顺序和内容不变
• 添加用户未要求的参数（prompt_extend、shot_type、风格提示）；注意，shot_type: "multi" 必须搭配 prompt_extend: true，但仅当用户确实要求多镜头时才使用
• “优化”用户明确指定的任何选项（duration、size、resolution、prompt）

以下选择指南仅适用于用户未指定模型的情况。

1. 用户指定了模型 → 必须使用该确切模型——不要替换，不要“优化”，不要添加未要求的参数。
2. 当模型选择取决于能力、场景或价格时，请查阅 qwencloud-model-selector 技能。

模型

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

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

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

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

执行

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

前置条件

• API 密钥：使用非明文方式依次检查 QWENCLOUD_API_KEY、QWEN_API_KEY 和 DASHSCOPE_API_KEY（例如，在 shell 中运行： [ -n "$QWENCLOUD_API_KEY" ]；只报告“已设置”或“未设置”，绝不显示密钥值）。如果未设置：如果有 qwencloud-ops-auth 技能，则运行该技能；否则，引导用户从 QwenCloud Console 获取密钥，并通过 .env 文件（在项目根目录或当前目录中运行 echo 'QWENCLOUD_API_KEY=sk-your-key-here' >> .env）或环境变量设置。脚本会在当前工作目录和项目根目录中搜索 .env。技能可能独立安装——不要假设存在 qwencloud-ops-auth。 注意：脚本会自动从当前目录和项目根目录加载 .env（以及任何已导出的环境变量）。如果 shell 检查显示 $QWENCLOUD_API_KEY“未设置”，并不意味着脚本会失败——它仍可能在 .env 中找到密钥。shell 检查仅供参考；权威测试是直接运行脚本（如果任何位置都找不到密钥，脚本会退出并给出明确错误）。
• Python 3.9+（仅使用标准库，无需 pip install）
• 对于媒体合并（拼接、剪辑、音频叠加）：参阅 merge-media.md，了解适用于用户环境的 ffmpeg/moviepy 操作方法

环境检查

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

python3 --version  # must be 3.9+

如果 python3 不可用或版本低于 3.9，PAYG 可以使用路径 2（curl）；Token Plan 则必须安装 Python 3.9+。

默认方式：运行脚本

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

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

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

python3 <this-skill-dir>/scripts/video.py \
  --model wan2.6-t2v \
  --request '{"prompt":"A detective in a rainy city at night","size":"1280*720","duration":5}' \
  --print-response

# Image-to-animation (no prompt): transfer dance moves from reference video to a character
python3 <this-skill-dir>/scripts/video.py \
  --model wan2.2-animate-move \
  --request '{"image_url":"https://example.com/character.jpg","video_url":"https://example.com/dance.mp4","mode":"wan-std"}' \
  --print-response

参数	说明
--request '{...}'	JSON 请求正文
--file path.json	从文件加载请求
--mode MODE	覆盖自动检测的模式（t2v/i2v/kf2v/r2v/vace/videoedit/animate）
--model ID	覆盖模型
--output dir/	将视频和响应 JSON 保存到目录；视频会根据下载 URL 的基本名称自动命名，以防止多次运行时覆盖；多次调用时使用不同文件名，以免覆盖响应数据
--print-response	将响应 JSON 输出到标准输出
--submit-only	提交后退出（输出 task_id）
--task-id ID	对现有任务执行操作
--poll-interval N	轮询间隔秒数（默认：15）
--timeout N	最长等待秒数（默认：600）

验证结果

• 退出代码为 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 → PAYG 可以使用路径 2（curl）；Token Plan 必须安装 Python 3.9+。

错误模式	诊断	解决方法
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+
未找到 QWENCLOUD_API_KEY/QWEN_API_KEY/DASHSCOPE_API_KEY	缺少 API 密钥	从 QwenCloud Console 获取密钥；添加到 .env：echo 'QWENCLOUD_API_KEY=sk-...' >> .env；或者在可用时运行 qwencloud-ops-auth
HTTP 401	密钥无效或不匹配	运行 qwencloud-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 指定可写入的目录

请求字段概要

除 animate（不需要提示词）和 wan2.7 的 videoedit（提示词可选）外，所有模式都需要 prompt。各模式的完整字段表请参阅 request-fields.md。

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

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

特定模式的必填字段

• 必填字段因模型系列而异。请使用 request-fields.md 查看请求负载格式，并使用上方的模型目录了解当前各模型的兼容性。

费用估算

🚨 绝不要猜测或捏造任何价格。 务必引导用户前往 官方定价页面查看准确费率。

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

如需查看实际用量和账单，请使用 qwencloud-usage 技能，或访问控制台： 用量分析 | 按量付费账单 | 编码计划账单

绝不要捏造、猜测或拼接用量／账单／控制台 URL。 仅提供此技能中列出的准确链接。如果此处未列出某个 URL，请勿编造。

本地文件处理

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

生产环境：默认临时存储的 TTL 为 48h，且上传限制为 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 权限）。如果已安装 qwencloud-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 会在 24h 后过期——脚本会自动将视频下载到 --output 目录。串联到其他技能时（例如，vace edit），直接传递 video_url——不要重新下载。
• 如需高级工作流 → 请参阅 workflows.md。

错误处理

错误	原因	操作
401 Unauthorized	API 密钥无效或缺失	如果可用，运行 qwencloud-ops-auth；否则提示用户设置密钥（仅检查是否为明文）
current user api does not support synchronous calls	缺少异步标头	添加 X-DashScope-Async: enable
429 / 5xx	速率限制或服务器错误	采用退避策略重试
任务 FAILED	生成失败	检查轮询响应中的 output.message

输出位置

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

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

Token Plan 支持

Token Plan 仅支持部分视频模型。选择或验证模型前，请先获取并阅读当前的 Token Plan 模型目录。如果 CDN 无法访问，请使用本地备用文件。

只有当前 Token Plan 目录中存在兼容模型的模式才能使用 Token Plan。请求其他模式可能会返回服务错误；请勿擅自切换请求的模型或模式。

如果目录中没有兼容的 kf2v 模型，请在提交 Token Plan kf2v 请求前停止操作。说明所选模型需要 PAYG，然后询问用户是选择已为此请求配置的 PAYG 密钥，还是更改请求的目标，以便通过 Token Plan 支持的模式实现。

⚠️ 额度警告：与文本对话相比，视频生成每次调用消耗的额度要多得多。根据时长和分辨率，生成单个视频可能会消耗数百额度。生成前请检查剩余额度。

必需的请求头

系统会自动添加 User-Agent: qwencloud-skills。

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

脚本执行后，请检查 stderr 中的操作信号。脚本会自动检测更新状态并输出结构化信号。你必须根据这些信号采取相应操作。本节也适用于用户明确要求检查更新的情况。

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

当 stderr 中出现此信号时，你必须向用户提供以下选项，并等待用户回复后再继续。不得默默跳过此步骤。

尚未安装更新检查 skill。它会通知你 qwencloud/qwencloud-ai 的新功能和错误修复。

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

用户回复后：

• 用户选择 1 → 运行：npx skills add QwenCloud/qwencloud-ai --skill qwencloud-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 目录中查找 qwencloud-update-check/SKILL.md。
2. 如果找到，则运行：python3 <qwencloud-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