zd-Ethan/jishuya-image

Tech Duck Image Generation

Use this skill's Go program to complete image generation and editing. The entire folder can be unzipped and used directly; the user does not need Python, Node.js, or Go, nor do they need to run any installation commands. Use the program's absolute path at runtime; do not assume it is on the PATH.

Selecting the Program

The universal package's bin/ directory contains programs for all five platforms. On first invocation, select the system and CPU architecture based on the actual execution command environment; WSL uses the Linux program. macOS/Linux can determine this with uname -s and uname -m; x86_64 corresponds to amd64, arm64/aarch64 corresponds to arm64.

Execution Environment	Program Path Relative to Skill Directory
Windows Intel/AMD x64	bin/jishuya-image-windows-amd64.exe
macOS Intel	bin/jishuya-image-darwin-amd64
macOS Apple Silicon	bin/jishuya-image-darwin-arm64
Linux x64	bin/jishuya-image-linux-amd64
Linux ARM64	bin/jishuya-image-linux-arm64

Windows can query [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture. Systems/architectures not listed indicate a missing program; do not guess compatibility. PowerShell uses & "program absolute path"; on macOS/Linux, if the unzipped files did not retain execute permissions, run chmod +x "program absolute path" on the selected program. macOS packages are not developer-signed/notarized; if the system blocks it, inform the user to confirm the source as prompted by the system, do not automatically disable system protection.

Execution Flow

1. Run doctor on first use or if a configuration error occurs; it only queries models, it does not generate images. If the key is configured and the request is clear, execute directly without reconfirming for every image. If the key is missing, provide the user with the complete init command to run in their local terminal, or the user can set JISHUYA_IMAGE_API_KEY for the host process; do not ask the user to paste the key in the conversation, and do not wait for input in a non-interactive background. If configuration or environment variables already exist, use them directly; init is an optional step to save the configuration.
2. Use generate for clear new image requests; use edit for reference image modifications or "take that previous one...", passing the absolute local path of the image provided by the user or previously generated. If the task lacks an actual reference image, first determine the image location; do not fabricate paths.
3. Select parameters based on the request; generate one image if no explicit count is given. If no model is specified, use the model from the configuration; if no model configuration is available, default to gpt-image-2; models can list visible models. Do not arbitrarily switch models to retry.
4. Keep the current request running until completion; if the host returns a running session, continue waiting for the same process. On success, display the image based on the actual files in paths and indicate their location, while also informing the user of any unsatisfied requirements in warnings; on failure, check the returned result.paths / result.partial_paths, and explain the existing results and errors.

The key is read first from JISHUYA_IMAGE_API_KEY, and second from the program-managed user configuration file. The environment variable mode can be used directly even without a user configuration directory; init still requires that directory to save the configuration. Do not read, display, or copy the key from the configuration file. The API is fixed at https://www.jishuya.net/v1. If the corresponding program is missing from bin/, first explain that a full release ZIP is needed; downloading only the source code or copying SKILL.md does not include the executable binary. The download entry point can be found in README.md.

The host sandbox must allow the program to read the local configuration, write to the specified output directory, and access Tech Duck. When encountering permission denials, apply for the required permissions for this command via the host's approval method; environments that prohibit such approval should explain the blockage and provide the local terminal command. Do not disable the sandbox, relax ACLs on the key file, or copy the key yourself to bypass restrictions. If the user has configured the environment variable for the host process, the program can use it directly, even if the local configuration file is unreadable.

Command Examples

Replace PROGRAM below with the absolute path of the program for the current system; PowerShell uses & "full path" for paths with spaces.

PROGRAM generate --prompt "a little yellow duck sitting by the window" --output-dir "project-dir/output/imagegen"
PROGRAM edit --image "/absolute/path/to/original.png" --prompt "keep the subject the same, change the background to blue" --output-dir "project-dir/output/imagegen"
PROGRAM edit --image "ref-image-one.png" --image "ref-image-two.png" --prompt "use the composition of the first image and the colors of the second"
PROGRAM generate --prompt "product image with transparent background" --background transparent
PROGRAM generate --model gpt-image-2.6-sunburst --prompt "generate a real GIF animation: a red ball moving left and right, 2 frames looped, each frame 200ms, output as a GIF file" --format gif --frame-count 2 --frame-duration-ms 200
PROGRAM generate --help
PROGRAM edit --help

Normal images default to PNG, 1024x1024, and auto quality; adjust size, quality, and aspect ratio as needed. When the user requests a specific size, also specify the dimensions and aspect ratio in the prompt, and verify the actual image after completion. --output-dir prefers the output directory for the current task; if omitted, it writes to the jishuya-output/ directory in the current working directory. Default timeout is 600 seconds.

Advanced Parameters and Platform Capabilities

Tested on 2026-11-09: gpt-image-2, gpt-image-2.6-sunburst, and gpt-image-2.6-flare can all return PNG; reference image editing, multi-reference images, dual outputs, and transparent PNGs have been successful. After explicitly requesting GIF animation in the prompt, 2.6 Sunburst/Flare were verified with 2-frame/200ms and 4-frame/120ms looping animations respectively. Flare's streaming final image has been verified; the client is compatible with Tech Duck's result events. The following limitations are based on endpoint testing and do not represent the model's inherent capabilities:

• The default request 1024x1024 has repeatedly returned 1254x1254; explicitly specifying 1536x1024 in both the prompt and parameters has succeeded in some cases, but must still verify the actual dimensions.
• JPEG, WebP, and native SVG have not yet been verified; even with explicit prompts, PNG may still be returned, so success cannot be judged by file extension alone.
• Streaming final images work, but the requested intermediate preview images have not been returned; the client will warn via warnings, so real-time image preview cannot be claimed.
• Flare's low/medium/high quality requests succeeded with matching quality labels; xhigh/max requests returned with a medium label, so higher quality generation cannot be claimed. The client will notify the user of any discrepancies in reported dimensions or quality.
• The mask may still modify pixels outside the masked area. Markup has succeeded in some cases with additional coordinates in the prompt specifying the top-left position, but strict region constraints or preservation of other pixels cannot be guaranteed.

If the user requires any of the above unverified capabilities, first explain the current tested limitations; do not present incorrect formats, incorrect regions, or results with only a successful exit code as fulfilling the request. See README.md for a detailed mapping of models to use cases. Parameter entry points are retained for verification after endpoint fixes.

• General parameters: --model, --size, --quality, --complexity, --count, --format, --background, --compression, --moderation. Quality accepts auto/low/medium/high/xhigh/max, output format accepts png/jpeg/webp/gif/svg; this is only the client-side parameter range, actual support depends on the Tech Duck endpoint.
• Editing: repeat --image up to 16 times; --mask and --markup are mutually exclusive and must be PNG. Dimensions must match the first reference image; annotation images should be independent transparent layers. The program checks input file signatures and does not substitute for endpoint checks on dimensions or transparency.
• GIF: In addition to --format gif, the prompt must explicitly state "generate a GIF animation", the moving content, frame count, and individual frame duration; specifying only the format parameter has previously returned PNG. --frame-count 2–16, --frame-duration-ms 20–2000; cannot be used with mask, streaming, or compression. The program rejects corrupted or single-frame GIFs; the animation effect and specified frame count/duration still need verification.
• SVG: One at a time, can add --svg-model and --svg-reasoning (the latter requires an authoring model); cannot be used with streaming or compression. SVG editing, transparent SVG, and additional quality tiers require endpoint testing and cannot be guaranteed.
• SSE: --stream or --partial-images 1–3. The program saves received images as events occur and returns paths via JSON after completion; no real-time preview is provided in the conversation. If the stream is interrupted, the already saved files are retained.

Generation and editing consume Tech Duck credits. Do not automatically resubmit after request failure, timeout, or stream interruption; first inform the user and check the platform records. A successful models call does not verify image generation functionality. See README.md for first-time use, configuration, upgrade, deactivation, and uninstallation. The program does not copy skills, rewrite personal rules, or auto-update.