pi-subscription-image

简体中文

A Pi image generation extension that exposes one generate_image_with_subscription tool and uses quota from existing OpenAI Codex and xAI Grok subscription accounts.

Why

Image extensions often expose provider-specific tools with different parameters and save behavior. This package keeps one stable tool contract, routes by the active Pi session provider, and returns every generated image inline.

Features

• Reuses Pi's openai-codex OAuth login for Codex image generation.
• Reuses Pi's xai subscription login for Grok Imagine.
• Provides the generate_image_with_subscription tool and /img command.
• Automatically routes openai-codex/* sessions to Codex and xai/* sessions to Grok.
• Lets callers explicitly select provider=codex or provider=grok from other sessions.
• Supports up to four sequential generations per call; if a later image fails, the images already generated are still returned.
• Supports Codex reference-image editing with up to five PNG, JPEG, or WebP inputs.
• Preserves none, project, global, and custom save modes.
• Returns valid images inline even when optional disk persistence fails.
• Includes strict base64, MIME, timeout, retry, and response validation.
• Does not store credentials or send telemetry.

Provider capabilities

Installation

Install from npm after the first release:

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

Try a local checkout without installing:

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

Restart Pi or run /reload after installation.

Authentication

Use Pi's normal login flow:

/login

• Select ChatGPT Plus/Pro (Codex) for Codex.
• Select the xAI subscription login for X Premium or SuperGrok.

Check readiness without exposing credentials:

/subscription-image status

Usage

Natural language:

Generate a cinematic 16:9 image of a lunar research station at sunrise.

Direct command:

/img a flat vector icon of a red panda

The model calls generate_image_with_subscription. The public parameters are:

Provider aliases are accepted:

• provider=openai maps to codex.
• provider=xai maps to grok.
• aspect_ratio maps to aspectRatio before validation.

Codemode

On Pi versions that support tool outputSchema / structuredContent, the same tool can be called from codemode. Direct tool calls and /img remain unchanged.

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);
}

The script receives { provider, model, output, generationErrors, savedPaths, saveWarnings }. output contains text and base64 image blocks accepted by image(). Images are returned even with save: "none" or when optional disk persistence fails; inspect saveWarnings for persistence errors. Validation errors, including save=custom without a directory, reject before any quota is used. The tool call also rejects when the first image fails or the call is cancelled; with saving enabled, images generated before a cancellation are still saved. If a later image in a multi-image request fails, generation stops and the images already generated are returned with the failure in generationErrors.

Do not print or return the whole result or base64 data with text(), console, or return; use image(block) to display it. Pi codemode caps a script's output at 16 MiB, and base64 image data counts toward it, so several large Codex PNGs can make the script fail. Keep saving enabled, as in the example, so images are on disk before the script displays them, and prefer outputFormat: "webp" or "jpeg" for multi-image Codex requests. Generation can take minutes, so avoid short script deadlines. This uses the existing subscription tool, not models.generateImages(). Older Pi versions without structured tool results retain direct tool use but cannot expose images to codemode scripts.

Routing

With provider=auto or no provider:

1. Reference-image inputs select Codex.
2. An openai-codex/* session selects Codex.
3. An xai/* session selects Grok.
4. defaultProvider is used when configured.
5. Otherwise the tool asks for an explicit provider instead of spending quota unexpectedly.

Save behavior

The default save mode is global.

Configuration

Global configuration:

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

Trusted project configuration:

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

Project values override global values only when project trust is active.

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

Set providers.grok.quality to low or medium when needed. When omitted, the extension does not send the field to xAI. The legacy codexRoutingModel and grokImageModel keys remain supported. Global and trusted-project providers.codex and providers.grok blocks are deep-merged independently.

The truly common parameters are prompt, provider, the per-call model override, aspectRatio, n, save, and saveDir. Provider-specific capabilities remain explicit: Codex owns outputFormat and reference-image inputs; Grok owns resolution and quality. The extension does not silently rewrite or embellish prompts; only Codex receives a deterministic aspect-ratio constraint appended to the prompt.

Environment overrides:

• 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 and PI_IMAGE_SAVE_DIR are also accepted.

Security and service boundaries

• This is an unofficial community extension.
• It reads resolved credentials through Pi's provider registry and never writes them to package-owned storage.
• Prompts and reference images are sent to the selected provider.
• Codex generation uses the ChatGPT Codex Responses backend and its built-in image_generation tool.
• Grok generation uses the xAI image generation endpoint.
• Subscription availability, quotas, regional access, and provider terms still apply.
• Backend changes can require a package update.

Development

npm install
npm test
npm run smoke
npm run check

Pushes to main and pull requests run type checking, tests, Pi loading, and package validation. The npm release workflow follows OIDC Trusted Publishing: creating a GitHub release repeats those checks and then publishes without a long-lived npm token.

License

MIT. See THIRD_PARTY_NOTICES.md for implementation references and attribution.