IMA AI Image & Photo Generator

⚠️ MANDATORY: You MUST read("SKILL-DETAIL.md") (full file — do NOT pass limit parameter) before your first image generation call. It contains the full API payload structure, error translation tables, upload flow, UX protocol, and FAQ that this summary omits. Skipping it causes parameter errors and poor user experience.

Model ID Reference (CRITICAL)

Use exact model_id. Do NOT infer from friendly names.

Aliases: 可梦/SeeDream → doubao-seedream-4.5 · MJ/Midjourney → midjourney · 香蕉/Banana → gemini-3.1-flash-image · 香蕉Pro → gemini-3-pro-image

Task Types

Visual Consistency (IMPORTANT)

For "same character" / "series" / "same product" across multiple images:

• Do NOT use text_to_image (produces different-looking results each time)
• Use image_to_image with previous result as reference
• Read ima-knowledge-ai/references/visual-consistency.md if available

Knowledge Base (if ima-knowledge-ai installed)

Read before generating: visual-consistency.md (character/product continuity), model-selection.md (cost/quality), workflow-design.md (multi-step projects).

Parameter Support

If user asks for custom aspect ratio with Midjourney → recommend SeeDream 4.5 or Nano Banana. No model supports 8K (max 4K).

Default Models

Model Selection Priority

1. User preference (if explicitly stated) → highest priority
2. ima-knowledge-ai recommendation (if installed)
3. Fallback defaults above

Script Usage

# AI image generator — text to image (poster, thumbnail, social media graphic)
python3 {baseDir}/scripts/ima_image_create.py \
  --api-key $IMA_API_KEY --task-type text_to_image \
  --model-id doubao-seedream-4.5 --prompt "product photo for social media" \
  --user-id {user_id} --output-json

# AI photo generator — image to image (product photo editing, logo refinement)
python3 {baseDir}/scripts/ima_image_create.py \
  --api-key $IMA_API_KEY --task-type image_to_image \
  --model-id doubao-seedream-4.5 --prompt "enhance and refine" \
  --input-images https://example.com/photo.jpg \
  --user-id {user_id} --output-json

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

Sending Results to User

# ✅ CORRECT: Use remote URL directly for inline image display
message(action="send", media=image_url, caption="✅ 图片生成成功！\n• 模型：[Name]\n• 耗时：[X]s\n• 积分：[N pts]\n🔗 原始链接：[url]")

# ❌ WRONG: Never download to local file

UX Protocol (Brief)

1. Acknowledge: Short reply ("好的！来帮你画 🎨")
2. Pre-gen: Model, time, cost via message tool
3. Progress: Every 15-30s: "⏳ [P]%" (cap 95%)
4. Success: Send media=url + include link in caption
5. Failure: Natural language + suggest alternatives
6. Done: No further action

Never expose: script names, API endpoints, attribute_id, technical params.

User Preferences

Storage: ~/.openclaw/memory/ima_prefs.json

• Save on explicit: "用XXX" / "默认用XXX" / "always use XXX"
• Clear on: "推荐一个" / "自动选择" / "用最好的"
• Never save auto-selected models

Core Flow

1. GET /open/v1/product/list?category= → attribute_id, credit, form_config
2. [image_to_image only] Upload local files → get CDN URL
3. POST /open/v1/tasks/create → task_id
4. POST /open/v1/tasks/detail → poll until resource_status==1

MANDATORY: Always query product list first. Missing attribute_id → task fails.

Environment

Base URL: https://api.imastudio.com

Headers: Authorization: Bearer $IMA_API_KEY · x-app-source: ima_skills · x_app_language: en

⚠️ REMINDER: read("SKILL-DETAIL.md") (full file, no limit) is required before generating images. This summary covers model selection and routing — SKILL-DETAIL.md has complete API payloads, error handling, upload flow, parameter details, aspect ratio FAQ, and UX protocol needed for correct execution.