@amaster.ai/pi-image-gen

添加一个扩展的 Pi image_generate 工具。 支助提供者:

上游 API 道克( 调试网关行为或添加新模式时手动):

• OpenAI GPT 图像 (2.5和2) - 开发者.openai.com/api/docs/指南/图像生成
• 谷歌双子座图像生成- ai.google.dev/gemini-api/docs/图像生成
• Alibaba Quen-Image 3.0(生成和编辑) - help.aliyun.com/zh/model-studio/qwen-image-世代-编辑-api-参考
• 阿里巴巴 DashScope Quen-Image 2.0 (文本对图像)- help.aliyun.com/zh/model-studio/qwen-image-api 页面存档备份,存于互联网档案馆
• 阿里巴巴 DashScope Quen-Image-Edit - 互联网电影数据库(IMDb)上"阿里巴巴"的资料(英文) help.aliyun.com/zh/model-studio/qwen-image-edit-api (中文(简体) )
• 伏尔肯金·方克种子梦—— volcengine.com/docs/82379/1824121 (中文(简体) )
• OpenRouter 图像 API - 开源软件国际化之简体中文组

内脏名字匹配 pi.dev 的提供者表 ——如果该剂已经拥有供货商的密钥集,此扩展将重新使用. 你不需要引入一个新的变量.

活动模式是 在设置中固定。 json编辑 image_generate 工具故意这样做 没有 带一个 model 参数 ——将您的工程指向一个模型,获得一致的输出. 要切换模型, 编辑设置并运行 /image-gen reload。 。 。 .

安装

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. <cwd>/.pi/settings.json (受托项目)

当项目信任降低时,项目设置会被忽略. ${ENV_VAR} 内插仅在全球和代理设置中支持,因此将环境支持的资质保留在项目设置之外.

所有设置都生活在 pi-image-gen 键。 最小可行的配置集 defaultModel数字 :

{
  "pi-image-gen": {
    "defaultModel": "nano-banana"
  }
}

...并导出相匹配的 env var :

export GEMINI_API_KEY=sk-...

就是这样。 从代理人: image_generate({ prompt: "a cyberpunk cat" })。 。 。 .

所有设置字段

{
  "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"
        ]
      }
    }
  }
}

在全球和代理人环境中, apiKey, (中文(简体) ), baseUrl,以及 headers 数值支持 $VAR 财务报告和审定财务报表 ${VAR} 环境插值。 后退需要加固的形态(例如, ${FOO:-default}(三); $FOO:-default 不被支持。 工程设置保留所有这些占位符文字 .

深搜索策略

遵循所选主机的文档进行安装和当前相容性细节.

内建设置走过

1. OpenAI (英语:gpt-image-2.5-flare(中文(简体) )

export OPENAI_API_KEY=sk-...

{ "pi-image-gen": { "defaultModel": "gpt-image-2.5" } }

2. 谷歌双子座"纳诺香蕉"

export GEMINI_API_KEY=...

{ "pi-image-gen": { "defaultModel": "nano-banana" } }

3. 阿里巴巴·达什斯科普(Quen-Image)

export DASHSCOPE_API_KEY=...

{ "pi-image-gen": { "defaultModel": "qwen-image-2.0" } }

对于国际 DashScope 端点, 覆盖基准 URL :

{
  "pi-image-gen": {
    "defaultModel": "qwen-image-2.0",
    "providers": {
      "dashscope": { "baseUrl": "https://dashscope-intl.aliyuncs.com/api/v1" }
    }
  }
}

4. 伏尔肯金克(ByteDance种子)

export ARK_API_KEY=...

{ "pi-image-gen": { "defaultModel": "seedream" } }

支助 size 值是依赖模型的,工具 schema 告诉代理器活动模型的确切形式: 级符 (1K编号 :1.5K编号 :2K编号 :3K编号 :4K ——每个模型的列表不同)或明确 "<w>x<h>" 像素字符串,从不混合. 种子梦 5.0 / 4.5 执行2K像素地板(1024x1024 失败 InvalidParameter); 5.0 亲接受 1K编号 :1.5K编号 :2K 下至921,600px; 4.0 接受1K. 表格中的全部大小 正式文件种子梦 没有 n 参数 —— API 每个请求生成一个图像( 多图像是 sequential_image_generation 因此 n 用于隐藏这些模型。 扩展名总是发送 watermark: false 种子梦的水印开关默认为 true 否则会在每个图像的角落 盖上"AI"的徽章.

默认基准 URL 是 https://ark.cn-beijing.volces.com/api/v3。使用不同的区域(例如:. ap-southeast),推翻:

{
  "pi-image-gen": {
    "defaultModel": "seedream",
    "providers": {
      "ark": { "baseUrl": "https://ark.ap-southeast.bytepluses.com/api/v3" }
    }
  }
}

5. OpenRouter (一键,多型号)

export OPENROUTER_API_KEY=...

{ "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 的自定义提供者文件。 。 。 .

每个自定义提供者声明:

一个自定义模型,它的 id 命名内置模型 继承该模型的能力合同 (大小表单, n 天花板,参考图像规则),所以当您通过自己的网关向一个已知的模型行走时,工具计划保持准确. 声明 capabilities (b) 任何未申报的,应追溯到内置的,然后是保守的通用合同。 所有路线和身份不明者都得不到合同——与以前一样,计划是完全通用的.

{
  "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兼容)

export SD_KEY=local-secret

{
  "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 兼容)

{
  "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 有线电视格式:

{
  "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 列表中,您还可以用 <providerName>/<remoteId>数字 :

{
  "pi-image-gen": {
    "defaultModel": "my-sd/sd-3-large",
    "customProviders": {
      "my-sd": { "api": "openai", "baseUrl": "http://localhost:8000/v1", "apiKey": "$SD_KEY" }
    }
  }
}

工具 : image_generate

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 (默认) <cwd>/.pi/images),文件名模式 <filename or model-UTC-stamp>.<ext>。 。 。 .

计划是模式意识的. 每个内置模型都带有来自官方API docs的能力合同,该工具以该合同设定的参数注册(在会话开始后) /image-gen reload)——因此代理完全看清了活性模型的荣誉,在enums和描述中都有所记载的值. 合同是 建议,不是门: 数值限制(大小范围, n 上限、参考图像计数和字节上限)在说明中加以说明,但从未硬性强制客户端——自备部署或网关可能合法地偏离云平台的文件限制,供应商本身的错误是后站。 唯一的客户端拒绝是适配器静静地放下的参数组合(像素) size 送到双子座模型,或者 aspectRatio 被发送到像素大小的模型中——提供商从未看到这些,因此无法抱怨.

• size 遵循该模型的文件格式:

  • 问 (单位:千美元)qwen-image-*: "<width>*<height>" (asterisk,例如:. "2048*2048"),总像素5122–20482; 3.0型号以1:8–8:1. x-形式作为安全网自动正常化.
  • 种子梦 (单位:千美元)doubao-seedream-*: 模型列表中的分级符號 (:1K编号 :1.5K编号 :2K编号 :3K编号 :4K(中文(简体) ) 或者说 明确 "<w>x<h>" 在模型的像素窗口内(2K层在5.0/4.5上).
  • 图片 (单位:千美元)gpt-image-2.5-*, (中文(简体) ), gpt-image-2: "auto" 或者说 "<w>x<h>" ——允许任意大小(双边可分出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,或 <model>-<UTC-stamp> 如果你没有。 当 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)

提供者行为 :

故意没有 model 工具上的参数——活动模式由 pi-image-gen.defaultModel 在设置中.

斜线命令

• /image-gen list ——显示活动模式,它向哪个提供方提供路径,是否设置了密钥,配置了提供者,以及内置模式代号的目录.
• /image-gen reload ——从磁盘上重新读取设置,并重新注册工具,这样其方案(例如: quality )跟踪新选择的模型.
• /image-gen generate <prompt> ——利用活性模型直接从命令行生成图像. 将保存的文件路径报告为纯文本通知( 命令使用) 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处理,以及被标注的即时图.