用途
seedance-2-prompt 用于通过 Seedance 2.0 生成单段 3-15 秒的视频片段，并下载生成的 MP4 文件。它把三种后端统一到一个 CLI 下，通过 with.provider 选择。
支持的后端
| provider | 端点 | 认证环境变量 | 默认模型 |
|---|---|---|---|
| openrouter（默认） | https://openrouter.ai/api/v1/videos | OPENROUTER_API_KEY | bytedance/seedance-2.0 |
| volcengine（国内） | https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks | ARK_API_KEY（或 VOLC_ARK_API_KEY） | doubao-seedance-2-0-260128 |
| byteplus（国际） | https://ark.ap-southeast.bytepluses.com/api/v3/contents/generations/tasks | ARK_API_KEY（或 BYTEPLUS_API_KEY） | dreamina-seedance-2-0-260128 |
两种风格都遵循“先提交再轮询”，但在请求结构（OpenRouter 使用扁平 prompt 字段；ARK 把所有内容打包进 content[] 数组）、轮询 URL（OpenRouter 返回 polling_url；ARK 返回 id，需自行构造 /contents/generations/tasks/{id}）、终态成功状态（completed 与 succeeded）以及最终 MP4 URL 位置（顶层 unsigned_urls[0] 与 content.video_url）上有所不同。脚本将两者归一化为单一 Python 契约。
输入参数（with:）
| 键 | 必填 | 默认 | 说明 |
|---|---|---|---|
| prompt | 是 | — | 结构化英文视频提示词（使用本技能的配方）。 |
| filename | 是 | — | 输出 .mp4 路径。 |
| provider | 否 | openrouter | openrouter、volcengine 或 byteplus。 |
| aspect_ratio | 否 | 9:16 | 9:16、16:9、1:1、4:3、3:4、21:9。 |
| duration | 否 | 5 | 秒，3-15。OpenRouter Seedance 接受 4-15；请求 3 秒会生成真实的 4 秒片段并在本地裁剪为恰好 3 秒。 |
| resolution | 否 | 720p | 480p、720p、1080p。OpenRouter 忽略此项。 |
| model | 否 | 后端默认 | 覆盖模型 id。留空表示使用后端默认。 |
| input_image | 否 | "" | 严格首帧路径。若设置，视频从该图像开始。 |
| input_reference | 否 | "" | 主要软性身份/风格锚点路径。仅在 input_image 为空时使用。跨镜头传入同一锚点可锁定角色。 |
| input_reference_2 | 否 | "" | 可选的第二参考（例如逐镜头场景构图）。作为第二个 --input-reference 转发，使底层后端同时看到两者。空字符串在 API 调用前被过滤掉。 |
| max_retries | 否 | 0 | 在任务 id 发出后，针对轮询时的瞬时 HTTP 429/5xx 或传输失败进行额外重试，上限 5；每次重试都停留在同一任务上。付费的 POST 提交从不自动重试，包括模糊的 429/5xx 或传输失败，因为后端可能已经接受并计费。HTTP 401/403/其他 4xx、终态策略失败以及下载的媒体无效也会立即停止。0 表示不额外重试轮询。 |
input_image 与 input_reference 的区别：input_image 成为字面意义上的第一帧。input_reference 是更柔和的风格 + 身份提示，模型使用它但不锁定帧。对于多镜头剧集，给每个镜头传入相同的 input_reference；仅当你想要特定开场帧时才传入 input_image。
提示词规则（来自上游 + OpenSquilla 收紧）
- 每 3-5 秒片段一个主要动作。不要塞入多个动作。
- 身份连续性——在每个镜头的提示词中重复主角的完整描述。
- 具体优于诗意——“a young woman in a red trench coat walks through rain-soaked neon streets” 优于 “a woman walking”。
- 内联负面约束——追加 no watermark, no logo, no subtitles, no on-screen text。
- IP 安全——发明原创角色/品牌名称。
- 明确宽高比——追加 aspect_ratio: 9:16。
更多上游手册见 references/recipes.md、references/modes-and-recipes.md、references/camera-and-styles.md。
认证
openrouter 后端的 API 密钥解析顺序：
- --api-key CLI 参数
- 父级注入的原子元组 OPENSQUILLA_META_CAPABILITY_PROVIDER、OPENSQUILLA_META_CAPABILITY_API_KEY 和 OPENSQUILLA_META_CAPABILITY_BASE_URL；可选的 OPENSQUILLA_META_CAPABILITY_PROXY 仅用于匹配后端的已认证 API 请求
- OPENSQUILLA_META_OPENROUTER_API_KEY，为较旧的父运行时保留，绑定到 OpenRouter 官方源
- OPENROUTER_API_KEY，用于直接 CLI 使用，也绑定到官方源
通用父密钥仅在与匹配的 provider 和 base URL 一起时才被接受。父级和规范环境凭据允许通过 --base-url 进行同源路径更改，但绝不允许 scheme、hostname 或有效端口更改。有意选择不同源的直接 CLI 用户必须同时传递 --api-key 和 --base-url。
子进程从不发现或解析其工作区中的 opensquilla.toml，也从不遵循工作区选择的任意 llm.api_key_env。正常配置活动 Gateway；其父运行时执行该解析。
当父级解析的 profile-pool 凭据收到认证、额度或速率限制失败时，OpenSquilla 会将该密钥停放，等待下一次明确授权的运行。它从不自动重复当前付费生成。
volcengine / byteplus 后端读取 ARK_API_KEY（带有后端特定回退 VOLC_ARK_API_KEY / BYTEPLUS_API_KEY）。这些没有配置文件回退——OpenSquilla [llm] 配置描述的是智能体选定的 LLM 后端，而非 ARK / BytePlus 视频凭据。
三者都仅向 scheme、hostname 和有效端口与配置的后端 base 完全匹配的 API URL 发送 Authorization: Bearer <key>。不跟随已认证重定向。后端提供的跨源轮询 URL 会被忽略，转而使用受信 base 下的规范任务 URL。父级注入的代理仅用于这些匹配的后端 API 请求，绝不用于匿名媒体下载。
媒体下载始终匿名，包括 OpenRouter 托管的 URL。下载 URL 及每个重定向必须使用 HTTPS、不包含 userinfo，并且仅解析到公共地址；localhost、私有、回环、链路本地、保留、未指定和多播目标会被拒绝。每个连接固定到通过验证的地址，同时保留原始 TLS SNI/hostname，消除验证与连接之间的 DNS 重绑定。
输出
打印保存的 .mp4 的绝对路径，然后在 stdout 上打印一行 VIDEO_GENERATION_RECEIPT: {...}。匹配的脱敏回执保存为 <filename>.receipt.json；它记录 provider、model、安全任务 id 以及针对后端片段和最终片段的 ffprobe 验证元数据。下载首先落在同目录的私有候选文件中。脚本要求真实的视频流、正时长、合理尺寸以及时长在容差内；3 秒请求在本地裁剪前后都会探测。只有验证通过的候选文件才会用 os.replace 原子发布，因此 HTML 错误页、截断下载或裁剪失败都无法覆盖现有输出。回执绝不包含 API 密钥、提示词、原始后端响应、请求/生成元数据、用量负载或签名下载 URL。日志省略 URL 查询/片段和原始后端消息。任何错误都以非零退出；stderr 在可用时携带脱敏的状态/代码摘要。
在识别到后端策略拒绝时，脚本立即停止并持久化一个失败 sidecar，而不是伪造 API 成功。该 sidecar 严格限于 status=policy_rejected、provider/model、reason=provider_policy_rejected 以及允许列表中的 policy_code；它绝不包含原始后端文本、签名 URL、请求/任务 ID、提示词或密钥。Meta 工作流随后可以运行其本地回退，同时为交付审计保留诚实、用户可见的降级原因。
成本 / 延迟
- OpenRouter bytedance/seedance-2.0 5 秒 @ 9:16 720p：约 30-90 秒墙钟时间，约 $0.76。
- 火山引擎官方 5 秒 1080p：约 30-120 秒墙钟时间，约 $0.93。
- 火山引擎 doubao-seedance-2-0-fast-260128：成本约减半且更快。
在火山引擎路径上，返回的 unsigned_urls / content.video_url 在成功后 24 小时过期——此脚本在该窗口前下载它们，因此本地 mp4 是持久的。
多段工作流（>15 秒）
以 duration ≤ 15 逐个生成片段，每个片段结束于稳定的交接帧。使用 video-merger 技能拼接。参见 references/modes-and-recipes.md § “Multi-Segment Stitching”。