@specode/pi-subscription-image

v1.1.1

Published

21 days ago

Generate and edit images in Pi using existing Codex and Grok subscription account quotas.

0High
0Medium
0Low

specode

pi-package pi-extension pi-coding-agent image-generation codex grok subscription

pi-subscription-image

English

一个 Pi 图片生成扩展：统一提供 generate_image_with_subscription 工具，使用现有 OpenAI Codex 与 xAI Grok 订阅账户额度生成或编辑图片。

为什么需要它

不同生图扩展通常会注册不同工具，并使用不同的参数、保存路径和返回格式。这个包提供一个稳定入口，按当前 Pi 会话自动路由，并把生成图片统一以内联图片返回。

功能

复用 Pi 的 openai-codex OAuth 登录生成 Codex 图片。
复用 Pi 的 xai 订阅登录调用 Grok Imagine。
提供 generate_image_with_subscription 工具和 /img 命令。
openai-codex/* 会话自动选择 Codex，xai/* 会话自动选择 Grok。
其他模型会话可显式传入 provider=codex 或 provider=grok。
单次调用可顺序生成 1–4 张图片，避免并发消耗配额；后续某张失败时，仍返回已经生成的图片。
Codex 支持最多 5 张 PNG、JPEG 或 WebP 参考图编辑。
统一支持 none、project、global、custom 保存模式。
即使可选的磁盘保存失败，仍返回已经生成成功的内联图片。
包含严格的 base64、MIME、超时、重试和响应校验。
不自行保存凭据，不发送遥测。

Provider 能力

| 能力 | Codex | Grok | | --- | --- | --- | | 认证 | Pi openai-codex OAuth | Pi xai 订阅登录 | | 文生图 | 支持 | 支持 | | 参考图编辑 | 支持，最多 5 张 | 当前未开放 | | 输出格式 | PNG、JPEG、WebP | Provider 决定，按返回字节检测 | | 图片比例 | 写入 Prompt 约束 | 原生请求参数 | | 分辨率 | 后端决定 | 1k、2k，默认 1k | | 质量等级 | 当前未开放 | low、medium，仅 Imagine 2.0 | | 默认模型 | gpt-5.6-sol 路由，当前已知后端 gpt-image-2 | grok-imagine-image-2.0 |

安装

首次发布后可从 npm 安装：

pi install npm:@specode/pi-subscription-image

本地开发阶段可临时试用：

pi --no-extensions --offline -e /path/to/pi-subscription-image

安装后重启 Pi 或执行 /reload。

使用

自然语言：

生成一张月球科研站日出时分的电影感 16:9 图片。

直接命令：

/img 一枚红熊猫扁平矢量图标

模型会调用 generate_image_with_subscription，参数如下：

| 参数 | 说明 | | --- | --- | | prompt | 必填，图片描述或编辑指令 | | provider | auto、codex 或 grok | | model | Codex 路由模型或 Grok Imagine 图片模型 | | aspectRatio | 通用图片比例约束 | | n | 顺序生成 1–4 张 | | outputFormat | 仅 Codex：png、jpeg、webp；Grok 的实际格式由 Provider 决定 | | resolution | 仅 Grok：1k 或 2k，默认 1k | | quality | 仅 Grok Imagine 2.0：low 或 medium；默认不发送，由 Provider 决定 | | save | none、project、global 或 custom | | saveDir | save=custom 时的目录 | | referencedImagePaths | Codex 最多 5 张本地参考图 | | numLastImagesToInclude | Codex 使用最近的会话图片进行编辑 |

支持以下参数别名：

provider=openai 映射为 codex。
provider=xai 映射为 grok。
旧的 aspect_ratio 会在校验前映射为 aspectRatio。

Codemode

在支持工具 outputSchema / structuredContent 的 Pi 版本中，可通过 codemode 调用同一个工具。直接工具调用与 /img 的行为不变。

const result = await tools.generate_image_with_subscription({
  prompt: "一只水彩风格的红熊猫",
});
for (const block of result.output) {
  if (block.type === "image") image(block);
  else text(block.text);
}

脚本收到 { provider, model, output, generationErrors, savedPaths, saveWarnings }。output 包含文本块和可直接传给 image() 的 base64 图片块。即使使用 save: "none" 或可选的磁盘保存失败，也会返回图片；保存错误见 saveWarnings。参数校验失败（包括 save=custom 未提供目录）会在消耗配额前 reject。第一张图片生成失败或调用被取消时，工具调用同样会 reject；启用保存时，取消前已经生成的图片仍会保存。多图请求中后续某张失败时，会停止生成并返回已经生成的图片，失败原因见 generationErrors。

不要用 text()、console 或 return 输出整个结果或 base64 数据，应使用 image(block) 展示图片。Pi codemode 单个脚本的输出上限为 16 MiB，base64 图片数据计入其中，多张较大的 Codex PNG 可能导致脚本失败。建议像示例一样保留默认保存，让图片在脚本展示前已写入磁盘；Codex 多图请求优先使用 outputFormat: "webp" 或 "jpeg"。生成可能需要数分钟，避免设置过短的脚本超时。这是现有订阅工具的适配，不是 models.generateImages() 接口。旧版 Pi 若不支持结构化工具结果，仍可直接调用工具，但无法把图片传入 codemode 脚本。

自动路由

没有指定 provider，或使用 provider=auto 时：

有参考图输入时选择 Codex。
当前会话为 openai-codex/* 时选择 Codex。
当前会话为 xai/* 时选择 Grok。
如果配置了 defaultProvider，则使用该值。
否则要求显式指定 provider，避免误消耗订阅额度。

保存位置

| 模式 | 位置 | | --- | --- | | none | 只返回内联图片 | | project | <cwd>/.pi/generated-images/ | | global | ~/.pi/agent/generated-images/ | | custom | saveDir 或配置目录 |

默认保存模式为 global。

配置

全局配置：

~/.pi/agent/extensions/subscription-image.json

可信项目配置：

<project>/.pi/extensions/subscription-image.json

只有项目处于可信状态时，项目配置才会覆盖全局配置。

{
  "defaultProvider": "codex",
  "save": "global",
  "saveDir": "~/Pictures/generated",
  "providers": {
    "codex": {
      "routingModel": "gpt-5.6-sol",
      "outputFormat": "png"
    },
    "grok": {
      "imageModel": "grok-imagine-image-2.0",
      "resolution": "1k"
    }
  }
}

providers.grok.quality 可设为 low 或 medium；省略时不向 xAI 发送该字段。旧的 codexRoutingModel 和 grokImageModel 配置仍兼容。全局与可信项目的 providers.codex、providers.grok 会分别深度合并。

真正统一的参数是 prompt、provider、model 覆盖入口、aspectRatio、n、save 和 saveDir。Provider 特有参数保持显式：Codex 使用 outputFormat 和参考图输入；Grok 使用 resolution、quality。扩展不会默认改写或润色 Prompt；只有 Codex 的比例要求会以确定性约束追加到 Prompt。

环境变量：

PI_SUBSCRIPTION_IMAGE_PROVIDER
PI_SUBSCRIPTION_IMAGE_SAVE_MODE
PI_SUBSCRIPTION_IMAGE_SAVE_DIR
PI_SUBSCRIPTION_IMAGE_CODEX_MODEL
PI_SUBSCRIPTION_IMAGE_CODEX_OUTPUT_FORMAT
PI_SUBSCRIPTION_IMAGE_GROK_MODEL
PI_SUBSCRIPTION_IMAGE_GROK_RESOLUTION
PI_SUBSCRIPTION_IMAGE_GROK_QUALITY
PI_SUBSCRIPTION_IMAGE_GROK_BASE_URL

同时支持 PI_IMAGE_SAVE_MODE 和 PI_IMAGE_SAVE_DIR。

安全和服务边界

这是非官方社区扩展。
凭据只通过 Pi provider registry 解析，不写入本包自己的存储。
Prompt 和参考图会发送到选择的 Provider。
Codex 使用 ChatGPT Codex Responses 后端的内置 image_generation 工具。
Grok 使用 xAI 图片生成接口。
订阅可用性、额度、地区限制和服务条款仍由对应 Provider 决定。
Provider 后端发生变化时，可能需要升级本包。

开发

npm install
npm test
npm run smoke
npm run check

推送到 main 和 Pull Request 会运行类型检查、测试、Pi 加载 smoke 与包内容校验。npm 发布流程沿用 OIDC Trusted Publishing：创建 GitHub Release 后会重复这些检查，再通过 OIDC 发布，不保存长期 npm token。

许可证

MIT。实现参考和第三方归属见 THIRD_PARTY_NOTICES.md。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme