openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-06 12:28:45 +00:00
parent f503afe2a9
commit 02f144dadb
2 changed files with 286 additions and 231 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

336
docs/zh-CN/plugins/sdk-provider-plugins.md
View File

@ -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 密钥凭证和动态模型解析的提供商。
<Info>
如果你之前没有构建过任何 OpenClaw 插件，请先阅读
[入门指南](/zh-CN/plugins/building-plugins)，了解基本包
结构和清单设置。
如果你之前从未构建过任何 OpenClaw 插件，请先阅读
[入门指南](/zh-CN/plugins/building-plugins)，了解基础的软件包结构和清单设置。
</Info>
## 演练
<Steps>
<a id="step-1-package-and-manifest"></a>
<Step title="包和清单">
<Step title="软件包和清单">
<CodeGroup>
```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 <key>",
"cliDescription": "Acme AI API key"
"cliDescription": "Acme AI API 密钥"
}
],
"configSchema": {
@ -86,10 +84,9 @@ API 密钥认证和动态模型解析能力的提供商。
```
</CodeGroup>
清单声明了 `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 <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，
也仍然可以选择启用。
</Step>
@ -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` 会再次运行。
</Step>
<Step title="添加运行时 hooks（按需）">
大多数提供商只需要 `catalog` + `resolveDynamicModel`。当你的提供商有需要时，
<Step title="按需添加运行时 hooks">
大多数提供商只需要 `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` 导出提供商构建器
以及新手引导/配置辅助函数
<Tabs>
<Tab title="令牌交换">
对于需要在每次推理调用前进行令牌交换的提供商：
对于那些在每次推理调用之前都需要进行令牌交换的提供商：
```typescript
prepareRuntimeAuth: async (ctx) => {
@ -406,10 +398,10 @@ API 密钥认证和动态模型解析能力的提供商。
```
</Tab>
<Tab title="自定义请求头">
对于需要自定义请求头或请求体修改的提供商：
对于那些需要自定义请求头或请求体修改的提供商：
```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 密钥认证和动态模型解析能力的提供商。
},
```
</Tab>
<Tab title="原生传输标识">
对于需要在通用 HTTP 或 WebSocket 传输上附加原生请求/会话头或元数据的提供商：
<Tab title="原生传输协议标识">
对于那些在通用 HTTP 或 WebSocket 传输协议上需要原生请求/会话头或元数据的提供商：
```typescript
resolveTransportTurnState: (ctx) => ({
@ -445,7 +437,7 @@ API 密钥认证和动态模型解析能力的提供商。
```
</Tab>
<Tab title="用量和计费">
对于公开用量/计费数据的提供商：
对于那些公开用量/计费数据的提供商：
```typescript
resolveUsageAuth: async (ctx) => {
@ -460,51 +452,52 @@ API 密钥认证和动态模型解析能力的提供商。
</Tabs>
<Accordion title="所有可用的提供商 hooks">
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.<id>` 配置 |
| 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.<id>` 配置 |
| 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 密钥认证和动态模型解析能力的提供商。
<Step title="添加额外能力（可选）">
<a id="step-5-add-extra-capabilities"></a>
除文本推理外，提供商插件还可以注册语音、实时转录、实时
语音、媒体理解、图像生成、视频生成、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`
仍然可作为汇总回退上限使用，但它们无法同样清晰地描述按模式区分的限制
或已禁用的转换模式。
</Step>
<Step title="测试">
<a id="step-6-test"></a>
```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 细节和内置示例

181
docs/zh-CN/tools/video-generation.md
View File

@ -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 密钥自动选择合适的提供商。
<Note>
仅当至少有一个视频生成提供商可用时，`video_generate` 工具才会显示。如果你没有在智能体工具中看到它，请设置提供商 API 密钥或配置 `agents.defaults.videoGenerationModel`。
只有在至少有一个视频生成提供商可用时，`video_generate` 工具才会出现。如果你没有在智能体工具中看到它，请设置提供商 API 密钥，或配置 `agents.defaults.videoGenerationModel`。
</Note>
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 <taskId>` 可从 CLI 检查进度。
当同一会话中已有任务正在进行时，重复调用 `video_generate` 不会启动新的生成，而是返回当前任务状态。使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可在 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`，仍可作为向后兼容的聚合上限使用，但它们无法同样精确地表达按模式划分的限制。
## 配置