# @amaster\.ai/pi-image-gen 中文文档 规范地址：https://npmcn.com/package/%40amaster.ai/pi-image-gen/ 版本：0\.1\.37 npm 元数据更新时间：2026-11-09T02:51:26.448Z 中文译文更新时间：2026-11-09T04:48:04.203Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40amaster.ai/pi-image-gen 原文对照：https://npmcn.com/package/%40amaster.ai/pi-image-gen/?lang=original 项目主页：https://github.com/TGYD-helige/pi#readme 源码仓库：https://github.com/TGYD-helige/pi ## 关键信息（来自 npm 元数据） - 包体积（解压后）：2.2 MB，70 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：1 个 - peer 依赖：typebox \*，@earendil-works/pi-ai \>=0\.80\.10，@earendil-works/pi-coding-agent \>=0\.79\.1 - 首次发布：2026-06-05T07:16:37.296Z - 最新版本发布：2026-11-09T02:51:26.135Z - 近 30 天下载量：12791（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：114（近 12 个月 114 个） ## 中文简介 通过OpenAI gpt-image,Google Nano Banana (Gemini),Alibaba Quen-Image,OpenRouter,以及自定义供应商,图像生成的 Pi扩展. ## 安装 ```sh npm install @amaster.ai/pi-image-gen ``` 也可以使用：`pnpm add @amaster.ai/pi-image-gen`、`yarn add @amaster.ai/pi-image-gen`、`bun add @amaster.ai/pi-image-gen` ## README # @amaster.ai/pi-image-gen ![pi-image-gen preview](https://raw.githubusercontent.com/TGYD-helige/pi/master/packages/pi-image-gen/preview.png) 添加一个扩展的 Pi `image_generate` 工具。 支助提供者: | 提供者 | 型号 id (别名) | 新闻 var | | --- | --- | --- | | 开放AI | `gpt-image-2.5-flare` (别名) `gpt-image-2.5`, (中文(简体) ), `gpt-image-2.5-sunburst`, (中文(简体) ), `gpt-image-2` | `OPENAI_API_KEY` | | 谷歌双子座 ("纳诺香蕉") | `gemini-3-pro-image` (别名) `nano-banana-pro`, (中文(简体) ), `gemini-3.1-flash-image` (别名) `nano-banana-2`, (中文(简体) ), `gemini-3.1-flash-lite-image` (别名) `nano-banana-2-lite`, (中文(简体) ), `gemini-2.5-flash-image` (别名) `nano-banana`, (中文(简体) ), **已贬值——关闭2026-10-02;使用 `gemini-3.1-flash-lite-image` 换成**(中文(简体) ) | `GEMINI_API_KEY` | | 阿里巴巴·达什斯科普(英语:Alibaba DashScope (Quen-Image)) | `qwen-image-3.0-pro`, (中文(简体) ), `qwen-image-3.0`, (中文(简体) ), `qwen-image-2.0-pro`, (中文(简体) ), `qwen-image-2.0` | `DASHSCOPE_API_KEY` | | 花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花 | `doubao-seedream-5-0-pro-260628` (别名) `seedream-5-pro`编号 `doubao-seedream-5-0-pro-260128` 仍然决心, `doubao-seedream-5-0-260128` (别名) `seedream-5`, (中文(简体) ), `seedream`;同一模式也回答 `doubao-seedream-5-0-lite-260128` 编号 : `seedream-5-lite`, (中文(简体) ), `doubao-seedream-4-5-251128` (别名) `seedream-4-5`, (中文(简体) ), `doubao-seedream-4-0-250828` (别名) `seedream-4`(中文(简体) ) | `ARK_API_KEY` | | 打开路透社 | 任何(使用 `openrouter//`(中文(简体) ) | `OPENROUTER_API_KEY` | | 自定义提供者 | 任何您在设置中声明的内容 | (你的选择,通过 `$VAR`(中文(简体) ) | 上游 API 道克( 调试网关行为或添加新模式时手动): - OpenAI GPT 图像 (2.5和2) - [开发者.openai.com/api/docs/指南/图像生成](https://developers.openai.com/api/docs/guides/image-generation) - 谷歌双子座图像生成- [ai.google.dev/gemini-api/docs/图像生成](https://ai.google.dev/gemini-api/docs/image-generation) - Alibaba Quen-Image 3.0(生成和编辑) - [help.aliyun.com/zh/model-studio/qwen-image-世代-编辑-api-参考](https://help.aliyun.com/zh/model-studio/qwen-image-generation-and-editing-api-reference) - 阿里巴巴 DashScope Quen-Image 2.0 (文本对图像)- [help.aliyun.com/zh/model-studio/qwen-image-api 页面存档备份,存于互联网档案馆](https://help.aliyun.com/zh/model-studio/qwen-image-api) - 阿里巴巴 DashScope Quen-Image-Edit - 互联网电影数据库(IMDb)上"阿里巴巴"的资料(英文) [help.aliyun.com/zh/model-studio/qwen-image-edit-api (中文(简体) )](https://help.aliyun.com/zh/model-studio/qwen-image-edit-api) - 伏尔肯金·方克种子梦—— [volcengine.com/docs/82379/1824121 (中文(简体) )](https://www.volcengine.com/docs/82379/1824121) - OpenRouter 图像 API - [开源软件国际化之简体中文组](https://openrouter.ai/docs/api/api-reference/images/create-images) 内脏名字匹配 [pi.dev 的提供者表](https://pi.dev/docs/latest/providers) ——如果该剂已经拥有供货商的密钥集,此扩展将重新使用. 你不需要引入一个新的变量. 活动模式是 **在设置中固定。 json**编辑 `image_generate` 工具故意这样做 **没有** 带一个 `model` 参数 ——将您的工程指向一个模型,获得一致的输出. 要切换模型, 编辑设置并运行 `/image-gen reload`。 。 。 . ## 安装 ```sh pnpm add @amaster.ai/pi-image-gen ``` 包裹 `pi.extensions` 字段自动注册它与主机 pi-coding- agent 运行时间;不需要额外的接线. ## 结构化工具成果 在有结构化工具支持的 Pi 运行时, 代码模式接收 `{ model, provider, images, totalImages, truncated }`。每个图像都有其保存的绝对 `path`, (中文(简体) ), `mimeType`,可选 `revisedPrompt`。普通工具结果中仍然包含用于显示的内嵌的Markdown图像链接。 大元数据为: `truncated` 识别缩短的提示或省略的图像记录,以及 `totalImages` 保存全部生成的计数。 调用失败返回 `{ error }` 与 `isError: true`; 检查 `error` 在使用图像路径之前。 年长的Pi 运行时间保留他们的文本结果行为. ## 配置 设置由 `pi-shared`是因为 `loadPiSettings`,它合并了三个文件(低至高优先级): 1. `~/.pi/agent/settings.json` (全球) 2. `$PI_AGENT_HOME/settings.json` (代理目录,如果 `PI_AGENT_HOME` 设置) 3. `/.pi/settings.json` (受托项目) 当项目信任降低时,项目设置会被忽略. `${ENV_VAR}` 内插仅在全球和代理设置中支持,因此将环境支持的资质保留在项目设置之外. 所有设置都生活在 `pi-image-gen` 键。 最小可行的配置集 `defaultModel`数字 : ```json { "pi-image-gen": { "defaultModel": "nano-banana" } } ``` ...并导出相匹配的 env var : ```sh export GEMINI_API_KEY=sk-... ``` 就是这样。 从代理人: `image_generate({ prompt: "a cyberpunk cat" })`。 。 。 . ### 所有设置字段 ```json { "pi-image-gen": { "defaultModel": "nano-banana", "outputDir": ".pi/images", "providers": { "openai": { "baseUrl": "https://my-proxy.example.com/v1", "apiKey": "${MY_OPENAI_KEY}" }, "gemini": { "headers": { "x-goog-trace": "pi-prod" } }, "dashscope": { "baseUrl": "https://dashscope-intl.aliyuncs.com/api/v1" }, "ark": { "apiKey": "$ARK_API_KEY" }, "openrouter": { "apiKey": "$OPENROUTER_API_KEY" } }, "customProviders": { "my-stable-diffusion": { "api": "openai", "baseUrl": "https://api.my-sd.example.com/v1", "apiKey": "${MY_SD_KEY}", "headers": { "x-tenant": "team-a" }, "models": [ { "id": "sd-3-large", "alias": "sd3" }, "sd-3-medium" ] } } } } ``` | 外地 | 目的 | | --- | --- | | `defaultModel` | 该工具将使用的型号为id或别名. **要求.** | | `outputDir` | 在哪里写入生成的图像 。 相对路径解析到会话 cwd 。 默认 `.pi/images`。 。 。 . | | `providers` | 内置服务员控制器 设定 `apiKey`, (中文(简体) ), `baseUrl`,或 `headers` 指代或非标准环境 var. | | `customProviders` | 用户定义的提供者——见下文. | 在全球和代理人环境中, `apiKey`, (中文(简体) ), `baseUrl`,以及 `headers` 数值支持 `$VAR` 财务报告和审定财务报表 `${VAR}` 环境插值。 后退需要加固的形态(例如, `${FOO:-default}`(三); `$FOO:-default` 不被支持。 工程设置保留所有这些占位符文字 . ## 深搜索策略 | 东道主 | `pi-image-gen` 状态 | | --- | --- | | [pi2dsh (英语)](https://github.com/weijiafu14/pi2dsh) | `@amaster.ai/pi-image-gen@0.1.8` 以可控的 OpenAI 兼容端点([范围和证据](https://github.com/TGYD-helige/pi/issues/159)) (中文(简体) ). | | [dsh- pi- 主机](https://github.com/TGYD-helige/dsh-pi) | 装入 `@amaster.ai/pi-image-gen` 当选择在其 `extensions` 列表中选择一个选项. | 遵循所选主机的文档进行安装和当前相容性细节. ## 内建设置走过 ### 1\. OpenAI (英语:`gpt-image-2.5-flare`(中文(简体) ) ```sh export OPENAI_API_KEY=sk-... ``` ```json { "pi-image-gen": { "defaultModel": "gpt-image-2.5" } } ``` ### 2\. 谷歌双子座"纳诺香蕉" ```sh export GEMINI_API_KEY=... ``` ```json { "pi-image-gen": { "defaultModel": "nano-banana" } } ``` ### 3\. 阿里巴巴·达什斯科普(Quen-Image) ```sh export DASHSCOPE_API_KEY=... ``` ```json { "pi-image-gen": { "defaultModel": "qwen-image-2.0" } } ``` 对于国际 DashScope 端点, 覆盖基准 URL : ```json { "pi-image-gen": { "defaultModel": "qwen-image-2.0", "providers": { "dashscope": { "baseUrl": "https://dashscope-intl.aliyuncs.com/api/v1" } } } } ``` ### 4\. 伏尔肯金克(ByteDance种子) ```sh export ARK_API_KEY=... ``` ```json { "pi-image-gen": { "defaultModel": "seedream" } } ``` > 支助 `size` 值是依赖模型的,工具 schema 告诉代理器活动模型的确切形式: 级符 (`1K`编号 :`1.5K`编号 :`2K`编号 :`3K`编号 :`4K` ——每个模型的列表不同)或明确 `"x"` 像素字符串,从不混合. 种子梦 5.0 / 4.5 执行2K像素地板(`1024x1024` 失败 `InvalidParameter`); 5.0 亲接受 `1K`编号 :`1.5K`编号 :`2K` 下至921,600px; 4.0 接受1K. 表格中的全部大小 [正式文件](https://www.volcengine.com/docs/82379/1824121)种子梦 **没有 `n` 参数** —— API 每个请求生成一个图像( 多图像是 `sequential_image_generation` 因此 `n` 用于隐藏这些模型。 扩展名总是发送 `watermark: false` 种子梦的水印开关默认为 `true` 否则会在每个图像的角落 盖上"AI"的徽章. 默认基准 URL 是 `https://ark.cn-beijing.volces.com/api/v3`。使用不同的区域(例如:. `ap-southeast`),推翻: ```json { "pi-image-gen": { "defaultModel": "seedream", "providers": { "ark": { "baseUrl": "https://ark.ap-southeast.bytepluses.com/api/v3" } } } } ``` ### 5\. OpenRouter (一键,多型号) ```sh export OPENROUTER_API_KEY=... ``` ```json { "pi-image-gen": { "defaultModel": "openrouter/bytedance-seed/seedream-4.5" } } ``` 后面的字符串 `openrouter/` 是 OpenRouter 模型 sult; 通过任何图像模型 OpenRouter 支持(`google/gemini-3.1-flash-image`, (中文(简体) ), `openai/gpt-image-2`, (中文(简体) ), `bytedance-seed/seedream-4.5`(中文(简体) ). OpenRouter 图像 API 是 **没有** 与OpenAI兼容 `POST /api/v1/images` (无) `/generations` 后缀)并使用 JSON `input_references` 用于图像对图像。 扩展对象为右端点自动;不需要有线形状配置. ## 自定义提供者 使用 `customProviders` 对于任何没有在其中构建的东西:自发托管的稳定分化,内部公司网关,第三方图像API. 形状镜 [pi.dev 的自定义提供者文件](https://pi.dev/docs/latest/custom-provider)。 。 。 . 每个自定义提供者声明: | 外地 | 需求 | 页:1 | | --- | --- | --- | | `api` | 对 | 一个 `openai`, (中文(简体) ), `gemini`, (中文(简体) ), `dashscope`, (中文(简体) ), `openrouter`, (中文(简体) ), `ark`。选择图像-API线形. | | `baseUrl` | 对 | API 端点 URL . `$VAR` 语法支持. | | `apiKey` | 通常 | API 密钥字符串. `$VAR` 语法支持. | | `name` | 没有 | 显示在 `/image-gen list`。 。 。 . | | `headers` | 没有 | 额外的信头合并到每个请求中. | | `models` | 没有 | 可选型号id/化名列表. {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}让这成为 **包罗万象** ——提供商将接受任何未知的型号代号(作为远程代号通过). 仅当您想要化名或想要将特定标识路由到其它地方时提供列表 。 每个条目都是字符串或 `{ id, alias?, name?, capabilities? }`。 。 。 . | 一个自定义模型,它的 `id` 命名内置模型 **继承该模型的能力合同** (大小表单, `n` 天花板,参考图像规则),所以当您通过自己的网关向一个已知的模型行走时,工具计划保持准确. 声明 `capabilities` (b) 任何未申报的,应追溯到内置的,然后是保守的通用合同。 所有路线和身份不明者都得不到合同——与以前一样,计划是完全通用的. ```json { "pi-image-gen": { "defaultModel": "qwen-image-3.0", "customProviders": { "corp-gateway": { "api": "dashscope", "baseUrl": "https://gateway.corp.example/api/v1", "apiKey": "$GW_KEY", "models": [ "qwen-image-3.0", { "id": "my-finetune", "capabilities": { "nMax": 4, "maxReferenceImages": 2 } } ] } } } } ``` > 注:pi.dev自定义提供者也有 `api` 字段,但其价值(`openai-completions`, (中文(简体) ), `anthropic-messages`,.)是LLM流式格式,不适用于图像生成. 这里的值( E)`openai`, (中文(简体) ), `gemini`, (中文(简体) ), `dashscope`, (中文(简体) ), `openrouter`, (中文(简体) ), `ark`)是图像-API线形——同域名,同名空间. ### 实例:自办的稳定扩散(OpenAI兼容) ```sh export SD_KEY=local-secret ``` ```json { "pi-image-gen": { "defaultModel": "sd3", "customProviders": { "my-sd": { "api": "openai", "baseUrl": "http://localhost:8000/v1", "apiKey": "$SD_KEY", "models": [{ "id": "sd-3-large", "alias": "sd3" }] } } } } ``` 经纪人打电话来 `image_generate({prompt: ...})`; 扩展显示 `defaultModel: "sd3"`,发现它下 `my-sd`,然后 POST 改为 `http://localhost:8000/v1/images/generations` 与 `Bearer $SD_KEY`。 。 。 . ### 示例: Volcengine Doubao 图像 API( OpenAI 兼容) ```json { "pi-image-gen": { "defaultModel": "doubao-seed-image", "customProviders": { "doubao": { "api": "openai", "baseUrl": "https://ark.cn-beijing.volces.com/api/v3", "apiKey": "${ARK_API_KEY}", "models": [{ "id": "doubao-seedream-4-0-250828", "alias": "doubao-seed-image" }] } } } } ``` ### 示例:双子形代理 如果您的提供者会说 Google Generative Language 有线电视格式: ```json { "pi-image-gen": { "defaultModel": "internal-banana", "customProviders": { "internal": { "api": "gemini", "baseUrl": "https://gemini-proxy.corp.example/v1beta", "apiKey": "$INTERNAL_GEMINI_KEY", "models": [{ "id": "gemini-2.5-flash-image", "alias": "internal-banana" }] } } } } ``` ### 无别名的直接地址 如果自定义提供者没有 `models` 列表中,您还可以用 `/`数字 : ```json { "pi-image-gen": { "defaultModel": "my-sd/sd-3-large", "customProviders": { "my-sd": { "api": "openai", "baseUrl": "http://localhost:8000/v1", "apiKey": "$SD_KEY" } } } } ``` ## 工具 : `image_generate` ```ts image_generate({ prompt: string, // required — what to draw or how to edit image?: string[], // optional — array of file paths or http(s) URLs n?: number, // per-model ceiling (qwen 1–6, gpt-image 1–10); hidden for Seedream size?: string, // per-model form (see below); hidden for Gemini models aspectRatio?: string, // Gemini models only — enum from the model's vocabulary imageSize?: string, // Gemini models only — tier enum ("1K"/"2K"/"4K"), when the model has tiers quality?: 'low'|'medium'|'high'|'auto', // present only for a built-in gpt-image route (see below) filename?: string, // filename prefix (no extension) outputDir?: string, // override settings.outputDir for this call }) ``` 返回已保存图像的绝对文件路径。 文件在 `outputDir` (默认) `/.pi/images`),文件名模式 `.`。 。 。 . **计划是模式意识的.** 每个内置模型都带有来自官方API docs的能力合同,该工具以该合同设定的参数注册(在会话开始后) `/image-gen reload`)——因此代理完全看清了活性模型的荣誉,在enums和描述中都有所记载的值. 合同是 **建议,不是门**: 数值限制(大小范围, `n` 上限、参考图像计数和字节上限)在说明中加以说明,但从未硬性强制客户端——自备部署或网关可能合法地偏离云平台的文件限制,供应商本身的错误是后站。 唯一的客户端拒绝是适配器静静地放下的参数组合(像素) `size` 送到双子座模型,或者 `aspectRatio` 被发送到像素大小的模型中——提供商从未看到这些,因此无法抱怨. - `size` 遵循该模型的文件格式: - **问** (单位:千美元)`qwen-image-*`: `"*"` (asterisk,例如:. `"2048*2048"`),总像素5122–20482; 3.0型号以1:8–8:1. x-形式作为安全网自动正常化. - **种子梦** (单位:千美元)`doubao-seedream-*`: 模型列表中的分级符號 (:`1K`编号 :`1.5K`编号 :`2K`编号 :`3K`编号 :`4K`(中文(简体) ) **或者说** 明确 `"x"` 在模型的像素窗口内(2K层在5.0/4.5上). - **图片** (单位:千美元)`gpt-image-2.5-*`, (中文(简体) ), `gpt-image-2`: `"auto"` 或者说 `"x"` ——允许任意大小(双边可分出16个,比例为: 3:1, 655,360–8,294,400 px,最长的边缘为:-3840个),超过标准 `1024x1024`编号 :`1536x1024`编号 :`1024x1536`。 。 。 . - 奥米 `size` 以使用模型本身的默认值(qwen-image-3.0 从提示中自动取出). - `aspectRatio` 编号 : `imageSize` 替换 `size` 页:1 **双子座** 模型( 它们没有像素大小的 knob ): `aspectRatio` 是一个来自模型词汇(10至14个值)的符号, `imageSize` 模型的分级(`1K`编号 :`2K`编号 :`4K`; 当模型固定在一等时隐藏, 如 `gemini-3.1-flash-lite-image` 财务报告和审定财务报表 `gemini-2.5-flash-image` (见a/cn.9/wg.iii/wp.96和corr.1). - `n` 搭载该型号在描述中记录的上限(第6回,gpt-image 10),并且 **隐藏为种子梦** ——API没有计数参数,所以 `n` 将默默地放弃. - `image` 在其描述(格式、最大计数、每个图像字节上限、尺寸建议)中详细说明了活动模型的有据可查的参考图像合同:qwen文件 3图像(JPG/JPEG/PNG/BMP/TIFF/WEBP/GIF,X-10MB),Seedream 10-14(包括HEIC/HEIF,X-30MB),gpt-image 16(png/webp/jpg,X-50MB),Gemini 3-14(X-100MB)。 这些是对云平台限制的描述,而不是客户端-侧门——提供者执行自己的规则. - `quality` 显示 **仅限** (单位:千美元) **内置 gpt- 图像** 路由 — 内置的 OpenAI 供应商 `gpt-image-*`,或OpenRouter路由,其型号为gpt-image(例如. `openrouter/openai/gpt-image-2`) (中文(简体) ). 只有它被束缚在阴道上 `low`编号 :`medium`编号 :`high`编号 :`auto` (这些APIs文档的词汇表). 没错 **完全省略了计划** 用于: - 双子座、 DashScope/ Quen 和 Ark/Seedream —— 他们的形象 API 没有 `quality` 字段(种子质量因 `size` 决议分级; - **非图像路径** openAI/OpenRouter接线——例如内置 `openai/dall-e-3` (使用 `standard`编号 :`hd`)或OpenRouter通向Seedream等非OpenAI模型的路线——因为上面的enum是gpt-image的词汇,而不是有线格式的;以及 - **任何自定义提供者**,包括OpenAI -_兼容_ 例如,DALL-E 3's `standard`编号 :`hd`)或根本没有,所以OpenAI 线条格式本身就是 **没有** 表示上述四个数值。 传递一个不支持的值只能作为400位提供者的一面而出. 若为 `defaultModel` 是未设或错位的, `quality` (该工具保持充分功能 `execute` 显示一个友好配置错误。 使用 `"low"` 快速的草稿和更高一级的最终资产或密集文本. 由于计划固定在注册时,通过 `/image-gen reload` 重新登记该工具,因此参数设置了跟踪新提供者. **非破坏性写道:** 保存的文件不会覆盖已有的文件。 两通电话 `filename: "hero"` 生产 `hero.png` 接下来 `hero-v2.png`,所以更早的结果被保留而不是被打乱. 路径保留为原子( Q)`O_EXCL`:甚至许多同时打的电话,都有同样的 `filename` 每一个都声称有一条不同的路——没有两条路相通. ### 工具结果格式 工具的文本结果被塑造为可以即时地将标记降级的模型可以将逐字记录复制到其回复中,因此UI使图像被内入: ``` Generated 1 image(s) via amaster (custom) (qwen-image-2.0). Show each one to the user as inline markdown — copy the lines below verbatim into your reply: ![white](/Users/.../white.png) ``` 这个 `alt` 文本是没有扩展名的文件名——即您通过的文件 `filename`,或 `-` 如果你没有。 当 OpenAI 返回时 a `revised_prompt`,它作为引线出现在图像下: ``` ![beaver](/Users/.../beaver.png) > revised prompt: a cute beaver, photorealistic, water droplets ``` 标记下 URL 是平台形状的,所以任何普通马克主机(桌面,TUI,CLI)都保持其完整:在macOS/Linux上有一个赤裸的绝对路径——字节-同义,除非它包含标记下-不安全字符(白空间, `#`, (中文(简体) ), `?`, (中文(简体) ), `%`, (中文(简体) ), `()`, (中文(简体) ), `<>`),这是 %-逃避;在Windows上是 %-编码的 `file:///…` URL (中文(简体) )`![result](file:///C:/Users/.../result.png)`) ——反应-标记剂等消毒剂 `defaultUrlTransform` 读取 `C:` 作为未知的 URI 方案并剥去插件 `src`不论降级, `details.images[].path` 总是带有原始文件系统路径. ### 图像到图像/ 编辑 `image` 总是数组——通过 `["path"]` 对于一个单一的图像, `["a", "b"]` 用于多图像调节. 每个条目必须是: - **本地文件路径** 常规 png/jpeg/gif/webp/bmp/tiff/heic/heif文件在会话 cwd 内(活动模型的接受格式可能比较窄) – `image` 参数描述列出它们). 路径可能是绝对的或相对的,但cwd外的对称和路径被拒绝. - **公开 https URL** ——拒绝私自,回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回. 基础64字符串和 `data:` URI被故意拒绝——工具论证不能干净地活过特大字节大小的字符串. 如果您有原始图像字节, 请将它们写入会话 cwd 下的文件, 然后通过该路径 . **根据先前的结果:** 将上一条输出路径递回。 下一个图像以最后一个为条件: ``` image_generate({ prompt: "a beaver chewing wood", filename: "beaver" }) → /Users/.../.pi/images/beaver.png image_generate({ prompt: "now in watercolor style", image: ["/Users/.../.pi/images/beaver.png"] }) → /Users/.../.pi/images/gpt-image-2-20260605-...png (edited) ``` 提供者行为 : | 提供者 | 图像输入路由 | | --- | --- | | OpenAI (英语:`gpt-image-2.5-*`, (中文(简体) ), `gpt-image-2`(中文(简体) ) | `POST /v1/images/edits` (多发. 支持多相观. | | 双子座( E)`gemini-3-pro-image`, (中文(简体) ), `gemini-3.1-flash-image`, (中文(简体) ), `gemini-3.1-flash-lite-image`, (中文(简体) ), `gemini-2.5-flash-image`(中文(简体) ) | `inline_data` 预留到用户信件的部件。 支持多相观. | | DashScope (英语:`qwen-image-3.0-pro`, (中文(简体) ), `qwen-image-3.0`, (中文(简体) ), `qwen-image-2.0-pro`, (中文(简体) ), `qwen-image-2.0`(中文(简体) ) | `image` 组件 `messages[].content`。最多3个图像. | | 打开路透社 | `POST /api/v1/images` 与 `input_references` 贾森。 支持多相观. | 故意没有 `model` 工具上的参数——活动模式由 `pi-image-gen.defaultModel` 在设置中. ## 斜线命令 - `/image-gen list` ——显示活动模式,它向哪个提供方提供路径,是否设置了密钥,配置了提供者,以及内置模式代号的目录. - `/image-gen reload` ——从磁盘上重新读取设置,并重新注册工具,这样其方案(例如: `quality` )跟踪新选择的模型. - `/image-gen generate ` ——利用活性模型直接从命令行生成图像. 将保存的文件路径报告为纯文本通知( 命令使用) `ctx.ui.notify`,它显示的是状态行,而不是使 Markdown — 因此与工具结果不同,它不会发出内线 `![](…)` 图片). 使用 `image_generate` 工具. 使用 `/image-gen list` 它会告诉你什么时候 `defaultModel` 未设置,指向一个没有 API 密钥的提供者,或指名未知的 ID. ## 捆绑的技巧 这个包裹载着一个 `image-gen` 技术(`skills/image-gen/SKILL.md`皮装入需求。 鼓励代理人在使用前阅读 `image_generate`,但工具没有它仍然可以使用。 该技能搭载了一行工具指南所无法持有的提示游戏本: 当使用光栅生成 vs repo-inative SVG/CSS,生成-vs-edit意图, `n`\-is-variants-n-assets,多图像角色标签,编辑不变量,文本-in-image处理,以及被标注的即时图. ## 常见问题 ### @amaster\.ai/pi-image-gen 是什么？ 通过OpenAI gpt-image,Google Nano Banana \(Gemini\),Alibaba Quen-Image,OpenRouter,以及自定义供应商,图像生成的 Pi扩展\. ### 如何安装 @amaster\.ai/pi-image-gen？ 在项目目录运行 npm install @amaster\.ai/pi-image-gen，或使用 pnpm add / yarn add / bun add。 ### @amaster\.ai/pi-image-gen 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @amaster\.ai/pi-image-gen 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @amaster\.ai/pi-image-gen 可以商用吗？ @amaster\.ai/pi-image-gen 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @amaster\.ai/pi-image-gen 的下载量有多少？ 根据 npm 官方下载统计，@amaster\.ai/pi-image-gen 在 2026/10/06 – 2026/11/04 这 30 天内被下载 12,791 次，日均约 426 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @amaster\.ai/pi-image-gen 还在维护吗？ 最新版本 0\.1\.37 发布于 2026/11/09（今天）；至今共发布 114 个版本，其中过去 12 个月发布了 114 个；首次发布于 2026/06/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。