tokease.cn 通用视频生成（不使用素材库）
通过 tokease.cn 生成 AI 视频。不使用素材库：参考图片、参考视频、参考音频、首尾帧图一律直接传公网 http/https URL。模型名由用户指定并原样透传，默认 Seedance 2.5，不限模型系列。完整接口字段见 @references/video-api.md。
1. 模型与素材规则
- 模型名：用户说模型名就原样传给
--model；未指定时用默认Seedance 2.5（平台自动映射真实模型 ID，用户不用关心）。 - 素材规则：所有参考素材（
--image、--ref-video、--ref-audio、--first-frame、--last-frame）必须是公网 http/https URL。 - 素材库引用
asset://一律不支持：出现即报错，提示改用原始公网链接，不猜测、不转换。 - 本技能仅提供生成与查询能力，不涉及素材上传与身份核验流程。
2. API Key 规则
- 首次使用时向用户询问 tokease.cn 的 API Key，获取入口见 @references/setup-guide.md。
- Key 只通过
--api-key参数传入脚本，同一会话内复用；不写入文件、不设置环境变量、不在输出中回显完整 Key。 - Key 失效或额度耗尽时，引导用户到 tokease.cn 控制台检查、轮换或撤销。
3. 首次使用前环境检查
运行只读检查（--network 允许对 tokease.cn 的匿名健康探测，不发送凭据）：
python scripts/check_environment.py --network --capability video-generation
ready：直接执行任务，不再展示配置引导。needs_setup：只展示缺失项（Python 版本或网络）及恢复步骤。unavailable：说明网络故障，生成类功能停止；用户可选择稍后重试。- API Key 属于调用时传入的凭据，不在环境检查范围内，缺失时向用户询问。
4. 生成视频
脚本路径：scripts/tokease_video.py，需 Python 3.10+。所有命令示例中的 <KEY> 指用户提供的 API Key。
4.1 文生视频
python scripts/tokease_video.py create --prompt "黄昏海岸线，电影级光影，慢镜头推进" --api-key <KEY> --ratio 16:9 --resolution 720p --wait --download ~/Desktop
4.2 图生视频 / 多参考图
# 单张参考图
python scripts/tokease_video.py create --prompt "镜头缓慢推进，背景树叶随风飘动" --image "https://cdn.example.com/main.png" --api-key <KEY> --wait --download ~/Desktop
# 多张参考图（可重复 --image）
python scripts/tokease_video.py create --prompt "保持第一张图的构图与色调，参考第二张图的光影与氛围" --image "https://cdn.example.com/composition.png" --image "https://cdn.example.com/lighting.png" --api-key <KEY> --wait
4.3 首尾帧生视频
python scripts/tokease_video.py create --prompt "镜头从首帧平滑过渡到尾帧" --first-frame "https://cdn.example.com/start.png" --last-frame "https://cdn.example.com/end.png" --api-key <KEY> --wait
首尾帧模式与参考图模式互斥，不能同时传 --image 和 --first-frame/--last-frame。
4.4 视频生视频 / 多参考视频
python scripts/tokease_video.py create --prompt "转为赛博朋克夜景风格" --ref-video "https://cdn.example.com/source.mp4" --api-key <KEY> --wait
--ref-video 可重复传入多个参考视频。
4.5 参考音频与无声视频
# 图 + 参考音频（配音/音画同步场景）
python scripts/tokease_video.py create --prompt "画面随参考音频的节奏与情绪同步演绎" --image "https://cdn.example.com/scene.png" --ref-audio "https://cdn.example.com/voice.mp3" --api-key <KEY> --wait
# 无声成片
python scripts/tokease_video.py create --prompt "城市夜景延时摄影" --no-audio --api-key <KEY> --wait
参考音频不能单独使用，须配合参考图、参考视频或首尾帧。
4.6 常用可选参数
| 参数 | 说明 |
|---|---|
--model |
模型名，默认 Seedance 2.5 |
--ratio |
16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 |
--resolution |
480p / 720p / 1080p / 4k |
--duration |
4–15 秒或 -1（模型智能选择） |
--seed |
随机种子，复现结果用 |
--no-audio |
输出无声视频（默认生成成片音频） |
--watermark / --no-watermark |
是否加水印 |
--web-search |
启用联网搜索（metadata.tools=[{"type":"web_search"}]） |
--service-tier |
服务等级（按上游约定） |
--execution-expires-after |
任务执行过期时间（秒） |
--callback-url |
任务完成回调地址 |
--return-last-frame |
查询结果中返回尾帧图 |
--dry-run |
只打印请求体，不发送网络请求（构造请求拿不准时先用它核对） |
用户未指定比例、分辨率、时长时不要传这些参数，交给接口默认值。
4.7 查询与下载
python scripts/tokease_video.py status <task_id> --api-key <KEY>
python scripts/tokease_video.py wait <task_id> --api-key <KEY> --download ~/Desktop
- 生成通常需要数分钟，创建后默认用
--wait等待；轮询间隔默认 15 秒。 - 完成后立即下载（视频 URL 有时效性）；
--return-last-frame时同时下载尾帧图。 - 始终把任务 ID 告知用户，便于后续查询。
5. 失败处理与降级
| 情况 | 处理 |
|---|---|
| 素材地址不是公网 URL（含 asset://） | 属于使用错误，停止并提示改用原始公网链接 |
| 图与首尾帧混用 / 音频单独使用 / 时长越界 | 参数冲突，提示修正后重试，不猜测参数 |
| 网络错误或服务超时 | 展示错误并建议重试，不无限重试 |
| 生成失败（status=failed） | 展示 error 内容，建议简化 prompt 或减少参考素材 |
| API Key 失效（401/403） | 引导用户到 tokease.cn 控制台检查或轮换 Key |
| 下载失败 | 输出视频 URL 让用户手动保存，不静默丢弃 |
停止条件：API Key 缺失且用户拒绝提供、网络不可用、素材 URL 不合规时，停止对应流程；不用猜测结果顶替。
6. 内容安全与合规
- 生成内容须合法合规：不生成违法或损害他人权益的内容。
- 参考素材须为用户有权使用的素材；涉及他人形象或声音的内容，须事先获得授权。
- AI 生成内容应依法进行标识并说明用途。
- 本技能仅调用 tokease.cn 官方生成接口，成片经平台内容审核后返回；技能不绕过、不干预平台的审核机制。
- 生成内容的使用责任由使用者承担，不得用于违法或侵犯他人权益的用途。
7. 使用前自查
- 模型名确认：用户有指定就用指定的，否则默认
Seedance 2.5。 - 素材就绪：所有参考素材均为公网 http/https URL，无
asset://。 - 模式互斥：
--image与首尾帧不同用；参考音频不单独使用。 - 内容合规：参考素材为用户有权使用的素材，生成内容合法合规（见第 6 章）。
- 每次生成后向用户报告任务 ID、成片路径或 URL。
