pi-subscription-image

English | 简体中文

A Pi extension that generates and edits images with your OpenAI Codex or xAI Grok subscription quota via the generate_image_with_subscription tool and /img.

/subscription-image status output:

Image Generation: Codex ready; Grok ready

/img command:

/img a flat vector icon of a red panda

Supported Providers

To sign in, run /login, pick Sign in with an account (Account below), then pick the name shown in the table.

Provider Notes

OpenAI Codex

Sign in with a ChatGPT Plus or Pro account (Account → OpenAI Codex (legacy)). Reference-image editing accepts up to 5 local images (png, jpeg, or webp, up to 20 MB each) or recent images from the current conversation. When aspectRatio is set, it is appended to the prompt as a composition constraint.

xAI Grok

Sign in with your X Premium or SuperGrok account (Account → xAI). Grok Imagine accepts aspectRatio (defaults to 1:1), resolution (1k default or 2k), and quality (low or medium, supported on grok-imagine-image-2.0 models only) as native request parameters.

Installation

Requires Node.js >= 22.19.0.

From npm:

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

From GitHub:

pi install git:github.com/specode/pi-subscription-image

From a local directory for development:

pi install /path/to/pi-subscription-image

Run /reload or restart Pi after installing.

Usage

Sign in through /login as described above, then ask Pi in natural language or run /img <prompt>:

• Generated images are shown inline in the conversation and saved to ~/.pi/agent/generated-images/ by default.
• Run /subscription-image status to check whether Codex and Grok credentials are available in Pi.
• Multi-image requests (n from 1 to 4) run sequentially and save each image as soon as it finishes. If a later image fails or the request is cancelled, already-generated images are still returned and kept on disk.

Provider Selection

When provider is omitted or set to "auto", the extension chooses a backend in this order:

1. Reference images are provided (referencedImagePaths or numLastImagesToInclude) → codex
2. Active session model is under openai-codex → codex
3. Active session model is under xai → grok
4. defaultProvider is configured → configured provider
5. Otherwise, the tool asks you to pass provider="codex" or provider="grok" (or configure defaultProvider).

Tool Parameters (generate_image_with_subscription)

Configuration

Create ~/.pi/agent/extensions/subscription-image.json (global) or .pi/extensions/subscription-image.json (trusted project override):

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

Optional: set providers.grok.quality to "low" or "medium". Legacy top-level keys (codexRoutingModel, grokImageModel) are also accepted.

Environment Variables

Privacy and Safety

• Credentials come only from Pi's own login (provider registry) in memory and are never written to disk by this extension.
• Requests go to https://chatgpt.com/backend-api/codex/responses for Codex and https://api.x.ai/v1/images/generations (or PI_SUBSCRIPTION_IMAGE_GROK_BASE_URL when set) for Grok.
• Save settings and provider parameters are validated before sending generation requests so invalid configuration does not spend quota.
• Prompts are sent as provided (with an explicit aspect-ratio line appended only on Codex when aspectRatio is set).

Development

# Run tests
npm test

# Run typecheck, tests, extension smoke check, and package check
npm run check

# Load the extension directly in Pi without installing
pi --no-extensions --offline -e ./src/index.ts --list-models

Calling from Codemode Scripts

On Pi versions with tool outputSchema and structuredContent support, Codemode scripts can call tools.generate_image_with_subscription directly:

const result = await tools.generate_image_with_subscription({
  prompt: "A red panda in watercolor",
});
for (const block of result.output) {
  if (block.type === "image") image(block);
  else text(block.text);
}

result has the shape { provider, model, output, generationErrors, savedPaths, saveWarnings }. Pass image blocks to image(block) rather than text(), console.log, or return so base64 image data does not hit Codemode's 16 MiB script output limit. For multiple Codex images in one script, prefer outputFormat: "webp" or "jpeg".

License

MIT. See THIRD_PARTY_NOTICES.md for adapted sources and licenses.