diff --git a/docs/zh-CN/plugins/sdk-provider-plugins.md b/docs/zh-CN/plugins/sdk-provider-plugins.md index 7a134c15f..0ee86e4ec 100644 --- a/docs/zh-CN/plugins/sdk-provider-plugins.md +++ b/docs/zh-CN/plugins/sdk-provider-plugins.md @@ -1,37 +1,35 @@ --- read_when: - 你正在构建一个新的模型提供商插件 - - 你想为 OpenClaw 添加一个兼容 OpenAI 的代理或自定义 LLM - - 你需要了解提供商认证、目录和运行时 hooks + - 你想向 OpenClaw 添加一个兼容 OpenAI 的代理或自定义 LLM + - 你需要理解提供商凭证、目录和运行时 hooks sidebarTitle: Provider Plugins -summary: 为 OpenClaw 构建模型提供商插件的分步指南 +summary: 构建 OpenClaw 模型提供商插件的分步指南 title: 构建提供商插件 x-i18n: - generated_at: "2026-04-05T18:15:33Z" + generated_at: "2026-04-06T12:28:45Z" model: gpt-5.4 provider: openai - source_hash: 69500f46aa2cfdfe16e85b0ed9ee3c0032074be46f2d9c9d2940d18ae1095f47 + source_hash: 21c888a988f6128f2c77b73ee4962ae7ad7b8a6c1b7d302610788c81ad25b0db source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # 构建提供商插件 -本指南将带你构建一个向 OpenClaw 添加模型提供商 -（LLM）的提供商插件。完成后，你将拥有一个带有模型目录、 -API 密钥认证和动态模型解析能力的提供商。 +本指南将带你逐步构建一个提供商插件，为 OpenClaw 添加一个模型提供商 +（LLM）。完成后，你将拥有一个带有模型目录、API 密钥凭证和动态模型解析的提供商。 - 如果你之前没有构建过任何 OpenClaw 插件，请先阅读 - [入门指南](/zh-CN/plugins/building-plugins)，了解基本包 - 结构和清单设置。 + 如果你之前从未构建过任何 OpenClaw 插件，请先阅读 + [入门指南](/zh-CN/plugins/building-plugins)，了解基础的软件包结构和清单设置。 ## 演练 - + ```json package.json { @@ -57,7 +55,7 @@ API 密钥认证和动态模型解析能力的提供商。 { "id": "acme-ai", "name": "Acme AI", - "description": "Acme AI model provider", + "description": "Acme AI 模型提供商", "providers": ["acme-ai"], "modelSupport": { "modelPrefixes": ["acme-"] @@ -70,12 +68,12 @@ API 密钥认证和动态模型解析能力的提供商。 "provider": "acme-ai", "method": "api-key", "choiceId": "acme-ai-api-key", - "choiceLabel": "Acme AI API key", + "choiceLabel": "Acme AI API 密钥", "groupId": "acme-ai", "groupLabel": "Acme AI", "cliFlag": "--acme-ai-api-key", "cliOption": "--acme-ai-api-key ", - "cliDescription": "Acme AI API key" + "cliDescription": "Acme AI API 密钥" } ], "configSchema": { @@ -86,10 +84,9 @@ API 密钥认证和动态模型解析能力的提供商。 ``` - 清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测 - 凭证。`modelSupport` 是可选的， - 它让 OpenClaw 可以在运行时 hooks 存在之前，根据简写模型 ID - （如 `acme-large`）自动加载你的提供商插件。如果你在 + 清单会声明 `providerAuthEnvVars`，这样 OpenClaw 就能在不加载你的插件运行时的情况下检测 + 凭证。`modelSupport` 是可选的，它允许 OpenClaw 根据简写模型 id + （例如 `acme-large`）自动加载你的提供商插件，此时甚至还没有运行时 hooks。如果你在 ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段 是必需的。 @@ -105,7 +102,7 @@ API 密钥认证和动态模型解析能力的提供商。 export default definePluginEntry({ id: "acme-ai", name: "Acme AI", - description: "Acme AI model provider", + description: "Acme AI 模型提供商", register(api) { api.registerProvider({ id: "acme-ai", @@ -117,12 +114,12 @@ API 密钥认证和动态模型解析能力的提供商。 createProviderApiKeyAuthMethod({ providerId: "acme-ai", methodId: "api-key", - label: "Acme AI API key", - hint: "API key from your Acme AI dashboard", + label: "Acme AI API 密钥", + hint: "来自你的 Acme AI 控制台的 API 密钥", optionKey: "acmeAiApiKey", flagName: "--acme-ai-api-key", envVar: "ACME_AI_API_KEY", - promptMessage: "Enter your Acme AI API key", + promptMessage: "输入你的 Acme AI API 密钥", defaultModel: "acme-ai/acme-large", }), ], @@ -167,12 +164,12 @@ API 密钥认证和动态模型解析能力的提供商。 }); ``` - 这就是一个可工作的提供商。用户现在可以 + 这就是一个可工作的提供商。现在用户可以运行 `openclaw onboard --acme-ai-api-key `，并选择 `acme-ai/acme-large` 作为他们的模型。 - 对于仅注册一个文本提供商、使用 API 密钥 - 认证并带有单个基于目录的运行时的内置提供商，优先使用更窄的 + 对于仅注册一个文本提供商、使用 API 密钥凭证，并且只有一个基于目录的运行时的内置提供商， + 优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数： ```typescript @@ -181,19 +178,19 @@ API 密钥认证和动态模型解析能力的提供商。 export default defineSingleProviderPluginEntry({ id: "acme-ai", name: "Acme AI", - description: "Acme AI model provider", + description: "Acme AI 模型提供商", provider: { label: "Acme AI", docsPath: "/providers/acme-ai", auth: [ { methodId: "api-key", - label: "Acme AI API key", - hint: "API key from your Acme AI dashboard", + label: "Acme AI API 密钥", + hint: "来自你的 Acme AI 控制台的 API 密钥", optionKey: "acmeAiApiKey", flagName: "--acme-ai-api-key", envVar: "ACME_AI_API_KEY", - promptMessage: "Enter your Acme AI API key", + promptMessage: "输入你的 Acme AI API 密钥", defaultModel: "acme-ai/acme-large", }, ], @@ -208,20 +205,19 @@ API 密钥认证和动态模型解析能力的提供商。 }); ``` - 如果你的认证流程在新手引导期间还需要修补 `models.providers.*`、别名以及 - 智能体默认模型，请使用 - `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数包括 + 如果你的凭证流程在新手引导期间还需要修补 `models.providers.*`、别名以及 + 智能体默认模型，请使用来自 + `openclaw/plugin-sdk/provider-onboard` 的预设辅助函数。最窄的辅助函数是 `createDefaultModelPresetAppliers(...)`、 `createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。 - 当某个提供商的原生端点在常规 - `openai-completions` 传输上支持分块流式传输使用量块时，优先使用 - `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数， - 而不是硬编码提供商 ID 检查。 + 当某个提供商的原生端点在常规 `openai-completions` 传输协议上支持流式使用量块时， + 优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数， + 而不是硬编码提供商 id 检查。 `supportsNativeStreamingUsageCompat(...)` 和 `applyProviderNativeStreamingUsageCompat(...)` 会根据端点能力映射检测支持情况， - 因此即使插件使用的是自定义 provider ID，原生 Moonshot/DashScope 风格端点 + 因此像原生 Moonshot/DashScope 这类风格的端点，即使插件使用的是自定义提供商 id， 也仍然可以选择启用。 @@ -232,7 +228,7 @@ API 密钥认证和动态模型解析能力的提供商。 ```typescript api.registerProvider({ - // ... 上面的 id、label、auth、catalog + // ... 来自上面的 id、label、auth、catalog resolveDynamicModel: (ctx) => ({ id: ctx.modelId, @@ -249,17 +245,17 @@ API 密钥认证和动态模型解析能力的提供商。 }); ``` - 如果解析需要进行网络调用，请使用 `prepareDynamicModel` 进行异步 - 预热——完成后会再次运行 `resolveDynamicModel`。 + 如果解析过程需要网络调用，请使用 `prepareDynamicModel` 进行异步 + 预热——在其完成后，`resolveDynamicModel` 会再次运行。 - - 大多数提供商只需要 `catalog` + `resolveDynamicModel`。当你的提供商有需要时， + + 大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着你的提供商需求增加， 再逐步添加 hooks。 - 共享辅助构建器现在已经覆盖了最常见的 replay/tool-compat - 系列，因此插件通常不需要手动逐个接线每个 hook： + 共享辅助构建器现在已覆盖最常见的回放/工具兼容性 + 系列，因此插件通常不需要再手动逐一接线每个 hook： ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -279,15 +275,15 @@ API 密钥认证和动态模型解析能力的提供商。 }); ``` - 当前可用的 replay 系列： + 当前可用的回放系列： - | 系列 | 接入内容 | + | 系列 | 它会接入的内容 | | --- | --- | - | `openai-compatible` | 用于兼容 OpenAI 传输的共享 OpenAI 风格 replay 策略，包括 tool-call-id 清理、assistant-first 顺序修复，以及在传输需要时的通用 Gemini 轮次校验 | - | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知 replay 策略，因此只有当解析后的模型实际是 Claude ID 时，Anthropic-message 传输才会获得 Claude 特有的 thinking block 清理 | - | `google-gemini` | 原生 Gemini replay 策略，加上 bootstrap replay 清理和带标签的 reasoning-output 模式 | - | `passthrough-gemini` | 适用于通过兼容 OpenAI 的代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini replay 校验或 bootstrap 重写 | - | `hybrid-anthropic-openai` | 适用于在同一个插件中混合 Anthropic-message 和兼容 OpenAI 模型面板的提供商的混合策略；可选的仅限 Claude 的 thinking block 丢弃仍然只作用于 Anthropic 一侧 | + | `openai-compatible` | 用于兼容 OpenAI 的传输协议的共享 OpenAI 风格回放策略，包括 tool-call-id 清理、assistant-first 顺序修复，以及在传输协议需要时进行通用 Gemini 轮次校验 | + | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知回放策略，因此 Anthropic message 传输协议只有在解析出的模型确实是 Claude id 时，才会获得 Claude 专用的 thinking block 清理 | + | `google-gemini` | 原生 Gemini 回放策略，以及 bootstrap 回放清理和带标记的 reasoning-output 模式 | + | `passthrough-gemini` | 用于通过兼容 OpenAI 的代理传输协议运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini 回放校验或 bootstrap 重写 | + | `hybrid-anthropic-openai` | 用于在一个插件中混合 Anthropic message 和兼容 OpenAI 模型面的提供商的混合策略；可选的仅 Claude thinking block 丢弃仍限制在 Anthropic 一侧 | 真实的内置示例： @@ -297,17 +293,17 @@ API 密钥认证和动态模型解析能力的提供商。 - `minimax`：`hybrid-anthropic-openai` - `moonshot`、`ollama`、`xai` 和 `zai`：`openai-compatible` - 当前可用的 stream 系列： + 当前可用的流式系列： - | 系列 | 接入内容 | + | 系列 | 它会接入的内容 | | --- | --- | - | `google-thinking` | 共享流路径上的 Gemini thinking 负载规范化 | - | `kilocode-thinking` | 共享代理流路径上的 Kilo reasoning 包装器，其中 `kilo/auto` 和不支持代理 reasoning 的 ID 会跳过注入的 thinking | - | `moonshot-thinking` | 基于配置 + `/think` 级别的 Moonshot 二进制 native-thinking 负载映射 | - | `minimax-fast-mode` | 共享流路径上的 MiniMax fast-mode 模型重写 | - | `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归属头、`/fast`/`serviceTier`、文本详细度、原生 Codex web 搜索、reasoning-compat 负载塑形，以及 Responses 上下文管理 | - | `openrouter-thinking` | 用于代理路由的 OpenRouter reasoning 包装器，集中处理不支持模型/`auto` 跳过逻辑 | - | `tool-stream-default-on` | 为像 Z.AI 这类希望默认启用工具流式传输的提供商提供默认开启的 `tool_stream` 包装器，除非显式禁用 | + | `google-thinking` | 在共享流路径上进行 Gemini thinking 负载标准化 | + | `kilocode-thinking` | 在共享代理流路径上提供 Kilo reasoning 包装器，其中 `kilo/auto` 和不支持的代理 reasoning id 会跳过注入的 thinking | + | `moonshot-thinking` | 根据配置和 `/think` 级别，将 Moonshot 二进制 native-thinking 负载进行映射 | + | `minimax-fast-mode` | 在共享流路径上进行 MiniMax fast-mode 模型重写 | + | `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归属头、`/fast`/`serviceTier`、文本冗长度、原生 Codex web 搜索、reasoning 兼容性负载整形，以及 Responses 上下文管理 | + | `openrouter-thinking` | 用于代理路由的 OpenRouter reasoning 包装器，集中处理不支持模型和 `auto` 跳过 | + | `tool-stream-default-on` | 为像 Z.AI 这样希望默认启用工具流式传输、除非显式禁用的提供商提供默认开启的 `tool_stream` 包装器 | 真实的内置示例： @@ -319,24 +315,23 @@ API 密钥认证和动态模型解析能力的提供商。 - `openrouter`：`openrouter-thinking` - `zai`：`tool-stream-default-on` - `openclaw/plugin-sdk/provider-model-shared` 还导出了 replay-family - 枚举，以及构建这些系列所用的共享辅助函数。常见公开导出包括： + `openclaw/plugin-sdk/provider-model-shared` 还会导出 replay-family + 枚举以及这些系列所基于的共享辅助函数。常见的公共导出包括： - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` - - 共享 replay 构建器，例如 `buildOpenAICompatibleReplayPolicy(...)`、 + - 共享回放构建器，例如 `buildOpenAICompatibleReplayPolicy(...)`、 `buildAnthropicReplayPolicyForModel(...)`、 `buildGoogleGeminiReplayPolicy(...)` 和 `buildHybridAnthropicOrOpenAIReplayPolicy(...)` - - Gemini replay 辅助函数，例如 `sanitizeGoogleGeminiReplayHistory(...)` + - Gemini 回放辅助函数，例如 `sanitizeGoogleGeminiReplayHistory(...)` 和 `resolveTaggedReasoningOutputMode()` - 端点/模型辅助函数，例如 `resolveProviderEndpoint(...)`、 `normalizeProviderId(...)`、`normalizeGooglePreviewModelId(...)` 和 `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` 同时公开了 family builder - 以及这些 family 复用的公开包装器辅助函数。常见公开导出 - 包括： + `openclaw/plugin-sdk/provider-stream` 同时公开 family 构建器以及这些 family 复用的公共包装辅助函数。 + 常见的公共导出包括： - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` @@ -350,49 +345,46 @@ API 密钥认证和动态模型解析能力的提供商。 - 共享代理/提供商包装器，例如 `createOpenRouterWrapper(...)`、 `createToolStreamWrapper(...)` 和 `createMinimaxFastModeWrapper(...)` - 有些 stream 辅助函数会有意保持为提供商本地。当前的内置 - 示例：`@openclaw/anthropic-provider` 从其公共 `api.ts` / - `contract-api.ts` 接缝导出 + 某些流式辅助函数有意保持为提供商本地。当前内置 + 示例：`@openclaw/anthropic-provider` 导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 - `resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及 - 更底层的 Anthropic 包装器构建器。这些辅助函数仍然是 Anthropic 专用的，因为 - 它们还编码了 Claude OAuth beta 处理和 `context1m` 门控。 + `resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及来自其公共 `api.ts` / + `contract-api.ts` 接缝的更底层 Anthropic 包装器构建器。之所以这些辅助函数仍然保持为 Anthropic 专用， + 是因为它们还编码了 Claude OAuth beta 处理和 `context1m` 门控。 - 其他内置提供商在 - 行为无法在各 family 之间干净共享时，也会把特定传输的包装器保留在本地。当前示例：内置 - xAI 插件将原生 xAI Responses 塑形保留在它自己的 + 其他内置提供商也会在行为无法在 family 之间干净共享时，将传输协议专用包装器保留在本地。 + 当前示例：内置 xAI 插件将原生 xAI Responses 整形保留在它自己的 `wrapStreamFn` 中，包括 `/fast` 别名重写、默认 `tool_stream`、 - 不支持的 strict-tool 清理以及 xAI 特有的 reasoning-payload - 删除。 + 对不受支持 strict-tool 的清理，以及移除 xAI 专用的 reasoning 负载。 - `openclaw/plugin-sdk/provider-tools` 当前公开了一个共享 - tool schema 系列以及共享 schema/compat 辅助函数： + `openclaw/plugin-sdk/provider-tools` 当前公开一个共享的 + 工具 schema 系列，以及共享的 schema/兼容性辅助函数： - - `ProviderToolCompatFamily` 记录了当前共享的系列清单。 + - `ProviderToolCompatFamily` 记录了当前共享 family 清单。 - `buildProviderToolCompatFamilyHooks("gemini")` 为需要 Gemini 安全工具 schema 的提供商接入 Gemini schema 清理 + 诊断。 - `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)` - 是底层公开的 Gemini schema 辅助函数。 - - `resolveXaiModelCompatPatch()` 返回内置 xAI compat patch： + 是底层的公共 Gemini schema 辅助函数。 + - `resolveXaiModelCompatPatch()` 返回内置的 xAI compat patch： `toolSchemaProfile: "xai"`、不支持的 schema 关键字、原生 - `web_search` 支持，以及 HTML 实体形式的工具调用参数解码。 - - `applyXaiModelCompat(model)` 会在解析后的模型到达 runner 之前 - 对其应用相同的 xAI compat patch。 + `web_search` 支持，以及 HTML 实体形式 tool-call 参数的解码。 + - `applyXaiModelCompat(model)` 会在解析后的模型到达运行器之前， + 对其应用同样的 xAI compat patch。 - 真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 加 - `contributeResolvedModelCompat`，以保持这些 compat 元数据归提供商所有， - 而不是在 core 中硬编码 xAI 规则。 + 真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 加上 + `contributeResolvedModelCompat`，使兼容性元数据由提供商自己持有， + 而不是在核心中硬编码 xAI 规则。 - 相同的 package-root 模式也支撑着其他内置提供商： + 其他内置提供商也采用相同的软件包根模式： - - `@openclaw/openai-provider`：`api.ts` 导出 provider builders、 - 默认模型辅助函数和 realtime provider builders - - `@openclaw/openrouter-provider`：`api.ts` 导出 provider builder - 以及 onboarding/config 辅助函数 + - `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、 + 默认模型辅助函数和 realtime 提供商构建器 + - `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器 + 以及新手引导/配置辅助函数 - 对于需要在每次推理调用前进行令牌交换的提供商： + 对于那些在每次推理调用之前都需要进行令牌交换的提供商： ```typescript prepareRuntimeAuth: async (ctx) => { @@ -406,10 +398,10 @@ API 密钥认证和动态模型解析能力的提供商。 ``` - 对于需要自定义请求头或请求体修改的提供商： + 对于那些需要自定义请求头或请求体修改的提供商： ```typescript - // wrapStreamFn 返回一个从 ctx.streamFn 派生出的 StreamFn + // wrapStreamFn 返回一个从 ctx.streamFn 派生的 StreamFn wrapStreamFn: (ctx) => { if (!ctx.streamFn) return undefined; const inner = ctx.streamFn; @@ -423,8 +415,8 @@ API 密钥认证和动态模型解析能力的提供商。 }, ``` - - 对于需要在通用 HTTP 或 WebSocket 传输上附加原生请求/会话头或元数据的提供商： + + 对于那些在通用 HTTP 或 WebSocket 传输协议上需要原生请求/会话头或元数据的提供商： ```typescript resolveTransportTurnState: (ctx) => ({ @@ -445,7 +437,7 @@ API 密钥认证和动态模型解析能力的提供商。 ``` - 对于公开用量/计费数据的提供商： + 对于那些公开用量/计费数据的提供商： ```typescript resolveUsageAuth: async (ctx) => { @@ -460,51 +452,52 @@ API 密钥认证和动态模型解析能力的提供商。 - OpenClaw 会按以下顺序调用 hooks。大多数提供商只会用到 2 到 3 个： + OpenClaw 会按照以下顺序调用 hooks。大多数提供商只会使用 2-3 个： - | # | Hook | 何时使用 | + | # | Hook | 适用场景 | | --- | --- | --- | - | 1 | `catalog` | 模型目录或基础 `base URL` 默认值 | - | 2 | `applyConfigDefaults` | 配置具体化期间由提供商拥有的全局默认值 | - | 3 | `normalizeModelId` | 查找前的旧版/预览模型 ID 别名清理 | - | 4 | `normalizeTransport` | 通用模型组装前，针对提供商系列的 `api` / `baseUrl` 清理 | - | 5 | `normalizeConfig` | 规范化 `models.providers.` 配置 | - | 6 | `applyNativeStreamingUsageCompat` | 面向配置提供商的原生流式用量 compat 重写 | - | 7 | `resolveConfigApiKey` | 由提供商拥有的 env-marker 认证解析 | - | 8 | `resolveSyntheticAuth` | 本地/自托管或由配置支持的 synthetic auth | - | 9 | `shouldDeferSyntheticProfileAuth` | 将 synthetic 的已存储 profile 占位符置于 env/config auth 之后 | + | 1 | `catalog` | 模型目录或默认 `baseUrl` | + | 2 | `applyConfigDefaults` | 在配置具体化期间应用由提供商持有的全局默认值 | + | 3 | `normalizeModelId` | 在查找前清理旧版/预览版模型 id 别名 | + | 4 | `normalizeTransport` | 在通用模型组装前清理 provider-family `api` / `baseUrl` | + | 5 | `normalizeConfig` | 标准化 `models.providers.` 配置 | + | 6 | `applyNativeStreamingUsageCompat` | 对配置提供商应用原生流式使用量兼容性重写 | + | 7 | `resolveConfigApiKey` | 由提供商持有的环境标记凭证解析 | + | 8 | `resolveSyntheticAuth` | 本地/自托管或基于配置的合成凭证 | + | 9 | `shouldDeferSyntheticProfileAuth` | 将合成的已存配置档占位符置于环境变量/配置凭证之后 | | 10 | `resolveDynamicModel` | 接受任意上游模型 ID | - | 11 | `prepareDynamicModel` | 解析前的异步元数据获取 | - | 12 | `normalizeResolvedModel` | runner 之前的传输重写 | + | 11 | `prepareDynamicModel` | 解析前进行异步元数据获取 | + | 12 | `normalizeResolvedModel` | 运行器之前的传输协议重写 | - 运行时回退说明： + 运行时回退说明： - - `normalizeConfig` 会先检查匹配的提供商，然后再检查其他 - 具备 hook 能力的提供商插件，直到其中一个实际更改配置为止。 - 如果没有任何 provider hook 重写受支持的 Google 系列配置条目， - 内置 Google 配置规范化器仍会应用。 - - 如果公开了 provider hook，则 `resolveConfigApiKey` 会使用它。内置的 - `amazon-bedrock` 路径在这里也有一个内建的 AWS env-marker 解析器， - 即使 Bedrock 运行时认证本身仍然使用 AWS SDK 默认链。 - | 13 | `contributeResolvedModelCompat` | 为运行在其他兼容传输之后的供应商模型提供 compat 标志 | - | 14 | `capabilities` | 旧版静态能力包；仅用于兼容性 | - | 15 | `normalizeToolSchemas` | 注册前由提供商拥有的工具 schema 清理 | - | 16 | `inspectToolSchemas` | 由提供商拥有的工具 schema 诊断 | - | 17 | `resolveReasoningOutputMode` | 带标签 vs 原生 reasoning-output 契约 | + - `normalizeConfig` 会先检查匹配的提供商，然后再检查其他 + 具备 hook 能力的提供商插件，直到某个插件确实改写了配置。 + 如果没有任何提供商 hook 重写受支持的 Google family 配置项， + 内置的 Google 配置标准化器仍会生效。 + - `resolveConfigApiKey` 在公开该 hook 时会使用提供商 hook。内置的 + `amazon-bedrock` 路径在这里还带有一个内建的 AWS 环境标记解析器， + 即使 Bedrock 运行时凭证本身仍然使用 AWS SDK 默认 + 链。 + | 13 | `contributeResolvedModelCompat` | 为运行在另一个兼容传输协议之后的供应商模型提供兼容性标志 | + | 14 | `capabilities` | 旧版静态能力包；仅为兼容性保留 | + | 15 | `normalizeToolSchemas` | 在注册前由提供商持有的工具 schema 清理 | + | 16 | `inspectToolSchemas` | 由提供商持有的工具 schema 诊断 | + | 17 | `resolveReasoningOutputMode` | 标记型还是原生 reasoning-output 契约 | | 18 | `prepareExtraParams` | 默认请求参数 | - | 19 | `createStreamFn` | 完全自定义的 StreamFn 传输 | - | 20 | `wrapStreamFn` | 常规流路径上的自定义请求头/请求体包装器 | + | 19 | `createStreamFn` | 完全自定义的 StreamFn 传输协议 | + | 20 | `wrapStreamFn` | 常规流路径上的自定义头/请求体包装器 | | 21 | `resolveTransportTurnState` | 原生逐轮请求头/元数据 | - | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话请求头/冷却时间 | + | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话头/冷却 | | 23 | `formatApiKey` | 自定义运行时令牌形态 | | 24 | `refreshOAuth` | 自定义 OAuth 刷新 | - | 25 | `buildAuthDoctorHint` | 认证修复指引 | - | 26 | `matchesContextOverflowError` | 由提供商拥有的溢出检测 | - | 27 | `classifyFailoverReason` | 由提供商拥有的限流/过载分类 | - | 28 | `isCacheTtlEligible` | 提示词缓存 TTL 门控 | - | 29 | `buildMissingAuthMessage` | 自定义缺失认证提示 | - | 30 | `suppressBuiltInModel` | 隐藏陈旧的上游条目 | - | 31 | `augmentModelCatalog` | synthetic 向前兼容条目 | + | 25 | `buildAuthDoctorHint` | 凭证修复指引 | + | 26 | `matchesContextOverflowError` | 由提供商持有的上下文溢出检测 | + | 27 | `classifyFailoverReason` | 由提供商持有的限流/过载分类 | + | 28 | `isCacheTtlEligible` | prompt cache TTL 门控 | + | 29 | `buildMissingAuthMessage` | 自定义缺失凭证提示 | + | 30 | `suppressBuiltInModel` | 隐藏过时的上游条目 | + | 31 | `augmentModelCatalog` | 合成的前向兼容条目 | | 32 | `isBinaryThinking` | 二进制 thinking 开/关 | | 33 | `supportsXHighThinking` | `xhigh` reasoning 支持 | | 34 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略 | @@ -512,17 +505,17 @@ API 密钥认证和动态模型解析能力的提供商。 | 36 | `prepareRuntimeAuth` | 推理前的令牌交换 | | 37 | `resolveUsageAuth` | 自定义用量凭证解析 | | 38 | `fetchUsageSnapshot` | 自定义用量端点 | - | 39 | `createEmbeddingProvider` | 由提供商拥有的记忆/搜索 embedding 适配器 | - | 40 | `buildReplayPolicy` | 自定义转录 replay/压缩策略 | - | 41 | `sanitizeReplayHistory` | 通用清理后的提供商特定 replay 重写 | - | 42 | `validateReplayTurns` | 嵌入式 runner 之前的严格 replay turn 校验 | + | 39 | `createEmbeddingProvider` | 用于记忆/搜索的、由提供商持有的嵌入适配器 | + | 40 | `buildReplayPolicy` | 自定义转录回放/压缩策略 | + | 41 | `sanitizeReplayHistory` | 通用清理之后的提供商专用回放重写 | + | 42 | `validateReplayTurns` | 在嵌入式运行器之前进行严格的回放轮次校验 | | 43 | `onModelSelected` | 选择模型后的回调（例如遥测） | - 提示词调优说明： + Prompt 调优说明： - - `resolveSystemPromptContribution` 允许提供商为某个模型系列注入 - 具备缓存感知能力的 system-prompt 指引。当该行为属于某个提供商/模型 - 系列，且应保留稳定/动态缓存拆分时，优先使用它，而不是 + - `resolveSystemPromptContribution` 允许提供商为某个模型 family 注入具备缓存感知能力的 + system prompt 指引。当某个行为属于单个提供商/模型 family， + 并且应该保留稳定/动态缓存拆分时，优先使用它，而不是 `before_prompt_build`。 有关详细说明和真实示例，请参见 @@ -533,8 +526,8 @@ API 密钥认证和动态模型解析能力的提供商。 - 除文本推理外，提供商插件还可以注册语音、实时转录、实时 - 语音、媒体理解、图像生成、视频生成、web 抓取 + 提供商插件除了文本推理外，还可以注册语音、实时转录、实时语音、 + 媒体理解、图像生成、视频生成、web 抓取 和 web 搜索： ```typescript @@ -597,9 +590,20 @@ API 密钥认证和动态模型解析能力的提供商。 id: "acme-ai", label: "Acme Video", capabilities: { - maxVideos: 1, - maxDurationSeconds: 10, - supportsResolution: true, + generate: { + maxVideos: 1, + maxDurationSeconds: 10, + supportsResolution: true, + }, + imageToVideo: { + enabled: true, + maxVideos: 1, + maxInputImages: 1, + maxDurationSeconds: 5, + }, + videoToVideo: { + enabled: false, + }, }, generateVideo: async (req) => ({ videos: [] }), }); @@ -607,7 +611,7 @@ API 密钥认证和动态模型解析能力的提供商。 api.registerWebFetchProvider({ id: "acme-ai-fetch", label: "Acme Fetch", - hint: "Fetch pages through Acme's rendering backend.", + hint: "通过 Acme 的渲染后端抓取页面。", envVars: ["ACME_FETCH_API_KEY"], placeholder: "acme-...", signupUrl: "https://acme.example.com/fetch", @@ -618,7 +622,7 @@ API 密钥认证和动态模型解析能力的提供商。 acme.apiKey = value; }, createTool: () => ({ - description: "Fetch a page through Acme Fetch.", + description: "通过 Acme Fetch 抓取页面。", parameters: {}, execute: async (args) => ({ content: [] }), }), @@ -632,17 +636,23 @@ API 密钥认证和动态模型解析能力的提供商。 } ``` - OpenClaw 会将其归类为**混合能力**插件。这是 - 公司插件（每个供应商一个插件）的推荐模式。参见 + OpenClaw 会将其归类为 **hybrid-capability** 插件。这是 + 公司插件（每个厂商一个插件）的推荐模式。请参见 [内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。 + 对于视频生成，优先使用上面展示的具备模式感知能力的能力结构： + `generate`、`imageToVideo` 和 `videoToVideo`。较旧的扁平字段， + 如 `maxInputImages`、`maxInputVideos` 和 `maxDurationSeconds` + 仍然可作为汇总回退上限使用，但它们无法同样清晰地描述按模式区分的限制 + 或已禁用的转换模式。 + ```typescript src/provider.test.ts import { describe, it, expect } from "vitest"; - // 从 index.ts 或专门的文件中导出你的 provider 配置对象 + // 从 index.ts 或单独文件中导出你的 provider 配置对象 import { acmeProvider } from "./provider.js"; describe("acme-ai provider", () => { @@ -682,7 +692,7 @@ clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -这里不要使用旧版的仅限 skill 的发布别名；插件包应使用 +这里不要使用旧版仅供 Skills 使用的发布别名；插件包应使用 `clawhub package publish`。 ## 文件结构 @@ -699,19 +709,19 @@ clawhub package publish your-org/your-plugin ## 目录顺序参考 -`catalog.order` 控制你的目录相对于内置 -提供商何时合并： +`catalog.order` 用于控制你的目录相对于内置 +提供商的合并时机： -| Order | 何时 | 使用场景 | +| 顺序 | 时机 | 用例 | | --------- | ------------- | ----------------------------------------------- | -| `simple` | 第一阶段 | 纯 API 密钥提供商 | -| `profile` | 在 simple 之后 | 受 auth profile 控制的提供商 | +| `simple` | 第一轮 | 普通 API 密钥提供商 | +| `profile` | 在 simple 之后 | 受凭证配置档控制的提供商 | | `paired` | 在 profile 之后 | 合成多个相关条目 | -| `late` | 最后阶段 | 覆盖现有提供商（冲突时生效） | +| `late` | 最后一轮 | 覆盖现有提供商（冲突时获胜） | ## 后续步骤 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 如果你的插件还提供一个渠道 -- [插件运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助函数（TTS、搜索、子智能体） +- [SDK 运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助函数（TTS、搜索、subagent） - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考 - [插件内部机制](/zh-CN/plugins/architecture#provider-runtime-hooks) — hook 细节和内置示例 diff --git a/docs/zh-CN/tools/video-generation.md b/docs/zh-CN/tools/video-generation.md index 92c40f56d..fce76d02c 100644 --- a/docs/zh-CN/tools/video-generation.md +++ b/docs/zh-CN/tools/video-generation.md @@ -1,118 +1,135 @@ --- read_when: - - 通过智能体生成视频 - - 配置视频生成提供商和模型 - - 了解 `video_generate` 工具参数 -summary: 使用 12 个提供商后端从文本、图像或现有视频生成视频 + - 通过智能体生成视频时 + - 配置视频生成提供商和模型时 + - 了解 `video_generate` 工具参数时 +summary: 使用 12 个提供商后端，从文本、图像或现有视频生成视频 title: 视频生成 x-i18n: - generated_at: "2026-04-06T03:20:01Z" + generated_at: "2026-04-06T12:28:04Z" model: gpt-5.4 provider: openai - source_hash: 90d8a392b35adbd899232b02c55c10895b9d7ffc9858d6ca448f2e4e4a57f12f + source_hash: a224c0a1bd6fe61592ac22ad9a65f0ae25a378a12b79c1210f2e7101886798bb source_path: tools/video-generation.md workflow: 15 --- # 视频生成 -OpenClaw 智能体可以根据文本提示、参考图像或现有视频生成视频。支持 12 个提供商后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的提供商。 +OpenClaw 智能体可以根据文本提示、参考图像或现有视频生成视频。支持 12 个提供商后端，每个后端具有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的提供商。 -仅当至少有一个视频生成提供商可用时，`video_generate` 工具才会显示。如果你没有在智能体工具中看到它，请设置提供商 API 密钥或配置 `agents.defaults.videoGenerationModel`。 +只有在至少有一个视频生成提供商可用时，`video_generate` 工具才会出现。如果你没有在智能体工具中看到它，请设置提供商 API 密钥，或配置 `agents.defaults.videoGenerationModel`。 +OpenClaw 将视频生成视为三种运行时模式： + +- `generate`：用于没有参考媒体的文生视频请求 +- `imageToVideo`：当请求包含一个或多个参考图像时使用 +- `videoToVideo`：当请求包含一个或多个参考视频时使用 + +提供商可以支持这些模式中的任意子集。工具会在提交前验证当前模式，并在 `action=list` 中报告支持的模式。 + ## 快速开始 -1. 为任意受支持的提供商设置 API 密钥： +1. 为任一受支持的提供商设置 API 密钥： ```bash export GEMINI_API_KEY="your-key" ``` -2. 可选：固定默认模型： +2. 可选：固定一个默认模型： ```bash openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" ``` -3. 向智能体发出请求： +3. 向智能体提出请求： -> 生成一段 5 秒钟的电影感视频，内容是一只友好的龙虾在日落时分冲浪。 +> 生成一个 5 秒长、具有电影感的友善龙虾在日落时冲浪的视频。 -智能体会自动调用 `video_generate`。不需要工具允许列表。 +智能体会自动调用 `video_generate`。无需对工具进行 allowlist 配置。 ## 生成视频时会发生什么 视频生成是异步的。当智能体在一个会话中调用 `video_generate` 时： -1. OpenClaw 将请求提交给提供商，并立即返回一个任务 ID。 -2. 提供商在后台处理该任务（通常需要 30 秒到 5 分钟，具体取决于提供商和分辨率）。 +1. OpenClaw 会将请求提交给提供商，并立即返回一个任务 ID。 +2. 提供商会在后台处理该任务（通常需要 30 秒到 5 分钟，具体取决于提供商和分辨率）。 3. 当视频准备就绪时，OpenClaw 会通过内部完成事件唤醒同一个会话。 -4. 智能体会将完成的视频发回原始对话中。 +4. 智能体会将完成的视频发布回原始对话中。 -当某个任务仍在处理中时，在同一会话中重复调用 `video_generate` 不会启动新的生成，而是返回当前任务状态。使用 `openclaw tasks list` 或 `openclaw tasks show ` 可从 CLI 检查进度。 +当同一会话中已有任务正在进行时，重复调用 `video_generate` 不会启动新的生成，而是返回当前任务状态。使用 `openclaw tasks list` 或 `openclaw tasks show ` 可在 CLI 中检查进度。 -在没有会话支持的智能体运行场景之外（例如直接调用工具），该工具会回退为内联生成，并在同一轮中返回最终媒体路径。 +在不依赖会话支持的智能体运行场景之外（例如直接调用工具），该工具会回退为内联生成，并在同一轮中返回最终媒体路径。 ## 支持的提供商 | 提供商 | 默认模型 | 文本 | 图像参考 | 视频参考 | API 密钥 | | ------ | ------------------------------- | ---- | ----------------- | ---------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `MODELSTUDIO_API_KEY` | -| BytePlus | `seedance-1-0-lite-t2v-250428`| 是 | 1 张图像 | 否 | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | 是 | 1 张图像 | 否 | `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live`| 是 | 1 张图像 | 否 | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | 是 | 1 张图像 | 1 个视频 | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | 是 | 1 张图像 | 否 | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | 是 | 1 张图像 | 1 个视频 | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `QWEN_API_KEY` | -| Runway | `gen4.5` | 是 | 1 张图像 | 1 个视频 | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | 是 | 1 张图像 | 否 | `TOGETHER_API_KEY` | -| Vydra | `veo3` | 是 | 1 张图像（`kling`） | 否 | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | 是 | 1 张图像 | 1 个视频 | `XAI_API_KEY` | +| Alibaba | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `MODELSTUDIO_API_KEY` | +| BytePlus | `seedance-1-0-lite-t2v-250428` | 是 | 1 张图像 | 否 | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | 是 | 1 张图像 | 否 | `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | 是 | 1 张图像 | 否 | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | 是 | 1 张图像 | 1 个视频 | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | 是 | 1 张图像 | 否 | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | 是 | 1 张图像 | 1 个视频 | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `QWEN_API_KEY` | +| Runway | `gen4.5` | 是 | 1 张图像 | 1 个视频 | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | 是 | 1 张图像 | 否 | `TOGETHER_API_KEY` | +| Vydra | `veo3` | 是 | 1 张图像（`kling`） | 否 | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | 是 | 1 张图像 | 1 个视频 | `XAI_API_KEY` | 某些提供商接受额外或替代的 API 密钥环境变量。详见各个[提供商页面](#related)。 -运行 `video_generate action=list` 以在运行时查看可用的提供商和模型。 +运行 `video_generate action=list` 可在运行时检查可用的提供商、模型和运行时模式。 ## 工具参数 ### 必填 -| 参数 | 类型 | 描述 | -| ---- | ------ | --------------------------------------------------------------------- | -| `prompt` | string | 要生成的视频的文本描述（对 `action: "generate"` 为必填） | +| 参数 | 类型 | 说明 | +| -------- | ------ | --------------------------------------------------------------------------- | +| `prompt` | string | 要生成视频的文本描述（对于 `action: "generate"` 为必填） | ### 内容输入 -| 参数 | 类型 | 描述 | -| ---- | -------- | ---------------------------- | -| `image` | string | 单个参考图像（路径或 URL） | -| `images` | string[] | 多个参考图像（最多 5 个） | -| `video` | string | 单个参考视频（路径或 URL） | -| `videos` | string[] | 多个参考视频（最多 4 个） | +| 参数 | 类型 | 说明 | +| -------- | -------- | ---------------------------- | +| `image` | string | 单个参考图像（路径或 URL） | +| `images` | string[] | 多个参考图像（最多 5 个） | +| `video` | string | 单个参考视频（路径或 URL） | +| `videos` | string[] | 多个参考视频（最多 4 个） | ### 风格控制 -| 参数 | 类型 | 描述 | -| ---- | ---- | ---- | +| 参数 | 类型 | 说明 | +| ----------------- | ------- | ------------------------------------------------------------------------ | | `aspectRatio` | string | `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` | -| `resolution` | string | `480P`、`720P` 或 `1080P` | -| `durationSeconds` | number | 目标时长（秒，四舍五入到最接近的提供商支持值） | -| `size` | string | 当提供商支持时的尺寸提示 | -| `audio` | boolean | 在支持时启用生成音频 | -| `watermark` | boolean | 在支持时切换提供商水印 | +| `resolution` | string | `480P`、`720P` 或 `1080P` | +| `durationSeconds` | number | 目标时长（秒，四舍五入到提供商支持的最接近值） | +| `size` | string | 当提供商支持时的尺寸提示 | +| `audio` | boolean | 在支持时启用生成音频 | +| `watermark` | boolean | 在支持时切换提供商水印 | ### 高级 -| 参数 | 类型 | 描述 | -| ---- | ---- | ---- | -| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` | -| `model` | string | 提供商/模型覆盖（例如 `runway/gen4.5`） | -| `filename` | string | 输出文件名提示 | +| 参数 | 类型 | 说明 | +| ---------- | ------ | ------------------------------------------------- | +| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` | +| `model` | string | 提供商/模型覆盖（例如 `runway/gen4.5`） | +| `filename` | string | 输出文件名提示 | -并非所有提供商都支持所有参数。不受支持的覆盖项会尽力忽略，并作为警告在工具结果中报告。硬性能力限制（例如参考输入过多）会在提交前直接失败。 +并非所有提供商都支持全部参数。不支持的覆盖项会以尽力而为的方式被忽略，并在工具结果中报告为警告。硬性能力限制（例如参考输入过多）会在提交前直接失败。 + +参考输入也会决定运行时模式： + +- 无参考媒体：`generate` +- 任意图像参考：`imageToVideo` +- 任意视频参考：`videoToVideo` + +混合使用图像和视频参考并不是稳定的共享能力接口。 +建议每次请求只使用一种参考类型。 ## 操作 @@ -127,7 +144,7 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 1. **`model` 工具参数** -- 如果智能体在调用中指定了该参数。 2. **`videoGenerationModel.primary`** -- 来自配置。 3. **`videoGenerationModel.fallbacks`** -- 按顺序尝试。 -4. **自动检测** -- 使用具有有效认证信息的提供商，从当前默认提供商开始，然后按字母顺序尝试其余提供商。 +4. **自动检测** -- 使用具有有效认证的提供商，先从当前默认提供商开始，然后按字母顺序尝试其余提供商。 如果某个提供商失败，会自动尝试下一个候选项。如果所有候选项都失败，错误中会包含每次尝试的详细信息。 @@ -146,20 +163,48 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 ## 提供商说明 -| 提供商 | 说明 | -| ------ | ---- | -| Alibaba | 使用 DashScope/Model Studio 异步端点。参考图像和视频必须是远程 `http(s)` URL。 | -| BytePlus | 仅支持单张参考图像。 | -| ComfyUI | 基于工作流的本地或云端执行。通过已配置的图，支持文生视频和图生视频。 | -| fal | 对长时间运行任务使用基于队列的流程。仅支持单张参考图像。 | -| Google | 使用 Gemini/Veo。支持一张参考图像或一个参考视频。 | -| MiniMax | 仅支持单张参考图像。 | -| OpenAI | 仅转发 `size` 覆盖项。其他风格覆盖项（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略并给出警告。 | -| Qwen | 与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `http(s)` URL；本地文件会在前期直接被拒绝。 | -| Runway | 通过 data URI 支持本地文件。视频转视频需要 `runway/gen4_aleph`。纯文本运行公开 `16:9` 和 `9:16` 宽高比。 | -| Together | 仅支持单张参考图像。 | -| Vydra | 直接使用 `https://www.vydra.ai/api/v1` 以避免认证在重定向过程中丢失。`veo3` 仅内置为文生视频；`kling` 需要远程图像 URL。 | -| xAI | 支持文生视频、图生视频，以及远程视频编辑/扩展流程。 | +| 提供商 | 说明 | +| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | 使用 DashScope/Model Studio 异步端点。参考图像和视频必须是远程 `http(s)` URL。 | +| BytePlus | 仅支持单张参考图像。 | +| ComfyUI | 由工作流驱动的本地或云端执行。通过已配置图形支持文生视频和图生视频。 | +| fal | 对长时间运行任务使用基于队列的流程。仅支持单张参考图像。 | +| Google | 使用 Gemini/Veo。支持一个图像参考或一个视频参考。 | +| MiniMax | 仅支持单张参考图像。 | +| OpenAI | 仅转发 `size` 覆盖项。其他风格覆盖项（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略，并附带警告。 | +| Qwen | 与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `http(s)` URL；本地文件会在前期直接被拒绝。 | +| Runway | 支持通过数据 URI 使用本地文件。视频转视频需要 `runway/gen4_aleph`。纯文本运行提供 `16:9` 和 `9:16` 宽高比。 | +| Together | 仅支持单张参考图像。 | +| Vydra | 直接使用 `https://www.vydra.ai/api/v1`，以避免认证在重定向中丢失。`veo3` 内置为仅文生视频；`kling` 需要远程图像 URL。 | +| xAI | 支持文生视频、图生视频，以及远程视频编辑/扩展流程。 | + +## 提供商能力模式 + +共享的视频生成契约现在允许提供商声明按模式划分的能力，而不只是扁平的聚合限制。新的提供商实现应优先使用显式模式块： + +```typescript +capabilities: { + generate: { + maxVideos: 1, + maxDurationSeconds: 10, + supportsResolution: true, + }, + imageToVideo: { + enabled: true, + maxVideos: 1, + maxInputImages: 1, + maxDurationSeconds: 5, + }, + videoToVideo: { + enabled: true, + maxVideos: 1, + maxInputVideos: 1, + maxDurationSeconds: 5, + }, +} +``` + +旧的扁平字段，如 `maxInputImages` 和 `maxInputVideos`，仍可作为向后兼容的聚合上限使用，但它们无法同样精确地表达按模式划分的限制。 ## 配置