Deploy eefbbba to Docker Space

Source: MisonL/gpt-image-playground-customer@eefbbbad2b16424e315cc90a8e789882e4925175

public/hf-space-deploy-marker.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "local_sha": "653775e99286817989ad7a4dfb56eedae605cdcb",
-  "created_at": "2026-06-30T11:54:17.314Z",
-  "deploy_id": "5a7966ca-fd3b-44a4-aea7-e7a5a4566be3"
+  "local_sha": "eefbbbad2b16424e315cc90a8e789882e4925175",
+  "created_at": "2026-07-02T07:57:46.310Z",
+  "deploy_id": "cb1184cc-a24f-4024-a8e5-f65a2f020dd4"
 }

scripts/smoke-image-upstream-local-final-gate.test.mjs

@@ -5,7 +5,8 @@ import { fileURLToPath } from 'node:url';
 
 const repoRoot = fileURLToPath(new URL('..', import.meta.url));
 const scriptPath = fileURLToPath(new URL('./smoke-image-upstream-local-final-gate.mjs', import.meta.url));
-const LOCAL_GATE_CASE_TIMEOUT_MS = '60000';
+// The fixture gate covers several independent upstream modes; leave room for bounded accepted-task retry paths.
+const LOCAL_GATE_CASE_TIMEOUT_MS = '120000';
 
 describe('local image upstream final gate smoke launcher', () => {
     it('runs all independent upstream cases against the local fixture', () => {

skills/gpt-image-playground-agent/SKILL.md

@@ -16,7 +16,7 @@ Agent API 是给自动化客户端使用的机器接口，不是自治 Agent 平
 - 批量 generate/edit：优先运行 `scripts/batch-images.mjs`，用 JSONL 输入和 append-only manifest 管理续跑。
 - 转换本地图片格式：优先运行 `scripts/convert-image-format.mjs`。
 - 查询页面请求的结果反馈或日志诊断摘要：优先运行 `scripts/diagnose-request.mjs`。
-- 诊断上游图片接口：优先运行 `scripts/probe-upstream-image.mjs`。接入新上游渠道时，先确认 `/models` 和 `/images/generations` 能通，再用 `npm run smoke:image-upstream-real -- --allow-billable` 逐个验证 `original-images-json`、`sub2api-images-sse`、`sub2api-responses-json`、`gpt2image-responses-sse`；如果 `/v1/responses` 返回 `403 Image generation is not enabled for this group`，就把该渠道的 `responses-non-stream`、`responses-sse` 从 `OPENAI_CHANNEL_N_REQUEST_MODES` 移除。
+- 诊断上游图片接口：优先运行 `scripts/probe-upstream-image.mjs`。接入新上游渠道时，先确认 `/models` 和 `/images/generations` 能通，再用 `npm run smoke:image-upstream-real -- --allow-billable` 逐个验证 `original-images-json`、`sub2api-images-sse`、`sub2api-responses-json`、`gpt2image-responses-sse`。如果某一路径先返回 `object=image.task,status=pending`，说明该请求方式不是直接完成结果；应先确认同一业务键能否在同一渠道下重试拿到最终图片，再把可用的 `request_modes` 写入 `OPENAI_CHANNEL_N_REQUEST_MODES`。如果 `/v1/responses` 返回 `403 Image generation is not enabled for this group`，就把该渠道的 `responses-non-stream`、`responses-sse` 从 `OPENAI_CHANNEL_N_REQUEST_MODES` 移除。
 - 不要临时编写 Node/Python/shell 脚本、curl 命令或手写 fetch/FormData 来重复实现这些脚本已经覆盖的 API 调用。
 - 只有在内置脚本缺少用户明确需要的能力时，才修改或扩展 `scripts/` 内的预置脚本，并同步补测试；不要在仓库外留下 ad hoc 调用脚本。
 - 先用 dry-run、`--check-remote` 或 `--contract-check` 检查请求、路由、鉴权和服务声明的默认编排入口；只有用户明确允许真实计费时才加 `--allow-billable`。

src/app/api/agent/agent-routes.test.ts

@@ -322,6 +322,47 @@ describe('Agent route integration', () => {
         }
     });
 
+    it('retries accepted async image tasks through Agent generate with the same upstream idempotency key', async () => {
+        const { generateImage } = await loadAgentRoutes();
+        const upstreamIdempotencyKeys: Array<string | undefined> = [];
+        let upstreamCalls = 0;
+        const upstream = await startImageUpstream((_body, _url, request, response) => {
+            upstreamCalls += 1;
+            const idempotencyKey = request.headers['idempotency-key'];
+            upstreamIdempotencyKeys.push(Array.isArray(idempotencyKey) ? idempotencyKey.join(',') : idempotencyKey);
+            if (upstreamCalls === 1) {
+                response.setHeader('Retry-After', '1');
+                return {
+                    object: 'image.task',
+                    status: 'pending',
+                    task_id: 'agent-route-accepted-task',
+                    poll_url: '/v1/image-tasks?ids=agent-route-accepted-task'
+                };
+            }
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_API_KEY = 'test-key';
+        process.env.OPENAI_API_BASE_URL = upstream.baseUrl;
+
+        try {
+            const response = await generateImage(
+                agentJsonRequest('agent-route-accepted-task-key', {
+                    prompt: 'agent route accepted task',
+                    response_mode: 'base64'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            const body = await response.json();
+            assert.equal(body.cached, false);
+            assert.equal(body.images[0].b64_json, PNG_BASE64);
+            assert.deepEqual(upstreamIdempotencyKeys, ['agent-route-accepted-task-key', 'agent-route-accepted-task-key']);
+            assert.equal(upstreamCalls, 2);
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('keeps Agent request diagnostics available when feedback lookup fails', async () => {
         const { generateImage, getAgentRequestDiagnostics } = await loadAgentRoutes();
         const upstream = await startImageUpstream(() => ({ data: [{ b64_json: PNG_BASE64 }] }));
@@ -3504,7 +3545,12 @@ function createPngWithDimensions(width: number, height: number): Buffer {
 }
 
 async function startImageUpstream(
-    handler: (body: string, url: string) => unknown | Promise<unknown>
+    handler: (
+        body: string,
+        url: string,
+        request: http.IncomingMessage,
+        response: http.ServerResponse
+    ) => unknown | Promise<unknown>
 ): Promise<{ baseUrl: string; close: () => Promise<void> }> {
     const server = http.createServer(async (request, response) => {
         if (
@@ -3519,7 +3565,7 @@ async function startImageUpstream(
         request.on('data', (chunk: Buffer) => chunks.push(chunk));
         await new Promise<void>((resolve) => request.on('end', resolve));
         try {
-            const body = await handler(Buffer.concat(chunks).toString('utf8'), request.url || '');
+            const body = await handler(Buffer.concat(chunks).toString('utf8'), request.url || '', request, response);
             response.writeHead(200, { 'Content-Type': 'application/json' });
             response.end(JSON.stringify(body));
         } catch (error) {

src/app/api/deploy-marker/route.ts

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server';
 
-const deployMarker = {"schema_version":1,"local_sha":"653775e99286817989ad7a4dfb56eedae605cdcb","created_at":"2026-06-30T11:54:17.314Z","deploy_id":"5a7966ca-fd3b-44a4-aea7-e7a5a4566be3"} as const;
+const deployMarker = {"schema_version":1,"local_sha":"eefbbbad2b16424e315cc90a8e789882e4925175","created_at":"2026-07-02T07:57:46.310Z","deploy_id":"cb1184cc-a24f-4024-a8e5-f65a2f020dd4"} as const;
 
 export const dynamic = 'force-dynamic';
 

src/app/api/images/route-test-helpers.ts

@@ -205,6 +205,62 @@ export async function startImagesStreamFallbackUpstream(): Promise<{
     return { ...result, calls };
 }
 
+export async function startImagesAcceptedTaskStreamFallbackUpstream(): Promise<{
+    baseUrl: string;
+    calls: Array<{ stream?: boolean; partial_images?: number; idempotencyKey?: string | string[] }>;
+    close: () => Promise<void>;
+}> {
+    const calls: Array<{ stream?: boolean; partial_images?: number; idempotencyKey?: string | string[] }> = [];
+    let nonStreamAttempts = 0;
+    const server = http.createServer(async (request, response) => {
+        if (request.method !== 'POST' || !request.url?.endsWith('/images/generations')) {
+            response.writeHead(404, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: { message: 'not found' } }));
+            return;
+        }
+        const chunks: Buffer[] = [];
+        request.on('data', (chunk: Buffer) => chunks.push(chunk));
+        await new Promise<void>((resolve) => request.on('end', resolve));
+        const payload = JSON.parse(Buffer.concat(chunks).toString('utf8')) as {
+            stream?: boolean;
+            partial_images?: number;
+        };
+        calls.push({
+            stream: payload.stream,
+            partial_images: payload.partial_images,
+            idempotencyKey: request.headers['idempotency-key']
+        });
+        if (payload.stream) {
+            response.writeHead(200, { 'Content-Type': 'text/event-stream' });
+            response.write(
+                `event: image_generation.partial_image\ndata: ${JSON.stringify({
+                    type: 'image_generation.partial_image',
+                    b64_json: 'partial-before-accepted-task-fallback'
+                })}\n\n`
+            );
+            response.write('data: [DONE]\n\n');
+            response.end();
+            return;
+        }
+        nonStreamAttempts += 1;
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        if (nonStreamAttempts === 1) {
+            response.end(
+                JSON.stringify({
+                    object: 'image.task',
+                    status: 'pending',
+                    task_id: 'fallback-task',
+                    poll_url: '/api/image-tasks?ids=fallback-task'
+                })
+            );
+            return;
+        }
+        response.end(JSON.stringify({ data: [{ b64_json: PNG_BASE64 }] }));
+    });
+    const result = await listen(server);
+    return { ...result, calls };
+}
+
 export async function startHangingImagesStreamUpstream(): Promise<{
     baseUrl: string;
     calls: Array<{ stream?: boolean; partial_images?: number }>;

src/app/api/images/route.test.ts

@@ -3,6 +3,7 @@ import {
     imageFormRequest,
     readSseEvents,
     startHangingImagesStreamUpstream,
+    startImagesAcceptedTaskStreamFallbackUpstream,
     startImagesJsonUpstream,
     startImagesStreamFallbackUpstream,
     startResponsesImageUpstream,
@@ -127,9 +128,11 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
     it('uses a non-streaming channel request mode when page auto streaming has no SSE channel', async () => {
         const { POST } = await import('./route');
         const upstreamBodies: string[] = [];
+        let observedIdempotencyKey: string | string[] | undefined;
         const upstream = await startImagesJsonUpstream(async (body, _url, request) => {
             if (request.method === 'POST') {
                 upstreamBodies.push(body);
+                observedIdempotencyKey = request.headers['idempotency-key'];
             }
             return { data: [{ b64_json: PNG_BASE64 }] };
         });
@@ -151,6 +154,95 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
             const upstreamJson = JSON.parse(upstreamBodies[0] || '{}') as Record<string, unknown>;
             assert.equal(upstreamJson.stream, false);
             assert.equal(Object.hasOwn(upstreamJson, 'partial_images'), false);
+            assert.equal(observedIdempotencyKey, 'client-route-stream');
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('retries accepted async image tasks with the same upstream idempotency key', async () => {
+        const { POST } = await import('./route');
+        const observedIdempotencyKeys: Array<string | string[] | undefined> = [];
+        let upstreamCalls = 0;
+        const upstream = await startImagesJsonUpstream(async (_body, _url, request) => {
+            if (request.method !== 'POST') {
+                return { data: [{ b64_json: PNG_BASE64 }] };
+            }
+            upstreamCalls += 1;
+            observedIdempotencyKeys.push(request.headers['idempotency-key']);
+            if (upstreamCalls === 1) {
+                return {
+                    object: 'image.task',
+                    status: 'pending',
+                    task_id: 'sync-gen-task',
+                    poll_url: '/api/image-tasks?ids=sync-gen-task'
+                };
+            }
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_CHANNEL_1_ID = 'json-task';
+        process.env.OPENAI_CHANNEL_1_BASE_URL = upstream.baseUrl;
+        process.env.OPENAI_CHANNEL_1_API_KEYS = 'test-key';
+        process.env.OPENAI_CHANNEL_1_REQUEST_MODES = 'images-non-stream';
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    streamMode: 'auto',
+                    clientRequestId: 'accepted-task-retry-key'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.notEqual(response.headers.get('content-type'), 'text/event-stream');
+            assert.equal(upstreamCalls, 2);
+            assert.deepEqual(observedIdempotencyKeys, ['accepted-task-retry-key', 'accepted-task-retry-key']);
+        } finally {
+            await upstream.close();
+        }
+    });
+
+    it('retries accepted async edit tasks with the same upstream idempotency key', async () => {
+        const { POST } = await import('./route');
+        const observedIdempotencyKeys: Array<string | string[] | undefined> = [];
+        let upstreamCalls = 0;
+        const upstream = await startImagesJsonUpstream(async (_body, _url, request) => {
+            if (request.method !== 'POST') {
+                return { data: [{ b64_json: PNG_BASE64 }] };
+            }
+            upstreamCalls += 1;
+            observedIdempotencyKeys.push(request.headers['idempotency-key']);
+            if (upstreamCalls === 1) {
+                return {
+                    object: 'image.task',
+                    status: 'pending',
+                    task_id: 'sync-edit-task',
+                    poll_url: '/api/image-tasks?ids=sync-edit-task'
+                };
+            }
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+        process.env.OPENAI_CHANNEL_1_ID = 'json-edit-task';
+        process.env.OPENAI_CHANNEL_1_BASE_URL = upstream.baseUrl;
+        process.env.OPENAI_CHANNEL_1_API_KEYS = 'test-key';
+        process.env.OPENAI_CHANNEL_1_REQUEST_MODES = 'images-non-stream';
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    mode: 'edit',
+                    streamMode: 'auto',
+                    clientRequestId: 'accepted-edit-task-retry-key'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.notEqual(response.headers.get('content-type'), 'text/event-stream');
+            assert.equal(upstreamCalls, 2);
+            assert.deepEqual(observedIdempotencyKeys, [
+                'accepted-edit-task-retry-key',
+                'accepted-edit-task-retry-key'
+            ]);
         } finally {
             await upstream.close();
         }
@@ -467,6 +559,45 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         }
     });
 
+    it('retries accepted async image tasks after auto stream fallback with the same idempotency key', async () => {
+        const { POST } = await import('./route');
+        const upstream = await startImagesAcceptedTaskStreamFallbackUpstream();
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    streamMode: 'auto',
+                    clientRequestId: 'client-route-auto-fallback-task'
+                })
+            );
+
+            assert.equal(response.status, 200);
+            assert.equal(response.headers.get('content-type'), 'text/event-stream');
+            const events = await readSseEvents(response);
+            assert.deepEqual(
+                events.map((event) => event.type),
+                ['partial_image', 'completed', 'done']
+            );
+            assert.equal(events[2].fallback_used, true);
+            assert.deepEqual(
+                upstream.calls.map((call) => call.stream),
+                [true, false, false]
+            );
+            assert.deepEqual(
+                upstream.calls.map((call) => call.idempotencyKey),
+                [
+                    'client-route-auto-fallback-task',
+                    'client-route-auto-fallback-task',
+                    'client-route-auto-fallback-task'
+                ]
+            );
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('does not mark auto streaming unavailable when the page SSE request is aborted', async () => {
         const { POST } = await import('./route');
         const { getServerChannelState } = await import('@/lib/server-channel-router');
@@ -1697,6 +1828,33 @@ describe('POST /api/images streaming', { concurrency: false }, () => {
         }
     });
 
+    it('rejects page SSE client request ids with control characters before contacting upstream', async () => {
+        const { POST } = await import('./route');
+        let upstreamCalls = 0;
+        const upstream = await startImagesJsonUpstream(async () => {
+            upstreamCalls += 1;
+            return { data: [{ b64_json: PNG_BASE64 }] };
+        });
+
+        try {
+            const response = await POST(
+                imageFormRequest({
+                    apiBaseUrl: upstream.baseUrl,
+                    apiKey: 'test-key',
+                    clientRequestId: 'bad\nrequest'
+                })
+            );
+
+            assert.equal(response.status, 400);
+            const body = (await response.json()) as Record<string, unknown>;
+            assert.match(String(body.error), /clientRequestId/);
+            assert.match(String(body.error), /控制字符/);
+            assert.equal(upstreamCalls, 0);
+        } finally {
+            await upstream.close();
+        }
+    });
+
     it('rejects invalid gpt-image-2 custom size boundaries before contacting upstream', async () => {
         const { POST } = await import('./route');
         let upstreamCalls = 0;

src/app/api/images/route.ts

@@ -334,6 +334,7 @@ export async function POST(request: NextRequest) {
         }
         const formData = await request.formData();
         clientRequestId = readClientRequestId(formData);
+        const upstreamIdempotencyKey = clientRequestId || crypto.randomUUID();
         requestLogContext = clientRequestId ? { clientRequestId } : undefined;
         const requestApiKey = String(formData.get('apiKey') || '').trim();
         const requestApiBaseUrl = String(formData.get('apiBaseUrl') || '').trim();
@@ -513,9 +514,11 @@ export async function POST(request: NextRequest) {
                       apiBaseUrl: effectiveApiBaseUrl,
                       apiKey: effectiveApiKey,
                       startedAtMs: upstreamStartedAtMs,
+                      upstreamIdempotencyKey,
                       clientRequestId,
                       requestLogContext,
                       selectedCredential,
+                      channelRequestMode: channelSelection.requestMode,
                       accessCookie,
                       abortSignal: request.signal,
                       streamFallbackEnabled: streamResolution.streamFallbackEnabled,
@@ -542,9 +545,11 @@ export async function POST(request: NextRequest) {
                       apiBaseUrl: effectiveApiBaseUrl,
                       apiKey: effectiveApiKey,
                       startedAtMs: upstreamStartedAtMs,
+                      upstreamIdempotencyKey,
                       clientRequestId,
                       requestLogContext,
                       selectedCredential,
+                      channelRequestMode: channelSelection.requestMode,
                       accessCookie,
                       abortSignal: request.signal,
                       streamFallbackEnabled: streamResolution.streamFallbackEnabled,

src/lib/accepted-image-task.ts

@@ -0,0 +1,23 @@
+export type AcceptedImageTaskDetails = {
+    taskId?: string;
+    pollUrl?: string;
+};
+
+export function readAcceptedImageTaskDetails(result: unknown): AcceptedImageTaskDetails | undefined {
+    if (!result || typeof result !== 'object' || Array.isArray(result)) return undefined;
+    const record = result as Record<string, unknown>;
+    if (readTrimmedString(record.object) !== 'image.task' || readTrimmedString(record.status) !== 'pending') {
+        return undefined;
+    }
+
+    const taskId = readTrimmedString(record.task_id);
+    const pollUrl = readTrimmedString(record.poll_url);
+    return {
+        ...(taskId ? { taskId } : {}),
+        ...(pollUrl ? { pollUrl } : {})
+    };
+}
+
+function readTrimmedString(value: unknown): string | undefined {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}

src/lib/agent-image-service.test.ts

@@ -1,4 +1,9 @@
-import { buildEditRequestHash, completeAgentExecutionState, hydrateAgentReplayResponse } from './agent-image-service';
+import {
+    buildEditRequestHash,
+    completeAgentExecutionState,
+    hydrateAgentReplayResponse,
+    readIdempotencyKey
+} from './agent-image-service';
 import type { AgentArtifactRecord, AgentStateStore } from './agent-state-store';
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
@@ -19,6 +24,21 @@ describe('buildEditRequestHash', () => {
     });
 });
 
+describe('readIdempotencyKey', () => {
+    it('rejects control characters before forwarding the value upstream', () => {
+        const headers = new Headers({ 'Idempotency-Key': `agent${String.fromCharCode(31)}key` });
+
+        assert.throws(
+            () => readIdempotencyKey(headers),
+            (error) => {
+                assert.ok(error instanceof Error);
+                assert.match(error.message, /控制字符/);
+                return true;
+            }
+        );
+    });
+});
+
 describe('hydrateAgentReplayResponse', () => {
     it('rejects base64 replay when stored artifact filepath escapes the image directory', async () => {
         const store = createReplayStore([

src/lib/agent-image-service.ts

@@ -68,6 +68,9 @@ import {
 import {
     InvalidOpenAiImagesResponseError,
     MissingOpenAiImageDataError,
+    readAcceptedImageTaskDetails,
+    resolveAcceptedImageTaskResponse,
+    type AcceptedImageTaskResponseError,
     persistOpenAiImages as persistSharedOpenAiImages
 } from './image-service';
 import { collectOpenAiImagesFromStream } from './image-stream-collector';
@@ -184,6 +187,8 @@ const AGENT_EDIT_UNSUPPORTED_FIELDS = [
     'moderation'
 ] as const;
 
+const HTTP_HEADER_VALUE_CONTROL_CHAR_PATTERN = /[\u0000-\u001f\u007f]/;
+
 export function readIdempotencyKey(headers: Headers): string {
     const value = headers.get('idempotency-key')?.trim();
     if (!value) {
@@ -203,6 +208,15 @@ export function readIdempotencyKey(headers: Headers): string {
             details: { fields: { 'Idempotency-Key': '长度不能超过 200 个字符' } }
         });
     }
+    if (HTTP_HEADER_VALUE_CONTROL_CHAR_PATTERN.test(value)) {
+        throw new AgentApiError({
+            code: 'validation_error',
+            message: 'Idempotency-Key 不能包含控制字符。',
+            status: 422,
+            retryable: false,
+            details: { fields: { 'Idempotency-Key': '不能包含控制字符' } }
+        });
+    }
     return value;
 }
 
@@ -315,13 +329,31 @@ export async function prepareAgentEdit(formData: FormData, headers: Headers): Pr
     return { credentialContext, prompt, model, n, size, quality, responseMode, streamRequest, imageFiles, maskFile };
 }
 
-function buildOpenAiRequestOptions(context: CredentialContext, abortSignal?: AbortSignal): OpenAI.RequestOptions {
+function buildOpenAiRequestOptions(
+    context: CredentialContext,
+    input: { abortSignal?: AbortSignal; idempotencyKey: string }
+): OpenAI.RequestOptions {
     return buildOpenAIImageRequestOptions({
-        abortSignal,
+        abortSignal: input.abortSignal,
+        idempotencyKey: input.idempotencyKey,
         headers: mergeUpstreamHeadersWithFixed(context.upstreamHeaders, {})
     });
 }
 
+function onAgentAcceptedImageTask(context: CredentialContext, modeLabel: string, idempotencyKey: string) {
+    return (details: AcceptedImageTaskResponseError, attempt: number, delayMs: number) => {
+        appLogger.warn(`Agent ${modeLabel} 上游返回异步图片任务，等待后重试同步结果。`, {
+            idempotencyKey,
+            channelId: context.selectedCredential?.channelId,
+            requestMode: context.channelRequestMode,
+            attempt,
+            delayMs,
+            taskId: details.taskId,
+            hasPollUrl: Boolean(details.pollUrl)
+        });
+    };
+}
+
 async function acquireAgentChannelCapacity(
     context: CredentialContext,
     abortSignal?: AbortSignal
@@ -395,7 +427,12 @@ export async function executeAgentGenerate(options: {
     let channelLease: ChannelCapacityLease | undefined;
     try {
         channelLease = await acquireAgentChannelCapacity(credentialContext, options.abortSignal);
-        const result = await executeAgentGenerateUpstream(options.request, credentialContext, options.abortSignal);
+        const result = await executeAgentGenerateUpstream(
+            options.request,
+            credentialContext,
+            options.idempotencyKey,
+            options.abortSignal
+        );
         channelLease?.release();
         channelLease = undefined;
         return await persistOpenAiImages({
@@ -445,6 +482,7 @@ export async function executeAgentGenerate(options: {
 async function executeAgentGenerateUpstream(
     request: AgentGenerateRequest,
     credentialContext: CredentialContext,
+    idempotencyKey: string,
     abortSignal?: AbortSignal
 ): Promise<OpenAI.Images.ImagesResponse> {
     const { openai } = credentialContext;
@@ -458,7 +496,7 @@ async function executeAgentGenerateUpstream(
         channelRequestMode: credentialContext.channelRequestMode
     };
     if (request.image_backend === 'responses-image-generation') {
-        return executeAgentResponsesGenerate(request, credentialContext, abortSignal);
+        return executeAgentResponsesGenerate(request, credentialContext, idempotencyKey, abortSignal);
     }
     const baseParams = {
         model: request.model,
@@ -473,21 +511,34 @@ async function executeAgentGenerateUpstream(
         ...(request.force_web !== undefined ? { force_web: request.force_web } : {})
     };
     if (!shouldUseAgentUpstreamStream(streamOptions)) {
-        return openai.images.generate(
-            { ...baseParams, stream: false },
-            buildOpenAiRequestOptions(credentialContext, abortSignal)
+        return resolveAcceptedImageTaskResponse(
+            () =>
+                openai.images
+                    .generate(
+                        { ...baseParams, stream: false },
+                        buildOpenAiRequestOptions(credentialContext, { abortSignal, idempotencyKey })
+                    )
+                    .withResponse(),
+            { abortSignal, onAcceptedTask: onAgentAcceptedImageTask(credentialContext, 'generate', idempotencyKey) }
         );
     }
     const fallback = () =>
-        openai.images.generate(
-            { ...baseParams, stream: false },
-            buildOpenAiRequestOptions(credentialContext, abortSignal)
+        resolveAcceptedImageTaskResponse(
+            () =>
+                openai.images
+                    .generate(
+                        { ...baseParams, stream: false },
+                        buildOpenAiRequestOptions(credentialContext, { abortSignal, idempotencyKey })
+                    )
+                    .withResponse(),
+            { abortSignal, onAcceptedTask: onAgentAcceptedImageTask(credentialContext, 'generate', idempotencyKey) }
         );
     try {
         const stream = await createImagesApiGenerateStream({
             apiBaseUrl: credentialContext.baseUrl,
             apiKey: credentialContext.apiKey,
             upstreamHeaders: credentialContext.upstreamHeaders,
+            idempotencyKey,
             abortSignal,
             params: {
                 ...baseParams,
@@ -544,6 +595,7 @@ function validateAgentGenerateAgainstUpstreamProfile(
 async function executeAgentResponsesGenerate(
     request: AgentGenerateRequest,
     credentialContext: CredentialContext,
+    idempotencyKey: string,
     abortSignal?: AbortSignal
 ): Promise<OpenAI.Images.ImagesResponse> {
     const { openai } = credentialContext;
@@ -566,6 +618,7 @@ async function executeAgentResponsesGenerate(
         outputFormat: request.output_format,
         background: request.background,
         moderation: request.moderation,
+        idempotencyKey,
         abortSignal,
         ...(request.output_compression !== undefined ? { outputCompression: request.output_compression } : {}),
         ...(request.promptOptimization !== undefined ? { promptOptimization: request.promptOptimization } : {}),
@@ -699,6 +752,8 @@ export async function executeAgentEdit(options: {
     try {
         const preparation = options.preparation ?? (await prepareAgentEdit(options.formData, options.headers));
         credentialContext = preparation.credentialContext;
+        // Keep a const alias so TypeScript preserves the narrowed credential context below.
+        const activeCredentialContext = credentialContext;
         const editParams: OpenAI.Images.ImageEditParamsNonStreaming = {
             model: preparation.model,
             prompt: preparation.prompt,
@@ -714,20 +769,37 @@ export async function executeAgentEdit(options: {
             streamMode: preparation.streamRequest.streamMode,
             streamingStrategy: preparation.streamRequest.streamingStrategy,
             partialImages: preparation.streamRequest.partialImages,
-            selectedCredential: credentialContext.selectedCredential,
-            channelRequestMode: credentialContext.channelRequestMode
+            selectedCredential: activeCredentialContext.selectedCredential,
+            channelRequestMode: activeCredentialContext.channelRequestMode
         };
-        channelLease = await acquireAgentChannelCapacity(credentialContext, options.abortSignal);
+        channelLease = await acquireAgentChannelCapacity(activeCredentialContext, options.abortSignal);
         const result = shouldUseAgentUpstreamStream(streamOptions)
             ? await executeAgentEditStream({
-                  credentialContext,
+                  credentialContext: activeCredentialContext,
                   params: editParams,
                   streamOptions,
+                  idempotencyKey: options.idempotencyKey,
                   abortSignal: options.abortSignal
               })
-            : await credentialContext.openai.images.edit(
-                  editParams,
-                  buildOpenAiRequestOptions(credentialContext, options.abortSignal)
+            : await resolveAcceptedImageTaskResponse(
+                  () =>
+                      activeCredentialContext.openai.images
+                          .edit(
+                              editParams,
+                              buildOpenAiRequestOptions(activeCredentialContext, {
+                                  abortSignal: options.abortSignal,
+                                  idempotencyKey: options.idempotencyKey
+                              })
+                          )
+                          .withResponse(),
+                  {
+                      abortSignal: options.abortSignal,
+                      onAcceptedTask: onAgentAcceptedImageTask(
+                          activeCredentialContext,
+                          'edit',
+                          options.idempotencyKey
+                      )
+                  }
               );
         channelLease?.release();
         channelLease = undefined;
@@ -742,9 +814,9 @@ export async function executeAgentEdit(options: {
             requestId: options.requestId,
             idempotencyKey: options.idempotencyKey,
             cached: options.cached,
-            apiBaseUrl: credentialContext.baseUrl,
-            apiKey: credentialContext.apiKey,
-            upstreamHeaders: credentialContext.upstreamHeaders,
+            apiBaseUrl: activeCredentialContext.baseUrl,
+            apiKey: activeCredentialContext.apiKey,
+            upstreamHeaders: activeCredentialContext.upstreamHeaders,
             execution: {
                 startedAtMs,
                 startedAt,
@@ -757,10 +829,10 @@ export async function executeAgentEdit(options: {
                 imageBackend: 'images-api',
                 streamMode: preparation.streamRequest.streamMode,
                 streamingStrategy: preparation.streamRequest.streamingStrategy,
-                channelRequestMode: credentialContext.channelRequestMode,
-                channelRequestModeFallbackApplied: credentialContext.channelRequestModeFallbackApplied,
-                channelRequestModeDecision: credentialContext.channelRequestModeDecision,
-                selectedCredential: credentialContext.selectedCredential
+                channelRequestMode: activeCredentialContext.channelRequestMode,
+                channelRequestModeFallbackApplied: activeCredentialContext.channelRequestModeFallbackApplied,
+                channelRequestModeDecision: activeCredentialContext.channelRequestModeDecision,
+                selectedCredential: activeCredentialContext.selectedCredential
             },
             abortSignal: options.abortSignal
         });
@@ -780,10 +852,21 @@ async function executeAgentEditStream(input: {
     credentialContext: CredentialContext;
     params: OpenAI.Images.ImageEditParamsNonStreaming;
     streamOptions: AgentStreamOptions;
+    idempotencyKey: string;
     abortSignal?: AbortSignal;
 }): Promise<OpenAI.Images.ImagesResponse> {
-    const requestOptions = buildOpenAiRequestOptions(input.credentialContext, input.abortSignal);
-    const fallback = () => input.credentialContext.openai.images.edit(input.params, requestOptions);
+    const requestOptions = buildOpenAiRequestOptions(input.credentialContext, {
+        abortSignal: input.abortSignal,
+        idempotencyKey: input.idempotencyKey
+    });
+    const fallback = () =>
+        resolveAcceptedImageTaskResponse(
+            () => input.credentialContext.openai.images.edit(input.params, requestOptions).withResponse(),
+            {
+                abortSignal: input.abortSignal,
+                onAcceptedTask: onAgentAcceptedImageTask(input.credentialContext, 'edit', input.idempotencyKey)
+            }
+        );
     try {
         const stream = await input.credentialContext.openai.images.edit(
             {
@@ -1145,16 +1228,20 @@ async function persistOpenAiImages(options: {
         if (!(error instanceof InvalidOpenAiImagesResponseError) && !(error instanceof MissingOpenAiImageDataError)) {
             throw error;
         }
+        const acceptedTask =
+            error instanceof InvalidOpenAiImagesResponseError ? readAcceptedImageTaskDetails(error.result) : undefined;
         throw new AgentApiError({
             code: 'upstream_unavailable',
             message:
                 error instanceof MissingOpenAiImageDataError
                     ? `索引 ${error.index} 的图片数据缺少 base64 数据。`
-                    : '上游返回了空的 Images 响应。',
+                    : acceptedTask
+                      ? '上游返回了异步图片任务元数据，而不是最终图片结果；当前渠道不兼容该请求方式。'
+                      : '上游返回了空的 Images 响应。',
             status: 502,
-            retryable: true,
+            retryable: !acceptedTask,
             upstreamStatus: 502,
-            retryAfterSeconds: 15
+            ...(acceptedTask ? {} : { retryAfterSeconds: 15 })
         });
     }
 

src/lib/api-error-response.test.ts

@@ -8,6 +8,7 @@ import {
 } from './api-error-response';
 import { type ChannelRequestMode } from './channel-request-mode';
 import { RequestValidationError } from './image-request-utils';
+import { AcceptedImageTaskResponseError } from './image-service';
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
@@ -114,6 +115,48 @@ describe('normalizeAgentError', () => {
             ).diagnostics?.transport_error_kind,
             'sse_final_missing'
         );
+        assert.equal(
+            normalizeAgentError(
+                Object.assign(new Error('上游返回了异步图片任务，但当前服务不支持该任务态的自动轮询。'), {
+                    name: 'AcceptedImageTaskStreamResultError',
+                    status: 502
+                })
+            ).diagnostics?.transport_error_kind,
+            'upstream_timeout'
+        );
+        assert.equal(
+            normalizeAgentError(new AcceptedImageTaskResponseError({ taskId: 'accepted-non-stream-task' }))
+                .diagnostics?.transport_error_kind,
+            'upstream_timeout'
+        );
+    });
+
+    it('maps accepted image task exhaustion to non-retryable upstream errors', () => {
+        const error = normalizeAgentError(new AcceptedImageTaskResponseError({ taskId: 'accepted-non-stream-task' }));
+
+        assert.equal(error.code, 'upstream_unavailable');
+        assert.equal(error.status, 502);
+        assert.equal(error.retryable, false);
+        assert.equal(error.retryAfterSeconds, undefined);
+        assert.equal(error.upstreamStatus, 502);
+        assert.equal(error.diagnostics?.transport_error_kind, 'upstream_timeout');
+        assert.equal(error.diagnostics?.retry_after_seconds, undefined);
+    });
+
+    it('keeps generic upstream failures mentioning async image tasks retryable', () => {
+        const error = normalizeAgentError(
+            Object.assign(new Error('代理层异步图片任务日志写入失败'), {
+                status: 502
+            })
+        );
+
+        assert.equal(error.code, 'upstream_unavailable');
+        assert.equal(error.status, 502);
+        assert.equal(error.retryable, true);
+        assert.equal(error.retryAfterSeconds, 15);
+        assert.equal(error.upstreamStatus, 502);
+        assert.equal(error.diagnostics?.transport_error_kind, undefined);
+        assert.equal(error.diagnostics?.retry_after_seconds, 15);
     });
 
     it('adds sanitized upstream diagnostics without inventing an HTTP status', () => {

src/lib/api-error-response.ts

@@ -363,6 +363,9 @@ function classifyTransportErrorKind(error: unknown): AgentTransportErrorKind | u
     ) {
         return 'sse_final_missing';
     }
+    if (isAcceptedImageTaskError(error)) {
+        return 'upstream_timeout';
+    }
     if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return 'dns';
     if (
         code === 'CERT_HAS_EXPIRED' ||
@@ -477,6 +480,19 @@ export function normalizeAgentError(error: unknown, diagnostics: AgentErrorDiagn
 
     const status = readNumberField(error, 'status') ?? readNumberField(error, 'statusCode');
     const message = error instanceof Error ? error.message : (readStringField(error, 'message') ?? '发生未知错误。');
+    if (isAcceptedImageTaskError(error)) {
+        return new AgentApiError({
+            code: 'upstream_unavailable',
+            message,
+            status: 502,
+            retryable: false,
+            upstreamStatus: status,
+            diagnostics: buildDiagnostics(error, {
+                ...diagnostics,
+                ...(status !== undefined ? { upstreamStatus: status } : {})
+            })
+        });
+    }
     if (isChannelRequestModeFailure(error, diagnostics.channel_request_mode)) {
         const retryAfterSeconds = readRetryAfterSeconds(error) ?? 15;
         return new AgentApiError({
@@ -596,3 +612,8 @@ export function normalizeAgentError(error: unknown, diagnostics: AgentErrorDiagn
         diagnostics: buildDiagnostics(error, diagnostics)
     });
 }
+
+function isAcceptedImageTaskError(error: unknown): boolean {
+    const name = readStringField(error, 'name') || readConstructorName(error);
+    return name === 'AcceptedImageTaskResponseError' || name === 'AcceptedImageTaskStreamResultError';
+}

src/lib/image-route-mode-handlers.ts

@@ -1,4 +1,5 @@
 import { appLogger } from './app-logger';
+import type { ChannelRequestMode } from './channel-request-mode';
 import type { ChannelCredential } from './channel-router';
 import {
     RequestValidationError,
@@ -22,6 +23,10 @@ import {
     type StorageMode,
     type ValidOutputFormat
 } from './image-request-utils';
+import {
+    resolveAcceptedImageTaskResponse,
+    type AcceptedImageTaskResponseError
+} from './image-service';
 import {
     appendAccessCookie,
     reportServerCredentialFailure,
@@ -61,9 +66,11 @@ type CommonModeInput = {
     apiBaseUrl?: string;
     apiKey: string;
     startedAtMs: number;
+    upstreamIdempotencyKey?: string;
     clientRequestId?: string;
     requestLogContext?: RequestLogContext;
     selectedCredential?: ChannelCredential;
+    channelRequestMode?: ChannelRequestMode;
     accessCookie?: AccessCookie;
     abortSignal?: AbortSignal;
     streamFallbackEnabled?: boolean;
@@ -214,10 +221,26 @@ function readResponsesImageExtensions(
 function openAiRequestOptions(input: CommonModeInput): OpenAI.RequestOptions {
     return buildOpenAIImageRequestOptions({
         abortSignal: input.abortSignal,
+        idempotencyKey: input.upstreamIdempotencyKey,
         headers: mergeUpstreamHeadersWithFixed(input.upstreamHeaders, {})
     });
 }
 
+function onAcceptedImageTask(input: CommonModeInput, modeLabel: string) {
+    return (details: AcceptedImageTaskResponseError, attempt: number, delayMs: number) => {
+        appLogger.warn(`上游 ${modeLabel} 返回异步图片任务，等待后重试同步结果。`, {
+            ...input.requestLogContext,
+            idempotencyKey: input.upstreamIdempotencyKey,
+            channelId: input.selectedCredential?.channelId,
+            requestMode: input.channelRequestMode,
+            attempt,
+            delayMs,
+            taskId: details.taskId,
+            hasPollUrl: Boolean(details.pollUrl)
+        });
+    };
+}
+
 async function createResponsesImageResult(input: CommonModeInput, options: GenerateOptions): Promise<ImageModeResult> {
     if (options.n !== 1) {
         throw new RequestValidationError('Responses API 图片后端当前只支持单张生成。', 400);
@@ -235,6 +258,7 @@ async function createResponsesImageResult(input: CommonModeInput, options: Gener
             outputFormat: options.outputFormat,
             background: options.background,
             moderation: options.moderation,
+            idempotencyKey: input.upstreamIdempotencyKey,
             abortSignal: input.abortSignal,
             ...(options.outputCompression !== undefined ? { outputCompression: options.outputCompression } : {}),
             ...readResponsesImageExtensions(input.formData)
@@ -259,6 +283,7 @@ async function createResponsesImageResultOnly(
         outputFormat: options.outputFormat,
         background: options.background,
         moderation: options.moderation,
+        idempotencyKey: input.upstreamIdempotencyKey,
         abortSignal: input.abortSignal,
         ...(options.outputCompression !== undefined ? { outputCompression: options.outputCompression } : {}),
         ...readResponsesImageExtensions(input.formData)
@@ -282,6 +307,7 @@ async function createResponsesImageStreamResponse(
         outputFormat: options.outputFormat,
         background: options.background,
         moderation: options.moderation,
+        idempotencyKey: input.upstreamIdempotencyKey,
         partialImagesCount: toResponsesPartialImagesCount(input.partialImagesCount),
         abortSignal: input.abortSignal,
         ...(options.outputCompression !== undefined ? { outputCompression: options.outputCompression } : {}),
@@ -324,7 +350,10 @@ async function createImagesGenerateResultOnly(
     const params: OpenAI.Images.ImageGenerateParamsNonStreaming = { ...options.baseParams, stream: false };
     appLogger.info('调用 OpenAI generate。', input.requestLogContext);
     appLogger.debug('调用 OpenAI generate，参数：', { ...params, ...input.requestLogContext });
-    return input.openai.images.generate(params, openAiRequestOptions(input));
+    return resolveAcceptedImageTaskResponse(
+        () => input.openai.images.generate(params, openAiRequestOptions(input)).withResponse(),
+        { abortSignal: input.abortSignal, onAcceptedTask: onAcceptedImageTask(input, 'generate') }
+    );
 }
 
 async function createGenerateStreamResponse(
@@ -342,6 +371,7 @@ async function createGenerateStreamResponse(
             apiBaseUrl: input.apiBaseUrl,
             apiKey: input.apiKey,
             upstreamHeaders: input.upstreamHeaders,
+            idempotencyKey: input.upstreamIdempotencyKey,
             abortSignal: input.abortSignal,
             params: streamParams
         });
@@ -461,7 +491,10 @@ async function createEditResultOnly(
     };
     appLogger.info('调用 OpenAI edit。', input.requestLogContext);
     logEditParams(input, options, params);
-    return input.openai.images.edit(params, openAiRequestOptions(input));
+    return resolveAcceptedImageTaskResponse(
+        () => input.openai.images.edit(params, openAiRequestOptions(input)).withResponse(),
+        { abortSignal: input.abortSignal, onAcceptedTask: onAcceptedImageTask(input, 'edit') }
+    );
 }
 
 async function createEditStreamResponse(input: CommonModeInput, options: EditOptions): Promise<ImageModeResult> {
@@ -531,6 +564,7 @@ export async function handleEditImageMode(
             outputFormat: options.outputFormat,
             background: 'auto' as const,
             moderation: options.moderation,
+            idempotencyKey: input.upstreamIdempotencyKey,
             abortSignal: input.abortSignal,
             ...(options.outputCompression !== undefined ? { outputCompression: options.outputCompression } : {}),
             ...readResponsesImageExtensions(input.formData)

src/lib/image-route-support.test.ts

@@ -0,0 +1,40 @@
+import { describeInvalidImagesResponse, readClientRequestId } from './image-route-support';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+function formDataWithClientRequestId(value: string): FormData {
+    const formData = new FormData();
+    formData.append('clientRequestId', value);
+    return formData;
+}
+
+describe('describeInvalidImagesResponse', () => {
+    it('explains accepted async image tasks explicitly', () => {
+        const message = describeInvalidImagesResponse({
+            object: 'image.task',
+            status: 'pending',
+            task_id: 'sync-gen-task',
+            poll_url: '/api/image-tasks?ids=sync-gen-task&signature=secret'
+        });
+
+        assert.match(message, /同一业务幂等键有界重试后仍拿不到最终图片/);
+        assert.match(message, /poll_url=present/);
+        assert.equal(message.includes('signature=secret'), false);
+    });
+
+    it('keeps the generic explanation for ordinary invalid Images responses', () => {
+        assert.match(describeInvalidImagesResponse({}), /不是 OpenAI Images 格式/);
+    });
+});
+
+describe('readClientRequestId', () => {
+    it('rejects all HTTP header control characters', () => {
+        for (const value of ['bad\u0000request', 'bad\u007frequest', 'bad\trequest']) {
+            assert.throws(() => readClientRequestId(formDataWithClientRequestId(value)), /控制字符/);
+        }
+    });
+
+    it('treats trimmed full-width whitespace as an empty request id', () => {
+        assert.equal(readClientRequestId(formDataWithClientRequestId('\u3000')), undefined);
+    });
+});

src/lib/image-route-support.ts

@@ -9,6 +9,7 @@ import {
     isCredentialFailure
 } from './channel-router';
 import { RequestValidationError } from './image-request-utils';
+import { readAcceptedImageTaskDetails } from './accepted-image-task';
 import type { ImageGenerationBackend } from './image-upstream-strategy';
 import { getServerChannelState } from './server-channel-router';
 import { buildAccessCookie, outputDir, readBooleanEnv, serializeAccessCookie } from './server-runtime';
@@ -20,6 +21,8 @@ export type AccessCookie = ReturnType<typeof buildAccessCookie>;
 export type ImageBackend = ImageGenerationBackend;
 export type RequestLogContext = { clientRequestId: string };
 
+const HTTP_HEADER_VALUE_CONTROL_CHAR_PATTERN = /[\u0000-\u001f\u007f]/;
+
 export function readClientRequestId(formData: FormData): string | undefined {
     const value = formData.get('clientRequestId');
     if (typeof value !== 'string') return undefined;
@@ -30,6 +33,9 @@ export function readClientRequestId(formData: FormData): string | undefined {
             `clientRequestId 长度不能超过 ${PAGE_SSE_CLIENT_REQUEST_ID_MAX_LENGTH} 个字符。`
         );
     }
+    if (HTTP_HEADER_VALUE_CONTROL_CHAR_PATTERN.test(normalized)) {
+        throw new RequestValidationError('clientRequestId 不能包含控制字符。');
+    }
     return normalized;
 }
 
@@ -103,6 +109,12 @@ export function describeInvalidImagesResponse(result: unknown): string {
             return 'API 返回的是 HTML 页面，不是 OpenAI Images JSON 响应。请确认 API URL 填的是兼容接口根地址，通常需要以 /v1 结尾，例如 https://api.openai.com/v1；不要填写管理后台或网页首页地址。';
         }
     }
+    const acceptedTask = readAcceptedImageTaskDetails(result);
+    if (acceptedTask) {
+        const taskSuffix = acceptedTask.taskId ? ` task_id=${acceptedTask.taskId}` : '';
+        const pollSuffix = acceptedTask.pollUrl ? ' poll_url=present' : '';
+        return `上游返回了异步图片任务${taskSuffix}${pollSuffix}，不是可直接消费的 OpenAI Images 完成结果。如果同一业务幂等键有界重试后仍拿不到最终图片，就不能把该渠道配置为 images-non-stream；只有同键重试可返回最终图片，或上游轮询接口真实可用且服务端已接入任务轮询后，才能配置该请求方式。`;
+    }
     return 'API 返回的数据不是 OpenAI Images 格式。请确认 API URL 是 OpenAI 兼容接口，并且该接口支持 Images generate/edit。';
 }
 

src/lib/image-service.test.ts

@@ -0,0 +1,323 @@
+import {
+    AcceptedImageTaskResponseError,
+    assertOpenAiImagesResponse,
+    readAcceptedImageTaskDetails,
+    readRetryAfterSecondsHeader,
+    resolveAcceptedImageTaskResponse
+} from './image-service';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import type OpenAI from 'openai';
+
+describe('readAcceptedImageTaskDetails', () => {
+    it('extracts task metadata from async upstream image payloads', () => {
+        assert.deepEqual(
+            readAcceptedImageTaskDetails({
+                object: 'image.task',
+                status: 'pending',
+                task_id: '  sync-gen-task  ',
+                poll_url: '  /api/image-tasks?ids=sync-gen-task  '
+            }),
+            {
+                taskId: 'sync-gen-task',
+                pollUrl: '/api/image-tasks?ids=sync-gen-task'
+            }
+        );
+    });
+
+    it('ignores regular image responses', () => {
+        assert.equal(readAcceptedImageTaskDetails({ data: [{ b64_json: 'abc' }] }), undefined);
+    });
+
+    it('requires accepted task object and pending status', () => {
+        assert.equal(readAcceptedImageTaskDetails(null), undefined);
+        assert.equal(readAcceptedImageTaskDetails([]), undefined);
+        assert.equal(readAcceptedImageTaskDetails({ object: 'image.task', status: 'completed' }), undefined);
+        assert.equal(readAcceptedImageTaskDetails({ object: 'image.job', status: 'pending' }), undefined);
+        assert.deepEqual(readAcceptedImageTaskDetails({ object: 'image.task', status: 'pending' }), {});
+        assert.deepEqual(readAcceptedImageTaskDetails({ object: ' image.task ', status: ' pending ' }), {});
+    });
+});
+
+describe('assertOpenAiImagesResponse', () => {
+    it('rejects async task payloads that are not final OpenAI Images results', () => {
+        assert.throws(() =>
+            assertOpenAiImagesResponse({
+                object: 'image.task',
+                status: 'pending',
+                task_id: 'sync-gen-task'
+            })
+        );
+    });
+});
+
+describe('resolveAcceptedImageTaskResponse', () => {
+    it('retries accepted task payloads until the final image result arrives', async () => {
+        const calls: number[] = [];
+        const sleeps: number[] = [];
+        const result = await resolveAcceptedImageTaskResponse(
+            async () => {
+                calls.push(Date.now());
+                if (calls.length === 1) {
+                    return {
+                        data: {
+                            object: 'image.task',
+                            status: 'pending',
+                            task_id: 'sync-gen-task',
+                            poll_url: '/api/image-tasks?ids=sync-gen-task'
+                        } as unknown as OpenAI.Images.ImagesResponse,
+                        response: new Response('', { headers: { 'retry-after': '1' } })
+                    };
+                }
+                return {
+                    data: {
+                        data: [{ b64_json: 'final-base64' }],
+                        created: 123
+                    } as OpenAI.Images.ImagesResponse,
+                    response: new Response('', { headers: { 'retry-after': '1' } })
+                };
+            },
+            {
+                sleep: async (ms) => {
+                    sleeps.push(ms);
+                }
+            }
+        );
+
+        assert.equal(calls.length, 2);
+        assert.deepEqual(sleeps, [1000]);
+        assert.equal(result.data[0]?.b64_json, 'final-base64');
+    });
+
+    it('throws a structured error after exhausting accepted-task retries', async () => {
+        await assert.rejects(
+            () =>
+                resolveAcceptedImageTaskResponse(
+                    async () => ({
+                        data: {
+                            object: 'image.task',
+                            status: 'pending',
+                            task_id: 'sync-gen-task',
+                            poll_url: '/api/image-tasks?ids=sync-gen-task'
+                        } as unknown as OpenAI.Images.ImagesResponse,
+                        response: new Response('', { headers: { 'retry-after': '1' } })
+                    }),
+                    { maxAttempts: 1 }
+                ),
+            (error) => {
+                assert.ok(error instanceof AcceptedImageTaskResponseError);
+                assert.equal(error.taskId, 'sync-gen-task');
+                assert.equal(error.pollUrl, '/api/image-tasks?ids=sync-gen-task');
+                assert.equal(error.retryAfterSeconds, 1);
+                return true;
+            }
+        );
+    });
+
+    it('uses the default retry delay for fractional Retry-After values', async () => {
+        const sleeps: number[] = [];
+        const result = await resolveAcceptedImageTaskResponse(
+            async () => {
+                if (sleeps.length === 0) {
+                    return {
+                        data: {
+                            object: 'image.task',
+                            status: 'pending',
+                            task_id: 'fractional-retry-after-task'
+                        } as unknown as OpenAI.Images.ImagesResponse,
+                        response: new Response('', { headers: { 'retry-after': '0.5' } })
+                    };
+                }
+                return {
+                    data: {
+                        data: [{ b64_json: 'final-base64' }],
+                        created: 123
+                    } as OpenAI.Images.ImagesResponse,
+                    response: new Response('')
+                };
+            },
+            {
+                retryDelayMs: 2500,
+                sleep: async (ms) => {
+                    sleeps.push(ms);
+                }
+            }
+        );
+
+        assert.deepEqual(sleeps, [2500]);
+        assert.equal(result.data[0]?.b64_json, 'final-base64');
+    });
+
+    it('caps fallback retry delays for accepted task responses', async () => {
+        const sleeps: number[] = [];
+        const result = await resolveAcceptedImageTaskResponse(
+            async () => {
+                if (sleeps.length === 0) {
+                    return {
+                        data: {
+                            object: 'image.task',
+                            status: 'pending',
+                            task_id: 'large-fallback-delay-task'
+                        } as unknown as OpenAI.Images.ImagesResponse,
+                        response: new Response('')
+                    };
+                }
+                return {
+                    data: {
+                        data: [{ b64_json: 'final-base64' }],
+                        created: 123
+                    } as OpenAI.Images.ImagesResponse,
+                    response: new Response('')
+                };
+            },
+            {
+                retryDelayMs: 60_000,
+                sleep: async (ms) => {
+                    sleeps.push(ms);
+                }
+            }
+        );
+
+        assert.deepEqual(sleeps, [15_000]);
+        assert.equal(result.data[0]?.b64_json, 'final-base64');
+    });
+
+    it('respects whole-second Retry-After values above the fallback cap', async () => {
+        const sleeps: number[] = [];
+        const result = await resolveAcceptedImageTaskResponse(
+            async () => {
+                if (sleeps.length === 0) {
+                    return {
+                        data: {
+                            object: 'image.task',
+                            status: 'pending',
+                            task_id: 'long-retry-after-task'
+                        } as unknown as OpenAI.Images.ImagesResponse,
+                        response: new Response('', { headers: { 'retry-after': '30' } })
+                    };
+                }
+                return {
+                    data: {
+                        data: [{ b64_json: 'final-base64' }],
+                        created: 123
+                    } as OpenAI.Images.ImagesResponse,
+                    response: new Response('')
+                };
+            },
+            {
+                sleep: async (ms) => {
+                    sleeps.push(ms);
+                }
+            }
+        );
+
+        assert.deepEqual(sleeps, [30_000]);
+        assert.equal(result.data[0]?.b64_json, 'final-base64');
+    });
+
+    it('caps excessive Retry-After values for accepted task responses', async () => {
+        const sleeps: number[] = [];
+        const result = await resolveAcceptedImageTaskResponse(
+            async () => {
+                if (sleeps.length === 0) {
+                    return {
+                        data: {
+                            object: 'image.task',
+                            status: 'pending',
+                            task_id: 'excessive-retry-after-task'
+                        } as unknown as OpenAI.Images.ImagesResponse,
+                        response: new Response('', { headers: { 'retry-after': '999' } })
+                    };
+                }
+                return {
+                    data: {
+                        data: [{ b64_json: 'final-base64' }],
+                        created: 123
+                    } as OpenAI.Images.ImagesResponse,
+                    response: new Response('')
+                };
+            },
+            {
+                sleep: async (ms) => {
+                    sleeps.push(ms);
+                }
+            }
+        );
+
+        assert.deepEqual(sleeps, [300_000]);
+        assert.equal(result.data[0]?.b64_json, 'final-base64');
+    });
+
+    it('stops accepted-task backoff when the caller aborts', async () => {
+        const controller = new AbortController();
+        let sleepSawSignal = false;
+
+        await assert.rejects(
+            () =>
+                resolveAcceptedImageTaskResponse(
+                    async () => ({
+                        data: {
+                            object: 'image.task',
+                            status: 'pending',
+                            task_id: 'abortable-task'
+                        } as unknown as OpenAI.Images.ImagesResponse,
+                        response: new Response('')
+                    }),
+                    {
+                        abortSignal: controller.signal,
+                        sleep: async (_ms, abortSignal) => {
+                            sleepSawSignal = abortSignal === controller.signal;
+                            controller.abort(new Error('caller aborted'));
+                            if (abortSignal?.aborted) {
+                                throw abortSignal.reason;
+                            }
+                        }
+                    }
+                ),
+            /caller aborted/
+        );
+
+        assert.equal(sleepSawSignal, true);
+    });
+
+    it('preserves string abort reasons before retrying accepted tasks', async () => {
+        const controller = new AbortController();
+        let operationCalled = false;
+        controller.abort('caller stopped');
+
+        await assert.rejects(
+            () =>
+                resolveAcceptedImageTaskResponse(
+                    async () => {
+                        operationCalled = true;
+                        return {
+                            data: {
+                                object: 'image.task',
+                                status: 'pending',
+                                task_id: 'abort-string-reason-task'
+                            } as unknown as OpenAI.Images.ImagesResponse,
+                            response: new Response('')
+                        };
+                    },
+                    { abortSignal: controller.signal }
+                ),
+            /caller stopped/
+        );
+        assert.equal(operationCalled, false);
+    });
+});
+
+describe('readRetryAfterSecondsHeader', () => {
+    it('accepts positive whole seconds only', () => {
+        assert.equal(readRetryAfterSecondsHeader('1'), 1);
+        assert.equal(readRetryAfterSecondsHeader(' 3 '), 3);
+        assert.equal(readRetryAfterSecondsHeader('15'), 15);
+        assert.equal(readRetryAfterSecondsHeader('0'), undefined);
+        assert.equal(readRetryAfterSecondsHeader('0.5'), undefined);
+        assert.equal(readRetryAfterSecondsHeader('2.4'), undefined);
+        assert.equal(readRetryAfterSecondsHeader('abc'), undefined);
+        assert.equal(readRetryAfterSecondsHeader('999999999999999999999'), undefined);
+        assert.equal(readRetryAfterSecondsHeader('Wed, 21 Oct 2015 07:28:00 GMT'), undefined);
+        assert.equal(readRetryAfterSecondsHeader(3), undefined);
+    });
+});

src/lib/image-service.ts

@@ -1,4 +1,5 @@
 import { detectImageFormat, readImageDimensions, writeFileAtomic } from './agent-file-utils';
+import { readAcceptedImageTaskDetails } from './accepted-image-task';
 import { createImageResult, type StorageMode, type ValidOutputFormat } from './image-request-utils';
 import type { UpstreamRequestHeaders } from './image-upstream-profile';
 import { downloadSameOriginImageAsBase64 } from './image-url-result';
@@ -7,6 +8,14 @@ import fs from 'fs/promises';
 import type OpenAI from 'openai';
 import path from 'path';
 
+export { readAcceptedImageTaskDetails } from './accepted-image-task';
+export type { AcceptedImageTaskDetails } from './accepted-image-task';
+
+const DEFAULT_ACCEPTED_IMAGE_TASK_MAX_ATTEMPTS = 3;
+const DEFAULT_ACCEPTED_IMAGE_TASK_RETRY_DELAY_MS = 5_000;
+const MAX_ACCEPTED_IMAGE_TASK_RETRY_DELAY_MS = 15_000;
+const MAX_ACCEPTED_IMAGE_TASK_RETRY_AFTER_SECONDS = 300;
+
 export type PersistedOpenAiImage = {
     filename: string;
     b64Json: string;
@@ -45,6 +54,21 @@ export class MissingOpenAiImageDataError extends Error {
     }
 }
 
+export class AcceptedImageTaskResponseError extends Error {
+    readonly taskId?: string;
+    readonly pollUrl?: string;
+    readonly retryAfterSeconds?: number;
+    readonly status = 502;
+
+    constructor(input: { taskId?: string; pollUrl?: string; retryAfterSeconds?: number }) {
+        super('上游返回了异步图片任务，但没有拿到可直接消费的最终图片结果。');
+        this.name = 'AcceptedImageTaskResponseError';
+        this.taskId = input.taskId;
+        this.pollUrl = input.pollUrl;
+        this.retryAfterSeconds = input.retryAfterSeconds;
+    }
+}
+
 export function assertOpenAiImagesResponse(result: unknown): asserts result is ValidImagesResponse {
     const candidate = result as Partial<OpenAI.Images.ImagesResponse> | null | undefined;
     if (!candidate || typeof candidate !== 'object' || !Array.isArray(candidate.data) || candidate.data.length === 0) {
@@ -52,6 +76,89 @@ export function assertOpenAiImagesResponse(result: unknown): asserts result is V
     }
 }
 
+export function readRetryAfterSecondsHeader(value: unknown): number | undefined {
+    if (typeof value !== 'string') return undefined;
+    const normalized = value.trim();
+    if (!/^[1-9]\d*$/.test(normalized)) return undefined;
+    const parsed = Number(normalized);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) return undefined;
+    return parsed;
+}
+
+export async function resolveAcceptedImageTaskResponse<T extends OpenAI.Images.ImagesResponse>(
+    operation: () => Promise<{ data: T; response?: Response }>,
+    options: {
+        abortSignal?: AbortSignal;
+        maxAttempts?: number;
+        retryDelayMs?: number;
+        sleep?: (ms: number, abortSignal?: AbortSignal) => Promise<void>;
+        onAcceptedTask?: (details: AcceptedImageTaskResponseError, attempt: number, delayMs: number) => void;
+    } = {}
+): Promise<T> {
+    const maxAttempts = Math.max(1, options.maxAttempts ?? DEFAULT_ACCEPTED_IMAGE_TASK_MAX_ATTEMPTS);
+    const sleep = options.sleep ?? delayAcceptedImageTaskResponse;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        throwIfAcceptedImageTaskRetryAborted(options.abortSignal);
+        const { data, response } = await operation();
+        const acceptedTask = readAcceptedImageTaskDetails(data);
+        if (!acceptedTask) return data;
+
+        const retryDelayMs = readAcceptedImageTaskRetryDelayMs(
+            response?.headers.get('retry-after'),
+            options.retryDelayMs ?? DEFAULT_ACCEPTED_IMAGE_TASK_RETRY_DELAY_MS
+        );
+        const error = new AcceptedImageTaskResponseError({
+            ...acceptedTask,
+            retryAfterSeconds: Math.ceil(retryDelayMs / 1000)
+        });
+        if (attempt >= maxAttempts) throw error;
+        options.onAcceptedTask?.(error, attempt, retryDelayMs);
+        await sleep(retryDelayMs, options.abortSignal);
+    }
+
+    throw new Error('UNREACHABLE: resolveAcceptedImageTaskResponse exhausted without return or throw.');
+}
+
+function delayAcceptedImageTaskResponse(ms: number, abortSignal?: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            abortSignal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(readAbortReason(abortSignal));
+        };
+
+        if (abortSignal?.aborted) {
+            onAbort();
+            return;
+        }
+        abortSignal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+
+function throwIfAcceptedImageTaskRetryAborted(abortSignal?: AbortSignal): void {
+    if (!abortSignal?.aborted) return;
+    throw readAbortReason(abortSignal);
+}
+
+function readAbortReason(abortSignal?: AbortSignal): Error {
+    if (abortSignal?.reason instanceof Error) return abortSignal.reason;
+    if (abortSignal?.reason !== undefined) {
+        return new DOMException(`The operation was aborted: ${String(abortSignal.reason)}`, 'AbortError');
+    }
+    return new DOMException('The operation was aborted.', 'AbortError');
+}
+
+function readAcceptedImageTaskRetryDelayMs(value: unknown, fallbackMs: number): number {
+    const retryAfterSeconds = readRetryAfterSecondsHeader(value);
+    if (retryAfterSeconds === undefined) return Math.min(fallbackMs, MAX_ACCEPTED_IMAGE_TASK_RETRY_DELAY_MS);
+    return Math.min(retryAfterSeconds, MAX_ACCEPTED_IMAGE_TASK_RETRY_AFTER_SECONDS) * 1000;
+}
+
 export async function persistOpenAiImages(options: {
     result: OpenAI.Images.ImagesResponse;
     outputFormat: ValidOutputFormat;

src/lib/image-stream-collector.test.ts

@@ -1,4 +1,8 @@
-import { collectOpenAiImagesFromStream, MissingFinalImageStreamResultError } from './image-stream-collector';
+import {
+    AcceptedImageTaskStreamResultError,
+    collectOpenAiImagesFromStream,
+    MissingFinalImageStreamResultError
+} from './image-stream-collector';
 import { upstreamEvents } from './sse-test-utils';
 import assert from 'node:assert/strict';
 import http from 'node:http';
@@ -206,6 +210,58 @@ describe('collectOpenAiImagesFromStream', () => {
         );
     });
 
+    it('reports accepted image tasks explicitly when the upstream only returns task metadata', async () => {
+        await assert.rejects(
+            () =>
+                collectOpenAiImagesFromStream(
+                    upstreamEvents([
+                        {
+                            id: 'sync-gen-task',
+                            object: 'image.task',
+                            status: 'pending',
+                            task_id: 'sync-gen-task',
+                            poll_url: '/api/image-tasks?ids=sync-gen-task',
+                            message: 'Image task accepted. Poll poll_url with the same Authorization header.'
+                        }
+                    ])
+                ),
+            (error) => {
+                assert.ok(error instanceof AcceptedImageTaskStreamResultError);
+                assert.equal(error.taskId, 'sync-gen-task');
+                assert.equal(error.pollUrl, '/api/image-tasks?ids=sync-gen-task');
+                return true;
+            }
+        );
+    });
+
+    it('does not return partial image data after an accepted task event', async () => {
+        await assert.rejects(
+            () =>
+                collectOpenAiImagesFromStream(
+                    upstreamEvents([
+                        {
+                            type: 'image_generation.partial_image',
+                            partial_image_index: 0,
+                            b64_json: 'partial-before-task'
+                        },
+                        {
+                            id: 'partial-before-task-id',
+                            object: 'image.task',
+                            status: 'pending',
+                            task_id: 'partial-before-task-id',
+                            poll_url: '/api/image-tasks?ids=partial-before-task-id'
+                        }
+                    ])
+                ),
+            (error) => {
+                assert.ok(error instanceof AcceptedImageTaskStreamResultError);
+                assert.equal(error.taskId, 'partial-before-task-id');
+                assert.equal(error.pollUrl, '/api/image-tasks?ids=partial-before-task-id');
+                return true;
+            }
+        );
+    });
+
     it('fails explicitly when upstream stream stays idle past the configured interval', async () => {
         let returnCalled = false;
         const stream: AsyncIterable<unknown> = {

src/lib/image-stream-collector.ts

@@ -1,3 +1,4 @@
+import { readAcceptedImageTaskDetails } from './accepted-image-task';
 import { normalizeUpstreamImageStreamEventWithDiagnostics } from './image-stream-events';
 import type { UpstreamRequestHeaders } from './image-upstream-profile';
 import { downloadSameOriginImageAsBase64 } from './image-url-result';
@@ -20,6 +21,19 @@ export class MissingFinalImageStreamResultError extends Error {
     }
 }
 
+export class AcceptedImageTaskStreamResultError extends Error {
+    readonly status = 502;
+    readonly taskId?: string;
+    readonly pollUrl?: string;
+
+    constructor(input: { taskId?: string; pollUrl?: string }) {
+        super('上游返回了异步图片任务，但当前服务不支持该任务态的自动轮询。');
+        this.name = 'AcceptedImageTaskStreamResultError';
+        this.taskId = input.taskId;
+        this.pollUrl = input.pollUrl;
+    }
+}
+
 export async function collectOpenAiImagesFromStream(
     stream: AsyncIterable<unknown>,
     options: {
@@ -36,12 +50,17 @@ export async function collectOpenAiImagesFromStream(
     let usage: ImageUsage | undefined;
     let upstreamEventType: string | undefined;
     let partialImageCount = 0;
+    let acceptedTaskInfo: { taskId?: string; pollUrl?: string } | undefined;
 
     for await (const event of withStreamDataIntervalTimeout(
         stream,
         options.streamDataIntervalTimeoutMs ?? readImageStreamDataIntervalTimeoutMs()
     )) {
         const diagnostics = normalizeUpstreamImageStreamEventWithDiagnostics(event);
+        if (diagnostics.providerDialect === 'image_task_accepted') {
+            acceptedTaskInfo = readAcceptedImageTaskDetails(event) ?? {};
+            continue;
+        }
         if (diagnostics.providerDialect === 'sdk_parsed_fallback') {
             options.onStreamingDegraded?.('json_final_fallback');
         }
@@ -80,6 +99,10 @@ export async function collectOpenAiImagesFromStream(
         }
     }
 
+    if (acceptedTaskInfo) {
+        throw new AcceptedImageTaskStreamResultError(acceptedTaskInfo);
+    }
+
     if (data.length === 0) {
         throw new MissingFinalImageStreamResultError({ upstreamEventType, partialImageCount });
     }

src/lib/image-stream-events.test.ts

@@ -620,4 +620,19 @@ describe('normalizeUpstreamImageStreamEvent', () => {
         assert.equal(unknown.providerDialect, 'unknown_ignored_event');
         assert.deepEqual(unknown.events, []);
     });
+
+    it('recognizes accepted image task payloads as a dedicated provider dialect', () => {
+        const result = normalizeUpstreamImageStreamEventWithDiagnostics({
+            id: 'sync-gen-task',
+            object: 'image.task',
+            status: 'pending',
+            task_id: 'sync-gen-task',
+            poll_url: '/api/image-tasks?ids=sync-gen-task',
+            message: 'Image task accepted. Poll poll_url with the same Authorization header.'
+        });
+
+        assert.equal(result.providerDialect, 'image_task_accepted');
+        assert.deepEqual(result.events, []);
+        assert.equal(result.upstreamEventType, undefined);
+    });
 });

src/lib/image-stream-events.ts

@@ -1,3 +1,4 @@
+import { readAcceptedImageTaskDetails } from './accepted-image-task';
 import { extractImageBase64FromDataUrl, isRemoteHttpUrl, readResponsesImageResultBase64 } from './image-payload';
 import { asRecord, type JsonRecord } from './json-record';
 import { createHash } from 'node:crypto';
@@ -9,6 +10,7 @@ export type ImageStreamProviderDialect =
     | 'official_image_event'
     | 'responses_image_event'
     | 'otokapi_image_event'
+    | 'image_task_accepted'
     | 'sdk_parsed_fallback'
     | 'unknown_ignored_event';
 
@@ -417,8 +419,12 @@ function normalizeCompletedEvent(record: JsonRecord, eventType: string | undefin
 
 function classifyProviderDialect(
     eventType: string | undefined,
-    events: NormalizedImageStreamEvent[]
+    events: NormalizedImageStreamEvent[],
+    record: JsonRecord
 ): ImageStreamProviderDialect {
+    if (readAcceptedImageTaskDetails(record)) {
+        return 'image_task_accepted';
+    }
     if (eventType && OFFICIAL_EVENT_TYPES.has(eventType)) {
         return 'official_image_event';
     }
@@ -459,7 +465,7 @@ export function normalizeUpstreamImageStreamEventWithDiagnostics(event: unknown)
         events = [];
     }
 
-    const providerDialect = classifyProviderDialect(eventType, events);
+    const providerDialect = classifyProviderDialect(eventType, events, record);
     return {
         events,
         providerDialect,

src/lib/images-api-stream.test.ts

@@ -7,7 +7,6 @@ const originalFetch = globalThis.fetch;
 afterEach(() => {
     globalThis.fetch = originalFetch;
 });
-
 describe('createImagesApiGenerateStream', () => {
     it('keeps fixed protocol and authorization headers ahead of upstream extras', async () => {
         let observedAuthorization: string | null = null;
@@ -15,6 +14,7 @@ describe('createImagesApiGenerateStream', () => {
         let observedContentType: string | null = null;
         let observedUserAgent: string | null = null;
         let observedAppId: string | null = null;
+        let observedIdempotencyKey: string | null = null;
         globalThis.fetch = async (_url, init) => {
             const headers = new Headers(init?.headers);
             observedAuthorization = headers.get('authorization');
@@ -22,6 +22,7 @@ describe('createImagesApiGenerateStream', () => {
             observedContentType = headers.get('content-type');
             observedUserAgent = headers.get('user-agent');
             observedAppId = headers.get('x-app-id');
+            observedIdempotencyKey = headers.get('idempotency-key');
             return new Response(JSON.stringify({ data: [] }), {
                 status: 200,
                 headers: { 'content-type': 'application/json' }
@@ -37,10 +38,12 @@ describe('createImagesApiGenerateStream', () => {
                 stream: true,
                 partial_images: 2
             },
+            idempotencyKey: 'stream-idempotency-key',
             upstreamHeaders: {
                 Authorization: 'Bearer wrong-key',
                 Accept: 'application/json',
                 'Content-Type': 'text/plain',
+                'Idempotency-Key': 'wrong-key',
                 'X-App-ID': 'app-id'
             }
         });
@@ -50,6 +53,7 @@ describe('createImagesApiGenerateStream', () => {
         assert.equal(observedContentType, 'application/json');
         assert.equal(observedUserAgent, 'gpt-image-playground/2.1.0');
         assert.equal(observedAppId, 'app-id');
+        assert.equal(observedIdempotencyKey, 'stream-idempotency-key');
     });
 
     it('aborts hanging stream setup using the configured upstream timeout', async () => {

src/lib/images-api-stream.ts

@@ -16,6 +16,7 @@ type ImagesApiStreamInput = {
     apiBaseUrl?: string;
     apiKey: string;
     upstreamHeaders?: UpstreamRequestHeaders;
+    idempotencyKey?: string;
     abortSignal?: AbortSignal;
     timeoutMs?: number;
     params: OpenAI.Images.ImageGenerateParamsStreaming;
@@ -132,7 +133,7 @@ function readSseChunk(chunk: string): unknown | undefined {
 }
 
 export async function createImagesApiGenerateStream(input: ImagesApiStreamInput): Promise<AsyncIterable<unknown>> {
-    const { abortSignal, apiBaseUrl, apiKey, params, upstreamHeaders } = input;
+    const { abortSignal, apiBaseUrl, apiKey, idempotencyKey, params, upstreamHeaders } = input;
     const abortContext = createAbortContext({ abortSignal, timeoutMs: input.timeoutMs });
     let response: Response;
     try {
@@ -141,7 +142,8 @@ export async function createImagesApiGenerateStream(input: ImagesApiStreamInput)
             headers: mergeUpstreamHeadersWithFixed(upstreamHeaders, {
                 Authorization: `Bearer ${apiKey}`,
                 'Content-Type': 'application/json',
-                Accept: 'text/event-stream, application/json'
+                Accept: 'text/event-stream, application/json',
+                ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {})
             }),
             signal: abortContext.signal,
             body: JSON.stringify(params)

src/lib/openai-image-transport.test.ts

@@ -43,6 +43,18 @@ describe('openai image transport settings', () => {
         assert.equal(buildOpenAIImageRequestOptions({ env }).maxRetries, 1);
     });
 
+    it('sends the idempotency key as an explicit upstream header', () => {
+        const options = buildOpenAIImageRequestOptions({
+            headers: { 'Idempotency-Key': 'configured-wrong-key', 'X-App-ID': 'app-id' },
+            idempotencyKey: 'business-operation-key'
+        });
+        const headers = new Headers(options.headers as HeadersInit);
+
+        assert.equal(options.idempotencyKey, 'business-operation-key');
+        assert.equal(headers.get('idempotency-key'), 'business-operation-key');
+        assert.equal(headers.get('x-app-id'), 'app-id');
+    });
+
     it('rejects invalid transport env values explicitly', () => {
         assert.throws(() => readImageUpstreamTimeoutMs({ IMAGE_UPSTREAM_TIMEOUT_MS: '15s' }), /非负整数/);
         assert.throws(() => readImageUpstreamTimeoutMs({ IMAGE_UPSTREAM_TIMEOUT_MS: '0' }), /正整数/);

src/lib/openai-image-transport.ts

@@ -42,12 +42,15 @@ export function buildOpenAIImageRequestOptions(
     input: {
         abortSignal?: AbortSignal;
         headers?: OpenAI.RequestOptions['headers'];
+        idempotencyKey?: string;
         env?: ImageTransportEnv;
     } = {}
 ): OpenAI.RequestOptions {
+    const headers = mergeRequestHeaders(input.headers, readIdempotencyHeader(input.idempotencyKey));
     return {
         ...(input.abortSignal ? { signal: input.abortSignal } : {}),
-        ...(input.headers ? { headers: input.headers } : {}),
+        ...(headers ? { headers } : {}),
+        ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
         timeout: readImageUpstreamTimeoutMs(input.env),
         maxRetries: readImageUpstreamMaxRetries(input.env)
     };
@@ -81,3 +84,20 @@ function readPositiveIntegerEnv(env: ImageTransportEnv, fieldName: string, fallb
     }
     return value;
 }
+
+function readIdempotencyHeader(idempotencyKey: string | undefined): Record<string, string> | undefined {
+    const value = idempotencyKey?.trim();
+    return value ? { 'Idempotency-Key': value } : undefined;
+}
+
+function mergeRequestHeaders(
+    headers: OpenAI.RequestOptions['headers'] | undefined,
+    fixedHeaders: Record<string, string> | undefined
+): OpenAI.RequestOptions['headers'] | undefined {
+    if (!fixedHeaders) return headers;
+    const normalizedHeaders = new Headers(headers as HeadersInit | undefined);
+    for (const [name, value] of Object.entries(fixedHeaders)) {
+        normalizedHeaders.set(name, value);
+    }
+    return normalizedHeaders;
+}

src/lib/responses-image-backend.ts

@@ -35,6 +35,7 @@ export type ResponsesImageGenerateInput = {
     outputCompression?: number;
     promptOptimization?: boolean;
     thinking?: string;
+    idempotencyKey?: string;
     abortSignal?: AbortSignal;
 };
 
@@ -196,7 +197,7 @@ export async function generateImageWithResponsesBackend(
             tool_choice: { type: 'image_generation' },
             tools: [buildResponsesImageTool(input)]
         },
-        buildOpenAIImageRequestOptions({ abortSignal: input.abortSignal })
+        buildOpenAIImageRequestOptions({ abortSignal: input.abortSignal, idempotencyKey: input.idempotencyKey })
     );
     const imageResults = extractCompletedImageResults(response.output);
 
@@ -226,7 +227,7 @@ export async function editImageWithResponsesBackend(
             tool_choice: { type: 'image_generation' },
             tools: [await buildResponsesImageEditTool(input)]
         },
-        buildOpenAIImageRequestOptions({ abortSignal: input.abortSignal })
+        buildOpenAIImageRequestOptions({ abortSignal: input.abortSignal, idempotencyKey: input.idempotencyKey })
     );
     const imageResults = extractCompletedImageResults(response.output);
 
@@ -254,7 +255,7 @@ export async function createResponsesImageStream(input: ResponsesImageStreamInpu
             tool_choice: { type: 'image_generation' },
             tools: [buildResponsesImageTool(input, input.partialImagesCount)]
         },
-        buildOpenAIImageRequestOptions({ abortSignal: input.abortSignal })
+        buildOpenAIImageRequestOptions({ abortSignal: input.abortSignal, idempotencyKey: input.idempotencyKey })
     );
 }
 
@@ -269,6 +270,6 @@ export async function createResponsesImageEditStream(
             tool_choice: { type: 'image_generation' },
             tools: [await buildResponsesImageEditTool(input, input.partialImagesCount)]
         },
-        buildOpenAIImageRequestOptions({ abortSignal: input.abortSignal })
+        buildOpenAIImageRequestOptions({ abortSignal: input.abortSignal, idempotencyKey: input.idempotencyKey })
     );
 }

src/lib/upstream-request-headers.test.ts

@@ -61,6 +61,14 @@ describe('upstream request headers', () => {
                 ),
             /不能配置 Content-Type/
         );
+        assert.throws(
+            () =>
+                normalizeConfiguredUpstreamHeaders(
+                    { 'Idempotency-Key': 'same-key-for-every-request' },
+                    'OPENAI_CHANNEL_1_UPSTREAM_HEADERS_JSON'
+                ),
+            /不能配置 Idempotency-Key/
+        );
     });
 
     it('summarizes request headers without exposing secret values', () => {

src/lib/upstream-request-headers.ts

@@ -10,12 +10,22 @@ export type UpstreamRequestHeaderSummary = {
 };
 
 const DEFAULT_PRODUCT_USER_AGENT = `gpt-image-playground/${packageJson.version}`;
-const CONFIGURABLE_HEADER_BLOCKLIST = new Set(['authorization', 'accept', 'content-type', 'content-length', 'host']);
+const CONFIGURABLE_HEADER_BLOCKLIST = new Set([
+    'authorization',
+    'accept',
+    'content-type',
+    'content-length',
+    'host',
+    'idempotency-key'
+]);
+// Defense-in-depth: fixed idempotency headers must never leak from extra upstream headers.
+const ALWAYS_FILTERED_EXTRA_HEADER_NAMES = new Set(['idempotency-key']);
 const CANONICAL_HEADER_NAMES: Record<string, string> = {
     accept: 'Accept',
     authorization: 'Authorization',
     'content-length': 'Content-Length',
     'content-type': 'Content-Type',
+    'idempotency-key': 'Idempotency-Key',
     'user-agent': 'User-Agent',
     'x-app-id': 'X-App-ID',
     'x-app-secret': 'X-App-Secret'
@@ -68,7 +78,10 @@ export function mergeUpstreamHeadersWithFixed(
     const extraHeaders = normalizeHeaderMap(upstreamHeaders, { rejectBlocked: false });
     const fixedNames = new Set(Object.keys(fixedHeaders).map((name) => name.toLowerCase()));
     const filteredExtraHeaders = Object.fromEntries(
-        Object.entries({ ...baseHeaders, ...extraHeaders }).filter(([name]) => !fixedNames.has(name.toLowerCase()))
+        Object.entries({ ...baseHeaders, ...extraHeaders }).filter(([name]) => {
+            const lowerName = name.toLowerCase();
+            return !fixedNames.has(lowerName) && !ALWAYS_FILTERED_EXTRA_HEADER_NAMES.has(lowerName);
+        })
     );
     return {
         ...filteredExtraHeaders,