企业官网建设流程全解析

claude-code-router 视频生成工具：为 Fusion 模型接入异步文生视频、图生视频与参考图生视频

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router

claude-code-router（CCR）的Video generation tool是 Fusion 内置媒体工具，它能让原本只支持文本的模型升级为具备视频生成能力的 Agent 模型：支持文生视频（text-to-video）、图生视频（image-to-video）和参考图生视频（reference-to-video）。视频生成始终以异步作业（asynchronous job）的方式运行，启动调用立即返回作业 ID，随后 CCR 持续轮询作业状态直至完成、失败或被取消。读完本文，你将掌握如何在 Fusion 模型中启用视频生成、理解其作业生命周期与重试/回退机制，并学会从源码层面排查失败原因。本文的主体说明见仓库文档 video-generation.md，与之配套的图片生成说明见 image-generation.md。

功能定位：把"文本模型"变成"能生成视频的 Agent"

Video generation tool 是一个built-in Fusion media tool。它解决的问题很直接：你有一个文本对话模型，但它没有视频输出通道；通过把视频生成工具绑定到 Fusion 模型上，模型就能借助工具提交视频生成作业，并读取最终产物的元数据。

在 contracts/app.ts 中，BUILTIN_FUSION_IMAGE_GENERATION_TOOL_NAME = "image_generation"、BUILTIN_FUSION_VIDEO_GENERATION_TOOL_NAME = "video_generation"，说明媒体能力在 Fusion 页面上以两个普通的内置 Fusion 工具暴露：Image generation与Video generation。它们与内置搜索工具行为一致：不属于 ToolHub，也不会在 Fusion 页面单独建区（参见 fusion-mcp-tool.md）。

两个要点值得提前说明：

• 视频生成是纯异步作业：启动（start）调用只负责提交，立即返回job ID；之后由工具负责查作业状态、回报进度，作业完成时返回视频产物的元数据，用户取消请求时则尝试取消或停止等待。
• 执行链不嵌套 Agent 进程：媒体请求通过 ai-gateway 的通用媒体协议发出，绝不启动嵌套的 Agent 或 CLI 进程（源码 service.ts 的submit/run/execute全程为进程内 HTTP 驱动）。

启用步骤

在 Fusion 模型中添加视频生成工具

按官方文档 video-generation.md 的步骤操作：

1. 在Providers页配置一个支持视频生成协议的 provider 与模型。
2. 新建或编辑一个 Fusion 模型。
3. 在Tools下添加Video generation。
4. 选择一个视频模型，格式形如Provider/model。
5. 保存 Fusion 模型，并把它作为 Agent 模型或路由目标使用。

从源码看，这里的"模型选择器（model selector）"即Provider/model形式的绑定字符串。内部绑定配置由VirtualModelFusionMediaConfig承载，定义在 contracts/app.ts，其中与视频相关的字段包括：

绑定编译逻辑位于 tools.ts：Fusion profile 携带metadata.fusionMedia配置时，会被readFusionMediaConfig解析，再为每个可用的视频工具名生成一条MediaToolBinding（video-generate、job-get、job-cancel三类操作）。需要留意：videoRetryCount会被收敛到0与ROUTER_FALLBACK_MAX_RETRY_COUNT之间（见 tools.ts），上限与路由层共享的 fallback 最大重试常量一致。

通过导入 Grok Agent 开箱使用

文档特别指出：导入 Grok Agent 后，CCR 会自动提供grok-imagine-video。ai-gateway 会复用已有 OAuth 登录态访问api.x.ai，不会额外启动 Grok CLI。对应实现见 contracts/app.ts：默认视频模型为grok-imagine-video（默认图片模型为grok-imagine-image-quality），isImportedGrokAgentProvider会识别本地 Agent 导入产生的 provider（apikey为ccr-local-agent-login且 baseURL 属于cli-chat-proxy.grok.com或名字含 grok），见 models.ts。这正是文档中所说的"重试后仍失败则走备用模型、但绝不启动 Grok CLI"的实现前提。

视频模型的独立重试与回退

视频生成拥有独立的重试次数与备用视频模型。当被选中的视频模型因可重试的媒体 provider 错误失败时，CCR 先对该模型本身重试，再依次尝试配置的备用视频模型；基础文本模型保持不变。从实现看：

• 尝试序列由mediaModelAttempts构造：[主模型 × (retryCount+1), 备用模型1 × (retryCount+1), …]（见 service.ts）；
• 每次失败若错误标记为retryable才继续，退避延迟为min(2000, 100 * 2^attempt)毫秒的指数退避（见 service.ts）；
• 回退视频模型必须与主模型使用同一媒体协议，否则mediaModelPlan会直接报错提示Configure video fallback models with the same media protocol（见 service.ts）；而videoToolBindingForRuntime在生成工具目录时也会静默剔除协议不兼容的回退项（service.ts）。

支持的请求

CCR 通过 ai-gateway 的通用媒体协议调用各 provider，文档列出了两张核心请求：

其中第一条对应videoStart（提交视频作业），第二条对应轮询阶段的GET videos/{id}。请求体由GatewayMediaExecutor组装（见 executors.ts）：

• model：目标视频模型；
• prompt：视频生成提示词；
• duration：时长（秒）；
• resolution/aspect_ratio：分辨率与画面比例；
• 传入 1 张图片时为image（图生视频），传入多张图片时为reference_images（参考图生视频）；图片以data:URI 形式内联。

视频作业的参数约束

由于不同协议对时长/比例/分辨率的要求不同，参数 schema 由videoGenerationConstraints(protocol)动态生成（见 tools.ts 与 models.ts）：

• openai_video_generations协议：aspect_ratio仅允许16:9、9:16；duration仅允许4 / 8 / 12秒；resolution仅允许720p；aspect_ratio、duration、resolution三者必填。
• xai_video_generations协议（Grok 路径默认）：aspect_ratio允许1:1、16:9、9:16、4:3、3:4、3:2、2:3；duration支持1~15秒、默认6秒；resolution支持480p / 720p、默认480p。

这些约束在启动时会严格校验（见 service.ts）：非整数时长、超出枚举/范围的值都会直接抛错；VideoGenerateRequest契约见 contracts.ts。

幂等键（idempotency_key）

工具调用可携带可选的idempotency_key。针对一次用户意图复用同一个稳定 key，可在网络重试时避免重复计费。其内部处理是：对模型选择器 + "\n" + idempotency_key做 SHA-256 得到idempotencyKeyHash；若已存在相同operation且哈希一致的作业，则直接返回已有作业而不重复提交（见 service.ts）。

运行时行为

官方文档把工具职责归纳为：

• 启动作业并返回 job ID；
• 轮询作业状态并把进度回报给模型；
• 作业完成时返回视频产物元数据；
• 用户取消请求时尝试取消或停止等待。

底层由MediaService实现一个进程内作业队列（见 service.ts），作业状态机在 contracts.ts 中定义：queued → running → succeeded / failed / canceled。

作业生命周期细节

• 提交即持久化：submit生成 UUID 作业写入MediaJobStore，随后入队并触发schedule。
• 并发与超时：schedule通过hasCapacity依据maxVideoConcurrency（默认 1）限制视频作业同时执行数；单个作业有jobTimeoutMs（默认 600000ms，即 10 分钟）超时保护，见 default-config.ts。超时会转换为timeout错误（retryable: true），见 service.ts。
• 重启恢复：recoverInterruptedJobs会在启用后把仍处于queued/running的历史作业分类处理：provider-API 提交且已有远端remoteRequestId的视频作业会尝试通过resumeVideo恢复远端查询，其余则标记为interrupted（不自动重提交），见 service.ts。
• 取消路径：cancelJob将未开始的作业从队列移除、中止在跑作业并标记canceled；取消语义与前端取消、AbortSignal贯通。
• 结果轮询：GatewayMediaExecutor.resumeVideo每 2 秒轮询一次videos/{id}，直到done/completed/succeeded拿到产物 URL，或failed/expired/canceled抛出带retryable标记的媒体错误（executors.ts）。

另外需要明确：请求超时与客户端取消依然生效；而并发数、产物保留期、作业超时属于 CCR 内部安全策略，正常情况不需要在 Fusion UI 配置。官方文档 fusion-mcp-tool.md 给出了内部策略示例（对应mediaTools配置块，位于核心配置中）：

{ "mediaTools": { "enabled": true, "artifactTtlHours": 24, "jobTimeoutMs": 600000, "maxImageConcurrency": 2, "maxVideoConcurrency": 1, "allowedInputRoots": [] } }

配置加载时还有范围约束：artifactTtlHours夹紧到 1–720，jobTimeoutMs夹紧到 30000–3600000，maxImageConcurrency1–8，maxVideoConcurrency1–4（见 config.ts）。

生成的运行时工具

保存 Fusion 模型时 CCR 会生成 profile 专属的运行时工具名，避免跨 profile 绑定冲突（见 fusion-mcp-tool.md 的 Runtime tools 小节）。视频相关工具名以常量形式定义在 contracts/app.ts：启动工具前缀video_generate、查状态前缀media_job_get、取消前缀media_job_cancel。第一代 Grok 专属工具名（grok_media_video_start、grok_media_job_get、grok_media_job_cancel等，contracts/app.ts）仍保留，仅用于把旧配置自动迁移进通用媒体工具（见 tools.ts 的 legacy 迁移逻辑）。

产物（Artifacts）

生成的视频存放在 CCR 的私有数据目录。具体路径为path.join(CONFIGDIR, "grok-media")（见 service.ts），作业与产物分别由MediaJobStore与MediaArtifactStore管理。作业结果会返回：

• 本地文件路径（localPath）
• MIME 类型
• 文件大小
• SHA-256
• 带过期时间的 URL

对应公开产物契约PublicMediaArtifact定义在 contracts.ts。注意：accessToken等敏感字段不会随作业结果下发；对外只暴露带 token 的临时 URL，格式为{endpoint}/__ccr/media/artifacts/{id}?token={accessToken}，令牌用常量时间比较校验（service.ts）。

两点工程细节值得说明：

1. HTTP Range 支持：视频 URL 支持 Range，播放器可按需加载内容。视频文件以本地产物形式落地并托管于 CCR 内部端点，天然可 Range。
2. 产物清理策略：产物 URL 按artifactTtlHours（默认 24 小时）过期；作业记录保留 30 天（jobRetentionDays），每次清理会同时删除对应产物文件（见 service.ts）。

此外，产物下载侧还有 SSRF 防护：下载远端产物 URL 前会解析域名做私网/回环地址判定，仅允许指向 provider 自身源站或公网地址（executors.ts），下载体量上限 250 MB 且最多跟随 5 次重定向（executors.ts）。

本地图片输入的安全校验

对图生视频/参考图生视频的本机图片，CCR 会执行三道校验（service.ts）：

• 规范化真实路径并确认落在allowed input roots之内；
• 必须是非空常规文件且 ≤ 25 MB（maxInputBytes）；
• 通过文件签名检测确认为图片格式。

默认允许的读取根包括：当前工作目录（若它不是 home 目录及其祖先）、系统临时目录与 CCR 配置目录（service.ts）。如需更宽泛的读取范围，须显式配置mediaTools.allowedInputRoots——这也正是 Troubleshooting 中"检查图生视频/参考图生视频输入是否位于允许读取根内"的出处。

Troubleshooting：视频生成失败排查清单

官方文档给出了如下排查顺序，逐条对应源码可实现定位：

1. Provider 模型是否声明或真实支持视频生成。providerSupportsMediaKind会检查 provider 是否具备xai_video_generations/openai_video_generationscapability，或是否包含grok-imagine-video之类按命名归类的视频模型（见 models.ts）；resolveProviderMediaTarget还会校验模型种类与 provider 声明（service.ts）。若 provider 未配置媒体 API baseURL 或无可用凭证，同样会在此处报错。
2. Fusion 工具是否绑定到正确的视频模型。核对videoModelSelector绑定的Provider/model是否真实存在于该 provider，以及工具名是否在保存后生成（可查看请求日志确认运行时工具是否被模型调用）。
3. 配置的视频重试次数与备用视频模型。留意回退模型必须与主模型同协议；videoRetryCount会被收敛到共享上限内，重试仅在错误retryable时发生。
4. 请求日志中的 ai-gateway 状态码与错误。provider 返回的错误经sanitizeRemoteError脱敏（抹掉 Bearer 凭证与超长 token），并会透传网关内多 provider 尝试的失败摘要（executors.ts），据此可区分是4xx配置错误还是可重试的5xx/429/408。
5. 图生视频/参考图生视频的输入是否位于允许读取根内。否则会抛出Input image is outside allowed roots，需显式扩展mediaTools.allowedInputRoots。

使用前提与限制小结

• 需要先在Providers页配置支持视频生成协议的 provider；直接对接 ai-gateway 的 MCP 端点为http://127.0.0.1:3456/__ccr/media/mcp（Bearer CCR API Key），Fusion 内部则通过 Core 配置生成的 stdio MCP 代理注册这些内置工具（详见 fusion-mcp-tool.md）。
• 视频作业的并发（默认 1）、超时（默认 10 分钟）与产物保留（默认 24 小时 URL 过期、30 天作业记录）是 CCR 内部安全策略，常规使用无需在 Fusion UI 调整。
• 若在接入自建 provider，请先用一个测试 Fusion profile 验证目标端点确实实现了videos/generations与videos/{id}，再投入生产路由使用。

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router