ai-world-sdk 1.5.8 → 1.5.9

package/dist/__tests__/llm.real.test.js

@@ -45,6 +45,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const dotenv = __importStar(require("dotenv"));
 const llm_1 = require("../llm");
+const image_1 = require("../image");
 const config_1 = require("../config");
 const ai_1 = require("ai");
 // 加载环境变量
@@ -214,17 +215,17 @@ describe("llm.ts — 真实集成测试（文本 + 图像）", () => {
     // ============================================================
     // createProvider + generateImage（kunpo 图像生成）
     // ============================================================
-    describe("createProvider + generateImage（kunpo 图像）", () => {
+    describe("generateKunpoImage（kunpo 图像）", () => {
         const promptArg = "A simple red circle on a white background";
-        test("kunpo — openai/gpt-5.4-image-2", async () => {
-            const modelId = process.env.KUNPO_IMAGE_MODEL || "openai/gpt-5.4-image-2";
-            const provider = (0, llm_1.createProvider)("kunpo", "openai", PLUGIN_ID);
-            const imageModel = provider.imageModel(modelId);
-            const result = await (0, ai_1.generateImage)({
-                model: imageModel,
+        test("kunpo — Image-GI2（异步）", async () => {
+            const modelId = process.env.KUNPO_IMAGE_MODEL || "Image-GI2";
+            const result = await (0, image_1.generateKunpoImage)({
+                pluginId: PLUGIN_ID,
+                model: modelId,
                 prompt: promptArg,
-                n: 1,
                 size: "1024x1024",
+                quality: "high",
+                async: true,
             });
             expect(result.images).toBeDefined();
             expect(result.images.length).toBeGreaterThan(0);
@@ -294,9 +295,10 @@ describe("llm.ts — 真实集成测试（文本 + 图像）", () => {
             const provider = (0, llm_1.createProvider)("api2img", "openai", "test");
             expect(typeof provider.languageModel).toBe("function");
         });
-        test("kunpo provider 实例有 imageModel 方法", () => {
-            const provider = (0, llm_1.createProvider)("kunpo", "openai", "test");
-            expect(typeof provider.imageModel).toBe("function");
+        test("getImageProxyConfig 返回 /api/llm/image 代理地址", () => {
+            const { getImageProxyConfig } = require("../image");
+            const cfg = getImageProxyConfig("test");
+            expect(cfg.baseUrl).toContain("/api/llm/image");
         });
     });
 });

package/dist/cli/commands/image.js

@@ -36,9 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerImageCommands = registerImageCommands;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const ai_1 = require("ai");
 const index_1 = require("../../index");
-const config_1 = require("../config");
+const config_1 = require("../../config");
+const config_2 = require("../config");
 const output_1 = require("../output");
 const utils_1 = require("../utils");
 function collectOpts(cmd) {
@@ -63,22 +63,86 @@ function stripB64ForLog(obj) {
     }
     return copy;
 }
+async function downloadUrlToFile(url, outputPath) {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`下载图像失败: ${res.status}`);
+    }
+    const abs = path.resolve(outputPath);
+    const dir = path.dirname(abs);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(abs, Buffer.from(await res.arrayBuffer()));
+}
+/** OpenAI 图像：经 /api/llm/openai 代理（HTTP，非 AI SDK） */
+async function generateOpenAIImageViaProxy(pluginId, model, prompt, size) {
+    const serverUrl = config_1.sdkConfig.getServerUrl() || '';
+    const token = config_1.sdkConfig.getToken() || '';
+    const body = {
+        model,
+        prompt,
+        n: 1,
+        response_format: 'b64_json',
+    };
+    if (size)
+        body.size = size;
+    const res = await fetch(`${serverUrl}/api/llm/openai/images/generations`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'X-Plugin-Id': pluginId,
+            'X-Provider': 'api2img',
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`OpenAI 图像生成失败: ${res.status} ${text}`);
+    }
+    const json = (await res.json());
+    const first = json.data?.[0];
+    if (!first) {
+        throw new Error('OpenAI 图像生成响应无数据');
+    }
+    if (first.b64_json) {
+        const buf = Buffer.from(first.b64_json, 'base64');
+        return { uint8Array: new Uint8Array(buf), mediaType: 'image/png' };
+    }
+    if (first.url) {
+        const imgRes = await fetch(first.url);
+        if (!imgRes.ok) {
+            throw new Error(`下载图像失败: ${imgRes.status}`);
+        }
+        const buf = Buffer.from(await imgRes.arrayBuffer());
+        return {
+            uint8Array: new Uint8Array(buf),
+            mediaType: imgRes.headers.get('content-type') || 'image/png',
+            url: first.url,
+        };
+    }
+    throw new Error('OpenAI 图像生成响应无 url 或 b64_json');
+}
 function registerImageCommands(program) {
-    const image = program.command('image').description('图像生成（doubao / gemini / openai）');
+    const image = program
+        .command('image')
+        .description('图像生成（doubao / gemini / openai / kunpo）');
     image
         .command('generate')
-        .requiredOption('--provider <name>', 'doubao, gemini, or openai')
+        .requiredOption('--provider <name>', 'doubao, gemini, openai, or kunpo')
         .requiredOption('--prompt <text>', 'Prompt text')
         .option('--model <id>', 'Model id')
-        .option('--size <value>', 'Size (provider-specific)')
+        .option('--size <value>', 'Size e.g. 1024x1024, 1536x1024')
+        .option('--quality <value>', 'KUNPO quality: low, standard, medium, high, hd')
+        .option('--sync', 'KUNPO: use sync /images/generations (not recommended)')
         .option('--output <file>', 'Write first image to file')
-        .option('--plugin-id <id>', 'Plugin id (required for openai)')
+        .option('--plugin-id <id>', 'Plugin id (required for openai / kunpo)')
         .action(async (options, cmd) => {
         const commandName = 'image generate';
         try {
             void (0, utils_1.getFormat)(program);
             const o = collectOpts(cmd);
-            const auth = (0, config_1.resolveAuth)({
+            const auth = (0, config_2.resolveAuth)({
                 baseUrl: o.baseUrl,
                 token: o.token,
                 pluginId: options.pluginId ??
@@ -88,8 +152,8 @@ function registerImageCommands(program) {
             (0, utils_1.requireOption)(options.prompt, 'prompt');
             (0, utils_1.requireOption)(options.provider, 'provider');
             const providerName = options.provider.toLowerCase();
-            if (!['doubao', 'gemini', 'openai'].includes(providerName)) {
-                const err = new Error('缺少必需参数: --provider 必须是 doubao、gemini 或 openai');
+            if (!['doubao', 'gemini', 'openai', 'kunpo'].includes(providerName)) {
+                const err = new Error('缺少必需参数: --provider 必须是 doubao、gemini、openai 或 kunpo');
                 err.code = 'VALIDATION_ERROR';
                 throw err;
             }
@@ -106,15 +170,7 @@ function registerImageCommands(program) {
                         (0, utils_1.writeOutputFile)(options.output, Buffer.from(first.b64_json, 'base64'));
                     }
                     else if (first?.url) {
-                        const abs = path.resolve(options.output);
-                        const dir = path.dirname(abs);
-                        if (!fs.existsSync(dir))
-                            fs.mkdirSync(dir, { recursive: true });
-                        const res = await fetch(first.url);
-                        if (!res.ok) {
-                            throw new Error(`下载图像失败: ${res.status}`);
-                        }
-                        fs.writeFileSync(abs, Buffer.from(await res.arrayBuffer()));
+                        await downloadUrlToFile(first.url, options.output);
                     }
                 }
                 (0, output_1.outputJSON)(options.output ? stripB64ForLog({ ...result, savedTo: options.output }) : result);
@@ -136,15 +192,7 @@ function registerImageCommands(program) {
                         (0, utils_1.writeOutputFile)(options.output, Buffer.from(first.b64_json, 'base64'));
                     }
                     else if (first?.url) {
-                        const abs = path.resolve(options.output);
-                        const dir = path.dirname(abs);
-                        if (!fs.existsSync(dir))
-                            fs.mkdirSync(dir, { recursive: true });
-                        const res = await fetch(first.url);
-                        if (!res.ok) {
-                            throw new Error(`下载图像失败: ${res.status}`);
-                        }
-                        fs.writeFileSync(abs, Buffer.from(await res.arrayBuffer()));
+                        await downloadUrlToFile(first.url, options.output);
                     }
                 }
                 (0, output_1.outputJSON)(options.output ? stripB64ForLog({ ...result, savedTo: options.output }) : result);
@@ -155,28 +203,83 @@ function registerImageCommands(program) {
                 auth.pluginId;
             (0, utils_1.requireOption)(pluginId, 'plugin-id');
             (0, utils_1.initSDK)({ ...auth, pluginId });
-            const provider = (0, index_1.createProvider)('api2img', 'openai', pluginId);
-            const modelId = options.model || 'dall-e-3';
-            const genOpts = {
-                model: provider.imageModel(modelId),
-                prompt: options.prompt,
-                n: 1,
-            };
-            if (options.size) {
-                genOpts.size = options.size;
+            if (providerName === 'kunpo') {
+                const modelId = options.model || 'Image-GI2';
+                const useSync = Boolean(options.sync);
+                if (useSync) {
+                    const body = {
+                        model: modelId,
+                        prompt: options.prompt,
+                        response_format: 'b64_json',
+                        n: 1,
+                    };
+                    if (options.size && /^\d+x\d+$|auto/.test(options.size)) {
+                        body.size = options.size;
+                    }
+                    if (options.quality) {
+                        body.quality = options.quality;
+                    }
+                    const resp = await (0, index_1.generateImageSync)(pluginId, body);
+                    const first = resp.data?.[0];
+                    if (options.output && first?.b64_json) {
+                        (0, utils_1.writeOutputFile)(options.output, Buffer.from(first.b64_json, 'base64'));
+                    }
+                    else if (options.output && first?.url) {
+                        await downloadUrlToFile(first.url, options.output);
+                    }
+                    (0, output_1.outputJSON)({
+                        provider: 'kunpo',
+                        model: modelId,
+                        mode: 'sync',
+                        proxy: (0, index_1.getImageProxyConfig)(pluginId).baseUrl,
+                        savedTo: options.output || undefined,
+                        data: resp.data?.map((d) => ({
+                            ...d,
+                            b64_json: d.b64_json ? '[omitted]' : undefined,
+                        })),
+                    });
+                    return;
+                }
+                const kunpoOpts = {
+                    pluginId: pluginId,
+                    model: modelId,
+                    prompt: options.prompt,
+                    async: true,
+                };
+                if (options.size && /^\d+x\d+$|auto/.test(options.size)) {
+                    kunpoOpts.size = options.size;
+                }
+                if (options.quality) {
+                    kunpoOpts.quality = options.quality;
+                }
+                const imgResult = await (0, index_1.generateKunpoImage)(kunpoOpts);
+                const first = imgResult.images[0];
+                if (options.output && first) {
+                    (0, utils_1.writeOutputFile)(options.output, Buffer.from(first.uint8Array));
+                }
+                (0, output_1.outputJSON)({
+                    provider: 'kunpo',
+                    model: modelId,
+                    mode: 'async',
+                    taskId: imgResult.taskId,
+                    resultUrl: imgResult.resultUrl,
+                    mediaType: first?.mediaType,
+                    savedTo: options.output || undefined,
+                });
+                return;
             }
-            const imgResult = await (0, ai_1.generateImage)(genOpts);
-            const first = imgResult.images[0];
-            if (options.output && first) {
-                (0, utils_1.writeOutputFile)(options.output, Buffer.from(first.uint8Array));
+            // openai：/api/llm/openai 代理 HTTP
+            const modelId = options.model || 'dall-e-3';
+            const img = await generateOpenAIImageViaProxy(pluginId, modelId, options.prompt, options.size);
+            if (options.output) {
+                (0, utils_1.writeOutputFile)(options.output, Buffer.from(img.uint8Array));
             }
             (0, output_1.outputJSON)({
                 provider: 'openai',
                 model: modelId,
-                mediaType: first?.mediaType,
+                mediaType: img.mediaType,
+                url: img.url,
                 savedTo: options.output || undefined,
-                usage: imgResult.usage,
-                warnings: imgResult.warnings,
             });
         }
         catch (err) {

package/dist/config.d.ts

@@ -9,7 +9,7 @@
  *
  * 注意: {VERSION} 占位符会在构建时被替换为实际版本号
  */
-export declare const SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.8";
+export declare const SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.9";
 /**
  * 版本兼容性错误
  */
@@ -35,8 +35,8 @@ declare class SDKConfig {
     private _authCheckPromise;
     private _currentUser;
     private _cliMode;
-    readonly sdkSignature = "AI_WORLD_SDK_V:1.5.8";
-    readonly sdkVersion = "1.5.8";
+    readonly sdkSignature = "AI_WORLD_SDK_V:1.5.9";
+    readonly sdkVersion = "1.5.9";
     constructor();
     /**
      * Set global base URL

package/dist/config.js

@@ -7,7 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sdkConfig = exports.VersionCompatibilityError = exports.SDK_SIGNATURE = void 0;
 // SDK 版本号（构建时自动从 package.json 更新）
 // 此版本号会在运行 npm run build 时自动从 package.json 读取并更新
-const SDK_VERSION = "1.5.8";
+const SDK_VERSION = "1.5.9";
 /**
  * SDK 特征码 - 用于在构建后的 JS 文件中识别 SDK 版本
  * 格式: AI_WORLD_SDK_V:版本号
@@ -15,7 +15,7 @@ const SDK_VERSION = "1.5.8";
  *
  * 注意: {VERSION} 占位符会在构建时被替换为实际版本号
  */
-exports.SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.8";
+exports.SDK_SIGNATURE = "AI_WORLD_SDK_V:1.5.9";
 /**
  * 版本兼容性错误
  */

package/dist/image.d.ts

@@ -0,0 +1,93 @@
+/** 腾讯 AIART 支持的模型 */
+export type KunpoTencentImageModel = "Image-GI" | "Image-GI2" | "Image-GPT2";
+/** OpenAI Images 兼容的 quality（GI 映射分辨率，GPT 映射质量档位） */
+export type KunpoImageQuality = "low" | "standard" | "medium" | "high" | "hd";
+export type KunpoInputFidelity = "high" | "low";
+export type KunpoResponseFormat = "url" | "b64_json";
+export interface KunpoImageGenerationOptions {
+    pluginId: string;
+    model: KunpoTencentImageModel | string;
+    prompt: string;
+    /** 默认 true：POST /images/tasks + 轮询 */
+    async?: boolean;
+    /** 图片数量，默认 1 */
+    n?: number;
+    /** 图片宽高，默认 auto：自动根据模型和质量生成 */
+    size?: `${number}x${number}` | "auto";
+    quality?: KunpoImageQuality;
+    responseFormat?: KunpoResponseFormat;
+    /** 图生图参考图 URL 数组 */
+    images?: string[];
+    /** 图生图 */
+    image?: string;
+    background?: string;
+    outputFormat?: "png";
+    inputFidelity?: KunpoInputFidelity;
+    seed?: number;
+    maxRetries?: number;
+    abortSignal?: AbortSignal;
+    headers?: Record<string, string>;
+    /** 轮询间隔时间，默认 30000ms */
+    pollIntervalMs?: number;
+    /** 轮询超时时间，默认 15 * 60 * 1000ms */
+    pollTimeoutMs?: number;
+}
+export interface GeneratedImageFile {
+    base64: string;
+    uint8Array: Uint8Array;
+    mediaType: string;
+    url?: string;
+}
+export interface KunpoImageGenerationResult {
+    image: GeneratedImageFile;
+    images: GeneratedImageFile[];
+    taskId?: string;
+    resultUrl?: string;
+}
+interface KunpoTaskSubmitResponse {
+    id?: string;
+    task_id?: string;
+    model?: string;
+    status?: string;
+    created_at?: number;
+}
+interface KunpoTaskQueryResponse {
+    code?: string;
+    data?: {
+        task_id?: string;
+        status?: string;
+        result_url?: string;
+        fail_reason?: string;
+    };
+}
+interface OpenAIImageGenerationResponse {
+    created?: number;
+    data?: Array<{
+        url?: string;
+        b64_json?: string;
+        revised_prompt?: string;
+    }>;
+}
+/** 后端图像专用代理 /api/llm/image */
+export declare function getImageProxyConfig(pluginId: string, headers?: Record<string, string>): {
+    baseUrl: string;
+    headers: Record<string, string>;
+};
+export declare function bytesFromUrl(url: string, signal?: AbortSignal): Promise<GeneratedImageFile>;
+/** POST /api/llm/image/images/tasks */
+export declare function submitImageTask(pluginId: string, body: Record<string, unknown>, signal?: AbortSignal, headers?: Record<string, string>): Promise<KunpoTaskSubmitResponse>;
+/** GET /api/llm/image/images/tasks/:taskId */
+export declare function getImageTask(pluginId: string, taskId: string, signal?: AbortSignal, headers?: Record<string, string>): Promise<KunpoTaskQueryResponse>;
+/** POST /api/llm/image/images/generations（同步，不推荐生产使用） */
+export declare function generateImageSync(pluginId: string, body: Record<string, unknown>, signal?: AbortSignal, headers?: Record<string, string>): Promise<OpenAIImageGenerationResponse>;
+export declare function pollImageTask(pluginId: string, taskId: string, options?: {
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    abortSignal?: AbortSignal;
+    headers?: Record<string, string>;
+}): Promise<string>;
+/**
+ * 通过后端 /api/llm/image 代理生成图像（默认异步）
+ */
+export declare function generateKunpoImage(options: KunpoImageGenerationOptions): Promise<KunpoImageGenerationResult>;
+export {};

package/dist/image.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getImageProxyConfig = getImageProxyConfig;
+exports.bytesFromUrl = bytesFromUrl;
+exports.submitImageTask = submitImageTask;
+exports.getImageTask = getImageTask;
+exports.generateImageSync = generateImageSync;
+exports.pollImageTask = pollImageTask;
+exports.generateKunpoImage = generateKunpoImage;
+const config_1 = require("./config");
+const TERMINAL_TASK_STATUSES = new Set(["SUCCESS", "FAILURE"]);
+/** 后端图像专用代理 /api/llm/image */
+function getImageProxyConfig(pluginId, headers) {
+    const serverUrl = config_1.sdkConfig.getServerUrl() || "";
+    const token = config_1.sdkConfig.getToken() || "proxy";
+    return {
+        baseUrl: `${serverUrl}/api/llm/image`,
+        headers: {
+            "Content-Type": "application/json",
+            "X-Plugin-Id": pluginId,
+            "X-Provider": "kunpo",
+            Authorization: `Bearer ${token}`,
+            ...headers,
+        },
+    };
+}
+function buildSyncBody(options) {
+    const body = {
+        model: options.model,
+        prompt: options.prompt,
+        response_format: options.responseFormat ?? "b64_json",
+    };
+    if (options.n != null)
+        body.n = options.n;
+    if (options.size)
+        body.size = options.size;
+    if (options.quality)
+        body.quality = options.quality;
+    if (options.images?.length)
+        body.images = options.images;
+    if (options.image)
+        body.image = options.image;
+    if (options.background)
+        body.background = options.background;
+    if (options.outputFormat)
+        body.output_format = options.outputFormat;
+    if (options.inputFidelity)
+        body.input_fidelity = options.inputFidelity;
+    if (options.seed != null)
+        body.seed = options.seed;
+    return body;
+}
+function buildAsyncSubmitBody(options) {
+    const body = {
+        model: options.model,
+        prompt: options.prompt,
+    };
+    if (options.size)
+        body.size = options.size;
+    if (options.images?.length)
+        body.images = options.images;
+    if (options.image)
+        body.image = options.image;
+    if (options.outputFormat)
+        body.output_format = options.outputFormat;
+    if (options.inputFidelity)
+        body.input_fidelity = options.inputFidelity;
+    if (options.quality) {
+        body.metadata = { quality: options.quality };
+    }
+    return body;
+}
+async function sleep(ms, signal) {
+    if (signal?.aborted) {
+        throw new DOMException("Aborted", "AbortError");
+    }
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        if (signal) {
+            const onAbort = () => {
+                clearTimeout(timer);
+                reject(new DOMException("Aborted", "AbortError"));
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+    });
+}
+async function bytesFromUrl(url, signal) {
+    const res = await fetch(url, { signal });
+    if (!res.ok) {
+        throw new Error(`下载生成图片失败: ${res.status} ${res.statusText}`);
+    }
+    const buffer = await res.arrayBuffer();
+    const uint8Array = new Uint8Array(buffer);
+    const mediaType = res.headers.get("content-type") || "image/png";
+    let binary = "";
+    for (let i = 0; i < uint8Array.length; i++) {
+        binary += String.fromCharCode(uint8Array[i]);
+    }
+    const base64 = typeof btoa !== "undefined"
+        ? btoa(binary)
+        : Buffer.from(uint8Array).toString("base64");
+    return { base64, uint8Array, mediaType, url };
+}
+function fileFromB64(b64, mediaType = "image/png") {
+    const uint8Array = typeof Buffer !== "undefined"
+        ? new Uint8Array(Buffer.from(b64, "base64"))
+        : Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+    return { base64: b64, uint8Array, mediaType };
+}
+/** POST /api/llm/image/images/tasks */
+async function submitImageTask(pluginId, body, signal, headers) {
+    const config = getImageProxyConfig(pluginId, headers);
+    const res = await fetch(`${config.baseUrl}/images/tasks`, {
+        method: "POST",
+        headers: config.headers,
+        body: JSON.stringify(body),
+        signal,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`提交图像任务失败: ${res.status} ${text}`);
+    }
+    return (await res.json());
+}
+/** GET /api/llm/image/images/tasks/:taskId */
+async function getImageTask(pluginId, taskId, signal, headers) {
+    const config = getImageProxyConfig(pluginId, headers);
+    const res = await fetch(`${config.baseUrl}/images/tasks/${taskId}`, {
+        method: "GET",
+        headers: config.headers,
+        signal,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`查询图像任务失败: ${res.status} ${text}`);
+    }
+    return (await res.json());
+}
+/** POST /api/llm/image/images/generations（同步，不推荐生产使用） */
+async function generateImageSync(pluginId, body, signal, headers) {
+    const config = getImageProxyConfig(pluginId, headers);
+    const res = await fetch(`${config.baseUrl}/images/generations`, {
+        method: "POST",
+        headers: config.headers,
+        body: JSON.stringify(body),
+        signal,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`同步图像生成失败: ${res.status} ${text}`);
+    }
+    return (await res.json());
+}
+async function pollImageTask(pluginId, taskId, options) {
+    const interval = options?.pollIntervalMs ?? 30000;
+    const timeout = options?.pollTimeoutMs ?? 15 * 60 * 1000;
+    const started = Date.now();
+    while (Date.now() - started < timeout) {
+        const json = await getImageTask(pluginId, taskId, options?.abortSignal, options?.headers);
+        const data = json.data;
+        const status = data?.status?.toUpperCase();
+        if (status && TERMINAL_TASK_STATUSES.has(status)) {
+            if (status === "SUCCESS" && data?.result_url) {
+                return data.result_url;
+            }
+            throw new Error(data?.fail_reason || `图像生成任务失败: ${status}`);
+        }
+        await sleep(interval, options?.abortSignal);
+    }
+    throw new Error(`图像生成任务超时（${timeout}ms）: ${taskId}`);
+}
+function parseGenerationResponse(resp) {
+    const files = [];
+    for (const item of resp.data ?? []) {
+        if (item.b64_json) {
+            files.push(fileFromB64(item.b64_json));
+        }
+        else if (item.url) {
+            // 同步 URL 需调用方自行下载；generateKunpoImage 内会处理
+            files.push({
+                base64: "",
+                uint8Array: new Uint8Array(),
+                mediaType: "image/png",
+                url: item.url,
+            });
+        }
+    }
+    if (!files.length) {
+        throw new Error("图像生成响应中无图片数据");
+    }
+    return files;
+}
+/**
+ * 通过后端 /api/llm/image 代理生成图像（默认异步）
+ */
+async function generateKunpoImage(options) {
+    const useAsync = options.async !== false;
+    if (useAsync) {
+        const body = buildAsyncSubmitBody(options);
+        const submitted = await submitImageTask(options.pluginId, body, options.abortSignal, options.headers);
+        const taskId = submitted.task_id || submitted.id;
+        if (!taskId) {
+            throw new Error("提交图像任务成功但未返回 task_id");
+        }
+        const resultUrl = await pollImageTask(options.pluginId, taskId, {
+            pollIntervalMs: options.pollIntervalMs,
+            pollTimeoutMs: options.pollTimeoutMs,
+            abortSignal: options.abortSignal,
+            headers: options.headers,
+        });
+        const file = await bytesFromUrl(resultUrl, options.abortSignal);
+        return {
+            image: file,
+            images: [file],
+            taskId,
+            resultUrl,
+        };
+    }
+    const resp = await generateImageSync(options.pluginId, buildSyncBody(options), options.abortSignal, options.headers);
+    let files = parseGenerationResponse(resp);
+    if (files[0]?.url && !files[0].base64) {
+        const downloaded = await bytesFromUrl(files[0].url, options.abortSignal);
+        files = [downloaded];
+    }
+    return { image: files[0], images: files };
+}

package/dist/index.d.ts

@@ -45,3 +45,4 @@ export { sdkConfig, VersionCompatibilityError, SDK_SIGNATURE, type Authenticated
  */
 export declare function createChatModel(model: string, config: LangchainClientConfig & BaseChatModelParams): BaseChatModel;
 export * from "./llm";
+export { generateKunpoImage, generateImageSync, submitImageTask, getImageTask, pollImageTask, getImageProxyConfig, bytesFromUrl, type KunpoTencentImageModel, type KunpoImageQuality, type KunpoInputFidelity, type KunpoResponseFormat, type KunpoImageGenerationOptions, type KunpoImageGenerationResult, type GeneratedImageFile, } from "./image";

package/dist/index.js

@@ -20,7 +20,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SDK_SIGNATURE = exports.VersionCompatibilityError = exports.sdkConfig = exports.ChromeExtensionClient = exports.SharedResourceClient = exports.AIConfigClient = exports.DashboardClient = exports.StatsClient = exports.PluginManagementClient = exports.AdminClient = exports.getCurrentUserInfo = exports.AuthClient = exports.AgentSkillClient = exports.VersionedResourceClient = exports.ResourceClient = exports.MinioStorageClient = exports.DownloadClient = exports.OpenAIVideoGenerationClient = exports.VideoUnderstandingClient = exports.VideoGenerationClient = exports.GeminiImageGenerationClient = exports.DoubaoImageGenerationClient = exports.ChatAnthropic = exports.ChatGoogleGenerativeAI = exports.ChatOpenAI = exports.BaseChatModel = exports.AIMessageChunk = exports.SystemMessage = exports.AIMessage = exports.HumanMessage = void 0;
+exports.bytesFromUrl = exports.getImageProxyConfig = exports.pollImageTask = exports.getImageTask = exports.submitImageTask = exports.generateImageSync = exports.generateKunpoImage = exports.SDK_SIGNATURE = exports.VersionCompatibilityError = exports.sdkConfig = exports.ChromeExtensionClient = exports.SharedResourceClient = exports.AIConfigClient = exports.DashboardClient = exports.StatsClient = exports.PluginManagementClient = exports.AdminClient = exports.getCurrentUserInfo = exports.AuthClient = exports.AgentSkillClient = exports.VersionedResourceClient = exports.ResourceClient = exports.MinioStorageClient = exports.DownloadClient = exports.OpenAIVideoGenerationClient = exports.VideoUnderstandingClient = exports.VideoGenerationClient = exports.GeminiImageGenerationClient = exports.DoubaoImageGenerationClient = exports.ChatAnthropic = exports.ChatGoogleGenerativeAI = exports.ChatOpenAI = exports.BaseChatModel = exports.AIMessageChunk = exports.SystemMessage = exports.AIMessage = exports.HumanMessage = void 0;
 exports.createChatModel = createChatModel;
 const openai_1 = require("./chat_models/openai");
 const google_1 = require("./chat_models/google");
@@ -121,3 +121,11 @@ function createChatModel(model, config) {
     });
 }
 __exportStar(require("./llm"), exports);
+var image_1 = require("./image");
+Object.defineProperty(exports, "generateKunpoImage", { enumerable: true, get: function () { return image_1.generateKunpoImage; } });
+Object.defineProperty(exports, "generateImageSync", { enumerable: true, get: function () { return image_1.generateImageSync; } });
+Object.defineProperty(exports, "submitImageTask", { enumerable: true, get: function () { return image_1.submitImageTask; } });
+Object.defineProperty(exports, "getImageTask", { enumerable: true, get: function () { return image_1.getImageTask; } });
+Object.defineProperty(exports, "pollImageTask", { enumerable: true, get: function () { return image_1.pollImageTask; } });
+Object.defineProperty(exports, "getImageProxyConfig", { enumerable: true, get: function () { return image_1.getImageProxyConfig; } });
+Object.defineProperty(exports, "bytesFromUrl", { enumerable: true, get: function () { return image_1.bytesFromUrl; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-world-sdk",
-  "version": "1.5.8",
+  "version": "1.5.9",
   "description": "TypeScript SDK for AI World Platform - Chat Models, Image Generation, and Video Generation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/ai-world-sdk/docs/image-generation.md

@@ -1,13 +1,331 @@
 # 图像生成
 
-## AI SDK 图像生成（DALL-E / GPT Image）
+## KUNPO 腾讯 AIART · `generateKunpoImage`
+
+通过 `generateKunpoImage` 调用腾讯 AIART（OpenAI Images API 兼容格式），请求经平台后端 **`/api/llm/image`** 代理转发至 KUNPO 网关的 `/v1/images/*`。
+
+接口语义与 [OpenAI Image API](https://developers.openai.com/api/docs/guides/image-generation?api=image) 的 **Generations** 端点相近（`model`、`prompt`、`size`、`quality`、参考图等），但模型名与映射规则以 KUNPO/腾讯 AIART 为准。
+
+### 调用路径
+
+| SDK `async` | 代理路径 | 说明 |
+|-------------|----------|------|
+| `true`（**默认**） | `POST /images/tasks` → 轮询 `GET /images/tasks/:id` | 生产推荐；GI 约 30–60s，`Image-GPT2` 可达数分钟 |
+| `false` | `POST /images/generations` | 网关内最长等待约 15 分钟；易受 CDN/反代超时，GPT 易 504 |
+
+SDK 在异步模式下自动轮询直至 `SUCCESS` 或 `FAILURE`，并下载 `result_url` 填入 `images[0]`。
+
+### 支持的模型
+
+| `model` | 类型 | 说明 |
+|---------|------|------|
+| `Image-GI` | GI | 腾讯 AIART 文生图 |
+| `Image-GI2` | GI | 腾讯 AIART 文生图 v2（**CLI 默认**） |
+| `Image-GPT2` | GPT | 腾讯 GPT Image 2（对齐 OpenAI GPT Image 类参数） |
+
+> **务必使用 `Image-GPT2`**，不要写 `gpt-image-2` / `gpt-image-1` 等 OpenAI 官方模型 ID，否则会路由到其他渠道，参数规则不同。
+
+### 快速开始
+
+```typescript
+import { generateKunpoImage } from 'ai-world-sdk';
+
+const { images, taskId, resultUrl } = await generateKunpoImage({
+  pluginId: 'my-plugin',
+  model: 'Image-GI2',
+  prompt: '赛博朋克风格的武汉长江大桥夜景，霓虹灯光',
+  size: '1536x1024',
+  quality: 'high',
+  // async: true 为默认值
+});
+
+// images[0].base64 / images[0].uint8Array / images[0].mediaType
+// 异步时另有 taskId、resultUrl（永久 CDN 地址）
+```
+
+### 返回值 `KunpoImageGenerationResult`
+
+| 字段 | 说明 |
+|------|------|
+| `image` | 第一张图（与 `images[0]` 相同） |
+| `images` | 图片数组（异步目前为 1 张） |
+| `taskId` | 异步任务 ID（仅 `async: true`） |
+| `resultUrl` | 生成图永久 CDN URL（仅 `async: true`） |
+
+---
+
+## `generateKunpoImage` 参数完整说明
+
+### 必填参数
+
+| 参数 | 类型 | 映射 API 字段 | 说明 |
+|------|------|---------------|------|
+| `pluginId` | `string` | 请求头 `X-Plugin-Id` | 插件 ID，用于鉴权与统计 |
+| `model` | `string` | `model` | `Image-GI` / `Image-GI2` / `Image-GPT2` |
+| `prompt` | `string` | `prompt` | 图像描述，建议具体、可视觉化（参考 [OpenAI 提示词实践](https://developers.openai.com/api/docs/guides/image-generation?api=image)） |
+
+### 调用模式
+
+| 参数 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `async` | `boolean` | `true` | `true`：提交任务并轮询；`false`：同步 `generations` |
+| `pollIntervalMs` | `number` | `30000` | 异步轮询间隔（毫秒） |
+| `pollTimeoutMs` | `number` | `900000`（15 分钟） | 异步轮询超时 |
+| `abortSignal` | `AbortSignal` | — | 取消请求或轮询 |
+| `headers` | `Record<string, string>` | — | 额外 HTTP 头 |
+
+### 输出与数量
+
+| 参数 | 类型 | 默认 | 同步 API | 异步 API | 说明 |
+|------|------|------|----------|----------|------|
+| `n` | `number` | `1` | `n` | — | **仅同步**有效；异步每次任务 1 张 |
+| `responseFormat` | `'url' \| 'b64_json'` | `'b64_json'`（同步） | `response_format` | — | 同步默认 SDK 请求 `b64_json` 便于直接拿字节；异步结果始终经 `result_url` 下载 |
+
+### `size` — 尺寸（OpenAI 兼容字段名）
+
+与 [OpenAI Image API 的 size](https://developers.openai.com/api/docs/guides/image-generation?api=image#size-and-quality-options) 使用相同字符串格式（如 `1024x1024`），但 **GI 与 GPT 映射逻辑不同**：
+
+#### GI / GI2（`Image-GI`、`Image-GI2`）
+
+`size` 映射为**宽高比**，非精确像素：
+
+| `size` 取值 | 实际宽高比 |
+|-------------|------------|
+| `1024x1024` 或省略 | `1:1` |
+| `1792x1024`、`1536x1024`、`1280x720` | `16:9` |
+| `1024x1792`、`1024x1536`、`720x1280` | `9:16` |
+| **其它任意值** | **回落 `1:1`** |
+
+常用横图：`1536x1024`；竖图：`1024x1536`。
+
+#### GPT（`Image-GPT2`）
+
+| `size` 取值 | 效果 |
+|-------------|------|
+| 省略 | 默认 `1024x1024` |
+| `1024x1024`、`1536x1024`、`1024x1536`、`auto` | 保持原值 |
+| **其它** | **回落 `1024x1024`** |
+
+OpenAI 文档中 `gpt-image-2` 还支持更多分辨率（如 `2048x2048`）；经 KUNPO 网关时以腾讯上游支持为准，非法值会被回落。
+
+SDK 类型：`size?: \`${number}x${number}\` | 'auto'`。
+
+### `quality` — 质量
+
+OpenAI 侧为渲染档位（`low` / `medium` / `high` 等）；经 KUNPO 后 **GI 映射分辨率、GPT 映射质量档位**：
+
+#### GI / GI2
+
+| `quality` | 上游分辨率 |
+|-----------|------------|
+| `hd`、`high` | `4K` |
+| `low`、`standard` | `1K` |
+| 省略、`medium` 及其它 | **`2K`（默认）** |
+
+#### Image-GPT2
+
+| `quality` | 效果 |
+|-----------|------|
+| `hd`、`high` | `high` |
+| `low` | `low` |
+| 省略及其它 | **`medium`（默认）** |
+
+#### 异步 vs 同步传参（重要）
+
+| 模式 | SDK 写法 | 实际请求体 |
+|------|----------|------------|
+| **异步**（`async: true`） | `quality: 'high'` | `metadata: { quality: 'high' }`（SDK 自动转换） |
+| **同步**（`async: false`） | `quality: 'high'` | 顶层 `quality: 'high'` |
+
+> 异步接口顶层 `quality` **不生效**；务必通过 SDK 的 `quality` 字段，不要手写错误结构。
+
+类型：`KunpoImageQuality = 'low' | 'standard' | 'medium' | 'high' | 'hd'`。
+
+### 图生图（参考图）
+
+| 参数 | 类型 | API 字段 | 说明 |
+|------|------|----------|------|
+| `images` | `string[]` | `images` | 多张参考图 URL；GI 映射 `Url`，GPT 映射 `ImageUrl` |
+| `image` | `string` | `image` | 单张参考图：**HTTPS URL** 或 **Base64**（网关会自动上传 Base64 到 COS） |
+
+**限制（上游）**：
+
+- 单张参考图 ≤ **10 MiB**
+- 格式：PNG、JPEG、WebP、GIF
+- GI/GI2：`images` 或 `image` 均可
+- **Image-GPT2 图生图推荐 `image` 单图 URL**
+
+与 OpenAI [Create a new image using image references](https://developers.openai.com/api/docs/guides/image-generation?api=image#create-a-new-image-using-image-references) 类似，用参考图约束风格/主体。
+
+### 仅 `Image-GPT2` 支持的参数
+
+| SDK 参数 | API 字段 | 说明 |
+|----------|----------|------|
+| `background` | `background` | 背景描述（如 `white background`）；OpenAI 还支持 `transparent`/`auto`，腾讯上游以网关为准 |
+| `outputFormat` | `output_format` | 仅 **`png`** 有效，其它值仍返回 png |
+| `inputFidelity` | `input_fidelity` | 仅 **`high`** 或 **`low`**，其它值返回 400；控制编辑/参考图保真度（概念同 OpenAI [`input_fidelity`](https://developers.openai.com/api/docs/guides/image-generation?api=image#image-input-fidelity)） |
+
+> OpenAI `gpt-image-2` 不建议传 `input_fidelity`（固定高保真）；`Image-GPT2` 经 KUNPO 时仍可传 `high`/`low`。
+
+### 其它
+
+| 参数 | 同步 | 异步 | 说明 |
+|------|------|------|------|
+| `seed` | ✓ | — | 随机种子（若上游支持） |
+| `maxRetries` | ✓ | — | 同步路径重试次数 |
+
+**当前不支持**：`mask`（蒙版）、水印等字段。
+
+---
+
+## 按场景的参数组合
+
+### 文生图（GI，横屏海报）
+
+```typescript
+await generateKunpoImage({
+  pluginId: 'my-plugin',
+  model: 'Image-GI2',
+  prompt: '水墨山水画，远处白云缭绕的山峰',
+  size: '1536x1024',   // → 16:9
+  quality: 'high',     // → 4K
+});
+```
+
+### 文生图（GPT，竖版）
+
+```typescript
+await generateKunpoImage({
+  pluginId: 'my-plugin',
+  model: 'Image-GPT2',
+  prompt: '扁平插画，一杯咖啡，白色背景',
+  size: '1024x1536',
+  quality: 'high',
+  background: 'white background',
+  outputFormat: 'png',
+});
+```
+
+### 图生图（URL 参考）
+
+```typescript
+await generateKunpoImage({
+  pluginId: 'my-plugin',
+  model: 'Image-GI',
+  prompt: '保持构图，改为水彩风格',
+  images: ['https://example.com/ref.png'],
+});
+```
+
+### 同步调试（不推荐生产）
+
+```typescript
+const { images } = await generateKunpoImage({
+  pluginId: 'my-plugin',
+  model: 'Image-GI2',
+  prompt: '红色圆形',
+  async: false,
+  n: 1,
+  responseFormat: 'b64_json',
+});
+```
+
+---
+
+## 底层 HTTP API（高级）
+
+无需 `generateKunpoImage` 时可直接调用：
+
+```typescript
+import {
+  submitImageTask,
+  getImageTask,
+  pollImageTask,
+  generateImageSync,
+  getImageProxyConfig,
+} from 'ai-world-sdk';
+
+// 提交异步任务
+const { task_id } = await submitImageTask('my-plugin', {
+  model: 'Image-GPT2',
+  prompt: '...',
+  size: '1024x1024',
+  metadata: { quality: 'high' },
+});
+
+// 轮询
+const url = await pollImageTask('my-plugin', task_id!);
+
+// 或同步
+const resp = await generateImageSync('my-plugin', {
+  model: 'Image-GI2',
+  prompt: '...',
+  quality: 'high',
+  response_format: 'b64_json',
+});
+```
+
+代理基址：`getImageProxyConfig(pluginId).baseUrl` → `{serverUrl}/api/llm/image`。
+
+---
+
+## CLI
+
+```bash
+# KUNPO 异步（默认）
+ai-world image generate --provider kunpo \
+  --prompt "赛博朋克大桥" \
+  --model Image-GI2 \
+  --size 1536x1024 \
+  --quality high \
+  --plugin-id my-plugin \
+  --output out.png
+
+# KUNPO 同步（易超时）
+ai-world image generate --provider kunpo --sync ...
+```
+
+---
+
+## 常见错误
+
+| 现象 | 原因 | 处理 |
+|------|------|------|
+| `unsupported model` | `model` 名称错误 | 使用 `Image-GI` / `Image-GI2` / `Image-GPT2` |
+| 异步 `quality` 无效 | 手写顶层 `quality` 而非 `metadata` | 使用 SDK `quality` 字段 |
+| 同步 504 | GPT 耗时长 + CDN 超时 | 改 `async: true` |
+| GI 同步 `terminated` | 连接超时 | 改异步 |
+| `invalid input_fidelity` | 非 `high`/`low` | 仅传 `high` 或 `low` |
+| `UrlIllegal` | 参考图 Base64/体积/格式错误 | ≤10MiB，PNG/JPEG/WebP/GIF |
+| `size` 不符合预期 | GI 将未知 size 回落 1:1 | 使用文档列出的 size 值 |
+
+---
+
+## 与 OpenAI Image API 的对照
+
+| 概念 | OpenAI（[文档](https://developers.openai.com/api/docs/guides/image-generation?api=image)） | KUNPO `generateKunpoImage` |
+|------|-------------------------------------------------------------------------------------------|---------------------------|
+| 端点 | `/v1/images/generations` | 经 `/api/llm/image/images/generations` |
+| 模型 | `gpt-image-2` 等 | `Image-GPT2`（勿混用 ID） |
+| `prompt` | 必填 | 必填 |
+| `size` | 像素或 `auto` | 同字段名；GI/GPT 映射见上 |
+| `quality` | `low`/`medium`/`high`/`auto` | 同枚举；GI 另映射分辨率 |
+| `n` | 单次多张 | 仅同步有效 |
+| 参考图 | `image` / 多图 | `image` / `images` |
+| 长耗时 | 官方建议 Image API 单次生成 | **务必** `async: true` |
+
+平台内 **DALL·E / api2img** 等仍走 `createProvider` + Vercel AI SDK `generateImage`，见下文。
+
+---
+
+## AI SDK 图像生成（DALL-E / GPT Image · api2img）
 
 ```typescript
 import { createProvider } from 'ai-world-sdk';
 import { generateImage } from 'ai';
 
 const provider = createProvider('api2img', 'openai', 'my-plugin');
-const imageModel = (provider as any).image('dall-e-3'); // as any: ProviderV3 类型不含 .image()
+const imageModel = (provider as any).image('dall-e-3');
 
 const { images } = await generateImage({
   model: imageModel,
@@ -15,7 +333,6 @@ const { images } = await generateImage({
   size: '1024x1024',
   n: 1,
 });
-// images[0].base64, images[0].mediaType
 ```
 
 ## 豆包（Doubao）图像生成
@@ -30,9 +347,9 @@ const client = new DoubaoImageGenerationClient({});
 const result = await client.generate({
   prompt: '一只可爱的小猫',
   model: 'doubao-seedream-4-5-251128',
-  size: '2K',       // '1K' | '2K' | '4K' | '2048x2048' | '2560x1440' 等
-  quality: 'hd',    // 'standard' | 'hd'
-  n: 1,             // 1-10
+  size: '2K',
+  quality: 'hd',
+  n: 1,
 });
 console.log(result.data[0]?.url);
 ```
@@ -63,12 +380,10 @@ await client.generate({
 ```typescript
 import { GeminiImageGenerationClient } from 'ai-world-sdk';
 
-// provider 在构造函数中指定
 const client = new GeminiImageGenerationClient({ provider: 'gemini' });
 const result = await client.generate({
   prompt: '一只可爱的小猫',
 });
-// result.images — 生成的图像列表
 ```
 
 ### Gemini 图像对话（chat）
@@ -87,6 +402,6 @@ const chatResult = await client.chat({
 |------|------|------|
 | `provider` | 构造函数 | 图像生成 Provider（如 `'gemini'`） |
 | `prompt` | `generate()` | 文本提示词 |
-| `model` | `generate()` | 模型名称（默认: `gemini-2.0-flash-exp-image-generation`，chat 默认: `gemini-3-pro-image-preview`） |
+| `model` | `generate()` | 模型名称 |
 | `image` | `generate()` / `chat()` | 输入图像（base64 或 URL） |
 | `aspect_ratio` | `generate()` | 宽高比 |