intelalloc-image

name

intelalloc-image

description

Generate and edit images through the IntelAlloc image API from Codex. Use when the user asks to create images, generate pictures, edit images, modify an uploaded or local image, use reference images, process an image directory, batch-edit images, configure IntelAlloc API keys, change default image size or quality, continue from the previous generated image, or troubleshoot IntelAlloc image generation/editing from Codex.

IntelAlloc Image

Overview

Use the bundled CLI to call the IntelAlloc image API for text-to-image generation, image editing, directory reference-image editing, and batch image edits. The skill is meant for Codex users on any device where this skill is installed and the IntelAlloc API is reachable.

The CLI is scripts/intelalloc_image.py. Run it with Python 3 and standard-library dependencies only. If Pillow is installed, the CLI can use it as an optional optimization helper for edit uploads.

The skill supports English and Chinese natural-language requests. Match the user's language in normal replies: answer English users in English and Chinese users in Chinese. Do not translate or rewrite raw API error bodies.

For onboarding another Codex user, include USAGE.md with the skill package. It contains end-user setup, English and Chinese natural-language examples, CLI commands, and safety notes.

Defaults

• Model: gpt-image-2
• Generation endpoint: https://backend.intelalloc.com/v1/images/generations
• Edit endpoint: https://backend.intelalloc.com/v1/images/edits
• Default size: 2048x1152
• Default quality: medium
• Output format: png
• Stream: true
• Partial images: 2
• Background: auto
• Max input images per edit request: 16
• Edit upload optimization: for multi-image edits, optimize upload copies first when Pillow is available; never modify the original input images.
• User-Agent: generated by init, using a Codex CLI style such as codex_cli_rs/0.77.0 (Windows 10.0.26200; x86_64) WindowsTerminal

Supported sizes: 1536x1024, 1024x1536, 1024x1024, 2048x1152, 1152x2048, 2048x2048, 3840x2160, 2160x3840.

Supported qualities: low, medium, high.

Configuration

Store user configuration in ~/.codex/intelalloc-image/config.json. Never put API keys, generated images, history, or user config inside the skill folder.

Config precedence:

1. CLI arguments
2. INTELALLOC_API_KEY environment variable
3. ~/.codex/intelalloc-image/config.json
4. Built-in defaults

If a request needs the API and no key is configured, ask the user for their IntelAlloc API key, then save it:

python scripts/intelalloc_image.py configure --api-key "<key>"

On a new device, initialize local settings before the first request:

python scripts/intelalloc_image.py init

Initialize and save an API key in one step when the user provides it:

python scripts/intelalloc_image.py init --api-key "<key>"

Use init --dry-run to inspect the device-derived config without writing it. Use init --force to refresh generated endpoint, model, size, quality, platform, and User-Agent while preserving the existing API key unless a new key is passed.

Update default size or quality when the user asks:

python scripts/intelalloc_image.py configure --default-size 2048x1152 --default-quality high

Never change or override size/quality unless the user explicitly asks for a size or quality. For ordinary generation/editing requests, omit --size and --quality so the local defaults are used. When a request starts, show the user the effective REQUEST_SIZE and REQUEST_QUALITY from the CLI and mention they can ask for another size or quality.

Update the HTTP User-Agent if the user needs to test Cloudflare/API access rules:

python scripts/intelalloc_image.py configure --user-agent "IntelAllocImageGenerate/1.3"

Show current config without leaking the full key:

python scripts/intelalloc_image.py show-config

Generate Images

Use generate for text-to-image. Require an explicit output path; if the user does not provide one, ask for it before running.

python scripts/intelalloc_image.py generate --prompt "city at night" --output "/path/to/city.png"

Override size or quality for a single request:

python scripts/intelalloc_image.py generate --prompt "poster" --size 3840x2160 --quality high --output "/path/to/poster.png"

Only use --size or --quality when the user explicitly requested those values.

Edit Images

Use edit when the user supplies local image paths, drags images into Codex with readable file paths, asks to use a directory as reference images, or says to continue from the previous generated image.

Single input:

python scripts/intelalloc_image.py edit --prompt "make this watercolor" --input "/path/to/source.png" --output "/path/to/watercolor.png"

Multiple inputs:

python scripts/intelalloc_image.py edit --prompt "combine these references" --input "/path/a.png" --input "/path/b.jpg" --output "/path/result.png"

For multi-image edits, the CLI should prefer optimized upload copies to reduce request size. This uses Pillow only when available; if Pillow is missing or optimization does not reduce bytes, upload the original file bytes. Original input files must never be changed.

Dragged images can be combined with the previous IntelAlloc output. When the user asks to add a dragged image to the previous output, use a dragged image as reference for the previous image, or modify the "above output image" with a dragged image, call edit with both --input <dragged-path> and --from-last:

python scripts/intelalloc_image.py edit --input "/path/dragged.png" --from-last --prompt "add the dragged image into the previous output and keep the overall style consistent" --output "/path/result.png"

Repeat --input for multiple dragged images. The 16-image limit includes dragged images, directory images, and the previous output. If a dragged image has no readable local path, ask only for the local file path and do not attempt a fallback image operation.

Directory references:

python scripts/intelalloc_image.py edit --prompt "use these references" --input-dir "/path/refs" --output "/path/result.png"

Use --recursive only when the user asks to include subdirectories. Use --limit 16 only when the user explicitly accepts limiting a larger directory.

Previous image:

python scripts/intelalloc_image.py edit --from-last --prompt "make it cinematic" --output "/path/cinematic.png"

If a dragged image is visible to Codex but no readable local path is available, ask the user for a file path. Do not try to reconstruct image bytes from the chat.

Batch Edit Directories

Use batch-edit when the user wants to process each image in a directory into separate outputs.

python scripts/intelalloc_image.py batch-edit --prompt "make each image watercolor" --input-dir "/path/source" --output-dir "/path/out"

By default, read only .png, .jpg, .jpeg, and .webp files directly inside the input directory. Add --recursive only when requested.

History And Display

The CLI writes history to ~/.codex/intelalloc-image/history.json after every successful generate, edit, or batch-edit.

Use these commands for continuity:

python scripts/intelalloc_image.py last
python scripts/intelalloc_image.py history

After successful commands, parse standard output lines:

• SAVED_IMAGE=<absolute path>
• DISPLAY_IMAGE=<absolute path with forward slashes>
• SAVED_IMAGES=<json array> for batch output
• DISPLAY_IMAGES=<json array> for batch output

Also surface request metadata from stderr/stdout when present:

• REQUEST_SIZE=<size>
• REQUEST_QUALITY=<quality>
• REQUEST_STARTED_AT=<local timestamp>
• REQUEST_FINISHED_AT=<local timestamp>
• REQUEST_ELAPSED_SECONDS=<seconds>

In the final Codex response, show every generated image with Markdown image syntax using DISPLAY_IMAGE or DISPLAY_IMAGES:

![generated image](/absolute/path/to/image.png)

On Windows, prefer the forward-slash DISPLAY_IMAGE path returned by the script.

Failure Handling

• Missing API key: ask the user for the key and call configure.
• Missing output path: ask the user for a destination path before running.
• Unreadable dragged image: ask for a local file path.
• More than 16 edit inputs: ask the user to reduce inputs or explicitly allow --limit 16.
• Missing last_output: ask the user to specify an input image path.
• Deleted last_output: report the missing file and ask for a replacement input path.
• API response errors: show the CLI's plain-text error output directly. Do not summarize, translate, restructure, or replace the API's returned error body. It is acceptable to introduce it with "接口返回错误如下：".
• If the API error body unexpectedly contains an API key, redact only the key and keep the rest of the returned text unchanged.
• Network errors without an API response body: report the CLI error text as-is.
• Cloudflare 1010/browser-signature errors: run show-config and confirm the User-Agent is the device-derived Codex CLI style from init. If it still fails, the backend Cloudflare rule must allow the API path or a compatible machine-client signature.
• HTTP 502 errors are not retried. Show the returned error body and the CLI's "建议稍后再试。" message.
• On any generate/edit/batch-edit API request failure, return the failure reason and tell the user to retry or try again later. Do not write history, do not claim an output was saved, do not attempt a fallback image operation, and do not continue with unrelated actions.

The CLI retries retryable network/upstream failures up to 2 times.