OpenClaw Vydra Provider 插件实战指南图像、视频与语音生成的一体化接入【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw导读本文基于 OpenClaw 仓库中官方 Vydra Provider 插件extensions/vydra的源码与文档系统讲解如何通过openclaw plugins install安装插件、配置VYDRA_API_KEY鉴权并深度剖析其图像生成、视频生成与语音合成三大 Provider 的实现原理——包括异步任务轮询、结果资产下载、SSRF 防护与超时控制等底层机制。读完本文你将掌握在 OpenClaw 网关中一键接入 Vydra 媒体生成能力并理解插件与 Plugin SDK 之间的契约调用关系。插件概览OpenClaw 官方 Vydra 媒体生成 ProviderVydra Provider 是 OpenClaw 的官方插件为图像、视频与语音三类媒体生成能力提供统一接入。插件以openclaw/vydra-provider为名发布插件元数据中声明了分类models、voice、media且enabledByDefault: true、onStartup: false即默认启用但不在启动时激活见 openclaw.plugin.json。从插件入口 index.ts 可以看到插件在注册阶段一次性挂载了三条能力api.registerSpeechProvider(buildVydraSpeechProvider())— 语音合成api.registerImageGenerationProvider(buildVydraImageGenerationProvider())— 图像生成api.registerVideoGenerationProvider(buildVydraVideoGenerationProvider())— 视频生成三条能力统一以vydra为 Provider ID并共同依赖VYDRA_API_KEY这一个环境变量完成鉴权。openclaw.plugin.json中的contracts字段也与此对应声明了speechProviders、imageGenerationProviders、videoGenerationProviders三个契约各含vydra这是网关侧发现与路由能力的基础。安装与鉴权配置安装插件官方 READMEextensions/vydra/README.md给出了两条命令完成安装与生效openclaw plugins install openclaw/vydra-provider openclaw gateway restartpackage.json中的openclaw.install元数据显示该插件同时发布到 ClawHub 与 npmclawhubSpec与npmSpec均为openclaw/vydra-provider默认安装渠道为 npm并要求宿主版本2026.7.2Plugin API 兼容版本2026.9.3。安装后必须重启网关新的 Provider 才会被加载。配置 API Key插件通过环境变量VYDRA_API_KEY鉴权。入口注册的 auth 方法index.ts提供了多种配置途径环境变量VYDRA_API_KEYCLI 参数--vydra-api-key配置文件vydraApiKey选项交互式引导openclaw初始化向导中的vydra-api-key选项属于vydra分组引导范围覆盖image-generation值得说明的是插件在完成 API Key 配置后还会自动执行一次开机自检式的配置注入onboard.ts若agents.defaults.mediaModels.image尚未设置则自动将其主模型指向vydra/grok-imagine让图像生成能力在配置完成后立即可用无需手动指定模型。自定义 Base URL 与语音参数除 API Key 外插件还支持若干可选配置项。语音 Provider 的配置归一化逻辑speech-provider.ts逐级回退读取配置优先级从高到低为会话/Provider 级配置 → 环境变量 → 内置默认值配置项环境变量默认值说明baseUrlVYDRA_BASE_URLhttps://www.vydra.ai/api/v1API 端点地址可指向自建代理modelVYDRA_TTS_MODELelevenlabs/tts语音合成模型voiceIdVYDRA_TTS_VOICE_ID21m00Tcm4TlvDq8ikWAM默认音色对应 RachelBase URL 的归一化逻辑在 defaults.ts 中实现传入vydra.ai域名会统一补全为www.vydra.ai路径为空时自动补/api/v1并去除末尾斜杠——这保证了无论用户配置时是否写全路径请求端点都保持一致。图像与视频生成的 Base URL 同样支持通过models.providers.vydra.baseUrl配置覆盖见 shared.ts并且models.providers.vydra.request配置会被传入sanitizeConfiguredModelProviderRequest做净化处理再与默认请求头合并。图像生成文生图与能力边界图像生成 Provider 实现在 image-generation-provider.ts默认模型为grok-imagine。其能力声明非常明确generate单次最多 1 张不支持尺寸、宽高比、分辨率参数edit关闭enabled: false即不支持图生图编辑传入输入图片会直接抛错currently supports text-to-image onlycount 1会抛错at most one image per request。请求体构造为{ prompt: 你的提示词, model: text-to-image }即插件目前只开放 Vydra 的 text-to-image 能力调用方Agent 或上层工具只需提供prompt。返回结果中除生成的图片资产外还会携带jobId、imageUrl与status元数据便于上层追踪任务状态。视频生成veo3 与 kling 双模型视频生成 Provider 实现在 video-generation-provider.ts默认模型为veo3同时支持kling模型能力声明为generate单次最多 1 个视频imageToVideo开启最多 1 张输入图、1 个输出视频videoToVideo关闭传入参考视频会抛错。两个模型的行为差异体现在请求体的构造逻辑resolveVydraVideoRequestBody中veo3纯文生视频仅发送prompt若误传输入图片会抛错提示该模型不支持图片参考输入kling图生视频必须提供远程图片 URLinputImages[0].url否则抛错 requires a remote image URL reference。请求体会同时写入image_url与video_url两个字段——源码注释说明这是因为 Vydra 的 kling 路由对字段要求并不一致插件做兼容性双写以规避问题。视频任务的默认超时被放宽到120_000msDEFAULT_VYDRA_VIDEO_TIMEOUT_MS以适配视频生成耗时更长的现实。语音合成TTS 与结果下载语音 Provider 实现在 speech-provider.ts默认模型elevenlabs/tts、默认音色 Rachel。其synthesize流程完整展示了 HTTP 请求、鉴权与资产下载的串联解析 Provider 配置与覆盖项支持按次调用传入model/voiceId覆盖通过resolveSpeechProviderApiKey解析 API Key配置值优先于环境变量缺失时抛 Vydra API key missing构造请求POST {baseUrl}/models/{model}请求体为{ text: ..., voice_id: ... }携带Authorization: Bearer key与Content-Type: application/json从响应中提取音频 URL若缺失则抛 response missing audio URL下载音频资产输出格式根据 MIME 判定为wav或mp3并返回audioBuffer、fileExtension等字段。底层原理任务轮询、结果提取与安全下载图像与视频生成共用的核心实现位于 shared.ts其流程是一个典型的提交—轮询—下载三步式异步任务模型1. 提交任务runVydraGeneration首先解析鉴权上下文resolveVydraRequestContext再向POST {baseUrl}/models/{model}提交请求体。请求头默认注入 Bearer Token且允许传入自定义request配置经净化后合入。2. 轮询任务状态提交响应若未直接携带完成状态或结果 URL插件会提取jobId兼容jobId/id两种字段然后轮询GET {baseUrl}/jobs/{jobId}。轮询参数轮询间隔POLL_INTERVAL_MS 2500ms最大尝试次数MAX_POLL_ATTEMPTS 120判完成条件状态为completed或已能从响应中提取到结果 URL判失败条件状态为failed/error/cancelled并从error.message、error.detail或顶层message中提取失败原因。轮询过程受统一的操作截止时间ProviderOperationDeadline约束超时会抛出带标签的Vydra job {jobId} did not finish in time错误。3. 结果 URL 提取Vydra 不同接口的响应结构并不统一因此插件实现了健壮的递归提取器extractVydraResultUrlsshared.ts按媒体类型匹配主键音频查audioUrl/audioUrls图像查imageUrl/imageUrls视频查videoUrl/videoUrls统一兜底键resultUrl(s)、outputUrl(s)、url(s)递归下钻键output(s)、result(s)、data、asset(s)深度上限 5 层仅接受http://或https://开头的值。该函数同样服务于语音合成的音频 URL 提取是三个 Provider 共用的关键工具并有专门的单元测试覆盖见 shared.test.ts。4. 资产下载与安全防护downloadVydraAsset负责把最终结果下载为本地资产安全细节值得关注凭据不跨域泄露仅当结果 URL 与 API 同源origin 一致时才附加 Vydra 的鉴权头与自定义头跨域 CDN 地址一律不带凭据shared.tsSSRF 防护默认不允许访问私网地址请求通过fetchWithTimeoutGuarded携带ssrfPolicy与dispatcherPolicy执行审计上下文标记为vydra-media-download大小限制按媒体类型调用resolveGeneratedMediaMaxBytes限制下载体积超限抛exceeds {maxBytes} bytes错误超时控制HTTP 默认超时120_000ms下载阶段按操作截止时间动态解析剩余额度防止整体任务被单个慢下载拖死MIME 兜底响应无Content-Type时按类型回退图片image/png、音频audio/mpeg、视频video/mp4文件扩展名由 MIME 推导推导失败再按类型兜底png/mp3/mp4。测试验证插件测试集中在 shared.test.ts 与各 Provider 测试image-generation-provider.test.ts、video-generation-provider.test.ts、speech-provider.test.ts另有连接真实服务的 vydra.live.test.ts。shared 测试使用本地 HTTP 服务器模拟滴流式chunked drip慢速响应验证下载在墙钟截止时间内被强制终止——这直接印证了插件对慢服务与挂起连接的兜底能力。典型接入流程总结将以上内容串成一次完整的实战流程安装openclaw plugins install openclaw/vydra-provider随后openclaw gateway restart配置设置VYDRA_API_KEY或使用--vydra-api-key/ 引导向导可选设置VYDRA_BASE_URL、VYDRA_TTS_MODEL、VYDRA_TTS_VOICE_ID使用配置 API Key 后插件会自动将默认图像模型设为vydra/grok-imagine此后即可通过 OpenClaw 的媒体生成能力发起图像grok-imagine、视频veo3/kling与语音elevenlabs/tts音色 Rachel生成请求观测每次生成返回的jobId与status元数据可用于任务追踪与日志审计。如果你需要为自建网关环境替换端点只需在配置中指定baseUrl插件会在归一化后直接使用同时请留意当前能力边界——图像仅支持文生图且单次 1 张视频不支持 video-to-videokling 图生视频必须提供可访问的远程图片 URL。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenClaw Vydra Provider 插件实战指南：图像、视频与语音生成的一体化接入
OpenClaw Vydra Provider 插件实战指南图像、视频与语音生成的一体化接入【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw导读本文基于 OpenClaw 仓库中官方 Vydra Provider 插件extensions/vydra的源码与文档系统讲解如何通过openclaw plugins install安装插件、配置VYDRA_API_KEY鉴权并深度剖析其图像生成、视频生成与语音合成三大 Provider 的实现原理——包括异步任务轮询、结果资产下载、SSRF 防护与超时控制等底层机制。读完本文你将掌握在 OpenClaw 网关中一键接入 Vydra 媒体生成能力并理解插件与 Plugin SDK 之间的契约调用关系。插件概览OpenClaw 官方 Vydra 媒体生成 ProviderVydra Provider 是 OpenClaw 的官方插件为图像、视频与语音三类媒体生成能力提供统一接入。插件以openclaw/vydra-provider为名发布插件元数据中声明了分类models、voice、media且enabledByDefault: true、onStartup: false即默认启用但不在启动时激活见 openclaw.plugin.json。从插件入口 index.ts 可以看到插件在注册阶段一次性挂载了三条能力api.registerSpeechProvider(buildVydraSpeechProvider())— 语音合成api.registerImageGenerationProvider(buildVydraImageGenerationProvider())— 图像生成api.registerVideoGenerationProvider(buildVydraVideoGenerationProvider())— 视频生成三条能力统一以vydra为 Provider ID并共同依赖VYDRA_API_KEY这一个环境变量完成鉴权。openclaw.plugin.json中的contracts字段也与此对应声明了speechProviders、imageGenerationProviders、videoGenerationProviders三个契约各含vydra这是网关侧发现与路由能力的基础。安装与鉴权配置安装插件官方 READMEextensions/vydra/README.md给出了两条命令完成安装与生效openclaw plugins install openclaw/vydra-provider openclaw gateway restartpackage.json中的openclaw.install元数据显示该插件同时发布到 ClawHub 与 npmclawhubSpec与npmSpec均为openclaw/vydra-provider默认安装渠道为 npm并要求宿主版本2026.7.2Plugin API 兼容版本2026.9.3。安装后必须重启网关新的 Provider 才会被加载。配置 API Key插件通过环境变量VYDRA_API_KEY鉴权。入口注册的 auth 方法index.ts提供了多种配置途径环境变量VYDRA_API_KEYCLI 参数--vydra-api-key配置文件vydraApiKey选项交互式引导openclaw初始化向导中的vydra-api-key选项属于vydra分组引导范围覆盖image-generation值得说明的是插件在完成 API Key 配置后还会自动执行一次开机自检式的配置注入onboard.ts若agents.defaults.mediaModels.image尚未设置则自动将其主模型指向vydra/grok-imagine让图像生成能力在配置完成后立即可用无需手动指定模型。自定义 Base URL 与语音参数除 API Key 外插件还支持若干可选配置项。语音 Provider 的配置归一化逻辑speech-provider.ts逐级回退读取配置优先级从高到低为会话/Provider 级配置 → 环境变量 → 内置默认值配置项环境变量默认值说明baseUrlVYDRA_BASE_URLhttps://www.vydra.ai/api/v1API 端点地址可指向自建代理modelVYDRA_TTS_MODELelevenlabs/tts语音合成模型voiceIdVYDRA_TTS_VOICE_ID21m00Tcm4TlvDq8ikWAM默认音色对应 RachelBase URL 的归一化逻辑在 defaults.ts 中实现传入vydra.ai域名会统一补全为www.vydra.ai路径为空时自动补/api/v1并去除末尾斜杠——这保证了无论用户配置时是否写全路径请求端点都保持一致。图像与视频生成的 Base URL 同样支持通过models.providers.vydra.baseUrl配置覆盖见 shared.ts并且models.providers.vydra.request配置会被传入sanitizeConfiguredModelProviderRequest做净化处理再与默认请求头合并。图像生成文生图与能力边界图像生成 Provider 实现在 image-generation-provider.ts默认模型为grok-imagine。其能力声明非常明确generate单次最多 1 张不支持尺寸、宽高比、分辨率参数edit关闭enabled: false即不支持图生图编辑传入输入图片会直接抛错currently supports text-to-image onlycount 1会抛错at most one image per request。请求体构造为{ prompt: 你的提示词, model: text-to-image }即插件目前只开放 Vydra 的 text-to-image 能力调用方Agent 或上层工具只需提供prompt。返回结果中除生成的图片资产外还会携带jobId、imageUrl与status元数据便于上层追踪任务状态。视频生成veo3 与 kling 双模型视频生成 Provider 实现在 video-generation-provider.ts默认模型为veo3同时支持kling模型能力声明为generate单次最多 1 个视频imageToVideo开启最多 1 张输入图、1 个输出视频videoToVideo关闭传入参考视频会抛错。两个模型的行为差异体现在请求体的构造逻辑resolveVydraVideoRequestBody中veo3纯文生视频仅发送prompt若误传输入图片会抛错提示该模型不支持图片参考输入kling图生视频必须提供远程图片 URLinputImages[0].url否则抛错 requires a remote image URL reference。请求体会同时写入image_url与video_url两个字段——源码注释说明这是因为 Vydra 的 kling 路由对字段要求并不一致插件做兼容性双写以规避问题。视频任务的默认超时被放宽到120_000msDEFAULT_VYDRA_VIDEO_TIMEOUT_MS以适配视频生成耗时更长的现实。语音合成TTS 与结果下载语音 Provider 实现在 speech-provider.ts默认模型elevenlabs/tts、默认音色 Rachel。其synthesize流程完整展示了 HTTP 请求、鉴权与资产下载的串联解析 Provider 配置与覆盖项支持按次调用传入model/voiceId覆盖通过resolveSpeechProviderApiKey解析 API Key配置值优先于环境变量缺失时抛 Vydra API key missing构造请求POST {baseUrl}/models/{model}请求体为{ text: ..., voice_id: ... }携带Authorization: Bearer key与Content-Type: application/json从响应中提取音频 URL若缺失则抛 response missing audio URL下载音频资产输出格式根据 MIME 判定为wav或mp3并返回audioBuffer、fileExtension等字段。底层原理任务轮询、结果提取与安全下载图像与视频生成共用的核心实现位于 shared.ts其流程是一个典型的提交—轮询—下载三步式异步任务模型1. 提交任务runVydraGeneration首先解析鉴权上下文resolveVydraRequestContext再向POST {baseUrl}/models/{model}提交请求体。请求头默认注入 Bearer Token且允许传入自定义request配置经净化后合入。2. 轮询任务状态提交响应若未直接携带完成状态或结果 URL插件会提取jobId兼容jobId/id两种字段然后轮询GET {baseUrl}/jobs/{jobId}。轮询参数轮询间隔POLL_INTERVAL_MS 2500ms最大尝试次数MAX_POLL_ATTEMPTS 120判完成条件状态为completed或已能从响应中提取到结果 URL判失败条件状态为failed/error/cancelled并从error.message、error.detail或顶层message中提取失败原因。轮询过程受统一的操作截止时间ProviderOperationDeadline约束超时会抛出带标签的Vydra job {jobId} did not finish in time错误。3. 结果 URL 提取Vydra 不同接口的响应结构并不统一因此插件实现了健壮的递归提取器extractVydraResultUrlsshared.ts按媒体类型匹配主键音频查audioUrl/audioUrls图像查imageUrl/imageUrls视频查videoUrl/videoUrls统一兜底键resultUrl(s)、outputUrl(s)、url(s)递归下钻键output(s)、result(s)、data、asset(s)深度上限 5 层仅接受http://或https://开头的值。该函数同样服务于语音合成的音频 URL 提取是三个 Provider 共用的关键工具并有专门的单元测试覆盖见 shared.test.ts。4. 资产下载与安全防护downloadVydraAsset负责把最终结果下载为本地资产安全细节值得关注凭据不跨域泄露仅当结果 URL 与 API 同源origin 一致时才附加 Vydra 的鉴权头与自定义头跨域 CDN 地址一律不带凭据shared.tsSSRF 防护默认不允许访问私网地址请求通过fetchWithTimeoutGuarded携带ssrfPolicy与dispatcherPolicy执行审计上下文标记为vydra-media-download大小限制按媒体类型调用resolveGeneratedMediaMaxBytes限制下载体积超限抛exceeds {maxBytes} bytes错误超时控制HTTP 默认超时120_000ms下载阶段按操作截止时间动态解析剩余额度防止整体任务被单个慢下载拖死MIME 兜底响应无Content-Type时按类型回退图片image/png、音频audio/mpeg、视频video/mp4文件扩展名由 MIME 推导推导失败再按类型兜底png/mp3/mp4。测试验证插件测试集中在 shared.test.ts 与各 Provider 测试image-generation-provider.test.ts、video-generation-provider.test.ts、speech-provider.test.ts另有连接真实服务的 vydra.live.test.ts。shared 测试使用本地 HTTP 服务器模拟滴流式chunked drip慢速响应验证下载在墙钟截止时间内被强制终止——这直接印证了插件对慢服务与挂起连接的兜底能力。典型接入流程总结将以上内容串成一次完整的实战流程安装openclaw plugins install openclaw/vydra-provider随后openclaw gateway restart配置设置VYDRA_API_KEY或使用--vydra-api-key/ 引导向导可选设置VYDRA_BASE_URL、VYDRA_TTS_MODEL、VYDRA_TTS_VOICE_ID使用配置 API Key 后插件会自动将默认图像模型设为vydra/grok-imagine此后即可通过 OpenClaw 的媒体生成能力发起图像grok-imagine、视频veo3/kling与语音elevenlabs/tts音色 Rachel生成请求观测每次生成返回的jobId与status元数据可用于任务追踪与日志审计。如果你需要为自建网关环境替换端点只需在配置中指定baseUrl插件会在归一化后直接使用同时请留意当前能力边界——图像仅支持文生图且单次 1 张视频不支持 video-to-videokling 图生视频必须提供可访问的远程图片 URL。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考