Image Generation

Image Generation

Use this skill to create an image from a text description with AI image generation, then save it locally and display it to the user.

Setup

Before the first use, ensure the agent-gw Python SDK (version 0.2.6 or newer) is installed. This checks the current environment and installs or upgrades it only when needed:

python3 scripts/image_generation_tool.py ensure-deps

The SDK needs an API key from api_key=..., KIMI_API_KEY, or ~/.kimi/agent-gw.json.

Parameters

• description (required): detailed text description of the image to generate.
• ratio: one of 1:1, 3:2, 2:3, 16:9, 9:16. Default 1:1.
• resolution: one of 1K, 2K, 4K. Default 1K.

Opaque background supports only these combinations: 1K: 1:1 (1024x1024), 3:2 (1536x1024), 2:3 (1024x1536); 2K: 1:1 (2048x2048), 16:9 (2048x1152); 4K: 16:9 (3840x2160), 9:16 (2160x3840). Transparent background only supports 1K with 1:1, 3:2, 2:3.

• background: opaque (default) or transparent.
• reference_image: public URL(s) that guide the generation. Repeat

--reference-image for multiple. The gateway only accepts public URLs, so a local image must be converted with image-to-url first (see "Reference images" below); passing a local path to generate is rejected.

• output (required): local output path ending in .jpg, .jpeg, or .png.

Transparent background must use .png.

Workflow

1. Build a detailed, descriptive description from the user's request: include

subject, style, composition, lighting, colors, and mood.

1. Choose ratio, resolution, and background. Enforce the supported

combinations. For opaque images: 1K allows 1:1 / 3:2 / 2:3; 2K allows 1:1 / 16:9; 4K allows 16:9 / 9:16. Transparent only allows 1:1 / 3:2 / 2:3 ratios, 1K resolution, and PNG output.

1. Pick an output file path with a matching extension.
2. If the user supplies reference images, they must be public URLs. For any

local image (a file on the execution environment, whether that is a sandbox or the client's local machine), first run the image-to-url command to upload it and get a public URL, then pass that URL with --reference-image. The gateway only accepts public reference URLs; passing a local path to generate is rejected.

1. Run the generate command (see "Script"). It calls generate_image on the

gateway, reads media.url / media.mime_type from the response, and downloads the image to your output path with curl (the extension is corrected to match mime_type).

1. If the call fails, explain the failure reason from the printed error. Do not

invent an image or a local path.

1. On success, the script prints the saved file path. Then **display the image

to the user by calling the readFile tool on that path**. Reading the image to show it is the model's job, not this plugin's work.

Reference images

The plugin runs in an execution environment that may be a sandbox or the client's local machine. Either way, the gateway's reference_image_urls must be public URLs, so any local reference image has to be converted first. This is an explicit, separate step — generate does not accept local paths.

Convert each local image to a public URL with image-to-url (it uploads the file via the agent-gw upload_storage API and returns the public signed_url), then pass the printed public URL to generate with --reference-image:

python3 scripts/image_generation_tool.py image-to-url --image-path /path/to/local.png

Script

Use the bundled script from the plugin directory.

Generate an image:

python3 scripts/image_generation_tool.py generate \
  --description "A serene mountain lake at sunrise, soft golden light, mirror reflection, ultra detailed" \
  --ratio "16:9" \
  --resolution "2K" \
  --background "opaque" \
  --output "/path/to/output.png"

Convert a local reference image to a public URL first, then pass that URL:

# Step 1: upload the local image, capture the printed public URL
python3 scripts/image_generation_tool.py image-to-url --image-path /path/to/local_ref.png

# Step 2: pass public URLs (only) to generate
python3 scripts/image_generation_tool.py generate \
  --description "Same character in a snowy forest, cinematic" \
  --ratio "3:2" \
  --reference-image "https://example.com/ref1.jpg" \
  --reference-image "https://" \
  --output "/path/to/output.jpg"

The script:

• generate accepts only public --reference-image URLs and sends them as

reference_image_urls; a local path is rejected with a hint to use image-to-url

• image-to-url uploads a local image via the agent-gw upload_storage API and

prints the resulting public signed_url

• sends `{"description", "ratio", "resolution", "background",

"referenceimageurls"} to the gateway generate_image` API

• reads the generated media.url and media.mime_type from the response
• downloads the image to the --output path with curl, naming the file by

mime_type (png/jpg)

• prints the saved path and a reminder to display it with readFile

generate_image response shape (resp.json()):

{
    "media": {
        "url": str,        # public URL of the generated image
        "mime_type": str,  # e.g. "image/png" or "image/jpeg"
    }
}

> This skill uses the agent-gw Python SDK: client.tools.generate_image(...) > for generation and client.upload_storage(...) (which returns a public > signed_url) to turn a local reference image into a public URL.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: serejaris
• Source: serejaris/kimi-skills
• License: MIT

Install and usage instructions live in the source repository linked above.