feat: split image providers into 1h-openai-image and 1h-gemini-image, rename video to 1h-openai-video

This commit is contained in:
openclaw committed 2026-10-19 14:36:20 +00:00
1 parent 3c5e5dd023
commit 8cd50b1c4d
16 files changed
+1553 -102

No files matched your search

+13 -11
View File
@@ -1,6 +1,6 @@
# 1-h Tools (`1h-tools`)
OpenClaw 统一私有扩展插件集合,聚合了自定义 Agent 工具、媒体生成驱动(视频/图像)以及内置技能库。
OpenClaw 统一私有扩展插件集合,聚合了自定义 Agent 工具、媒体生成驱动(视频/图像,支持 OpenAI 与 Gemini 双协议)以及内置技能库。
各模块采用**就近同构原则(Co-location)**维护其独立代码、测试与文档,避免全局单页膨胀与文档漂移。
@@ -8,12 +8,13 @@ OpenClaw 统一私有扩展插件集合,聚合了自定义 Agent 工具、媒
## 包含模块清单
| 模块类别 | 标识符 (ID) | 契约类型 | 说明 | 详细文档 |
| :--- | :--- | :--- | :--- | :--- |
| **视频生成** | `1h-video` | `videoGenerationProviders` | OpenAI `/v1/videos` 协议兼容视频生成驱动(支持自建网关 / gemini-web2api / Sora 协议) | [查看文档 →](src/video/README.md) |
| **图像生成** | `1h-image` | `imageGenerationProviders` | OpenAI `/v1/images` 协议兼容图像生成驱动(支持 Bifrost / ccLoad,修复 16:9 尺寸 Bug 与 Base64/URL 双模解析) | [查看文档 →](src/image/README.md) |
| **基础工具** | `echo` | `tools` | 基础测试与连通性回显工具 | [查看文档 →](src/tools/README.md) |
| **内置技能** | `agent-access` | `skills` | Bitwarden Agent Access 自动化技能 | [查看技能 →](skills/agent-access/SKILL.md) |
| 模块类别 | 标识符 (ID) | 契约类型 | 协议支持 | 说明 | 详细文档 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **视频生成** | `1h-openai-video` | `videoGenerationProviders` | OpenAI `/v1/videos` | OpenAI 格式视频生成驱动(支持自建网关 / gemini-web2api / Sora 协议) | [查看文档 →](src/video/README.md) |
| **图像生成 (OpenAI)** | `1h-openai-image` | `imageGenerationProviders` | OpenAI `/v1/images` | OpenAI 格式图像生成驱动(支持 gpt-image-2 等,修复 16:9 尺寸 Bug 与 URL 模式) | [查看文档 →](src/image/README.md) |
| **图像生成 (Gemini)** | `1h-gemini-image` | `imageGenerationProviders` | Gemini `:generateContent` | Gemini 原生图像生成驱动(专职适配 gemini-3.1-flash-image,秒级出图) | [查看文档 →](src/image/README.md) |
| **基础工具** | `echo` | `tools` | Tool Plugin | 基础测试与连通性回显工具 | [查看文档 →](src/tools/README.md) |
| **内置技能** | `agent-access` | `skills` | OpenClaw Skill | Bitwarden Agent Access 自动化技能 | [查看技能 →](skills/agent-access/SKILL.md) |
---
@@ -23,7 +24,7 @@ OpenClaw 统一私有扩展插件集合,聚合了自定义 Agent 工具、媒
在 OpenClaw Gateway 主机上执行:
```bash
openclaw plugins install git:git.1-h.cc/OpenClaw/openclaw-plugin-tools --force
openclaw plugins install git:https://git.1-h.cc/OpenClaw/openclaw-plugin-tools.git --force --acknowledge-install-policy-warning --accept-capabilities
```
### 插件更新
@@ -60,10 +61,11 @@ openclaw-plugin-tools/
│ │ ├── echo.ts
│ │ └── README.md # 📍 工具专属说明
│ ├── video/ # 视频生成驱动模块
│ │ ├── index.ts
│ │ ├── openai.ts # 1h-openai-video 驱动实现
│ │ └── README.md # 📍 视频驱动专属说明
│ └── image/ # 图像生成驱动模块
│ ├── index.ts
│ └── image/ # 图像生成驱动模块集合
│ ├── openai.ts # 1h-openai-image 驱动实现
│ ├── gemini.ts # 1h-gemini-image 驱动实现
│ └── README.md # 📍 图像驱动专属说明
└── skills/ # 官方规范就近内置技能
└── agent-access/
+21
View File
@@ -0,0 +1,21 @@
import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
import type { ImageGenerationProvider, ImageGenerationRequest } from "openclaw/plugin-sdk/image-generation";
export interface SecretRefObject {
source: string;
provider: string;
id: string;
}
export interface GeminiImagePluginConfig {
baseUrl?: string;
apiKey?: string | SecretRefObject;
allowPrivateNetwork?: boolean;
defaultModel?: string;
models?: string[];
}
export declare function resolvePluginApiKey(rawKey: string | SecretRefObject | undefined): string | undefined;
export declare function resolveGeminiImageConfig(cfg: ImageGenerationRequest["cfg"] | undefined, apiPluginConfig?: Record<string, unknown>): GeminiImagePluginConfig | undefined;
export declare function resolveConfiguredGeminiImageBaseUrl(pluginCfg?: GeminiImagePluginConfig): string;
export declare function buildGeminiImageGenerationProvider({ isProviderApiKeyConfigured, getPluginConfig, }: {
isProviderApiKeyConfigured: OpenClawPluginApi["runtime"]["modelAuth"]["isProviderApiKeyConfigured"];
getPluginConfig?: () => Record<string, unknown> | undefined;
}): ImageGenerationProvider;
+197
View File
@@ -0,0 +1,197 @@
import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
const DEFAULT_GEMINI_IMAGE_BASE_URL = "http://host.incus.internal:8080/v1beta";
const DEFAULT_GEMINI_IMAGE_MODEL = "gemini-3.1-flash-image";
const DEFAULT_TIMEOUT_MS = 120_000;
export function resolvePluginApiKey(rawKey) {
if (typeof rawKey === "string") {
const trimmed = rawKey.trim();
const envMatch = trimmed.match(/^\$\{([A-Za-z0-9_]+)\}$/);
if (envMatch) {
return normalizeOptionalString(process.env[envMatch[1]]);
}
return normalizeOptionalString(trimmed);
}
if (rawKey && typeof rawKey === "object" && typeof rawKey.id === "string") {
return normalizeOptionalString(process.env[rawKey.id]);
}
return undefined;
}
export function resolveGeminiImageConfig(cfg, apiPluginConfig) {
const toolsConfig = (apiPluginConfig ?? cfg?.plugins?.entries?.["1h-tools"]?.config);
return toolsConfig?.geminiImage ?? toolsConfig?.image;
}
export function resolveConfiguredGeminiImageBaseUrl(pluginCfg) {
return (normalizeOptionalString(pluginCfg?.baseUrl) ??
normalizeOptionalString(process.env.GEMINI_IMAGE_BASE_URL) ??
DEFAULT_GEMINI_IMAGE_BASE_URL);
}
export function buildGeminiImageGenerationProvider({ isProviderApiKeyConfigured, getPluginConfig, }) {
return {
id: "1h-gemini-image",
label: "1-h Gemini Image",
defaultModel: DEFAULT_GEMINI_IMAGE_MODEL,
models: [DEFAULT_GEMINI_IMAGE_MODEL],
isConfigured: (ctx) => {
const pluginCfg = resolveGeminiImageConfig(ctx.cfg, getPluginConfig?.());
if (resolvePluginApiKey(pluginCfg?.apiKey) ||
Boolean(pluginCfg?.apiKey) ||
normalizeOptionalString(process.env.CCLOAD_API_KEY) ||
normalizeOptionalString(process.env.GEMINI_API_KEY) ||
normalizeOptionalString(process.env.BIFROST_API_KEY)) {
return true;
}
return isProviderApiKeyConfigured({
provider: "google",
...ctx,
profileTypes: ["api_key"],
});
},
capabilities: {
generate: {
maxCount: 1,
supportsSize: false,
supportsAspectRatio: true,
supportsResolution: false,
},
edit: {
enabled: true,
maxCount: 1,
maxInputImages: 3,
supportsSize: false,
supportsAspectRatio: true,
supportsResolution: false,
},
geometry: {
aspectRatios: ["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "21:9"],
},
output: {
formats: ["jpeg", "png"],
},
},
async generateImage(req) {
const pluginCfg = resolveGeminiImageConfig(req.cfg, getPluginConfig?.());
const explicitApiKey = resolvePluginApiKey(pluginCfg?.apiKey) ??
normalizeOptionalString(process.env.CCLOAD_API_KEY) ??
normalizeOptionalString(process.env.GEMINI_API_KEY) ??
normalizeOptionalString(process.env.BIFROST_API_KEY);
let apiKey = explicitApiKey;
if (!apiKey) {
const { resolveApiKeyForProvider } = await import("openclaw/plugin-sdk/provider-auth-runtime");
const auth = await resolveApiKeyForProvider({
provider: "google",
cfg: req.cfg,
agentDir: req.agentDir,
store: req.authStore,
});
if (!auth.apiKey) {
throw new Error("Gemini Image API key missing");
}
apiKey = auth.apiKey;
}
const [{ assertOkOrThrowHttpError, createProviderOperationDeadline, postJsonRequest, readProviderJsonResponse, resolveProviderHttpRequestConfig, resolveProviderOperationTimeoutMs, sanitizeConfiguredModelProviderRequest, },] = await Promise.all([import("openclaw/plugin-sdk/provider-http")]);
const fetchFn = fetch;
const deadline = createProviderOperationDeadline({
timeoutMs: req.timeoutMs,
label: "Gemini Image Generation",
});
const rawBaseUrl = resolveConfiguredGeminiImageBaseUrl(pluginCfg);
const allowPrivate = pluginCfg?.allowPrivateNetwork ?? true;
const requestConfig = sanitizeConfiguredModelProviderRequest({
allowPrivateNetwork: allowPrivate,
});
const { baseUrl, allowPrivateNetwork, headers, dispatcherPolicy } = resolveProviderHttpRequestConfig({
baseUrl: rawBaseUrl,
defaultBaseUrl: DEFAULT_GEMINI_IMAGE_BASE_URL,
allowPrivateNetwork: allowPrivate,
request: requestConfig,
defaultHeaders: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
provider: "google",
capability: "image",
transport: "http",
});
const model = normalizeOptionalString(req.model) ??
normalizeOptionalString(pluginCfg?.defaultModel) ??
DEFAULT_GEMINI_IMAGE_MODEL;
const submitTimeoutMs = resolveProviderOperationTimeoutMs({
deadline,
defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
});
const parts = [];
const inputImages = req.inputImages ?? [];
for (const img of inputImages) {
parts.push({
inlineData: {
mimeType: img.mimeType || "image/jpeg",
data: img.buffer.toString("base64"),
},
});
}
parts.push({
text: req.prompt,
});
const jsonBody = {
contents: [
{
parts,
},
],
generationConfig: {
responseMimeType: "image/jpeg",
},
};
const normalizedBaseUrl = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
const url = `${normalizedBaseUrl}/models/${model}:generateContent`;
const { response, release } = await postJsonRequest({
url,
headers,
body: jsonBody,
timeoutMs: submitTimeoutMs,
fetchFn,
allowPrivateNetwork,
dispatcherPolicy,
});
let payload;
try {
await assertOkOrThrowHttpError(response, "Gemini image generation request failed");
payload = await readProviderJsonResponse(response, "Gemini image generation failed");
}
finally {
await release();
}
if (payload.error?.message) {
throw new Error(`Gemini image generation error: ${payload.error.message}`);
}
const candidateParts = payload.candidates?.[0]?.content?.parts ?? [];
const generatedImages = [];
for (let i = 0; i < candidateParts.length; i++) {
const part = candidateParts[i];
if (part.inlineData?.data) {
const buffer = Buffer.from(part.inlineData.data, "base64");
const mimeType = part.inlineData.mimeType || "image/jpeg";
const ext = mimeType.includes("png") ? "png" : "jpg";
generatedImages.push({
buffer,
mimeType,
fileName: `image-${i + 1}.${ext}`,
});
}
}
if (generatedImages.length === 0) {
const textMessage = candidateParts.find((p) => p.text)?.text;
throw new Error(textMessage
? `Gemini returned text instead of an image: ${textMessage}`
: "Gemini image generation returned no image data");
}
return {
images: generatedImages,
model,
metadata: {
finishReason: payload.candidates?.[0]?.finishReason,
},
};
},
};
}
+27
View File
@@ -0,0 +1,27 @@
import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
import type { ImageGenerationProvider, ImageGenerationRequest } from "openclaw/plugin-sdk/image-generation";
export interface SecretRefObject {
source: string;
provider: string;
id: string;
}
export interface ImagePluginConfig {
baseUrl?: string;
apiKey?: string | SecretRefObject;
allowPrivateNetwork?: boolean;
defaultModel?: string;
models?: string[];
responseFormat?: "url" | "b64_json";
}
export declare function resolvePluginApiKey(rawKey: string | SecretRefObject | undefined): string | undefined;
export declare function resolveImageConfig(cfg: ImageGenerationRequest["cfg"] | undefined, apiPluginConfig?: Record<string, unknown>): ImagePluginConfig | undefined;
export declare function resolveConfiguredImageBaseUrl(cfg: ImageGenerationRequest["cfg"], pluginCfg?: ImagePluginConfig): string;
export declare function resolveImageSize(params: {
size?: string;
aspectRatio?: string;
model?: string;
}): string;
export declare function buildOpenAIImageGenerationProvider({ isProviderApiKeyConfigured, getPluginConfig, }: {
isProviderApiKeyConfigured: OpenClawPluginApi["runtime"]["modelAuth"]["isProviderApiKeyConfigured"];
getPluginConfig?: () => Record<string, unknown> | undefined;
}): ImageGenerationProvider;
+305
View File
@@ -0,0 +1,305 @@
import { bufferToBlobPart } from "openclaw/plugin-sdk/blob-runtime";
import { extensionForMime } from "openclaw/plugin-sdk/media-mime";
import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
const DEFAULT_OPENAI_IMAGE_BASE_URL = "https://api.openai.com/v1";
const DEFAULT_OPENAI_IMAGE_MODEL = "gpt-image-2";
const DEFAULT_TIMEOUT_MS = 120_000;
const DEFAULT_SIZE = "1024x1024";
const SUPPORTED_SIZES = [
"1024x1024",
"1536x1024",
"1024x1536",
"1792x1024",
"1024x1792",
"2048x2048",
"2048x1152",
"3840x2160",
];
const SUPPORTED_ASPECT_RATIOS = [
"1:1",
"16:9",
"9:16",
"4:3",
"3:4",
"3:2",
"2:3",
"21:9",
];
export function resolvePluginApiKey(rawKey) {
if (typeof rawKey === "string") {
const trimmed = rawKey.trim();
const envMatch = trimmed.match(/^\$\{([A-Za-z0-9_]+)\}$/);
if (envMatch) {
return normalizeOptionalString(process.env[envMatch[1]]);
}
return normalizeOptionalString(trimmed);
}
if (rawKey && typeof rawKey === "object" && typeof rawKey.id === "string") {
return normalizeOptionalString(process.env[rawKey.id]);
}
return undefined;
}
export function resolveImageConfig(cfg, apiPluginConfig) {
const toolsConfig = (apiPluginConfig ?? cfg?.plugins?.entries?.["1h-tools"]?.config);
return toolsConfig?.openaiImage ?? toolsConfig?.image;
}
export function resolveConfiguredImageBaseUrl(cfg, pluginCfg) {
return (normalizeOptionalString(pluginCfg?.baseUrl) ??
normalizeOptionalString(process.env.OPENAI_IMAGE_BASE_URL) ??
normalizeOptionalString(process.env.BIFROST_BASE_URL) ??
normalizeOptionalString(cfg?.models?.providers?.openai?.baseUrl) ??
normalizeOptionalString(process.env.OPENAI_BASE_URL) ??
DEFAULT_OPENAI_IMAGE_BASE_URL);
}
export function resolveImageSize(params) {
const explicitSize = normalizeOptionalString(params.size);
if (explicitSize) {
return explicitSize;
}
// Safe aspect ratio normalization preventing issue #168665 (proxy rejecting 2048x1152)
switch (normalizeOptionalString(params.aspectRatio)) {
case "1:1":
return "1024x1024";
case "16:9":
return "1792x1024";
case "9:16":
return "1024x1792";
case "4:3":
case "3:2":
return "1536x1024";
case "3:4":
case "2:3":
return "1024x1536";
case "21:9":
return "1792x1024";
default:
return DEFAULT_SIZE;
}
}
export function buildOpenAIImageGenerationProvider({ isProviderApiKeyConfigured, getPluginConfig, }) {
return {
id: "1h-openai-image",
label: "1-h OpenAI Image",
defaultModel: DEFAULT_OPENAI_IMAGE_MODEL,
models: [DEFAULT_OPENAI_IMAGE_MODEL, "gpt-image-2.5", "gpt-image-2.5-flare", "gpt-image-2.5-sunburst"],
isConfigured: (ctx) => {
const pluginCfg = resolveImageConfig(ctx.cfg, getPluginConfig?.());
if (resolvePluginApiKey(pluginCfg?.apiKey) ||
Boolean(pluginCfg?.apiKey) ||
normalizeOptionalString(process.env.OPENAI_IMAGE_API_KEY) ||
normalizeOptionalString(process.env.CCLOAD_API_KEY) ||
normalizeOptionalString(process.env.BIFROST_API_KEY) ||
normalizeOptionalString(process.env.OPENAI_API_KEY)) {
return true;
}
return isProviderApiKeyConfigured({
provider: "openai",
...ctx,
profileTypes: ["api_key"],
});
},
capabilities: {
generate: {
maxCount: 4,
supportsSize: true,
supportsAspectRatio: true,
supportsResolution: true,
},
edit: {
enabled: true,
maxCount: 4,
maxInputImages: 5,
supportsSize: true,
supportsAspectRatio: true,
supportsResolution: true,
},
geometry: {
sizes: [...SUPPORTED_SIZES],
aspectRatios: [...SUPPORTED_ASPECT_RATIOS],
resolutions: ["1K", "2K", "4K"],
},
output: {
formats: ["png", "jpeg", "webp"],
qualities: ["low", "medium", "high", "auto"],
},
},
async generateImage(req) {
const pluginCfg = resolveImageConfig(req.cfg, getPluginConfig?.());
const explicitApiKey = resolvePluginApiKey(pluginCfg?.apiKey) ??
normalizeOptionalString(process.env.OPENAI_IMAGE_API_KEY) ??
normalizeOptionalString(process.env.CCLOAD_API_KEY) ??
normalizeOptionalString(process.env.BIFROST_API_KEY) ??
normalizeOptionalString(process.env.OPENAI_API_KEY);
let apiKey = explicitApiKey;
if (!apiKey) {
const { resolveApiKeyForProvider } = await import("openclaw/plugin-sdk/provider-auth-runtime");
const auth = await resolveApiKeyForProvider({
provider: "openai",
cfg: req.cfg,
agentDir: req.agentDir,
store: req.authStore,
modelApi: "openai-responses",
});
if (!auth.apiKey) {
throw new Error("OpenAI / Bifrost Image API key missing");
}
apiKey = auth.apiKey;
}
const [{ assertOkOrThrowHttpError, createProviderOperationDeadline, createProviderOperationTimeoutResolver, fetchWithTimeoutGuarded, postJsonRequest, postMultipartRequest, readProviderJsonResponse, resolveProviderHttpRequestConfig, resolveProviderOperationTimeoutMs, sanitizeConfiguredModelProviderRequest, },] = await Promise.all([import("openclaw/plugin-sdk/provider-http")]);
const fetchFn = fetch;
const deadline = createProviderOperationDeadline({
timeoutMs: req.timeoutMs,
label: "OpenAI Image Generation",
});
const providerConfig = req.cfg?.models?.providers?.openai;
const allowPrivate = pluginCfg?.allowPrivateNetwork ?? true;
const requestConfig = sanitizeConfiguredModelProviderRequest({
...providerConfig?.request,
allowPrivateNetwork: allowPrivate,
});
const rawBaseUrl = resolveConfiguredImageBaseUrl(req.cfg, pluginCfg);
const { baseUrl, allowPrivateNetwork, headers, dispatcherPolicy } = resolveProviderHttpRequestConfig({
baseUrl: rawBaseUrl,
defaultBaseUrl: DEFAULT_OPENAI_IMAGE_BASE_URL,
allowPrivateNetwork: allowPrivate,
request: requestConfig,
defaultHeaders: {
Authorization: `Bearer ${apiKey}`,
},
provider: "openai",
capability: "image",
transport: "http",
});
const model = normalizeOptionalString(req.model) ??
normalizeOptionalString(pluginCfg?.defaultModel) ??
DEFAULT_OPENAI_IMAGE_MODEL;
const size = resolveImageSize({
size: req.size,
aspectRatio: req.aspectRatio,
model,
});
const count = Math.max(1, Math.min(req.count ?? 1, 4));
const inputImages = req.inputImages ?? [];
const isEdit = inputImages.length > 0;
const submitTimeoutMs = resolveProviderOperationTimeoutMs({
deadline,
defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
});
let response;
let release;
const responseFormat = pluginCfg?.responseFormat ?? "url";
if (isEdit) {
const form = new FormData();
form.set("model", model);
form.set("prompt", req.prompt);
form.set("n", String(count));
form.set("size", size);
form.set("response_format", responseFormat);
inputImages.forEach((img, idx) => {
const mime = img.mimeType || "image/png";
const ext = extensionForMime(mime)?.slice(1) || "png";
const name = img.fileName || `input-${idx + 1}.${ext}`;
form.append(idx === 0 ? "image" : "image[]", new File([bufferToBlobPart(img.buffer)], name, { type: mime }));
});
const multipartHeaders = new Headers(headers);
multipartHeaders.delete("Content-Type");
({ response, release } = await postMultipartRequest({
url: `${baseUrl}/images/edits`,
headers: multipartHeaders,
body: form,
timeoutMs: submitTimeoutMs,
fetchFn,
allowPrivateNetwork,
dispatcherPolicy,
}));
}
else {
const jsonHeaders = new Headers(headers);
jsonHeaders.set("Content-Type", "application/json");
const jsonBody = {
model,
prompt: req.prompt,
n: count,
size,
response_format: responseFormat,
};
if (req.quality) {
jsonBody.quality = req.quality;
}
({ response, release } = await postJsonRequest({
url: `${baseUrl}/images/generations`,
headers: jsonHeaders,
body: jsonBody,
timeoutMs: submitTimeoutMs,
fetchFn,
allowPrivateNetwork,
dispatcherPolicy,
}));
}
let payload;
try {
await assertOkOrThrowHttpError(response, "Image generation request failed");
payload = await readProviderJsonResponse(response, "OpenAI image generation failed");
}
finally {
await release();
}
if (payload.error?.message) {
throw new Error(`Image generation error: ${payload.error.message}`);
}
const dataItems = payload.data ?? [];
if (dataItems.length === 0) {
throw new Error("Image generation returned no image data");
}
const generatedImages = [];
const downloadTimeout = createProviderOperationTimeoutResolver({
deadline,
defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
});
for (let i = 0; i < dataItems.length; i++) {
const item = dataItems[i];
if (item.b64_json) {
const buffer = Buffer.from(item.b64_json, "base64");
generatedImages.push({
buffer,
mimeType: "image/png",
fileName: `image-${i + 1}.png`,
revisedPrompt: item.revised_prompt,
});
}
else if (item.url) {
const dlResult = await fetchWithTimeoutGuarded(item.url, { method: "GET" }, downloadTimeout(), fetchFn, {
allowPrivateNetwork,
auditContext: "openai-image-download",
});
try {
await assertOkOrThrowHttpError(dlResult.response, "Failed to download generated image");
const arrayBuf = await dlResult.response.arrayBuffer();
const mime = dlResult.response.headers.get("content-type") || "image/png";
const ext = extensionForMime(mime)?.slice(1) || "png";
generatedImages.push({
buffer: Buffer.from(arrayBuf),
mimeType: mime,
fileName: `image-${i + 1}.${ext}`,
revisedPrompt: item.revised_prompt,
});
}
finally {
await dlResult.release();
}
}
}
if (generatedImages.length === 0) {
throw new Error("Failed to extract any valid image from provider response");
}
return {
images: generatedImages,
model,
metadata: {
created: payload.created,
size,
},
};
},
};
}
+11 -5
View File
@@ -2,12 +2,13 @@ import { jsonResult } from "openclaw/plugin-sdk/core";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { toolPluginMetadataSymbol } from "openclaw/plugin-sdk/tool-plugin";
import { echoTool } from "./tools/echo.js";
import { buildOpenAIVideoGenerationProvider } from "./video/index.js";
import { buildOpenAIImageGenerationProvider } from "./image/index.js";
import { buildOpenAIVideoGenerationProvider } from "./video/openai.js";
import { buildOpenAIImageGenerationProvider } from "./image/openai.js";
import { buildGeminiImageGenerationProvider } from "./image/gemini.js";
const entry = definePluginEntry({
id: "1h-tools",
name: "1-h Tools",
description: "Custom Tools and Media Providers for OpenClaw.",
description: "Custom Tools and Media Providers (OpenAI/Gemini) for OpenClaw.",
register(api) {
// 1. Register tools
api.registerTool({
@@ -20,16 +21,21 @@ const entry = definePluginEntry({
return jsonResult(result);
},
});
// 2. Register video generation provider
// 2. Register OpenAI-compatible video generation provider
api.registerVideoGenerationProvider(buildOpenAIVideoGenerationProvider({
isProviderApiKeyConfigured: api.runtime.modelAuth.isProviderApiKeyConfigured,
getPluginConfig: () => api.pluginConfig,
}));
// 3. Register image generation provider
// 3. Register OpenAI-compatible image generation provider
api.registerImageGenerationProvider(buildOpenAIImageGenerationProvider({
isProviderApiKeyConfigured: api.runtime.modelAuth.isProviderApiKeyConfigured,
getPluginConfig: () => api.pluginConfig,
}));
// 4. Register Gemini-native image generation provider
api.registerImageGenerationProvider(buildGeminiImageGenerationProvider({
isProviderApiKeyConfigured: api.runtime.modelAuth.isProviderApiKeyConfigured,
getPluginConfig: () => api.pluginConfig,
}));
},
});
Object.defineProperty(entry, toolPluginMetadataSymbol, {
+60
View File
@@ -0,0 +1,60 @@
import { type MediaKind } from "openclaw/plugin-sdk/media-mime";
import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
import type { createProviderOperationDeadline, postMultipartRequest } from "openclaw/plugin-sdk/provider-http";
import type { VideoGenerationProvider, VideoGenerationRequest } from "openclaw/plugin-sdk/video-generation";
declare const OPENAI_VIDEO_SIZES: readonly ["720x1280", "1280x720", "1024x1792", "1792x1024"];
export type OpenAIVideoRequestPolicy = {
allowPrivateNetwork: boolean;
dispatcherPolicy?: Parameters<typeof postMultipartRequest>[0]["dispatcherPolicy"];
};
export type OpenAIVideoStatus = "queued" | "in_progress" | "completed" | "failed";
export type OpenAIReferenceAsset = {
kind: Extract<MediaKind, "image" | "video">;
file: File;
};
export type OpenAIVideoResponse = {
id?: string;
model?: string;
status?: OpenAIVideoStatus;
prompt?: string | null;
seconds?: string;
size?: string;
error?: string | {
code?: string;
message?: string;
} | null;
};
export interface SecretRefObject {
source: string;
provider: string;
id: string;
}
export interface VideoPluginConfig {
baseUrl?: string;
apiKey?: string | SecretRefObject;
allowPrivateNetwork?: boolean;
defaultModel?: string;
models?: string[];
}
export declare function resolvePluginApiKey(rawKey: string | SecretRefObject | undefined): string | undefined;
export declare function resolveVideoConfig(cfg: VideoGenerationRequest["cfg"] | undefined, apiPluginConfig?: Record<string, unknown>): VideoPluginConfig | undefined;
export declare function resolveConfiguredOpenAIBaseUrl(cfg: VideoGenerationRequest["cfg"], pluginCfg?: VideoPluginConfig): string;
export declare function readOpenAIVideoFailureMessage(payload: OpenAIVideoResponse): string | undefined;
export declare function resolveDurationSeconds(durationSeconds: number | undefined): "4" | "8" | "12" | undefined;
export declare function resolveSize(params: {
size?: string;
aspectRatio?: string;
resolution?: string;
}): (typeof OPENAI_VIDEO_SIZES)[number] | undefined;
export declare function resolveReferenceAsset(req: VideoGenerationRequest): OpenAIReferenceAsset | null;
export declare function fetchOpenAIVideoDownload(params: {
url: string;
init: RequestInit;
deadline: ReturnType<typeof createProviderOperationDeadline>;
fetchFn: typeof fetch;
} & OpenAIVideoRequestPolicy): Promise<any>;
export declare function buildOpenAIVideoGenerationProvider({ isProviderApiKeyConfigured, getPluginConfig, }: {
isProviderApiKeyConfigured: OpenClawPluginApi["runtime"]["modelAuth"]["isProviderApiKeyConfigured"];
getPluginConfig?: () => Record<string, unknown> | undefined;
}): VideoGenerationProvider;
export {};
+371
View File
@@ -0,0 +1,371 @@
import { bufferToBlobPart } from "openclaw/plugin-sdk/blob-runtime";
import { extensionForMime } from "openclaw/plugin-sdk/media-mime";
import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
const DEFAULT_OPENAI_VIDEO_BASE_URL = "https://api.openai.com/v1";
const DEFAULT_OPENAI_VIDEO_MODEL = "sora-2";
const DEFAULT_TIMEOUT_MS = 120_000;
const POLL_INTERVAL_MS = 2_500;
const MAX_POLL_ATTEMPTS = 120;
const OPENAI_VIDEO_SECONDS = [4, 8, 12];
const OPENAI_VIDEO_SIZES = ["720x1280", "1280x720", "1024x1792", "1792x1024"];
export function resolvePluginApiKey(rawKey) {
if (typeof rawKey === "string") {
const trimmed = rawKey.trim();
const envMatch = trimmed.match(/^\$\{([A-Za-z0-9_]+)\}$/);
if (envMatch) {
return normalizeOptionalString(process.env[envMatch[1]]);
}
return normalizeOptionalString(trimmed);
}
if (rawKey && typeof rawKey === "object" && typeof rawKey.id === "string") {
return normalizeOptionalString(process.env[rawKey.id]);
}
return undefined;
}
export function resolveVideoConfig(cfg, apiPluginConfig) {
const toolsConfig = (apiPluginConfig ?? cfg?.plugins?.entries?.["1h-tools"]?.config);
return toolsConfig?.openaiVideo ?? toolsConfig?.video;
}
export function resolveConfiguredOpenAIBaseUrl(cfg, pluginCfg) {
return (normalizeOptionalString(pluginCfg?.baseUrl) ??
normalizeOptionalString(process.env.OPENAI_VIDEO_BASE_URL) ??
normalizeOptionalString(cfg?.models?.providers?.openai?.baseUrl) ??
normalizeOptionalString(process.env.OPENAI_BASE_URL) ??
DEFAULT_OPENAI_VIDEO_BASE_URL);
}
export function readOpenAIVideoFailureMessage(payload) {
if (payload.status !== "failed") {
return undefined;
}
if (typeof payload.error === "string") {
return normalizeOptionalString(payload.error) ?? "OpenAI video generation failed";
}
return normalizeOptionalString(payload.error?.message) ?? "OpenAI video generation failed";
}
export function resolveDurationSeconds(durationSeconds) {
if (typeof durationSeconds !== "number" || !Number.isFinite(durationSeconds)) {
return undefined;
}
const rounded = Math.max(OPENAI_VIDEO_SECONDS[0], Math.round(durationSeconds));
const nearest = OPENAI_VIDEO_SECONDS.reduce((best, current) => Math.abs(current - rounded) < Math.abs(best - rounded) ? current : best);
return String(nearest);
}
export function resolveSize(params) {
const explicitSize = normalizeOptionalString(params.size);
const supportedSize = OPENAI_VIDEO_SIZES.find((size) => size === explicitSize);
if (supportedSize) {
return supportedSize;
}
switch (normalizeOptionalString(params.aspectRatio)) {
case "9:16":
return "720x1280";
case "16:9":
return "1280x720";
case "4:7":
return "1024x1792";
case "7:4":
return "1792x1024";
default:
break;
}
if (params.resolution === "1080P") {
return "1792x1024";
}
return undefined;
}
export function resolveReferenceAsset(req) {
const allAssets = [...(req.inputImages ?? []), ...(req.inputVideos ?? [])];
if (allAssets.length === 0) {
return null;
}
if (allAssets.length > 1) {
throw new Error("OpenAI video generation supports at most one reference image or video.");
}
const [asset] = allAssets;
if (!asset?.buffer) {
throw new Error("OpenAI video generation currently requires local image/video uploads for reference assets.");
}
const kind = (req.inputVideos?.length ?? 0) > 0 ? "video" : "image";
const mimeType = normalizeOptionalString(asset.mimeType) || (kind === "video" ? "video/mp4" : "image/png");
const extension = extensionForMime(mimeType)?.slice(1) ?? (mimeType.startsWith("video/") ? "mp4" : "png");
const fileName = normalizeOptionalString(asset.fileName) || `reference-${kind}.${extension}`;
return {
kind,
file: new File([bufferToBlobPart(asset.buffer)], fileName, { type: mimeType }),
};
}
export async function fetchOpenAIVideoDownload(params) {
const { assertOkOrThrowHttpError, createProviderOperationTimeoutResolver, executeProviderOperationWithRetry, fetchProviderDownloadResponse, fetchWithTimeoutGuarded, } = await import("openclaw/plugin-sdk/provider-http");
const timeoutMs = createProviderOperationTimeoutResolver({
deadline: params.deadline,
defaultTimeoutMs: params.deadline.timeoutMs ?? DEFAULT_TIMEOUT_MS,
});
if (!params.allowPrivateNetwork && !params.dispatcherPolicy) {
const response = await fetchProviderDownloadResponse({
url: params.url,
init: params.init,
deadline: params.deadline,
fetchFn: params.fetchFn,
provider: "openai",
requestFailedMessage: "OpenAI video download failed",
});
return {
response,
release: async () => { },
};
}
return await executeProviderOperationWithRetry({
provider: "openai",
stage: "download",
operation: async () => {
const result = await fetchWithTimeoutGuarded(params.url, params.init, timeoutMs(), params.fetchFn, {
...(params.allowPrivateNetwork ? { ssrfPolicy: { allowPrivateNetwork: true } } : {}),
...(params.dispatcherPolicy ? { dispatcherPolicy: params.dispatcherPolicy } : {}),
auditContext: "openai-video-download",
});
try {
await assertOkOrThrowHttpError(result.response, "OpenAI video download failed");
return result;
}
catch (error) {
await result.release();
throw error;
}
},
});
}
export function buildOpenAIVideoGenerationProvider({ isProviderApiKeyConfigured, getPluginConfig, }) {
return {
id: "1h-openai-video",
label: "1-h OpenAI Video",
defaultModel: DEFAULT_OPENAI_VIDEO_MODEL,
models: [DEFAULT_OPENAI_VIDEO_MODEL, "sora-2-pro", "gemini-video"],
isConfigured: (ctx) => {
const pluginCfg = resolveVideoConfig(ctx.cfg, getPluginConfig?.());
if (resolvePluginApiKey(pluginCfg?.apiKey) ||
Boolean(pluginCfg?.apiKey) ||
normalizeOptionalString(process.env.OPENAI_VIDEO_API_KEY) ||
normalizeOptionalString(process.env.GEMINI_WEB2API_API_KEY) ||
normalizeOptionalString(process.env.CCLOAD_API_KEY)) {
return true;
}
return isProviderApiKeyConfigured({
provider: "openai",
...ctx,
profileTypes: ["api_key"],
});
},
capabilities: {
generate: {
maxVideos: 1,
maxDurationSeconds: 12,
supportedDurationSeconds: OPENAI_VIDEO_SECONDS,
supportsSize: true,
sizes: OPENAI_VIDEO_SIZES,
},
imageToVideo: {
enabled: true,
maxVideos: 1,
maxInputImages: 1,
maxDurationSeconds: 12,
supportedDurationSeconds: OPENAI_VIDEO_SECONDS,
supportsSize: true,
sizes: OPENAI_VIDEO_SIZES,
},
videoToVideo: {
enabled: true,
maxVideos: 1,
maxInputVideos: 1,
},
},
async generateVideo(req) {
const pluginCfg = resolveVideoConfig(req.cfg, getPluginConfig?.());
const explicitApiKey = resolvePluginApiKey(pluginCfg?.apiKey) ??
normalizeOptionalString(process.env.OPENAI_VIDEO_API_KEY) ??
normalizeOptionalString(process.env.GEMINI_WEB2API_API_KEY) ??
normalizeOptionalString(process.env.CCLOAD_API_KEY);
let apiKey = explicitApiKey;
if (!apiKey) {
const { resolveApiKeyForProvider } = await import("openclaw/plugin-sdk/provider-auth-runtime");
const auth = await resolveApiKeyForProvider({
provider: "openai",
cfg: req.cfg,
agentDir: req.agentDir,
store: req.authStore,
modelApi: "openai-responses",
});
if (!auth.apiKey || (auth.mode !== undefined && auth.mode !== "api-key")) {
throw new Error("OpenAI API key missing");
}
apiKey = auth.apiKey;
}
const [{ assertOkOrThrowHttpError, createProviderOperationDeadline, createProviderOperationTimeoutResolver, pollProviderOperationJson, postJsonRequest, postMultipartRequest, readProviderJsonResponse, resolveProviderOperationTimeoutMs, resolveProviderHttpRequestConfig, sanitizeConfiguredModelProviderRequest, }, { downloadGeneratedVideoAsset, resolveGeneratedMediaMaxBytes },] = await Promise.all([
import("openclaw/plugin-sdk/provider-http"),
import("openclaw/plugin-sdk/media-generation-runtime"),
]);
const fetchFn = fetch;
const deadline = createProviderOperationDeadline({
timeoutMs: req.timeoutMs,
label: "OpenAI video generation",
});
const providerConfig = req.cfg.models?.providers?.openai;
const allowPrivate = pluginCfg?.allowPrivateNetwork ?? true;
const requestConfig = sanitizeConfiguredModelProviderRequest({
...providerConfig?.request,
allowPrivateNetwork: allowPrivate,
});
const { baseUrl, allowPrivateNetwork, headers, dispatcherPolicy } = resolveProviderHttpRequestConfig({
baseUrl: resolveConfiguredOpenAIBaseUrl(req.cfg, pluginCfg),
defaultBaseUrl: DEFAULT_OPENAI_VIDEO_BASE_URL,
allowPrivateNetwork: allowPrivate,
request: requestConfig,
defaultHeaders: {
Authorization: `Bearer ${apiKey}`,
},
provider: "openai",
capability: "video",
transport: "http",
});
const model = normalizeOptionalString(req.model) ??
normalizeOptionalString(pluginCfg?.defaultModel) ??
DEFAULT_OPENAI_VIDEO_MODEL;
const seconds = resolveDurationSeconds(req.durationSeconds);
const size = resolveSize(req);
const referenceAsset = resolveReferenceAsset(req);
const isVideoEdit = referenceAsset?.kind === "video";
const submitTimeoutMs = resolveProviderOperationTimeoutMs({
deadline,
defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
});
let response;
let release;
if (referenceAsset) {
const form = new FormData();
form.set("prompt", req.prompt);
if (isVideoEdit) {
form.set("video", referenceAsset.file);
}
else {
form.set("model", model);
if (seconds) {
form.set("seconds", seconds);
}
if (size) {
form.set("size", size);
}
form.set("input_reference", referenceAsset.file);
}
const multipartHeaders = new Headers(headers);
multipartHeaders.delete("Content-Type");
({ response, release } = await postMultipartRequest({
url: `${baseUrl}/videos${isVideoEdit ? "/edits" : ""}`,
headers: multipartHeaders,
body: form,
timeoutMs: submitTimeoutMs,
fetchFn,
allowPrivateNetwork,
dispatcherPolicy,
}));
}
else {
const jsonHeaders = new Headers(headers);
jsonHeaders.set("Content-Type", "application/json");
const jsonBody = {
model,
prompt: req.prompt,
...(seconds ? { seconds } : {}),
...(size ? { size } : {}),
};
({ response, release } = await postJsonRequest({
url: `${baseUrl}/videos`,
headers: jsonHeaders,
body: jsonBody,
timeoutMs: submitTimeoutMs,
fetchFn,
allowPrivateNetwork,
dispatcherPolicy,
}));
}
let submitted;
try {
await assertOkOrThrowHttpError(response, "OpenAI video generation failed");
submitted = await readProviderJsonResponse(response, "OpenAI video generation failed");
}
finally {
await release();
}
const failureMessage = readOpenAIVideoFailureMessage(submitted);
if (failureMessage) {
throw new Error(failureMessage);
}
const videoId = normalizeOptionalString(submitted.id);
if (!videoId) {
throw new Error("OpenAI video generation response missing video id");
}
const completed = submitted.status === "completed"
? submitted
: await pollProviderOperationJson({
url: `${baseUrl}/videos/${videoId}`,
headers,
deadline: createProviderOperationDeadline({
timeoutMs: resolveProviderOperationTimeoutMs({
deadline,
defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
}),
label: `OpenAI video generation task ${videoId}`,
}),
defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
fetchFn,
maxAttempts: MAX_POLL_ATTEMPTS,
pollIntervalMs: POLL_INTERVAL_MS,
requestFailedMessage: "OpenAI video status request failed",
timeoutMessage: `OpenAI video generation task ${videoId} did not finish in time`,
allowPrivateNetwork,
dispatcherPolicy,
auditContext: "openai-video-status",
isComplete: (payload) => payload.status === "completed",
getFailureMessage: readOpenAIVideoFailureMessage,
});
const url = new URL(`${baseUrl}/videos/${videoId}/content`);
url.searchParams.set("variant", "video");
const video = await downloadGeneratedVideoAsset({
url: url.toString(),
timeoutMs: createProviderOperationTimeoutResolver({
deadline,
defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
}),
defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
fetchFn,
provider: "openai",
label: "OpenAI generated video download",
requestFailedMessage: "OpenAI video download failed",
maxBytes: resolveGeneratedMediaMaxBytes(req.cfg, "video"),
validateBinaryResponse: true,
fetchResponse: async ({ deadline: downloadDeadline }) => await fetchOpenAIVideoDownload({
url: url.toString(),
init: {
method: "GET",
headers: new Headers({
...Object.fromEntries(headers.entries()),
Accept: "application/binary",
}),
},
deadline: downloadDeadline,
fetchFn,
allowPrivateNetwork,
dispatcherPolicy,
}),
});
return {
videos: [video],
model: completed.model ?? submitted.model ?? model,
metadata: {
videoId,
status: completed.status,
seconds: completed.seconds ?? submitted.seconds,
size: completed.size ?? submitted.size,
},
};
},
};
}
+157 -18
View File
@@ -1,8 +1,8 @@
{
"id": "1h-tools",
"name": "1-h Tools",
"description": "Custom Tools and Media Providers (Video & Image) for OpenClaw.",
"version": "0.3.0",
"description": "Custom Tools and Media Providers (OpenAI & Gemini) for OpenClaw.",
"version": "0.4.0",
"categories": [
"media",
"developer-tools"
@@ -16,7 +16,7 @@
"setup": {
"providers": [
{
"id": "1h-video",
"id": "1h-openai-video",
"envVars": [
"OPENAI_VIDEO_API_KEY",
"CCLOAD_API_KEY",
@@ -25,13 +25,21 @@
]
},
{
"id": "1h-image",
"id": "1h-openai-image",
"envVars": [
"OPENAI_IMAGE_API_KEY",
"BIFROST_API_KEY",
"CCLOAD_API_KEY",
"BIFROST_API_KEY",
"OPENAI_API_KEY"
]
},
{
"id": "1h-gemini-image",
"envVars": [
"CCLOAD_API_KEY",
"GEMINI_API_KEY",
"BIFROST_API_KEY"
]
}
]
},
@@ -40,14 +48,15 @@
"echo"
],
"videoGenerationProviders": [
"1h-video"
"1h-openai-video"
],
"imageGenerationProviders": [
"1h-image"
"1h-openai-image",
"1h-gemini-image"
]
},
"videoGenerationProviderMetadata": {
"1h-video": {
"1h-openai-video": {
"authSignals": [
{
"provider": "openai"
@@ -56,12 +65,19 @@
}
},
"imageGenerationProviderMetadata": {
"1h-image": {
"1h-openai-image": {
"authSignals": [
{
"provider": "openai"
}
]
},
"1h-gemini-image": {
"authSignals": [
{
"provider": "google"
}
]
}
},
"configContracts": {
@@ -72,21 +88,40 @@
"expected": "string",
"ownerKind": "capability"
},
{
"path": "openaiVideo.apiKey",
"expected": "string",
"ownerKind": "capability"
},
{
"path": "image.apiKey",
"expected": "string",
"ownerKind": "capability"
},
{
"path": "openaiImage.apiKey",
"expected": "string",
"ownerKind": "capability"
},
{
"path": "geminiImage.apiKey",
"expected": "string",
"ownerKind": "capability"
}
]
}
},
"uiHints": {
"video.apiKey": {
"label": "Video API Key",
"openaiVideo.apiKey": {
"label": "OpenAI Video API Key",
"sensitive": true
},
"image.apiKey": {
"label": "Image API Key",
"openaiImage.apiKey": {
"label": "OpenAI Image API Key",
"sensitive": true
},
"geminiImage.apiKey": {
"label": "Gemini Image API Key",
"sensitive": true
}
},
@@ -96,8 +131,7 @@
"properties": {
"video": {
"type": "object",
"title": "Video Generation Settings",
"description": "Configuration for video generation (openai-video)",
"title": "Video Generation Settings (Alias for openaiVideo)",
"additionalProperties": false,
"properties": {
"baseUrl": {
@@ -115,7 +149,37 @@
},
"defaultModel": {
"type": "string",
"default": "sora-2"
"default": "gemini-video"
},
"models": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"openaiVideo": {
"type": "object",
"title": "OpenAI Video Generation Settings (1h-openai-video)",
"additionalProperties": false,
"properties": {
"baseUrl": {
"type": "string"
},
"apiKey": {
"type": [
"string",
"object"
]
},
"allowPrivateNetwork": {
"type": "boolean",
"default": true
},
"defaultModel": {
"type": "string",
"default": "gemini-video"
},
"models": {
"type": "array",
@@ -127,8 +191,7 @@
},
"image": {
"type": "object",
"title": "Image Generation Settings",
"description": "Configuration for image generation (openai-image / bifrost-image)",
"title": "Image Generation Settings (Alias for openaiImage)",
"additionalProperties": false,
"properties": {
"baseUrl": {
@@ -148,6 +211,82 @@
"type": "string",
"default": "gpt-image-2"
},
"responseFormat": {
"type": "string",
"enum": [
"url",
"b64_json"
],
"default": "url"
},
"models": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"openaiImage": {
"type": "object",
"title": "OpenAI Image Generation Settings (1h-openai-image)",
"additionalProperties": false,
"properties": {
"baseUrl": {
"type": "string"
},
"apiKey": {
"type": [
"string",
"object"
]
},
"allowPrivateNetwork": {
"type": "boolean",
"default": true
},
"defaultModel": {
"type": "string",
"default": "gpt-image-2"
},
"responseFormat": {
"type": "string",
"enum": [
"url",
"b64_json"
],
"default": "url"
},
"models": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"geminiImage": {
"type": "object",
"title": "Gemini Image Generation Settings (1h-gemini-image)",
"additionalProperties": false,
"properties": {
"baseUrl": {
"type": "string"
},
"apiKey": {
"type": [
"string",
"object"
]
},
"allowPrivateNetwork": {
"type": "boolean",
"default": true
},
"defaultModel": {
"type": "string",
"default": "gemini-3.1-flash-image"
},
"models": {
"type": "array",
"items": {
+34 -31
View File
@@ -1,35 +1,33 @@
# 1-h Image Provider (`1h-image`)
# 1-h Image Providers (`1h-openai-image` & `1h-gemini-image`)
OpenClaw 图像生成驱动模块,适配标准 **OpenAI Images API**(`/v1/images/generations` 及 `/v1/images/edits` 规范)。
专为自建聚合网关或第三方中转(如 `Bifrost`、`ccLoad`)定制打造:
* **尺寸安全归一化**:修复官方驱动在反代环境下因 `16:9` 映射为 `2048x1152` 导致上游报 400 错误的 Bug(Issue #168665),自动将 `16:9` / `9:16` 适配为上游通用的安全比例规格(如 `1792x1024` / `1536x1024`)。
* **格式双模自适应**:同时支持解析上游返回的 `b64_json`(Base64 内存直解码)与 `url`(自动安全下载并保存为本地 Buffer),彻底杜绝 `response malformed` 解析失败。
* **图生图编辑支持**:当传入 `inputImages` 时,自动走 Multipart 表单发起编辑请求;纯文本生图时走轻量 JSON 请求。
* **私有网络与反代直通**:原生支持私有/内网端点请求(`allowPrivateNetwork: true`),兼容 `127.0.0.1`、`host.incus.internal` 或自建反代网关。
OpenClaw 图像生成驱动模块集合,根据上游协议严格分离为两个专职驱动,彻底杜绝跨协议调用引发的 400 错配。
---
## 标识符
## 包含驱动一览
* **Provider ID**:`1h-image`
* **默认模型**:`gpt-image-2`
* **支持模型列表**:`gpt-image-2`, `gpt-image-1.5`, `gemini-3.1-flash-image`(也可在配置中自定义扩展)
| Provider ID | 对应协议 | 默认模型 | 适用场景 / 支持模型 |
| :--- | :--- | :--- | :--- |
| **`1h-openai-image`** | OpenAI 标准图像协议<br>(`POST /v1/images/generations`) | `gpt-image-2` | 专为号池/公益站的 OpenAI 协议图像生成打造:<br>• `gpt-image-2`<br>• `gpt-image-2.5`<br>• `gpt-image-2.5-flare`<br>• `gpt-image-2.5-sunburst` |
| **`1h-gemini-image`** | Google Gemini 原生内容协议<br>(`POST /v1beta/models/...:generateContent`) | `gemini-3.1-flash-image` | 专为渠道 87(CLI-Proxy)的原生 Gemini 图像生成打造:<br>• `gemini-3.1-flash-image` |
---
## 核心特性
1. **`1h-openai-image`(OpenAI 协议)**:
* **尺寸安全映射**:自动将 16:9 / 9:16 安全归一化为通用尺寸(`1792x1024` / `1024x1792` / `1536x1024`),修复 Issue #168665;
* **URL 优先与双模自适应**:默认使用 `response_format=url`,完美契合公益站防 400 校验,并自动将链接异步下载为本地图片文件;
* **图生图编辑**:传入 `inputImages` 时自动切至 Multipart 表单走 `/v1/images/edits`。
2. **`1h-gemini-image`(Gemini 协议)**:
* **原生 JSON 结构**:以标准的 `contents[].parts` 构造请求,并在返回时原生提取 `inlineData` Base64 流;
* **无损回退链**:作为主模型的首选备用渠道,当 OpenAI 渠道拥堵超时时,以纯正 Gemini 协议秒级接管。
---
## 配置说明
支持通过 **Web 控制台(Control UI)** 或直接编辑 `~/.openclaw/openclaw.json`。
### 方式 1:Web 控制台可视化配置
进入 **Settings → Plugins → 1-h Tools**:
* **Image Base URL**:填写图像上游端点(例如 `https://Direct-Bifrost.oo1.dev/v1` 或内部反代地址)
* **Image API Key**:填写 API Key 或 SecretRef(留空时自动回退读取环境变量 `OPENAI_IMAGE_API_KEY`、`BIFROST_API_KEY`、`CCLOAD_API_KEY` 或 `OPENAI_API_KEY`)
* **Default Image Model**:例如 `gpt-image-2`
### 方式 2:编辑 `openclaw.json`
在 `~/.openclaw/openclaw.json` 中配置:
```json5
@@ -39,10 +37,17 @@ OpenClaw 图像生成驱动模块,适配标准 **OpenAI Images API**(`/v1/im
"1h-tools": {
"enabled": true,
"config": {
"image": {
"baseUrl": "https://Direct-Bifrost.oo1.dev/v1",
"apiKey": "sk-your-bifrost-key",
"openaiImage": {
"baseUrl": "http://host.incus.internal:8080/v1",
"defaultModel": "gpt-image-2",
"apiKey": "1842894d437ee54443a99390f79811ba9ebb785175af340b492e3398dc317921",
"responseFormat": "url",
"allowPrivateNetwork": true
},
"geminiImage": {
"baseUrl": "http://host.incus.internal:8080/v1beta",
"defaultModel": "gemini-3.1-flash-image",
"apiKey": "1842894d437ee54443a99390f79811ba9ebb785175af340b492e3398dc317921",
"allowPrivateNetwork": true
}
}
@@ -53,9 +58,9 @@ OpenClaw 图像生成驱动模块,适配标准 **OpenAI Images API**(`/v1/im
"defaults": {
"mediaModels": {
"image": {
"primary": "1h-image/gpt-image-2",
"primary": "1h-openai-image/gpt-image-2",
"fallbacks": [
"1h-image/gemini-3.1-flash-image"
"1h-gemini-image/gemini-3.1-flash-image"
]
}
}
@@ -69,7 +74,5 @@ OpenClaw 图像生成驱动模块,适配标准 **OpenAI Images API**(`/v1/im
## 使用方法
配置完成后,OpenClaw 内置的 `image_generate` 工具即可自动调度:
* **文本生成图像**:
> “生成一张 16:9 的秋日晨光现代书房桌面壁纸”
* **垫图修改/编辑**:
在对话中附带图片,提示助手基于该图进行风格调整或重绘。
* **正常请求**:默认走 `1h-openai-image/gpt-image-2`;
* **容灾回退**:若主模型超时(如公益站排队超时 499),系统自动使用纯正的 `1h-gemini-image/gemini-3.1-flash-image` 协议回退,绝不报 400。
+302
View File
@@ -0,0 +1,302 @@
import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
import type {
GeneratedImageAsset,
ImageGenerationProvider,
ImageGenerationRequest,
ImageGenerationResult,
} from "openclaw/plugin-sdk/image-generation";
const DEFAULT_GEMINI_IMAGE_BASE_URL = "http://host.incus.internal:8080/v1beta";
const DEFAULT_GEMINI_IMAGE_MODEL = "gemini-3.1-flash-image";
const DEFAULT_TIMEOUT_MS = 120_000;
export interface SecretRefObject {
source: string;
provider: string;
id: string;
}
export interface GeminiImagePluginConfig {
baseUrl?: string;
apiKey?: string | SecretRefObject;
allowPrivateNetwork?: boolean;
defaultModel?: string;
models?: string[];
}
export function resolvePluginApiKey(rawKey: string | SecretRefObject | undefined): string | undefined {
if (typeof rawKey === "string") {
const trimmed = rawKey.trim();
const envMatch = trimmed.match(/^\$\{([A-Za-z0-9_]+)\}$/);
if (envMatch) {
return normalizeOptionalString(process.env[envMatch[1]]);
}
return normalizeOptionalString(trimmed);
}
if (rawKey && typeof rawKey === "object" && typeof rawKey.id === "string") {
return normalizeOptionalString(process.env[rawKey.id]);
}
return undefined;
}
export function resolveGeminiImageConfig(
cfg: ImageGenerationRequest["cfg"] | undefined,
apiPluginConfig?: Record<string, unknown>,
): GeminiImagePluginConfig | undefined {
const toolsConfig = (apiPluginConfig ?? cfg?.plugins?.entries?.["1h-tools"]?.config) as
| {
geminiImage?: GeminiImagePluginConfig;
image?: GeminiImagePluginConfig;
}
| undefined;
return toolsConfig?.geminiImage ?? toolsConfig?.image;
}
export function resolveConfiguredGeminiImageBaseUrl(
pluginCfg?: GeminiImagePluginConfig,
): string {
return (
normalizeOptionalString(pluginCfg?.baseUrl) ??
normalizeOptionalString(process.env.GEMINI_IMAGE_BASE_URL) ??
DEFAULT_GEMINI_IMAGE_BASE_URL
);
}
export function buildGeminiImageGenerationProvider({
isProviderApiKeyConfigured,
getPluginConfig,
}: {
isProviderApiKeyConfigured: OpenClawPluginApi["runtime"]["modelAuth"]["isProviderApiKeyConfigured"];
getPluginConfig?: () => Record<string, unknown> | undefined;
}): ImageGenerationProvider {
return {
id: "1h-gemini-image",
label: "1-h Gemini Image",
defaultModel: DEFAULT_GEMINI_IMAGE_MODEL,
models: [DEFAULT_GEMINI_IMAGE_MODEL],
isConfigured: (ctx) => {
const pluginCfg = resolveGeminiImageConfig(ctx.cfg, getPluginConfig?.());
if (
resolvePluginApiKey(pluginCfg?.apiKey) ||
Boolean(pluginCfg?.apiKey) ||
normalizeOptionalString(process.env.CCLOAD_API_KEY) ||
normalizeOptionalString(process.env.GEMINI_API_KEY) ||
normalizeOptionalString(process.env.BIFROST_API_KEY)
) {
return true;
}
return isProviderApiKeyConfigured({
provider: "google",
...ctx,
profileTypes: ["api_key"],
});
},
capabilities: {
generate: {
maxCount: 1,
supportsSize: false,
supportsAspectRatio: true,
supportsResolution: false,
},
edit: {
enabled: true,
maxCount: 1,
maxInputImages: 3,
supportsSize: false,
supportsAspectRatio: true,
supportsResolution: false,
},
geometry: {
aspectRatios: ["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "21:9"],
},
output: {
formats: ["jpeg", "png"],
},
},
async generateImage(req: ImageGenerationRequest): Promise<ImageGenerationResult> {
const pluginCfg = resolveGeminiImageConfig(req.cfg, getPluginConfig?.());
const explicitApiKey =
resolvePluginApiKey(pluginCfg?.apiKey) ??
normalizeOptionalString(process.env.CCLOAD_API_KEY) ??
normalizeOptionalString(process.env.GEMINI_API_KEY) ??
normalizeOptionalString(process.env.BIFROST_API_KEY);
let apiKey = explicitApiKey;
if (!apiKey) {
const { resolveApiKeyForProvider } = await import(
"openclaw/plugin-sdk/provider-auth-runtime"
);
const auth = await resolveApiKeyForProvider({
provider: "google",
cfg: req.cfg,
agentDir: req.agentDir,
store: req.authStore,
});
if (!auth.apiKey) {
throw new Error("Gemini Image API key missing");
}
apiKey = auth.apiKey;
}
const [
{
assertOkOrThrowHttpError,
createProviderOperationDeadline,
postJsonRequest,
readProviderJsonResponse,
resolveProviderHttpRequestConfig,
resolveProviderOperationTimeoutMs,
sanitizeConfiguredModelProviderRequest,
},
] = await Promise.all([import("openclaw/plugin-sdk/provider-http")]);
const fetchFn = fetch;
const deadline = createProviderOperationDeadline({
timeoutMs: req.timeoutMs,
label: "Gemini Image Generation",
});
const rawBaseUrl = resolveConfiguredGeminiImageBaseUrl(pluginCfg);
const allowPrivate = pluginCfg?.allowPrivateNetwork ?? true;
const requestConfig = sanitizeConfiguredModelProviderRequest({
allowPrivateNetwork: allowPrivate,
});
const { baseUrl, allowPrivateNetwork, headers, dispatcherPolicy } =
resolveProviderHttpRequestConfig({
baseUrl: rawBaseUrl,
defaultBaseUrl: DEFAULT_GEMINI_IMAGE_BASE_URL,
allowPrivateNetwork: allowPrivate,
request: requestConfig,
defaultHeaders: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
provider: "google",
capability: "image",
transport: "http",
});
const model =
normalizeOptionalString(req.model) ??
normalizeOptionalString(pluginCfg?.defaultModel) ??
DEFAULT_GEMINI_IMAGE_MODEL;
const submitTimeoutMs = resolveProviderOperationTimeoutMs({
deadline,
defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
});
const parts: Array<Record<string, unknown>> = [];
const inputImages = req.inputImages ?? [];
for (const img of inputImages) {
parts.push({
inlineData: {
mimeType: img.mimeType || "image/jpeg",
data: img.buffer.toString("base64"),
},
});
}
parts.push({
text: req.prompt,
});
const jsonBody: Record<string, unknown> = {
contents: [
{
parts,
},
],
generationConfig: {
responseMimeType: "image/jpeg",
},
};
const normalizedBaseUrl = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
const url = `${normalizedBaseUrl}/models/${model}:generateContent`;
const { response, release } = await postJsonRequest({
url,
headers,
body: jsonBody,
timeoutMs: submitTimeoutMs,
fetchFn,
allowPrivateNetwork,
dispatcherPolicy,
});
interface GeminiGenerateContentResponse {
candidates?: Array<{
content?: {
parts?: Array<{
text?: string;
inlineData?: {
mimeType?: string;
data?: string;
};
}>;
};
finishReason?: string;
}>;
error?: {
code?: number;
message?: string;
status?: string;
};
}
let payload: GeminiGenerateContentResponse;
try {
await assertOkOrThrowHttpError(response, "Gemini image generation request failed");
payload = await readProviderJsonResponse<GeminiGenerateContentResponse>(
response,
"Gemini image generation failed",
);
} finally {
await release();
}
if (payload.error?.message) {
throw new Error(`Gemini image generation error: ${payload.error.message}`);
}
const candidateParts = payload.candidates?.[0]?.content?.parts ?? [];
const generatedImages: GeneratedImageAsset[] = [];
for (let i = 0; i < candidateParts.length; i++) {
const part = candidateParts[i];
if (part.inlineData?.data) {
const buffer = Buffer.from(part.inlineData.data, "base64");
const mimeType = part.inlineData.mimeType || "image/jpeg";
const ext = mimeType.includes("png") ? "png" : "jpg";
generatedImages.push({
buffer,
mimeType,
fileName: `image-${i + 1}.${ext}`,
});
}
}
if (generatedImages.length === 0) {
const textMessage = candidateParts.find((p) => p.text)?.text;
throw new Error(
textMessage
? `Gemini returned text instead of an image: ${textMessage}`
: "Gemini image generation returned no image data",
);
}
return {
images: generatedImages,
model,
metadata: {
finishReason: payload.candidates?.[0]?.finishReason,
},
};
},
};
}
+11 -6
View File
@@ -70,9 +70,14 @@ export function resolveImageConfig(
cfg: ImageGenerationRequest["cfg"] | undefined,
apiPluginConfig?: Record<string, unknown>,
): ImagePluginConfig | undefined {
const direct = apiPluginConfig?.image as ImagePluginConfig | undefined;
const fromCfg = cfg?.plugins?.entries?.["1h-tools"]?.config?.image as ImagePluginConfig | undefined;
return direct ?? fromCfg;
const toolsConfig = (apiPluginConfig ?? cfg?.plugins?.entries?.["1h-tools"]?.config) as
| {
openaiImage?: ImagePluginConfig;
image?: ImagePluginConfig;
}
| undefined;
return toolsConfig?.openaiImage ?? toolsConfig?.image;
}
export function resolveConfiguredImageBaseUrl(
@@ -128,10 +133,10 @@ export function buildOpenAIImageGenerationProvider({
getPluginConfig?: () => Record<string, unknown> | undefined;
}): ImageGenerationProvider {
return {
id: "1h-image",
label: "1-h Image",
id: "1h-openai-image",
label: "1-h OpenAI Image",
defaultModel: DEFAULT_OPENAI_IMAGE_MODEL,
models: [DEFAULT_OPENAI_IMAGE_MODEL, "gpt-image-1.5", "gemini-3.1-flash-image"],
models: [DEFAULT_OPENAI_IMAGE_MODEL, "gpt-image-2.5", "gpt-image-2.5-flare", "gpt-image-2.5-sunburst"],
isConfigured: (ctx) => {
const pluginCfg = resolveImageConfig(ctx.cfg, getPluginConfig?.());
if (
+5 -4
View File
@@ -7,7 +7,7 @@ describe("1h-tools", () => {
expect(getToolPluginMetadata(entry)?.tools.map((tool) => tool.name)).toEqual(["echo"]);
});
it("registers tool, video generation provider, and image generation provider", () => {
it("registers tool, video provider, and both image providers", () => {
const registeredTools: unknown[] = [];
const registeredVideoProviders: unknown[] = [];
const registeredImageProviders: unknown[] = [];
@@ -34,9 +34,10 @@ describe("1h-tools", () => {
expect(registeredTools[0]).toMatchObject({ name: "echo" });
expect(mockApi.registerVideoGenerationProvider).toHaveBeenCalledTimes(1);
expect(registeredVideoProviders[0]).toMatchObject({ id: "1h-video" });
expect(registeredVideoProviders[0]).toMatchObject({ id: "1h-openai-video" });
expect(mockApi.registerImageGenerationProvider).toHaveBeenCalledTimes(1);
expect(registeredImageProviders[0]).toMatchObject({ id: "1h-image" });
expect(mockApi.registerImageGenerationProvider).toHaveBeenCalledTimes(2);
expect(registeredImageProviders[0]).toMatchObject({ id: "1h-openai-image" });
expect(registeredImageProviders[1]).toMatchObject({ id: "1h-gemini-image" });
});
});
+14 -5
View File
@@ -2,13 +2,14 @@ import { jsonResult } from "openclaw/plugin-sdk/core";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { toolPluginMetadataSymbol } from "openclaw/plugin-sdk/tool-plugin";
import { echoTool } from "./tools/echo.js";
import { buildOpenAIVideoGenerationProvider } from "./video/index.js";
import { buildOpenAIImageGenerationProvider } from "./image/index.js";
import { buildOpenAIVideoGenerationProvider } from "./video/openai.js";
import { buildOpenAIImageGenerationProvider } from "./image/openai.js";
import { buildGeminiImageGenerationProvider } from "./image/gemini.js";
const entry = definePluginEntry({
id: "1h-tools",
name: "1-h Tools",
description: "Custom Tools and Media Providers for OpenClaw.",
description: "Custom Tools and Media Providers (OpenAI/Gemini) for OpenClaw.",
register(api) {
// 1. Register tools
api.registerTool({
@@ -22,7 +23,7 @@ const entry = definePluginEntry({
},
});
// 2. Register video generation provider
// 2. Register OpenAI-compatible video generation provider
api.registerVideoGenerationProvider(
buildOpenAIVideoGenerationProvider({
isProviderApiKeyConfigured: api.runtime.modelAuth.isProviderApiKeyConfigured,
@@ -30,13 +31,21 @@ const entry = definePluginEntry({
}),
);
// 3. Register image generation provider
// 3. Register OpenAI-compatible image generation provider
api.registerImageGenerationProvider(
buildOpenAIImageGenerationProvider({
isProviderApiKeyConfigured: api.runtime.modelAuth.isProviderApiKeyConfigured,
getPluginConfig: () => api.pluginConfig,
}),
);
// 4. Register Gemini-native image generation provider
api.registerImageGenerationProvider(
buildGeminiImageGenerationProvider({
isProviderApiKeyConfigured: api.runtime.modelAuth.isProviderApiKeyConfigured,
getPluginConfig: () => api.pluginConfig,
}),
);
},
});
+15 -17
View File
@@ -1,27 +1,25 @@
# 1-h Video Provider (`1h-video`)
# 1-h OpenAI Video Provider (`1h-openai-video`)
OpenClaw 视频生成驱动模块,适配标准 **OpenAI Videos API**(`/v1/videos` 规范)。
OpenClaw 视频生成驱动模块,专职适配标准 **OpenAI Videos API**(`/v1/videos` 规范)。
专为自建聚合网关或第三方中转(如 `gemini-web2api-go`、`ccLoad`)做了深度兼容修复:
专为自建聚合网关或第三方中转(如 `gemini-web2api-go`、`ccLoad`)定制:
* **任务创建**:`POST /v1/videos`。纯文本任务自动发送 JSON Body,避免第三方服务因不支持 Multipart 表单报 400 错误;带参考图/垫视频时使用标准 Multipart 表单。
* **状态轮询**:`GET /v1/videos/{id}`。兼容提取普通对象错误信息与字符串错误消息。
* **视频下载**:`GET /v1/videos/{id}/content`。流式下载 MP4 二进制视频流。
* **私有网络**:原生支持私有/内网端点请求(`allowPrivateNetwork: true`),兼容 `host.incus.internal`、Tailnet 或局域网反代地址。
* **私有网络**:原生支持私有/内网端点请求(`allowPrivateNetwork: true`),兼容 `host.incus.internal` 或局域网反代地址。
---
## 标识符
* **Provider ID**:`1h-openai-video`
* **默认模型**:`gemini-video`
* **支持模型**:`gemini-video`, `sora-2`, `sora-2-pro`
---
## 配置说明
支持通过 **Web 控制台(Control UI)** 或直接编辑 `~/.openclaw/openclaw.json`。
### 方式 1:Web 控制台可视化配置
进入 **Settings → Plugins → 1-h Tools**:
* **API Base URL**:填写视频上游端点(例如 `http://host.incus.internal:8083/v1` 或内部网关地址)
* **API Key**:填写 API Key 或 SecretRef(留空时自动回退读取环境变量 `OPENAI_VIDEO_API_KEY`、`CCLOAD_API_KEY` 或 `BIFROST_API_KEY`)
* **默认视频模型**:例如 `gemini-video` 或 `sora-2`
### 方式 2:编辑 `openclaw.json`
在 `~/.openclaw/openclaw.json` 中配置:
```json5
@@ -31,10 +29,10 @@ OpenClaw 视频生成驱动模块,适配标准 **OpenAI Videos API**(`/v1/vi
"1h-tools": {
"enabled": true,
"config": {
"video": {
"openaiVideo": {
"baseUrl": "http://host.incus.internal:8083/v1",
"apiKey": "sk-your-video-key",
"defaultModel": "gemini-video",
"apiKey": "sk-your-video-key",
"allowPrivateNetwork": true
}
}
@@ -45,7 +43,7 @@ OpenClaw 视频生成驱动模块,适配标准 **OpenAI Videos API**(`/v1/vi
"defaults": {
"mediaModels": {
"video": {
"primary": "1h-video/gemini-video"
"primary": "1h-openai-video/gemini-video"
}
}
}
+10 -5
View File
@@ -80,9 +80,14 @@ export function resolveVideoConfig(
cfg: VideoGenerationRequest["cfg"] | undefined,
apiPluginConfig?: Record<string, unknown>,
): VideoPluginConfig | undefined {
const direct = apiPluginConfig?.video as VideoPluginConfig | undefined;
const fromCfg = cfg?.plugins?.entries?.["1h-tools"]?.config?.video as VideoPluginConfig | undefined;
return direct ?? fromCfg;
const toolsConfig = (apiPluginConfig ?? cfg?.plugins?.entries?.["1h-tools"]?.config) as
| {
openaiVideo?: VideoPluginConfig;
video?: VideoPluginConfig;
}
| undefined;
return toolsConfig?.openaiVideo ?? toolsConfig?.video;
}
export function resolveConfiguredOpenAIBaseUrl(
@@ -241,8 +246,8 @@ export function buildOpenAIVideoGenerationProvider({
getPluginConfig?: () => Record<string, unknown> | undefined;
}): VideoGenerationProvider {
return {
id: "1h-video",
label: "1-h Video",
id: "1h-openai-video",
label: "1-h OpenAI Video",
defaultModel: DEFAULT_OPENAI_VIDEO_MODEL,
models: [DEFAULT_OPENAI_VIDEO_MODEL, "sora-2-pro", "gemini-video"],
isConfigured: (ctx) => {