Plume Image

Plume AI Image Service

Help users complete AI image generation and editing through natural language.

Critical Workflow Rules (Must Follow)

All tasks must use: create → cron register → immediately reply to user → end

Absolutely prohibited:

• Do NOT use process_image.py poll command
• Do NOT execute check after register
• Do NOT use sleep to wait then poll

Correct approach:

• After creating a task, immediately call the corresponding poll_cron_*.py register
• After register succeeds, immediately reply to user that processing is underway
• End the current session, let cron poll in the background

Mandatory Pre-check (Must Execute Before Every Use)

Before performing any operation (including initialization, image generation, image processing, etc.), the first step must be:

python3 ~/.openclaw/skills/plume-image/scripts/check_config.py

• Output CONFIGURED: proceed with subsequent operations
• Output NOT_CONFIGURED: immediately stop all operations, execute the initialization flow below

Initialization (When API Key Is Not Configured)

When check_config.py outputs NOT_CONFIGURED, reply to user with the following guidance:

Using Plume AI Image Service requires configuring an API Key first

Please follow these steps:

1. Visit Plume Platform to register an account
2. After logging in, get your API Key from "API Key" section
3. Tell me your API Key and I'll configure it for you

When user provides the API Key, execute:

python3 ~/.openclaw/skills/plume-image/scripts/setup_key.py <user-provided-key>
python3 ~/.openclaw/skills/plume-image/scripts/validate_key.py

• validate_key.py outputs VALID: inform user configuration is successful, they can type /restart in the chat input to restart
• validate_key.py outputs INVALID: prompt user to check if the key is correct

After successful configuration, user restarts OpenClaw, next time check_config.py will output CONFIGURED and normal usage can begin.

Supported Categories (Fixed Enum, Do Not Invent)

Style transfer (cartoon, Pixar, watercolor, etc.) always uses BananaPro + --prompt to describe the style. Do NOT invent new categories.

Image/Video Specifications

• Default: 2K, 9:16 (portrait)
• Resolution: 1K / 2K
• Aspect ratio: 21:9 / 16:9 / 4:3 / 3:2 / 1:1 / 9:16 / 3:4 / 2:3 / 5:4 / 4:5
• Only adjust aspect ratio based on keywords explicitly stated by the user. Do NOT infer from image content.

Unified Workflow

All tasks: create → cron register → immediately reply to user → end

Very important: absolutely do NOT use process_image.py poll, do NOT execute check after register.

Channel Detection

Group Delivery (Important)

All register commands must include --session-key, with your current full session key as the value. The script will automatically determine if it's a group and deliver to the correct target. You don't need to make any additional judgments.

Create Task

python3 ~/.openclaw/skills/plume-image/scripts/process_image.py create \
  --category <category> \
  --prompt "<English prompt>" \
  [--processing-mode text_to_image|image_to_image|text_to_video] \
  [--image-url <r2_url>] \
  [--first-frame-url <url>] \
  [--image-size 2K] \
  [--aspect-ratio 9:16]

Output format: JSON, must check success field

• {"success": true, "task_id": "xxx", ...} → Task created successfully, proceed to register
• {"success": false, "error": "PLUME_API_KEY not configured..."} → Stop immediately, prompt user to configure API Key
• {"success": false, "error": "..."} → Task creation failed, report error to user

Register Cron Polling

Choose parameters based on category:

# Feishu
python3 ~/.openclaw/skills/plume-image/scripts/poll_cron_feishu.py register \
  --task-id <id> --user-id "<open_id>" --channel feishu \
  --session-key "<your full session key>" \
  --interval <interval> --max-duration <max>

# QQ Bot (--user-id must contain qqbot:c2c: prefix, copy full value from context "delivery target")
python3 ~/.openclaw/skills/plume-image/scripts/poll_cron_qqbot.py register \
  --task-id <id> --channel qqbot --user-id "qqbot:c2c:XXXX" \
  --interval <interval> --max-duration <max>

# Telegram / Other
python3 ~/.openclaw/skills/plume-image/scripts/poll_cron_universal.py register \
  --task-id <id> --channel telegram --user-id "telegram:XXXX" \
  --session-key "<your full session key>" \
  --interval <interval> --max-duration <max>

Image Source (When No Attachment in Context)

Read last generation result:

cat ~/.openclaw/media/plume/last_result_<channel>.json  # Get result_url

Channel to filename mapping: feishu / qqbot / telegram / others use last_result.json

Upload user image to R2:

python3 ~/.openclaw/skills/plume-image/scripts/process_image.py transfer \
  --image-key "img_xxx"        # Feishu image_key
  # or
  --file "/path/to/image.jpg"  # Local file

Prohibited Actions

• Do NOT fabricate task_id (can only be obtained from create return value)
• Do NOT fabricate image URLs (can only use result_url or r2_url returned by transfer, domain must be pics.useplume.app)
• Do NOT invent categories (only the 7 values in the table above are allowed)
• Do NOT execute check after register
• Do NOT use curl/wget to download images
• Do NOT use /tmp directory

Reference Documentation

• Detailed workflow examples: references/workflows.md
• Category parameter reference: references/categories.md
• Error code reference: references/error-codes.md