Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(media): 支持自定义 OpenAI Images 来源

nanae49f565cab6b
diff --git a/apps/desktop/src/main/cindy-brain/__tests__/customImageChannel.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/customImageChannel.test.ts
new file mode 100644
index 0000000000..36bbfa54dc
--- /dev/null
+++ b/apps/desktop/src/main/cindy-brain/__tests__/customImageChannel.test.ts
@@ -0,0 +1,263 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { buildUserProvider, type Provider } from '@cindy/model-providers';
+import { createCustomImageChannel, registerCustomImageChannels } from '../customImageChannel.js';
+import { pruneDynamicImageChannels } from '../byokImageChannel.js';
+import { ImageChannelRegistry } from '../imageChannelRegistry.js';
+
+const MODEL = 'team/gpt-image-2.5-sunburst';
+const PNG = Buffer.from('89504e470d0a1a0a', 'hex');
+const folders: string[] = [];
+afterEach(async () => {
+ await Promise.all(
+ folders.splice(0).map((folder) => fs.rm(folder, { recursive: true, force: true })),
+ );
+});
+
+function provider(baseUrl = 'https://relay.example.invalid/proxy/v1'): Provider {
+ return buildUserProvider({
+ id: 'relay',
+ name: 'My relay',
+ auth: { method: 'apiKey' },
+ runtimes: {
+ pi: {
+ baseUrl,
+ wireProtocol: 'openai-chat',
+ imageApi: 'openai-images',
+ headers: { 'X-Team': 'drawing', 'Content-Type': 'wrong', Authorization: 'wrong-key' },
+ models: [
+ {
+ id: MODEL,
+ name: 'My image',
+ mode: 'image_generation',
+ modalities: { input: ['text', 'image'], output: ['image'] },
+ },
+ ],
+ },
+ codex: { baseUrl: 'https://other.example.invalid/v1', models: [] },
+ },
+ });
+}
+
+function harness(initial = provider()) {
+ let current: Provider | undefined = initial;
+ let owner = 'owner-a:1';
+ let pending = false;
+ let key: string | null = 'invalid-test-pi-key';
+ const readApiKey = vi.fn((agent) => (agent === 'pi' ? key : 'invalid-test-other-key'));
+ const fetchImplementation = vi.fn<typeof fetch>(
+ async () =>
+ new Response(JSON.stringify({ data: [{ b64_json: PNG.toString('base64') }] }), {
+ headers: { 'Content-Type': 'application/json' },
+ }),
+ );
+ const beforeDispatch = vi.fn();
+ const channel = createCustomImageChannel({
+ getProvider: () => current,
+ readApiKey,
+ getOwnerScopeKey: () => owner,
+ isOwnerBoundaryPending: () => pending,
+ fetchImplementation,
+ beforeDispatch,
+ });
+ return {
+ channel,
+ readApiKey,
+ fetchImplementation,
+ beforeDispatch,
+ setProvider: (value: Provider | undefined) => {
+ current = value;
+ },
+ setKey: (value: string | null) => {
+ key = value;
+ },
+ setOwner: (value: string) => {
+ owner = value;
+ },
+ setPending: (value: boolean) => {
+ pending = value;
+ },
+ };
+}
+
+describe('standalone custom OpenAI Images', () => {
+ it.each([
+ ['https://relay.example.invalid', 'https://relay.example.invalid/v1/images/generations'],
+ ['https://relay.example.invalid/v1/', 'https://relay.example.invalid/v1/images/generations'],
+ ['http://127.0.0.1:8080/sub2api/v1', 'http://127.0.0.1:8080/sub2api/v1/images/generations'],
+ ])('uses the configured endpoint %s, model and source runtime key', async (baseUrl, target) => {
+ const h = harness(provider(baseUrl));
+ expect(h.channel.ready()).toBe(true);
+ await h.channel.generateImage({
+ model: MODEL,
+ prompt: 'red circle',
+ size: '1024x1024',
+ quality: 'high',
+ });
+ const [url, init] = h.fetchImplementation.mock.calls[0]!;
+ expect(url).toBe(target);
+ expect(init?.headers).toEqual({
+ 'x-team': 'drawing',
+ authorization: 'Bearer invalid-test-pi-key',
+ 'Content-Type': 'application/json',
+ });
+ expect(init?.redirect).toBe('error');
+ expect(JSON.parse(String(init?.body))).toMatchObject({
+ model: MODEL,
+ prompt: 'red circle',
+ size: '1024x1024',
+ quality: 'high',
+ });
+ expect(h.readApiKey).not.toHaveBeenCalledWith('codex');
+ expect(h.beforeDispatch).toHaveBeenCalledWith(MODEL);
+ });
+
+ it('sends edits as multipart to the same source, retaining size, quality and reference bytes', async () => {
+ const h = harness();
+ const folder = await fs.mkdtemp(path.join(os.tmpdir(), 'cindy-custom-images-'));
+ folders.push(folder);
+ const imagePath = path.join(folder, 'reference.png');
+ await fs.writeFile(imagePath, PNG);
+ await h.channel.editImage({
+ model: MODEL,
+ prompt: 'blue circle',
+ imagePaths: [imagePath],
+ aspectRatio: '3:2',
+ quality: 'max',
+ });
+ const [url, init] = h.fetchImplementation.mock.calls[0]!;
+ expect(url).toBe('https://relay.example.invalid/proxy/v1/images/edits');
+ expect(init?.headers).not.toHaveProperty('Content-Type');
+ const form = init?.body as FormData;
+ expect(form.get('model')).toBe(MODEL);
+ expect(form.get('size')).toBe('1536x1024');
+ expect(form.get('quality')).toBe('max');
+ expect(Buffer.from(await (form.get('image[]') as Blob).arrayBuffer())).toEqual(PNG);
+ });
+
+ it('does not infer an Images API from chat compatibility or a model name', () => {
+ const source = provider();
+ delete source.routing.pi!.imageApi;
+ const h = harness(source);
+ expect(h.channel.ready()).toBe(false);
+ });
+
+ it('does not borrow another runtime when the model owner has no key or API declaration', async () => {
+ const h = harness();
+ h.setKey(null);
+ expect(h.channel.ready()).toBe(false);
+ await expect(h.channel.generateImage({ model: MODEL, prompt: 'circle' })).rejects.toThrow(
+ /未就绪/,
+ );
+ expect(h.fetchImplementation).not.toHaveBeenCalled();
+ expect(h.readApiKey).not.toHaveBeenCalledWith('codex');
+ });
+
+ it('filters unsupported models within a ready provider and rejects their dispatch', async () => {
+ const source = provider();
+ source.imageModels!.push({ id: 'other-image', name: 'Other', sourceAgent: 'codex' });
+ const h = harness(source);
+ const registry = new ImageChannelRegistry();
+ registry.register(source.id, h.channel);
+ expect(registry.isProviderReady(source.id)).toBe(true);
+ expect(registry.isProviderReady(source.id, MODEL)).toBe(true);
+ expect(registry.isProviderReady(source.id, 'other-image')).toBe(false);
+ expect(registry.isProviderEditReady(source.id, 'other-image')).toBe(false);
+ expect(() => registry.resolve(source.id, 'other-image')).toThrow(/未就绪/);
+ await expect(
+ h.channel.generateImage({ model: 'other-image', prompt: 'circle' }),
+ ).rejects.toThrow(/未就绪/);
+ });
+
+ it('uses updated configuration on the next call and releases revoked or removed connections', async () => {
+ const h = harness();
+ await h.channel.generateImage({ model: MODEL, prompt: 'circle' });
+ h.setProvider(provider('https://changed.example.invalid/v1'));
+ h.setKey('invalid-test-rotated-key');
+ await h.channel.generateImage({ model: MODEL, prompt: 'circle' });
+ expect(h.fetchImplementation.mock.calls[1]?.[0]).toBe(
+ 'https://changed.example.invalid/v1/images/generations',
+ );
+ expect(h.fetchImplementation.mock.calls[1]?.[1]?.headers).toMatchObject({
+ authorization: 'Bearer invalid-test-rotated-key',
+ });
+ h.setProvider(undefined);
+ expect(h.channel.ready()).toBe(false);
+ await expect(h.channel.generateImage({ model: MODEL, prompt: 'circle' })).rejects.toThrow(
+ /未就绪/,
+ );
+ expect(h.fetchImplementation).toHaveBeenCalledTimes(2);
+ });
+
+ it('rejects a changed endpoint/key in the await before paid dispatch', async () => {
+ const h = harness();
+ const request = h.channel.generateImage({ model: MODEL, prompt: 'circle' });
+ h.setKey('invalid-test-replaced-key');
+ await expect(request).rejects.toThrow(/配置已变化/);
+ expect(h.fetchImplementation).not.toHaveBeenCalled();
+ });
+
+ it('rejects results after an owner switch and hides sources during the boundary', async () => {
+ const h = harness();
+ h.fetchImplementation.mockImplementation(async () => {
+ h.setOwner('owner-b:2');
+ return new Response(JSON.stringify({ data: [{ b64_json: PNG.toString('base64') }] }));
+ });
+ await expect(h.channel.generateImage({ model: MODEL, prompt: 'circle' })).rejects.toThrow(
+ /账号已切换/,
+ );
+ h.setPending(true);
+ expect(h.channel.ready()).toBe(false);
+ });
+
+ it('supports explicitly unauthenticated loopback services without leaking chat auth headers', async () => {
+ const source = provider('http://127.0.0.1:8080/v1');
+ source.auth = { method: 'none' };
+ source.routing.pi!.authStrategy = 'none';
+ const h = harness(source);
+ await h.channel.generateImage({ model: MODEL, prompt: 'circle' });
+ expect(h.readApiKey).not.toHaveBeenCalled();
+ expect(h.fetchImplementation.mock.calls[0]?.[1]?.headers).toEqual({
+ 'x-team': 'drawing',
+ 'Content-Type': 'application/json',
+ });
+ source.routing.pi!.upstream = 'https://remote.example.invalid/v1';
+ expect(h.channel.ready()).toBe(false);
+ });
+
+ it('never switches sources or retries an upstream rejection', async () => {
+ const h = harness();
+ h.fetchImplementation.mockResolvedValue(
+ new Response(
+ JSON.stringify({
+ error: { message: 'model access denied', code: 'permission_denied' },
+ }),
+ { status: 403 },
+ ),
+ );
+ await expect(h.channel.generateImage({ model: MODEL, prompt: 'circle' })).rejects.toThrow(
+ /HTTP 403/,
+ );
+ expect(h.fetchImplementation).toHaveBeenCalledTimes(1);
+ });
+
+ it('prunes a custom channel before a reused ID becomes a native subscription', () => {
+ const source = provider();
+ const h = harness(source);
+ const registry = new ImageChannelRegistry();
+ const registered = new Set<string>();
+ registerCustomImageChannels(registry, [source], registered, () => h.channel);
+ registerCustomImageChannels(registry, [source], registered, () => {
+ throw new Error('duplicate');
+ });
+ expect(registry.resolve(source.id, MODEL)).toBe(h.channel);
+ const native = { ...source, auth: { method: 'oauth' as const, native: 'codex' as const } };
+ pruneDynamicImageChannels(registry, [native], new Set(), new Set(), registered);
+ expect(registry.hasProvider(source.id)).toBe(false);
+ expect(registered.size).toBe(0);
+ registerCustomImageChannels(registry, [native], registered, () => h.channel);
+ expect(registry.hasProvider(source.id)).toBe(false);
+ });
+});
diff --git a/apps/desktop/src/main/cindy-brain/byokImageChannel.ts b/apps/desktop/src/main/cindy-brain/byokImageChannel.ts
index 0154034abf..78f129cea8 100644
--- a/apps/desktop/src/main/cindy-brain/byokImageChannel.ts
+++ b/apps/desktop/src/main/cindy-brain/byokImageChannel.ts
@@ -21,6 +21,7 @@ import {
type CreateGatewayImageClientOptions,
} from '../cindy-proxy-media/api/gatewayImageClient.js';
import type { ImageChannel, ImageChannelRegistry } from './imageChannelRegistry.js';
+import { isCustomImageProvider } from './customImageChannel.js';
/**
* Consciousness aspect → gpt-image size enum. Mirrors LEGACY_SIZES in
@@ -111,6 +112,7 @@ export function pruneDynamicImageChannels(
providers: readonly Provider[],
registeredCodex: Set<string>,
registeredByok: Set<string>,
+ registeredCustom: Set<string> = new Set(),
): void {
const codexIds = new Set(providers.filter((provider) =>
!isOrganizationManagedProvider(provider) && provider.auth.native === 'codex',
@@ -118,8 +120,11 @@ export function pruneDynamicImageChannels(
const byokIds = new Set(providers.filter((provider) =>
isOrganizationManagedProvider(provider) && provider.imageModels?.length,
).map((provider) => provider.id));
- // Prune both kinds before registering either: their IDs can collide across owners.
- for (const [registered, current] of [[registeredCodex, codexIds], [registeredByok, byokIds]]) {
+ const customIds = new Set(providers.filter(isCustomImageProvider).map(provider => provider.id));
+ // Prune every dynamic kind before registration: IDs can collide across owners.
+ for (const [registered, current] of [
+ [registeredCodex, codexIds], [registeredByok, byokIds], [registeredCustom, customIds],
+ ]) {
for (const id of registered) {
if (current.has(id)) continue;
registry.unregister(id);
diff --git a/apps/desktop/src/main/cindy-brain/customImageChannel.ts b/apps/desktop/src/main/cindy-brain/customImageChannel.ts
new file mode 100644
index 0000000000..ac34254e93
--- /dev/null
+++ b/apps/desktop/src/main/cindy-brain/customImageChannel.ts
@@ -0,0 +1,207 @@
+/**
+ * Standalone OpenAI Images for user connections. The model's sourceAgent owns
+ * its endpoint, encrypted key and headers; chat compatibility alone never opts
+ * a connection into media. No supplier names or proxy-specific adapters.
+ */
+import { isLoopbackProviderUrl, type AgentKind, type Provider } from '@cindy/model-providers';
+import { normalizeImageParameters } from '../cindy-media/imageParameters.js';
+import {
+ createGatewayImageClient,
+ type CreateGatewayImageClientOptions,
+} from '../cindy-proxy-media/api/gatewayImageClient.js';
+import type { ImageChannel, ImageChannelRegistry } from './imageChannelRegistry.js';
+
+interface CustomImageConnection {
+ agent: AgentKind;
+ baseUrl: string;
+ headers: Record<string, string>;
+}
+
+export interface CustomImageChannelOptions {
+ getProvider(): Provider | undefined;
+ readApiKey(agent: AgentKind): string | null;
+ getOwnerScopeKey(): string;
+ isOwnerBoundaryPending(): boolean;
+ fetchImplementation: typeof fetch;
+ beforeDispatch(model: string): void;
+ logger?: CreateGatewayImageClientOptions['logger'];
+}
+
+/** Preserve gateway path prefixes, accepting either an API origin or a /v1 base. */
+function imagesBaseUrl(raw: string): string | null {
+ try {
+ const url = new URL(raw);
+ if (
+ !['http:', 'https:'].includes(url.protocol) ||
+ url.username ||
+ url.password ||
+ url.search ||
+ url.hash
+ )
+ return null;
+ const path = url.pathname.replace(/\/+$/, '');
+ url.pathname = path.endsWith('/v1') ? path : `${path}/v1`;
+ return url.toString().replace(/\/+$/, '');
+ } catch {
+ return null;
+ }
+}
+
+/** Explicit API-key/loopback connections only; native subscription auth stays in its channel. */
+export function isCustomImageProvider(provider: Provider): boolean {
+ return (
+ provider.source === 'user' &&
+ !provider.auth.native &&
+ (provider.auth.method === 'apiKey' || provider.auth.method === 'none') &&
+ (provider.imageModels?.length ?? 0) > 0 &&
+ Object.values(provider.routing).some((route) => route?.imageApi === 'openai-images')
+ );
+}
+
+function connectionForModel(
+ opts: CustomImageChannelOptions,
+ modelId: string,
+): CustomImageConnection | null {
+ const provider = opts.getProvider();
+ if (opts.isOwnerBoundaryPending() || !provider || !isCustomImageProvider(provider)) return null;
+ const media = provider.imageModels?.find((model) => model.id === modelId);
+ // Never borrow another runtime's credentials when the model's own route is missing.
+ const agent = media?.sourceAgent;
+ if (!agent) return null;
+ const route = provider.routing[agent];
+ const model = provider.models[agent]?.find((model) => model.id === modelId);
+ if (
+ !route ||
+ route.disabled ||
+ route.imageApi !== 'openai-images' ||
+ !model ||
+ route.headerOverrideState === 'unknown'
+ )
+ return null;
+ const upstream = model.route?.baseUrl ?? route.upstream;
+ const baseUrl = imagesBaseUrl(upstream);
+ if (!baseUrl || !imagesBaseUrl(route.upstream)) return null;
+ // Model overrides must stay within the credential owner's origin.
+ if (new URL(upstream).origin !== new URL(route.upstream).origin) return null;
+ const headers: Record<string, string> = {};
+ for (const [name, value] of Object.entries(route.headerOverride ?? {})) {
+ // Authentication belongs to this connection. Multipart boundaries, host and
+ // body length are generated by fetch, never inherited from chat headers.
+ const lower = name.toLowerCase();
+ if (
+ [
+ 'authorization',
+ 'x-api-key',
+ 'api-key',
+ 'cookie',
+ 'host',
+ 'content-type',
+ 'content-length',
+ 'connection',
+ 'chatgpt-account-id',
+ 'openai-account-id',
+ 'openai-beta',
+ 'originator',
+ 'session_id',
+ ].includes(lower)
+ )
+ continue;
+ headers[lower] = value;
+ }
+ for (const name of route.headerDelete ?? []) delete headers[name.toLowerCase()];
+ if (provider.auth.method === 'none') {
+ if (route.authStrategy !== 'none' || !isLoopbackProviderUrl(baseUrl)) return null;
+ } else {
+ if (route.authStrategy !== 'api-key-header') return null;
+ const key = opts.readApiKey(agent)?.trim();
+ if (!key) return null;
+ headers.authorization = `Bearer ${key}`;
+ }
+ return { agent, baseUrl, headers };
+}
+
+export function createCustomImageChannel(opts: CustomImageChannelOptions): ImageChannel {
+ const connection = (model: string) => connectionForModel(opts, model);
+ const ready = () =>
+ !opts.isOwnerBoundaryPending() &&
+ (opts.getProvider()?.imageModels ?? []).some((model) => connection(model.id) !== null);
+
+ const invoke = async (
+ operation: 'generate' | 'edit',
+ params: Parameters<ImageChannel['editImage']>[0],
+ ) => {
+ const owner = opts.getOwnerScopeKey();
+ const binding = connection(params.model);
+ if (!binding) throw new Error('所选图像来源的 OpenAI Images 接口或凭证未就绪');
+ const assertOwner = () => {
+ if (opts.isOwnerBoundaryPending() || owner !== opts.getOwnerScopeKey()) {
+ throw new Error('图像请求期间账号已切换,本次操作已取消');
+ }
+ };
+ const client = createGatewayImageClient({
+ getApiKey: () => null,
+ getRequestHeaders: () => binding.headers,
+ proxy: {
+ baseUrl: binding.baseUrl,
+ generatePath: '/images/generations',
+ editPath: '/images/edits',
+ },
+ brandLabel: opts.getProvider()?.name,
+ logger: opts.logger,
+ // Custom credential headers must never follow a redirect to another endpoint.
+ fetchImplementation: (url, init) => {
+ assertOwner();
+ return opts.fetchImplementation(url, { ...init, redirect: 'error' });
+ },
+ beforeDispatch: () => {
+ assertOwner();
+ params.signal?.throwIfAborted();
+ const current = connection(params.model);
+ if (
+ !current ||
+ current.agent !== binding.agent ||
+ current.baseUrl !== binding.baseUrl ||
+ JSON.stringify(current.headers) !== JSON.stringify(binding.headers)
+ ) {
+ throw new Error('图像来源配置已变化,本次请求未发出');
+ }
+ opts.beforeDispatch(params.model);
+ },
+ });
+ const normalized = normalizeImageParameters('openai', params.model, params);
+ const input = { model: params.model, prompt: params.prompt, ...normalized };
+ const result =
+ operation === 'edit'
+ ? await client.editImage({ ...input, imagePaths: params.imagePaths }, params.signal)
+ : await client.generateImage(input, params.signal);
+ assertOwner();
+ return result;
+ };
+
+ return {
+ imageProtocol: 'openai',
+ ready,
+ isModelReady: (model) => connection(model) !== null,
+ generateImage: (params) => invoke('generate', { ...params, imagePaths: [] }),
+ editImage: (params) => invoke('edit', params),
+ };
+}
+
+/** Synchronize user connections without overwriting built-in or native subscription channels. */
+export function registerCustomImageChannels(
+ registry: ImageChannelRegistry,
+ providers: readonly Provider[],
+ registered: Set<string>,
+ createChannel: (providerId: string) => ImageChannel,
+): void {
+ for (const provider of providers) {
+ if (
+ !isCustomImageProvider(provider) ||
+ registered.has(provider.id) ||
+ registry.hasProvider(provider.id)
+ )
+ continue;
+ registry.register(provider.id, createChannel(provider.id));
+ registered.add(provider.id);
+ }
+}
diff --git a/apps/desktop/src/main/cindy-brain/imageChannelRegistry.ts b/apps/desktop/src/main/cindy-brain/imageChannelRegistry.ts
index 36a472ddec..c94627c765 100644
--- a/apps/desktop/src/main/cindy-brain/imageChannelRegistry.ts
+++ b/apps/desktop/src/main/cindy-brain/imageChannelRegistry.ts
@@ -37,9 +37,9 @@ export function assertLibraryEditImageSource(relOrAbs: string): void {
}
}
-/** 通道适配层的出参(decodeImageResponse 的入参:字节 base64;声明格式仅作参考)。 */
+/** 通道适配层返回图片 base64 或下载 URL;Core 负责校验并保存受管媒体。 */
export interface ImageChannelResult {
- data: Array<{ b64_json?: string }>;
+ data: Array<{ b64_json?: string; url?: string | null }>;
output_format?: string;
}
@@ -67,6 +67,8 @@ export interface ImageChannel {
imageProtocol?: ImageProtocol;
/** 执行凭证是否就绪。false ⇒ 该来源整段不进 cindy 白名单。 */
ready(): boolean;
+ /** A multi-runtime connection can be executable for only some of its image models. */
+ isModelReady?(modelId: string): boolean;
/**
* 单次图像编辑可接收的源图上限。省略 = 沿用 cindy slot 的通用上限;
* provider 上限更低时在这里声明,让 slot 在读文件、取凭证、出网前按
@@ -106,27 +108,33 @@ export class ImageChannelRegistry {
this.channels.delete(providerId);
}
+ hasProvider(providerId: string): boolean {
+ return this.channels.has(providerId);
+ }
+
/** 白名单派生用:未注册 = 不就绪(目录数据先行时的乱序安全兜底)。 */
- isProviderReady(providerId: string): boolean {
- return this.channels.get(providerId)?.ready() === true;
+ isProviderReady(providerId: string, modelId?: string): boolean {
+ const channel = this.channels.get(providerId);
+ return channel?.ready() === true &&
+ (modelId === undefined || channel.isModelReady?.(modelId) !== false);
}
/** 编辑操作清单派生用:就绪且 supportsEdit !== false。 */
- isProviderEditReady(providerId: string): boolean {
+ isProviderEditReady(providerId: string, modelId?: string): boolean {
const ch = this.channels.get(providerId);
- return ch?.ready() === true && ch.supportsEdit !== false;
+ return this.isProviderReady(providerId, modelId) && ch?.supportsEdit !== false;
}
/**
* 派发用:取该来源的通道。未注册/未就绪时抛人话错——正常流程走不到这里
* (白名单派生已过滤),走到即说明白名单与派发窗口之间凭证被移除。
*/
- resolve(providerId: string): ImageChannel {
+ resolve(providerId: string, modelId?: string): ImageChannel {
const channel = this.channels.get(providerId);
if (!channel) {
throw new Error(`图像来源 ${providerId} 没有可用的执行通道`);
}
- if (!channel.ready()) {
+ if (!this.isProviderReady(providerId, modelId)) {
throw new Error(`图像来源 ${providerId} 的凭证未就绪,请先在设置中完成配置`);
}
return channel;
diff --git a/apps/desktop/src/main/cindy-brain/index.ts b/apps/desktop/src/main/cindy-brain/index.ts
index 79826b290f..63bc1a52e5 100644
--- a/apps/desktop/src/main/cindy-brain/index.ts
+++ b/apps/desktop/src/main/cindy-brain/index.ts
@@ -511,6 +511,7 @@ import {
pruneDynamicImageChannels,
registerByokImageChannels,
} from './byokImageChannel.js';
+import { createCustomImageChannel, registerCustomImageChannels } from './customImageChannel.js';
import { readByokCredential, readByokInferenceBase } from '../model-access/byokCredentials.js';
import { createXaiVideoProvider } from '../cindy-proxy-media/video/providers/xai.js';
import * as blobStore from '../cindy-media/blobStore.js';
@@ -3563,6 +3564,7 @@ function getCatalogMediaConfig(
selectedProviderId?: string,
): CindyMediaCatalogConfig {
try {
+ const imageRegistry = kind === 'image' ? getImageChannelRegistry() : null;
// 停用过滤:用户在 设置 → 模型供应商 停用的媒体模型 / 供应商不进候选清单
// (与对话模型的准入口径同源,见 model-disable-store)。
const access = readModelDisableOverrides();
@@ -3602,22 +3604,27 @@ function getCatalogMediaConfig(
// 目录默认指向它时回落清单首项;整份清单都不认识才是空清单 → NO_CANDIDATE。
// 执行侧那道防御保留 —— 它管的是这里与执行层之间的窗口。
(kind === 'embed' && !isKnownEmbeddingModel(modelId)) ||
+ // A ready provider may contain image models owned by an unready runtime.
+ (kind === 'image' && !imageRegistry?.isProviderReady(providerId, modelId)) ||
// 视频目录可能比当前客户端通道先热更。执行 registry 不认识的型号
// 必须先过滤,不能把“目录有”冒充成“这版客户端能下单”。
(kind === 'video' && !(videoRegistry?.hasAlias(modelId, providerId) ?? false)),
// 执行通道凭证就绪过滤(未就绪的来源整段不进白名单,见 imageChannelRegistry
// 头注)。视频按目录 provider 归属分别检查:xd 要求账号网关能力与 endpoint
// 同时在场,xai 要求 SuperGrok OAuth 已连接;未知来源 fail closed。
- // 向量仍只有 xd 一家执行通道。
+ // 向量仍只有 xd 一家执行通道。Standalone custom Images use Core media's
+ // managed URL/base64 handling; keep new sources out of the frozen legacy API.
kind === 'image'
- ? (providerId) => getImageChannelRegistry().isProviderReady(providerId)
+ ? (providerId) =>
+ !registeredCustomImageAccounts.has(providerId) &&
+ (imageRegistry?.isProviderReady(providerId) ?? false)
: kind === 'video'
? isVideoCatalogProviderReady
: isXdGatewayProviderReady,
// 编辑就绪过滤:仅支持生成的来源(supportsEdit: false)的模型不进编辑清单,
// 防用户把该型号钉到 image.edit 偏好后在 editImage 路径拿到确定性 400。
kind === 'image'
- ? (providerId) => getImageChannelRegistry().isProviderEditReady(providerId)
+ ? (providerId) => imageRegistry?.isProviderEditReady(providerId) ?? false
: undefined,
kind === 'image' || kind === 'video' ? isCatalogMediaModelVisible : undefined,
);
@@ -4164,6 +4171,7 @@ function getGhostImageCapabilities(
*/
const registeredCodexImageAccounts = new Set<string>();
const registeredByokImageAccounts = new Set<string>();
+const registeredCustomImageAccounts = new Set<string>();
let imageChannelRegistrySingleton: ImageChannelRegistry | null = null;
function getImageChannelRegistry(): ImageChannelRegistry {
if (!imageChannelRegistrySingleton) {
@@ -4308,6 +4316,7 @@ function getImageChannelRegistry(): ImageChannelRegistry {
imageProviders,
registeredCodexImageAccounts,
registeredByokImageAccounts,
+ registeredCustomImageAccounts,
);
for (const provider of imageProviders) {
if (
@@ -4360,6 +4369,20 @@ function getImageChannelRegistry(): ImageChannelRegistry {
});
},
);
+ registerCustomImageChannels(
+ imageChannelRegistrySingleton,
+ imageProviders,
+ registeredCustomImageAccounts,
+ (providerId) => createCustomImageChannel({
+ getProvider: () => getActiveCatalog().providers.find(provider => provider.id === providerId),
+ readApiKey: agent => readCustomProviderKey(providerId, agent),
+ getOwnerScopeKey: activeOwnerScopeKey,
+ isOwnerBoundaryPending: isGhostBoundaryPending,
+ fetchImplementation: ((url, init) => outboundFetch(url as string, init)) as typeof fetch,
+ beforeDispatch: model => assertMediaModelStillEnabled('image', model, providerId),
+ logger: log,
+ }),
+ );
return imageChannelRegistrySingleton;
}
@@ -4382,7 +4405,7 @@ function resolveImageChannelForModel(
if (operation === 'edit' && !exact.supportsEdit) {
throw new Error(`图像来源 ${providerId} 不支持图像编辑,请在设置中选择支持编辑的来源`);
}
- return getImageChannelRegistry().resolve(providerId);
+ return getImageChannelRegistry().resolve(providerId, model);
}
const entry = getCatalogMediaConfig('image').models.find((m) => m.id === model);
if (!entry) {
@@ -4393,7 +4416,7 @@ function resolveImageChannelForModel(
if (operation === 'edit' && !entry.supportsEdit) {
throw new Error(`图像来源 ${entry.providerId} 不支持图像编辑,请在设置中选择支持编辑的来源`);
}
- return getImageChannelRegistry().resolve(entry.providerId);
+ return getImageChannelRegistry().resolve(entry.providerId, model);
}
function listLocalProviderMediaModels(respectDisplaySwitch = false) {
@@ -4406,15 +4429,16 @@ function listLocalProviderMediaModels(respectDisplaySwitch = false) {
) {
return [];
}
- const supportsEdit = getImageChannelRegistry().isProviderEditReady(provider.id);
return (provider.imageModels ?? []).flatMap((model) => {
if (
+ !getImageChannelRegistry().isProviderReady(provider.id, model.id) ||
isModelDisabled(access, provider.id, model.id) ||
(respectDisplaySwitch &&
!isCatalogMediaModelVisible(provider.id, model.id, model.defaultEnabled))
) {
return [];
}
+ const supportsEdit = getImageChannelRegistry().isProviderEditReady(provider.id, model.id);
// Legacy/provider catalogs may only carry id/name. The channel registry is
// the executable capability source in that case: every registered image
// channel accepts text generation, and editable channels additionally
@@ -4521,6 +4545,8 @@ configureProviderMediaRuntime({
...normalizeImageParameters(channel.imageProtocol, request.modelId, request),
signal: request.signal,
});
+ const first = response.data[0];
+ if (!first?.b64_json && first?.url) return { url: first.url };
return decodeImageResponse(response);
},
});
diff --git a/apps/desktop/src/main/cindy-media/__tests__/invocationService.test.ts b/apps/desktop/src/main/cindy-media/__tests__/invocationService.test.ts
index 8f0da35df0..5bc28de0df 100644
--- a/apps/desktop/src/main/cindy-media/__tests__/invocationService.test.ts
+++ b/apps/desktop/src/main/cindy-media/__tests__/invocationService.test.ts
@@ -512,6 +512,61 @@ describe('Cindy Core media invocation state and security boundary', () => {
expect(mocks.providerInvoke).toHaveBeenCalledTimes(1);
});
+ it('redacts provider error credentials and never resubmits an uncertain paid request', async () => {
+ const model = { id: 'gpt-image-2', name: 'Image', providerId: 'custom-relay',
+ mode: 'image_generation', imageProtocol: 'openai',
+ modalities: { input: ['text', 'image'], output: ['image'] } };
+ mocks.models.mockResolvedValue([model]);
+ mocks.providerModel.mockReturnValue(model);
+ mocks.providerInvoke.mockRejectedValue(new Error(
+ 'HTTP 403: Bearer invalid-test-secret-123456789 https://relay.example.com/?key=secret',
+ ));
+ const prepared = await callCindyMedia({
+ action: 'prepare', providerId: model.providerId, modelId: model.id, capability: 'image.generate',
+ });
+ const result = await callCindyMedia({
+ action: 'request', invocationId: prepared.invocation_id as string, body: { prompt: 'circle' },
+ });
+ expect(result).toMatchObject({ ok: false, errorCode: 'SUBMISSION_OUTCOME_UNKNOWN' });
+ expect(result.message).toContain('HTTP 403');
+ expect(result.message).not.toContain('invalid-test-secret');
+ expect(result.message).not.toContain('key=secret');
+ await callCindyMedia({ action: 'request', invocationId: prepared.invocation_id as string,
+ body: { prompt: 'circle' } });
+ expect(mocks.providerInvoke).toHaveBeenCalledOnce();
+ });
+
+ it('persists a custom Images URL before download and resumes it without another paid invocation', async () => {
+ const model = { id: 'gpt-image-2', name: 'Image', providerId: 'custom-relay',
+ mode: 'image_generation', imageProtocol: 'openai',
+ modalities: { input: ['text', 'image'], output: ['image'] } };
+ mocks.models.mockResolvedValue([model]);
+ mocks.providerModel.mockReturnValue(model);
+ const url = 'https://cdn.example.com/generated.png?signature=opaque';
+ mocks.providerInvoke.mockResolvedValue({ url });
+ const prepared = await callCindyMedia({
+ action: 'prepare', providerId: model.providerId, modelId: model.id, capability: 'image.generate',
+ });
+ const invocationId = prepared.invocation_id as string;
+ mocks.confirm.mockResolvedValue(false);
+ expect(await callCindyMedia({
+ action: 'request', invocationId, body: { prompt: 'red circle' },
+ })).toMatchObject({ ok: false, errorCode: 'MEDIA_DOWNLOAD_DENIED', retryable: false, invocation_id: invocationId });
+ expect(mocks.rows.get(invocationId)).toMatchObject({ state: 'pending', responseJson: JSON.stringify({ url }) });
+ expect(mocks.outboundFetch).not.toHaveBeenCalled();
+
+ mocks.confirm.mockResolvedValue(true);
+ mocks.outboundFetch.mockResolvedValue(new Response(PNG, { headers: { 'Content-Type': 'image/png' } }));
+ expect(await callCindyMedia({
+ action: 'request', invocationId, body: { prompt: 'ignored; already generated' },
+ })).toMatchObject({ ok: true, status: 'complete', xdt_image_urls: [`cindy-media://blobs/${'a'.repeat(64)}.png`] });
+ expect(mocks.providerInvoke).toHaveBeenCalledTimes(1);
+ expect(mocks.outboundFetch).toHaveBeenCalledTimes(1);
+ expect(mocks.outboundFetch.mock.calls[0]?.[1]?.headers).toBeUndefined();
+ expect(mocks.guardedOutboundFetch).toHaveBeenCalledOnce();
+ expect(mocks.ingestMedia).toHaveBeenCalledOnce();
+ });
+
it.each([
['openai', 'account/gpt-image-2.5-sunburst', { size: '1760x3824', quality: 'max' }, { size: '1760x3824', quality: 'max' }],
['gemini', 'gemini/gemini-3-pro-image', { aspect_ratio: '16:9', resolution: '4k' }, { aspectRatio: '16:9', resolution: '4K' }],
diff --git a/apps/desktop/src/main/cindy-media/invocationService.ts b/apps/desktop/src/main/cindy-media/invocationService.ts
index b99efba763..dd8d7185b9 100644
--- a/apps/desktop/src/main/cindy-media/invocationService.ts
+++ b/apps/desktop/src/main/cindy-media/invocationService.ts
@@ -198,7 +198,7 @@ function providerImageGuide(
schemaVersion: MODEL_ACCESS_INVOCATION_GUIDE_SCHEMA_VERSION,
guideId: CLIENT_PROVIDER_IMAGE_GUIDE_ID,
modelId: model.id,
- revision: '2',
+ revision: '3',
connection: { providerId: model.providerId },
capability,
request: {
@@ -212,7 +212,10 @@ function providerImageGuide(
},
response: {
mode: 'sync',
- media: [{ path: ['image'], encoding: 'base64', kind: 'image' }],
+ media: [
+ { path: ['image'], encoding: 'base64', kind: 'image' },
+ { path: ['url'], encoding: 'url', kind: 'image' },
+ ],
},
instructions: edit
? '必填 prompt 和 image。image 可传一条 Cindy 本地媒体引用或引用数组。尺寸与质量参数见 inputSchema;不要丢弃用户的明确要求。'
@@ -1020,6 +1023,23 @@ async function submitProviderInvocation(
signal: AbortSignal.timeout(invocation.guide.request.timeoutMs),
});
assertAuthScope(scope, invocation.owner);
+ if ('url' in result) {
+ // Persist the successful generation before downloading. A denied/failed
+ // CDN download can resume this result without paying for another image.
+ const response = { url: result.url };
+ const responseJson = JSON.stringify(response);
+ const persisted = await transitionMediaInvocation(
+ { id: invocation.id, owner: invocation.owner, from: 'submitting', to: 'pending', responseJson },
+ db,
+ );
+ assertAuthScope(scope, invocation.owner);
+ if (!persisted) {
+ return submissionOutcomeUnknown('第三方媒体已生成,但本地未能保存结果;不要自动重提');
+ }
+ return materializeSyncInvocation(
+ { ...invocation, state: 'pending', responseJson }, response, scope, db,
+ );
+ }
if (
result.buffer.byteLength === 0 ||
result.buffer.byteLength > MAX_IMAGE_RESULT_BYTES ||
@@ -1082,11 +1102,11 @@ async function submitProviderInvocation(
log.warn('provider media submission failed after claim', {
providerId,
modelId: providerModel.id,
- error: error instanceof Error ? error.message : String(error),
+ error: mediaErrorForLog(error),
});
return submissionOutcomeUnknown(
error instanceof Error
- ? `第三方媒体请求未能确认结果:${error.message}`
+ ? `第三方媒体请求未能确认结果:${mediaErrorForLog(error)}`
: '第三方媒体请求未能确认结果;不要自动重提',
);
}
@@ -1308,6 +1328,9 @@ async function submitInvocation(
if (!media || typeof media !== 'object' || Array.isArray(media)) {
return failure('MEDIA_RESULT_INVALID', '第三方媒体调用保存的结果不合法');
}
+ if ('url' in media) {
+ return materializeSyncInvocation(invocation, media, scope, db);
+ }
return persistCompletedInvocation(invocation, media as Record<string, unknown>, scope, db);
}
if (
diff --git a/apps/desktop/src/main/cindy-media/providerMediaRuntime.ts b/apps/desktop/src/main/cindy-media/providerMediaRuntime.ts
index ebd5f4e896..75cc677cf5 100644
--- a/apps/desktop/src/main/cindy-media/providerMediaRuntime.ts
+++ b/apps/desktop/src/main/cindy-media/providerMediaRuntime.ts
@@ -21,10 +21,10 @@ export interface ProviderMediaRuntimeRequest extends ImageParameters {
signal?: AbortSignal;
}
-export interface ProviderMediaRuntimeResult {
+export type ProviderMediaRuntimeResult = {
buffer: Buffer;
mimeType: string;
-}
+} | { url: string };
interface ProviderMediaRuntime {
listModels(): ProviderMediaRuntimeModel[];
diff --git a/apps/desktop/src/main/cindy-proxy-media/api/gatewayImageClient.ts b/apps/desktop/src/main/cindy-proxy-media/api/gatewayImageClient.ts
index 61464ab731..3002895b46 100644
--- a/apps/desktop/src/main/cindy-proxy-media/api/gatewayImageClient.ts
+++ b/apps/desktop/src/main/cindy-proxy-media/api/gatewayImageClient.ts
@@ -26,6 +26,8 @@ export class GatewayImageError extends Error {
export interface CreateGatewayImageClientOptions {
getApiKey(): CindyProxyMediaMaybePromise<string | null>;
+ /** Host-owned connection headers; used by standalone custom Images connections. */
+ getRequestHeaders?(): CindyProxyMediaMaybePromise<Record<string, string>>;
proxy: CindyProxyMediaProxyConfig;
fetchImplementation?: typeof fetch;
logger?: LiziMcpLogger;
@@ -204,6 +206,11 @@ export function createGatewayImageClient(opts: CreateGatewayImageClientOptions):
return key;
}
+ async function requestHeaders(): Promise<Record<string, string>> {
+ if (opts.getRequestHeaders) return { ...await opts.getRequestHeaders() };
+ return { Authorization: `Bearer ${await requireApiKey()}` };
+ }
+
function assertSizeQualityAllowed(params: { size?: string; quality?: string }): void {
if (allowSizeQuality) return;
if (params.size !== undefined || params.quality !== undefined) {
@@ -219,7 +226,7 @@ export function createGatewayImageClient(opts: CreateGatewayImageClientOptions):
signal?: AbortSignal,
): Promise<GatewayImageResponse> {
assertSizeQualityAllowed(params);
- const apiKey = await requireApiKey();
+ const headers = await requestHeaders();
const body: Record<string, unknown> = {
model: params.model,
prompt: params.prompt,
@@ -237,7 +244,7 @@ export function createGatewayImageClient(opts: CreateGatewayImageClientOptions):
{
method: 'POST',
headers: {
- Authorization: `Bearer ${apiKey}`,
+ ...headers,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
@@ -257,7 +264,7 @@ export function createGatewayImageClient(opts: CreateGatewayImageClientOptions):
throw new GatewayImageError(`${brandLabel} 图像通道不支持改图,请换支持改图的模型`, 400);
}
assertSizeQualityAllowed(params);
- const apiKey = await requireApiKey();
+ const headers = await requestHeaders();
if (params.imagePaths.length === 0) {
throw new GatewayImageError('image_edit requires at least 1 image', 400);
}
@@ -285,9 +292,7 @@ export function createGatewayImageClient(opts: CreateGatewayImageClientOptions):
editUrl,
{
method: 'POST',
- headers: {
- Authorization: `Bearer ${apiKey}`,
- },
+ headers,
body: form as unknown as BodyInit,
signal,
},
diff --git a/apps/desktop/src/main/maker-host/__tests__/custom-provider-store.test.ts b/apps/desktop/src/main/maker-host/__tests__/custom-provider-store.test.ts
index f496e86deb..d4fb3719d6 100644
--- a/apps/desktop/src/main/maker-host/__tests__/custom-provider-store.test.ts
+++ b/apps/desktop/src/main/maker-host/__tests__/custom-provider-store.test.ts
@@ -493,6 +493,29 @@ describe('validateCustomProviderConfig (per-runtime)', () => {
});
describe('custom-provider-store CRUD (per-runtime)', () => {
+ it('round-trips an explicit standalone Images API independently of chat wire and hosted tools', async () => {
+ mountDb();
+ const config = {
+ id: 'standalone-images', name: 'Standalone images',
+ runtimes: { pi: {
+ baseUrl: 'http://127.0.0.1:8080/v1', wireProtocol: 'openai-chat' as const,
+ imageApi: 'openai-images' as const,
+ models: [{ id: 'gpt-image-2', name: 'Image', mode: 'image_generation' }],
+ } },
+ };
+ expect(validateCustomProviderConfig(config)).toEqual({ ok: true });
+ expect(validateCustomProviderConfig({
+ ...config, runtimes: { pi: { ...config.runtimes.pi, imageApi: 'private-cli' } },
+ }).ok).toBe(false);
+ await createCustomProvider(config);
+ const stored = await getCustomProvider(config.id);
+ expect(stored?.runtimes.pi?.imageApi).toBe('openai-images');
+ expect(stored?.runtimes.pi?.supportsImageGeneration).toBeUndefined();
+ const { imageApi: _removed, ...runtime } = config.runtimes.pi;
+ await updateCustomProvider(config.id, { ...config, runtimes: { pi: runtime } });
+ expect((await getCustomProvider(config.id))?.runtimes.pi?.imageApi).toBeUndefined();
+ });
+
it('accepts image generation only for a Codex runtime with an OpenAI Responses route', () => {
const model = { id: 'image-chat', name: 'Image Chat' };
expect(
diff --git a/apps/desktop/src/main/maker-host/custom-provider-store.ts b/apps/desktop/src/main/maker-host/custom-provider-store.ts
index 761d966850..9aa9003c38 100644
--- a/apps/desktop/src/main/maker-host/custom-provider-store.ts
+++ b/apps/desktop/src/main/maker-host/custom-provider-store.ts
@@ -231,6 +231,9 @@ function validateRuntime(agent: string, rt: unknown): ValidationResult {
if (r.supportsImageGeneration === true && agent !== 'codex') {
return invalid(`runtime '${agent}' supportsImageGeneration requires Codex`);
}
+ if (r.imageApi !== undefined && r.imageApi !== 'openai-images') {
+ return invalid(`runtime '${agent}' imageApi must be openai-images`);
+ }
if (!Array.isArray(r.models)) return invalid(`runtime '${agent}' models must be an array`);
for (const m of r.models) {
if (!m || typeof m !== 'object') return invalid(`runtime '${agent}' model must be an object`);
@@ -634,6 +637,7 @@ function normalizeRuntime(
if (agent === 'codex' && rt.supportsImageGeneration === true) {
out.supportsImageGeneration = true;
}
+ if (rt.imageApi === 'openai-images') out.imageApi = rt.imageApi;
if (agent !== 'pi' && rt.requestPath && rt.requestPath.trim()) {
out.requestPath = rt.requestPath.trim();
}
@@ -855,6 +859,7 @@ function parseRuntimes(raw: string): Partial<Record<AgentKind, CustomProviderRun
if (agent === 'codex' && r.supportsImageGeneration === true) {
entry.supportsImageGeneration = true;
}
+ if (r.imageApi === 'openai-images') entry.imageApi = r.imageApi;
if (agent !== 'pi' && isProviderRequestPath(r.requestPath)) {
entry.requestPath = r.requestPath;
}
diff --git a/apps/desktop/src/renderer/components/settings/ProviderConnectionDialog.tsx b/apps/desktop/src/renderer/components/settings/ProviderConnectionDialog.tsx
index 644b5dda43..93e63167d7 100644
--- a/apps/desktop/src/renderer/components/settings/ProviderConnectionDialog.tsx
+++ b/apps/desktop/src/renderer/components/settings/ProviderConnectionDialog.tsx
@@ -1,6 +1,6 @@
import { useDialogExit } from '@/hooks/useDialogExit';
import { WINDOW_DRAG_STYLE, WINDOW_NO_DRAG_STYLE } from '@/components/layout/windowDrag';
-import { providerEndpointBindings, canonicalProviderEndpoint, BUNDLED_CATALOG, classifyModel, isChatEligible, isAgentSelectableModel, mergeModelMetadata } from '@cindy/model-providers';
+import { providerEndpointBindings, canonicalProviderEndpoint, BUNDLED_CATALOG, mergeModelMetadata } from '@cindy/model-providers';
/**
* Connection credentials and advanced routing only. Model capabilities are imported into the
* shared catalog and edited through standard model settings. Stored per-runtime credentials,
@@ -195,6 +195,8 @@ interface RuntimeFields extends RuntimeFillDraft {
catalogPresetId?: string;
/** Codex Responses runtime 级原生图片生成能力。 */
supportsImageGeneration: boolean;
+ /** Standalone Images API, independent of the Codex Responses hosted tool. */
+ imageApi?: 'openai-images';
}
function runtimeProbeFields(agent: DialogAgentKind, runtime: RuntimeFields): RuntimeFields {
@@ -278,6 +280,7 @@ function initRuntimes(initial?: CustomProviderConfig): Record<DialogAgentKind, R
piCatalogProviderId: rc.piCatalogProviderId,
catalogPresetId: rc.catalogPresetId,
supportsImageGeneration: a === 'codex' && rc.supportsImageGeneration === true,
+ imageApi: rc.imageApi,
headersState: rc.headersState,
});
}
@@ -1685,6 +1688,7 @@ export function ProviderConnectionDialog({
...(a === 'codex' && rf.supportsImageGeneration && canRuntimeUseNativeImageGeneration(rf)
? { supportsImageGeneration: true }
: {}),
+ ...(rf.imageApi ? { imageApi: rf.imageApi } : {}),
models,
...(Object.keys(savedHeaders).length > 0 ? { headers: savedHeaders } : {}),
...(rf.modelsUrl.trim() ? { modelsUrl: rf.modelsUrl.trim() } : {}),
@@ -2532,6 +2536,34 @@ export function ProviderConnectionDialog({
</button>
</div>
+ {authMode !== 'oauth' && (
+ <div className="flex flex-col gap-1.5 border-t border-[var(--border-default)] pt-3">
+ <label className="flex cursor-pointer items-center gap-2 text-13 text-[var(--settings-section-title)]">
+ <input
+ type="checkbox"
+ id={fieldId(`${activeTab}:image-api`)}
+ aria-describedby={fieldId(`${activeTab}:image-api-hint`)}
+ checked={f.imageApi === 'openai-images'}
+ onChange={(event) => {
+ const enabled = event.currentTarget.checked;
+ patch(activeTab, (runtime) => ({
+ ...runtime,
+ imageApi: enabled ? 'openai-images' : undefined,
+ }));
+ }}
+ className="h-4 w-4 shrink-0 cursor-pointer accent-[var(--settings-menu-text-selected)]"
+ />
+ {t('settings.providers.custom.fields.openaiImages')}
+ </label>
+ <p
+ id={fieldId(`${activeTab}:image-api-hint`)}
+ className="text-12 leading-5 text-[var(--settings-section-desc)]"
+ >
+ {t('settings.providers.custom.fields.openaiImagesHint')}
+ </p>
+ </div>
+ )}
+
{/* Codex Responses Provider 级能力。放在自定义请求头之后,默认收起;
同一张说明卡片支持 hover/focus 临时预览和 click/tap 固定。 */}
{canShowImageGenerationAdvanced && (
diff --git a/apps/desktop/src/renderer/components/settings/__tests__/CustomProviderDialogAccessibility.test.tsx b/apps/desktop/src/renderer/components/settings/__tests__/CustomProviderDialogAccessibility.test.tsx
index c0a9fcee87..b465d9166f 100644
--- a/apps/desktop/src/renderer/components/settings/__tests__/CustomProviderDialogAccessibility.test.tsx
+++ b/apps/desktop/src/renderer/components/settings/__tests__/CustomProviderDialogAccessibility.test.tsx
@@ -50,6 +50,36 @@ beforeEach(() => {
afterEach(cleanup);
+it('retains standalone Images on edit and saves only the selected runtime when toggled off', async () => {
+ const initial: CustomProviderConfig = {
+ id: 'images', name: 'Images', auth: { method: 'apiKey' },
+ runtimes: { pi: {
+ baseUrl: 'https://images.example.test/v1', wireProtocol: 'openai-chat',
+ imageApi: 'openai-images',
+ models: [{ id: 'gpt-image-2', name: 'Image', mode: 'image_generation' }],
+ } },
+ };
+ customProviderMocks.readCustomProviderKey.mockResolvedValue('invalid-test-key');
+ const user = userEvent.setup();
+ render(<ProviderConnectionDialog initial={initial} focusAgent="pi" onSaved={vi.fn()} onClose={vi.fn()} />);
+ await waitForInitialDialogFocus();
+ const checkbox = screen.getByLabelText('settings.providers.custom.fields.openaiImages');
+ expect((checkbox as HTMLInputElement).checked).toBe(true);
+ await user.click(screen.getByRole('button', { name: 'settings.providers.custom.save' }));
+ await waitFor(() => expect(customProviderMocks.updateCustomProvider).toHaveBeenCalledOnce());
+ expect(customProviderMocks.updateCustomProvider.mock.calls[0]?.[0].runtimes.pi).toMatchObject({
+ imageApi: 'openai-images',
+ });
+ cleanup();
+ render(<ProviderConnectionDialog initial={initial} focusAgent="pi" onSaved={vi.fn()} onClose={vi.fn()} />);
+ await waitForInitialDialogFocus();
+ await user.click(screen.getByLabelText('settings.providers.custom.fields.openaiImages'));
+ await user.click(screen.getByRole('button', { name: 'settings.providers.custom.save' }));
+ await waitFor(() => expect(customProviderMocks.updateCustomProvider).toHaveBeenCalledTimes(2));
+ expect(customProviderMocks.updateCustomProvider.mock.calls[1]?.[0].runtimes.pi.imageApi).toBeUndefined();
+ expect(initial.runtimes.pi?.imageApi).toBe('openai-images');
+});
+
async function waitForInitialDialogFocus(): Promise<void> {
const nameInput = screen.getByPlaceholderText('settings.providers.custom.fields.namePlaceholder');
await waitFor(() => expect(document.activeElement).toBe(nameInput));
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index 92238be91a..b6133dc177 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -2482,6 +2482,8 @@
"modelSupportsImageInput": "Supports image input",
"modelSupportsImageInputHelp": "Enable only when the model actually accepts visual input. Start a new Pi task after saving.",
"runtimeAdvanced": "Advanced",
+ "openaiImages": "Use OpenAI Images API",
+ "openaiImagesHint": "Enable only if this connection provides /images/generations and /images/edits. Art uses this connection’s address, key and image models. Chat API compatibility alone is insufficient.",
"runtimeSupportsImageGeneration": "Supports image generation and editing",
"runtimeSupportsImageGenerationHelpLabel": "About image generation and editing support",
"runtimeSupportsImageGenerationConditionTitle": "When to enable",
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index bdf64eb03e..3eeed92bc5 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -2476,6 +2476,8 @@
"modelSupportsImageInput": "画像入力に対応",
"modelSupportsImageInputHelp": "モデルが実際に画像入力へ対応している場合のみ有効にしてください。保存後、新しい Pi タスクで反映されます。",
"runtimeAdvanced": "詳細設定",
+ "openaiImages": "OpenAI Images API を使用",
+ "openaiImagesHint": "この接続が /images/generations と /images/edits を提供する場合のみ有効にしてください。Art はこの接続のアドレス、キー、画像モデルを使用します。チャット API との互換性だけでは画像を生成できません。",
"runtimeSupportsImageGeneration": "画像の生成と編集に対応",
"runtimeSupportsImageGenerationHelpLabel": "画像の生成と編集への対応について",
"runtimeSupportsImageGenerationConditionTitle": "適用条件",
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index 1c1ff213a6..81a7f0fe24 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -2476,6 +2476,8 @@
"modelSupportsImageInput": "이미지 입력 지원",
"modelSupportsImageInputHelp": "모델이 실제로 시각 입력을 지원할 때만 켜세요. 저장 후 새 Pi 작업부터 적용됩니다.",
"runtimeAdvanced": "고급",
+ "openaiImages": "OpenAI Images API 사용",
+ "openaiImagesHint": "이 연결이 /images/generations와 /images/edits를 제공할 때만 켜세요. Art는 이 연결의 주소, 키, 이미지 모델을 사용합니다. 채팅 API 호환성만으로는 이미지를 생성할 수 없습니다.",
"runtimeSupportsImageGeneration": "이미지 생성 및 편집 지원",
"runtimeSupportsImageGenerationHelpLabel": "이미지 생성 및 편집 지원 정보",
"runtimeSupportsImageGenerationConditionTitle": "적용 조건",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index 772af988cb..2e241da7eb 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -2476,6 +2476,8 @@
"modelSupportsImageInput": "支持图片输入",
"modelSupportsImageInputHelp": "仅在该模型确实支持视觉输入时开启。保存后新建 Pi 任务生效。",
"runtimeAdvanced": "高级",
+ "openaiImages": "使用 OpenAI Images 接口",
+ "openaiImagesHint": "仅在此连接提供 /images/generations 和 /images/edits 时开启。Art 使用此连接的地址、密钥和图片模型;兼容对话接口并不代表支持出图。",
"runtimeSupportsImageGeneration": "支持图片生成与编辑",
"runtimeSupportsImageGenerationHelpLabel": "了解图片生成与编辑支持",
"runtimeSupportsImageGenerationConditionTitle": "适用条件",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index 039e68b03f..9995a81ad4 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -2476,6 +2476,8 @@
"modelSupportsImageInput": "支援圖片輸入",
"modelSupportsImageInputHelp": "僅在該模型確實支援視覺輸入時開啟。儲存後新建 Pi 任務生效。",
"runtimeAdvanced": "進階",
+ "openaiImages": "使用 OpenAI Images 介面",
+ "openaiImagesHint": "僅在此連線提供 /images/generations 和 /images/edits 時開啟。Art 使用此連線的位址、金鑰和圖片模型;相容對話介面並不代表支援產生圖片。",
"runtimeSupportsImageGeneration": "支援圖片生成與編輯",
"runtimeSupportsImageGenerationHelpLabel": "瞭解圖片生成與編輯支援",
"runtimeSupportsImageGenerationConditionTitle": "適用條件",
diff --git a/apps/desktop/src/renderer/lib/__tests__/customProviders.test.ts b/apps/desktop/src/renderer/lib/__tests__/customProviders.test.ts
index bb9d523f7e..f607354753 100644
--- a/apps/desktop/src/renderer/lib/__tests__/customProviders.test.ts
+++ b/apps/desktop/src/renderer/lib/__tests__/customProviders.test.ts
@@ -527,6 +527,7 @@ describe('providerViewToCustomProviderConfig', () => {
authStrategy: 'api-key-header',
wireProtocol: 'openai-responses',
supportsImageGeneration: true,
+ imageApi: 'openai-images',
},
},
models: {
@@ -546,6 +547,7 @@ describe('providerViewToCustomProviderConfig', () => {
expect(providerViewToCustomProviderConfig(provider).runtimes.codex).toMatchObject({
supportsImageGeneration: true,
+ imageApi: 'openai-images',
models: [{ id: 'image-model', name: 'Image Model' }],
});
});
diff --git a/apps/desktop/src/renderer/lib/customProviders.ts b/apps/desktop/src/renderer/lib/customProviders.ts
index 4cf74393a5..bb129f3f78 100644
--- a/apps/desktop/src/renderer/lib/customProviders.ts
+++ b/apps/desktop/src/renderer/lib/customProviders.ts
@@ -136,6 +136,7 @@ export function providerViewToCustomProviderConfig(p: ProviderView): CustomProvi
...(agent === 'codex' && routing?.supportsImageGeneration === true
? { supportsImageGeneration: true }
: {}),
+ ...(routing?.imageApi ? { imageApi: routing.imageApi } : {}),
models: models.map((model) => customProviderModelConfigFromCatalogModel(model, agent)),
...(routing?.headerOverride && Object.keys(routing.headerOverride).length > 0
? { headers: { ...routing.headerOverride } }
diff --git a/docs/custom-image-api.md b/docs/custom-image-api.md
new file mode 100644
index 0000000000..89654db8ef
--- /dev/null
+++ b/docs/custom-image-api.md
@@ -0,0 +1,55 @@
+# 自定义供应商的 OpenAI Images 接口
+
+Cindy Gateway 已有的图片、视频目录继续跟随网关。自定义连接可单独启用
+OpenAI Images 接口,让使用 Core 媒体能力的 Art 等插件调用自己的图片来源。
+适配按接口契约复用,不按中转产品名分支。
+
+## 使用方式
+
+1. 在供应商的连接设置中选中持有该图片来源的 Agent 连接,填写 API 地址与 API Key。
+ 本机回环地址也可以使用无鉴权连接。
+2. 勾选「使用 OpenAI Images 接口」。只有实际提供下列两个端点的连接才应开启。
+ 仅兼容对话接口,或订阅中能在网页上作图,不能证明该连接有 Images API。
+3. 获取模型列表,并在常规模型设置中确认目标模型属于图片生成类型。
+ 返回列表未标识类型时,手动调整模型能力;不会按供应商名称自动开启。
+4. 在 Art 的图片生成、图片编辑能力中选用该来源的模型。
+
+连接地址可以填写 API origin、以 `/v1` 结尾的地址或带路径前缀的 `/v1` 地址。
+例如 `http://127.0.0.1:8317/v1` 对应
+`http://127.0.0.1:8317/v1/images/generations`。
+未以 `/v1` 结尾的地址会追加 `/v1`,路径前缀保留。
+
+## 一期支持的契约
+
+| 操作 | 接口 | 请求与响应 |
+| --- | --- | --- |
+| 图片生成 | `POST /images/generations` | JSON;原样发送模型 ID、prompt,使用既有 OpenAI 图片参数规范化 |
+| 图片编辑 | `POST /images/edits` | multipart;参考图与 model、prompt、size、quality |
+| 返回图片 | `data[0].b64_json` 或 `data[0].url` | 客户端下载、校验并保存为受管媒体 |
+
+鉴权为该 Agent 连接的 API Key(Bearer),或仅本机回环地址的无鉴权模式。
+不会借用其他 Agent、其他供应商或订阅登录的凭证。自定义业务请求头保留,
+鉴权、账号、协议会话和 multipart 的请求头由客户端隔离或生成。
+模型级地址覆盖必须与连接地址同源;付费提交不跟随重定向。
+
+CPA/CLIProxyAPI、Sub2API 等自建中转只要提供上述契约即可复用此通道;
+它们内部如何管理订阅或 CLI,不进入 Cindy 的媒体适配层。
+是否能使用某个模型仍取决于中转实际开放的接口、模型及账号权限。
+
+## 已安装用户与失败恢复
+
+- 新字段 `imageApi: "openai-images"` 为可选配置。缺省不启用,不自动改变已存连接或付费来源。
+- Gateway、OpenAI、Codex 和 xAI 既有通道优先保留;不替换原有原生订阅通道。
+- 本次不修改插件包、批准记录、权限指纹或凭证存储布局,无需重新安装或重新授权插件。
+- URL 结果先保存调用记录,再走既有下载许可与安全校验。下载不携带生成来源的 API Key。
+ 下载失败后使用原 invocation 再次执行 request,只恢复同一结果,不重新付费生成。
+- 上游提交结果不确定时不自动重提,不自动换模型或换来源;拒绝与诊断文本脱敏后返回。
+- 新来源使用 Core 媒体能力;冻结的旧 `cindy-request` 同步接口不扩展自定义来源。
+ 旧插件已有能力保持原状。要使用新来源,插件需要采用 Core 媒体能力。
+
+## 后续边界
+
+本阶段不实现视频接口、原生 Gemini/其他私有图片协议、任意 CLI 进程驱动、
+网页 Cookie 或私有订阅登录的复用,也不新增逐家 OAuth 适配。
+只开放生成、缺少编辑端点的来源暂不应开启此选项。
+新协议应独立评估其主流程度和稳定契约,避免在 OpenAI Images 通道上叠加供应商特例。
diff --git a/packages/model-providers/src/__tests__/user-provider.test.ts b/packages/model-providers/src/__tests__/user-provider.test.ts
index e4469149f5..e9e0c2d737 100644
--- a/packages/model-providers/src/__tests__/user-provider.test.ts
+++ b/packages/model-providers/src/__tests__/user-provider.test.ts
@@ -1073,6 +1073,7 @@ describe("buildUserProvider (per-runtime)", () => {
baseUrl: "https://images.example/v1",
wireProtocol: "openai-responses",
supportsImageGeneration: true,
+ imageApi: "openai-images",
models: [
{ id: "generate", name: "Generate" },
{ id: "input", name: "Input", supportsImageInput: true },
@@ -1081,6 +1082,7 @@ describe("buildUserProvider (per-runtime)", () => {
},
});
expect(p.routing.codex?.supportsImageGeneration).toBe(true);
+ expect(p.routing.codex?.imageApi).toBe("openai-images");
expect(p.models.codex?.[0]?.supportsImageInput).toBeUndefined();
expect(p.models.codex?.[1]?.supportsImageInput).toBe(true);
});
diff --git a/packages/model-providers/src/types.ts b/packages/model-providers/src/types.ts
index 66337c3357..e0afa1d9b2 100644
--- a/packages/model-providers/src/types.ts
+++ b/packages/model-providers/src/types.ts
@@ -199,6 +199,8 @@ export interface RoutingDescriptor {
* 缺省按 false 处理;它与模型图片输入能力独立,也不得从模型名推断。
*/
supportsImageGeneration?: boolean;
+ /** Explicit standalone image API; independent of chat wire and Codex hosted tools. */
+ imageApi?: "openai-images";
/** Enterprise BYOK image model binding used by the Codex Images route. */
imageModel?: { wireModel: string; litellmModel: string; supportsEdit: boolean };
/** 真实上游 base URL(direct 时是供应商自家;gateway 时是 XD 网关 base)。 */
@@ -769,6 +771,8 @@ export interface CustomProviderRuntimeConfig {
requestPath?: string;
/** Codex Responses runtime 是否支持原生图片生成与编辑;缺省为 false。 */
supportsImageGeneration?: boolean;
+ /** Opt-in to standalone OpenAI Images generation/edits on this runtime's connection. */
+ imageApi?: "openai-images";
/** 用户模型;contextWindow 可由预设带入,缺省时由 `buildUserProvider` 补保守默认。 */
models: ProviderRuntimeModelConfig[];
/**
diff --git a/packages/model-providers/src/user-provider.ts b/packages/model-providers/src/user-provider.ts
index 6fe525cfe9..41c2ab6c4c 100644
--- a/packages/model-providers/src/user-provider.ts
+++ b/packages/model-providers/src/user-provider.ts
@@ -476,6 +476,7 @@ export function buildUserProvider(
rt.piCatalogProviderId,
rt.supportsImageGeneration,
);
+ if (rt.imageApi === "openai-images") routing[agent]!.imageApi = rt.imageApi;
const followsPreset =
presetRuntime &&
withoutTrailingSlashes(resolvedBaseUrl) ===