ai-nano-banana-ima（ai 纳米香蕉 ima）

IMA Nano Banana Image Generator

Scope

This skill is for IMA Open API image generation with strict Nano Banana scope:

• Task types: text_to_image, image_to_image
• Allowed model IDs only:

- gemini-3.1-flash-image - gemini-3-pro-image

• Always execute through bundled script: scripts/ima_image_create.py

Out of scope:

• Video or non-image tasks
• Non-IMA providers
• Non-Nano-Banana model families (for example SeeDream, Midjourney)
• Handcrafted API requests (do not bypass script)

Quick Runbook (Authoritative)

If any later section conflicts with this runbook, follow this runbook.

1. Confirm request is in scope (IMA + Nano Banana image generation/editing).
2. Resolve task_type:

- No reference image -> text_to_image - With reference image/edit request -> image_to_image

1. Resolve model:

- Premium/best quality -> gemini-3-pro-image - Cheapest/budget -> gemini-3.1-flash-image + --size 512 - Otherwise -> gemini-3.1-flash-image

1. Resolve parameters:

- Size -> --size (512,1K,2K,4K) - Ratio -> --extra-params JSON (for example {"aspect_ratio":"16:9"})

1. If user asks 8K, explain unsupported and downgrade to 4K.
2. For image_to_image, require at least one input image.
3. For remote image URLs:

- Prefer https:// - If user gives http://, ask for https:// URL or local file

1. Endpoint policy is fixed:

- Main API: https://api.imastudio.com - Upload API: https://imapi.liveme.com - No CLI/env override for these domains in this skill.

1. Run only scripts/ima_image_create.py; do not call API endpoints manually.
2. Use messaging Step 0-4 flow. If message tool is unavailable, use normal replies with same content.
3. On success, prefer rendered media output; if media unsupported, return URL + model + elapsed/credit summary.

FAQ (For Ambiguous Inputs)

Q1) How to map intent to task_type?

Q2) How to map user wording to model?

Q3) How to set ratio and size?

8K is not supported; downgrade to 4K.

Q4) What placeholder substitutions are required?

• {baseDir} -> current skill root path
• {user_id} -> real user/session id string

User-Facing Messaging Protocol

Step 0: Acknowledge immediately

Use a short warm reply in user language, for example:

• 收到，马上开始生成。
• OK, generating now.

Step 1: Start notification

🎨 开始生成图片，请稍候…
• 模型：[Model Name]
• 预计耗时：[X~Y 秒]
• 消耗积分：[N pts]

Step 2: Progress notification

Progress format:

⏳ 正在生成中… [P]%
已等待 [elapsed]s，预计最长 [max]s

P = min(95, floor(elapsed / max * 100)) until success.

Step 3: Success notification

✅ 图片生成成功！
• 模型：[Model Name]
• 耗时：预计 [X~Y]s，实际 [actual]s
• 消耗积分：[N pts]
🔗 原始链接：{image_url}

Prefer media attachment; fallback to plain text message if media is not supported.

Step 4: Failure notification

❌ 图片生成失败
• 原因：[natural language reason]
• 建议：[retry strategy or model switch]
需要我帮你重试吗？

After Step 4, stop. Do not send duplicate completion messages.

Command Templates (Minimal)

# 1) List models
python3 {baseDir}/scripts/ima_image_create.py \
  --api-key "$IMA_API_KEY" \
  --task-type text_to_image \
  --list-models

# 2) text_to_image (default/premium/budget/ratio via params)
python3 {baseDir}/scripts/ima_image_create.py \
  --api-key "$IMA_API_KEY" \
  --task-type text_to_image \
  --model-id gemini-3.1-flash-image \
  --prompt "a cute puppy on grass" \
  --size 1K \
  --extra-params '{"aspect_ratio":"1:1"}' \
  --user-id {user_id} \
  --output-json
# Notes:
# - Premium: set --model-id gemini-3-pro-image
# - Cheapest: keep flash model and set --size 512

# 3) image_to_image with remote URL input
python3 {baseDir}/scripts/ima_image_create.py \
  --api-key "$IMA_API_KEY" \
  --task-type image_to_image \
  --model-id gemini-3.1-flash-image \
  --prompt "turn into oil painting" \
  --input-images "https://example.com/photo.jpg" \
  --user-id {user_id} \
  --output-json

# 4) image_to_image with local file input
python3 {baseDir}/scripts/ima_image_create.py \
  --api-key "$IMA_API_KEY" \
  --task-type image_to_image \
  --model-id gemini-3.1-flash-image \
  --prompt "turn into oil painting" \
  --input-images "./local-photo.jpg" \
  --user-id {user_id} \
  --output-json

Security And Data Handling

Network domains

Why two domains?

• api.imastudio.com: IMA's image generation API (handles task orchestration)
• imapi.liveme.com: IMA's media storage infrastructure (handles large file uploads)
• Both services are owned and operated by IMA Studio

Credential flow

Notes:

• Upload signing uses shared built-in credentials (same as ima-image-ai skill).
• No API key is sent to presigned upload hosts during binary upload.
• API domains are fixed in script and not user-overridable.
• Never print or persist raw API keys in chat or repo files.

Local persistence

Error Handling Playbook

Fallback messages:

• Chinese: 图片生成遇到问题，请稍后重试或换个模型试试。
• English: Image generation encountered an issue, please retry or switch model.

Quick Defaults

1. Default model: gemini-3.1-flash-image
2. Premium model: gemini-3-pro-image
3. Cheapest profile: flash model + --size 512
4. Max output: 4K
5. Recommended ratios: 1:1, 16:9, 9:16, 4:3, 3:4