image-gen

Image Gen — AI Image Generation

Supports text-to-image + image-to-image, automatically manages API Keys, and generated results can be inserted directly into WPS Notes.

Iron Rules

API Keys must not be output in the conversation, under any circumstances
encrypt-key The subcommand output ciphertext_b64 may be displayed (this is ciphertext, not the real Key)
Warning text must be displayed in full and must not be omitted
Model names may not be modified, and users are not allowed to customize them. Each provider has only one confirmed usable model; the AI must strictly use the values in the table below and must not fill in other model names based on user descriptions, preferences, or its own inference—any other model name is considered a hallucination:

provider	Only usable model (hardcoded, cannot be changed)
openrouter	`google/gemini-3.1-flash-image-preview`
dashscope (Bailian)	`qwen-image-2.0-pro`
ark (Jimeng)	`doubao-seedream-5-0-260128`
gemini	`gemini-3-pro-image-preview`

Users can only choose which providerto use; the model is automatically filled in by the AI according to the table above, and overwriting is not accepted under any circumstances.

Core Process

确认需求 → 确定 provider + model → 获取/解密 Key → 执行生图 → 询问是否插入笔记

Step 1: Confirm image generation requirements

Ask:

请告诉我：
1. 生图描述（prompt）是什么？
2. 有参考图吗？（有 → 图生图；没有 → 文生图）
3. 比例偏好？（1:1 / 16:9 / 9:16 / 4:3 / 3:4，默认 1:1）

No reference image → text-to-image, all providers available
Has reference image → image-to-image, only openrouter (local file) / gemini (local file) / ark Jimeng (public URL) support it; Bailian does not support image-to-image

Step 2: Determine Provider

Have the user choose one of the following four providers; the model is automatically filled in by the AI (see Iron Rules):

provider	Features	Suitable scenarios
openrouter	Uses a proxy, text-to-image + image-to-image (local file as reference image)	Proxy environment, needs image-to-image
dashscope (Bailian)	Direct connection in China, text-to-image only	China network, pure text-to-image
ark (Jimeng)	Direct connection in China, text-to-image + image-to-image (reference image must be a public URL)	China network, needs image-to-image
gemini	Uses a proxy, text-to-image + image-to-image (local file as reference image)	Proxy environment, Google direct connection

When the user does not specify, proactively recommend based on whether a proxy is available and whether image-to-image is needed.

openrouter / gemini require a proxy in China; ask the user whether they can provide --proxy。

Step 3: Obtain Key

3.1 Search notes first

search_notes Search 图像生成 Key, after finding it read_note read, find the row corresponding to the provider in the table, and retrieve ciphertext_b64 and note_id。

Ciphertext found → go directly to Step 4(note mode, the script automatically decrypts).

Note not found or corresponding row not found → go to Step 3.2。

3.2 Request Key from user

我需要 {provider} 的 API Key 才能继续。
获取地址：{平台 URL}

请直接粘贴你的 Key：

provider	Key acquisition address
openrouter	https://openrouter.ai/workspaces/default/keys
dashscope	https://bailian.console.aliyun.com/cn-beijing?tab=model#/api-key
ark	https://console.volcengine.com/ark/
gemini	https://aistudio.google.com/app/api-keys

After receiving the Key, ask whether to save it (see Step 3.3).

3.3 Ask whether to save the Key

The following warning must be displayed in full:

⚠️ Security Risk Notice (please read carefully)

If you choose to save, the Key will be AES encryptedand then stored in WPS Notes:

The encryption key is derived on the spot from "local device ID + note ID + provider. No extra files need to be stored on this device.

WPS Notes will not obtain your Key content, and the ciphertext cannot be decrypted on other devices.

⚠️ If you have addeda third-party MCP plugin, that plugin can read the note content (including the ciphertext).

⚠️ After switching devices, the same ciphertext cannot be decrypted, and it must be saved again.

Save? A. Save (I am aware of the risks) B. Do not save (use temporarily this time)

Choose Save：

Check whether the 图像生成 Key note exists; if it does not, create_note create a new one (title 图像生成 Key, add the #图像生成 tag)
Perform encryption:

python3 comm_script/image_gen.py encrypt-key \
    --note-id "{笔记 note_id}" \
    --provider "{provider}" \
    --key "{用户提供的Key}"

Take ciphertext_b64from the output, replace the entire table and write it to the note (add or replace the corresponding provider row):

<table>
  <tr>
    <td><p><strong>provider</strong></p></td>
    <td><p><strong>ciphertext_b64</strong></p></td>
    <td><p><strong>更新时间</strong></p></td>
  </tr>
  <tr>
    <td><p>{provider}</p></td>
    <td><p>{ciphertext_b64}</p></td>
    <td><p>{当前日期}</p></td>
  </tr>
</table>

In the conversation, only say: "The Key has been encrypted and saved to the note 《Image Generation Key》. It will be read automatically next time."

Choose Do Not Save: the Key is used only this time; go directly to Step 4,--key pass the string directly.

Step 4: Perform image generation

note mode (there is already a saved Key)

python3 comm_script/image_gen.py \
    --provider "{provider}" \
    --model "{model}" \
    --key "note:{note_id}" \
    --ciphertext "{ciphertext_b64}" \
    --prompt "{prompt}" \
    [--image "{参考图路径或URL}"] \
    [--proxy "{代理地址}"] \
    --aspect "{比例}" \
    [--size "{分辨率}"] \
    --out "./output"

temporary mode (use directly this time)

python3 comm_script/image_gen.py \
    --provider "{provider}" \
    --model "{model}" \
    --key "{用户提供的Key}" \
    --prompt "{prompt}" \
    [--image "{参考图路径或URL}"] \
    [--proxy "{代理地址}"] \
    --aspect "{比例}" \
    --out "./output"

Before execution, inform: "Calling {provider} to generate the image, estimated 30-120 seconds…"

After image generation is complete, obtain the local image path from the [saved] {路径} line.

Step 5: Ask whether to insert into the note

图片已生成：{路径}
需要插入到 WPS 笔记吗？
A. 插入当前打开的笔记
B. 插入指定笔记（请告诉我标题）
C. 不用，本地保存就行

When Insert is selected, perform the following steps:

1. Obtain the target note's anchor_id (must be done first)

wpsnote-cli outline --note_id "{note_id}" --json

Take the blocks of the last element of the id array as the anchor_id。

2. Insert the image (prefer CLI)

wpsnote-cli insert-image \
    --note_id "{note_id}" \
    --anchor_id "{最后一个block的id}" \
    --position "after" \
    --src "{图片本地路径或URL}" \
    --json

Return block_id to indicate successful insertion.

3. Fallback: if CLI fails, use MCP

insert_image({ note_id: "{note_id}", anchor_id: "{anchor_id}", position: "after", src: "{url或本地路径}" })

⚠️ insert-image requires the target notecurrently open in the WPS editor, otherwise report INTERNAL_ERROR. If an error is reported, prompt the user to open the note in WPS and retry.

Step 6: Delete Key

When the user says "delete Key", "clear the saved Key", or "change to another Key":

Search the 图像生成 Key note, replace the entire table to delete the corresponding provider row
Inform: "The ciphertext for {provider} has been deleted from the note. The Key must be provided again for the next image generation."

No local files need to be cleaned up (in note mode there is no local storage to begin with).

Common issue handling

Scenario	Handling method
Decryption failed (switched devices)	Prompt "the ciphertext is unavailable after switching devices; please run the save process again"
openrouter / gemini connection timeout	Prompt "a proxy is required in China; please provide the proxy address"
Bailian was passed a reference image	Ignore automatically, and inform "Bailian does not support image-to-image"
The base image for Volcano Ark is a local file	Prompt "must be a public URL"
Dependencies not installed	Prompt `pip install httpx cryptography`