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

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-routerclaude-code-routerCCR的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。功能定位把文本模型变成能生成视频的 AgentVideo 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 的步骤操作在Providers页配置一个支持视频生成协议的 provider 与模型。新建或编辑一个 Fusion 模型。在Tools下添加Video generation。选择一个视频模型格式形如Provider/model。保存 Fusion 模型并把它作为 Agent 模型或路由目标使用。从源码看这里的模型选择器model selector即Provider/model形式的绑定字符串。内部绑定配置由VirtualModelFusionMediaConfig承载定义在 contracts/app.ts其中与视频相关的字段包括字段含义videoModelSelector主视频模型格式Provider/modelvideoFallbackModelSelectors备用视频模型列表videoRetryCount视频作业的专属重试次数videoStartToolName启动视频作业的运行时工具名jobGetToolName查询作业状态的运行时工具名jobCancelToolName取消作业的运行时工具名绑定编译逻辑位于 tools.tsFusion profile 携带metadata.fusionMedia配置时会被readFusionMediaConfig解析再为每个可用的视频工具名生成一条MediaToolBindingvideo-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-qualityisImportedGrokAgentProvider会识别本地 Agent 导入产生的 providerapikey为ccr-local-agent-login且 baseURL 属于cli-chat-proxy.grok.com或名字含 grok见 models.ts。这正是文档中所说的重试后仍失败则走备用模型、但绝不启动 Grok CLI的实现前提。视频模型的独立重试与回退视频生成拥有独立的重试次数与备用视频模型。当被选中的视频模型因可重试的媒体 provider 错误失败时CCR 先对该模型本身重试再依次尝试配置的备用视频模型基础文本模型保持不变。从实现看尝试序列由mediaModelAttempts构造[主模型 × (retryCount1), 备用模型1 × (retryCount1), …]见 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文档列出了两张核心请求请求用途videos/generations提交文生视频、图生视频或参考图生视频作业videos/{id}查询视频作业状态与结果其中第一条对应videoStart提交视频作业第二条对应轮询阶段的GET videos/{id}。请求体由GatewayMediaExecutor组装见 executors.tsmodel目标视频模型prompt视频生成提示词duration时长秒resolution/aspect_ratio分辨率与画面比例传入 1 张图片时为image图生视频传入多张图片时为reference_images参考图生视频图片以data:URI 形式内联。视频作业的参数约束由于不同协议对时长/比例/分辨率的要求不同参数 schema 由videoGenerationConstraints(protocol)动态生成见 tools.ts 与 models.tsopenai_video_generations协议aspect_ratio仅允许16:9、9:16duration仅允许4 / 8 / 12秒resolution仅允许720paspect_ratio、duration、resolution三者必填。xai_video_generations协议Grok 路径默认aspect_ratio允许1:1、16:9、9:16、4:3、3:4、3:2、2:3duration支持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–720jobTimeoutMs夹紧到 30000–3600000maxImageConcurrency1–8maxVideoConcurrency1–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管理。作业结果会返回本地文件路径localPathMIME 类型文件大小SHA-256带过期时间的 URL对应公开产物契约PublicMediaArtifact定义在 contracts.ts。注意accessToken等敏感字段不会随作业结果下发对外只暴露带 token 的临时 URL格式为{endpoint}/__ccr/media/artifacts/{id}?token{accessToken}令牌用常量时间比较校验service.ts。两点工程细节值得说明HTTP Range 支持视频 URL 支持 Range播放器可按需加载内容。视频文件以本地产物形式落地并托管于 CCR 内部端点天然可 Range。产物清理策略产物 URL 按artifactTtlHours默认 24 小时过期作业记录保留 30 天jobRetentionDays每次清理会同时删除对应产物文件见 service.ts。此外产物下载侧还有 SSRF 防护下载远端产物 URL 前会解析域名做私网/回环地址判定仅允许指向 provider 自身源站或公网地址executors.ts下载体量上限 250 MB 且最多跟随 5 次重定向executors.ts。本地图片输入的安全校验对图生视频/参考图生视频的本机图片CCR 会执行三道校验service.ts规范化真实路径并确认落在allowed input roots之内必须是非空常规文件且 ≤ 25 MBmaxInputBytes通过文件签名检测确认为图片格式。默认允许的读取根包括当前工作目录若它不是 home 目录及其祖先、系统临时目录与 CCR 配置目录service.ts。如需更宽泛的读取范围须显式配置mediaTools.allowedInputRoots——这也正是 Troubleshooting 中检查图生视频/参考图生视频输入是否位于允许读取根内的出处。Troubleshooting视频生成失败排查清单官方文档给出了如下排查顺序逐条对应源码可实现定位Provider 模型是否声明或真实支持视频生成。providerSupportsMediaKind会检查 provider 是否具备xai_video_generations/openai_video_generationscapability或是否包含grok-imagine-video之类按命名归类的视频模型见 models.tsresolveProviderMediaTarget还会校验模型种类与 provider 声明service.ts。若 provider 未配置媒体 API baseURL 或无可用凭证同样会在此处报错。Fusion 工具是否绑定到正确的视频模型。核对videoModelSelector绑定的Provider/model是否真实存在于该 provider以及工具名是否在保存后生成可查看请求日志确认运行时工具是否被模型调用。配置的视频重试次数与备用视频模型。留意回退模型必须与主模型同协议videoRetryCount会被收敛到共享上限内重试仅在错误retryable时发生。请求日志中的 ai-gateway 状态码与错误。provider 返回的错误经sanitizeRemoteError脱敏抹掉 Bearer 凭证与超长 token并会透传网关内多 provider 尝试的失败摘要executors.ts据此可区分是4xx配置错误还是可重试的5xx/429/408。图生视频/参考图生视频的输入是否位于允许读取根内。否则会抛出Input image is outside allowed roots需显式扩展mediaTools.allowedInputRoots。使用前提与限制小结需要先在Providers页配置支持视频生成协议的 provider直接对接 ai-gateway 的 MCP 端点为http://127.0.0.1:3456/__ccr/media/mcpBearer CCR API KeyFusion 内部则通过 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考