IMA Studio — All-in-One AI Creation

IMA AI Creation

⚠️ 重要：模型 ID 参考

CRITICAL: When calling the script, you MUST use the exact model_id (second column), NOT the friendly model name. Do NOT infer model_id from the friendly name (e.g., ❌ nano-banana-pro is WRONG; ✅ gemini-3-pro-image is CORRECT).

Quick Reference Table:

图像模型 (Image Models)

视频模型 (Video Models)

音乐模型 (Music Models)

语音模型 (Speech/TTS Models)

How to get the correct model_id:

1. Check this table first
2. Use --list-models --task-type <type> to query available models
3. Refer to command examples in this SKILL.md

Example:

# ❌ WRONG: Inferring from friendly name
--model-id nano-banana-pro

# ✅ CORRECT: Using exact model_id from table
--model-id gemini-3-pro-image

⚠️ MANDATORY PRE-CHECK: Read Knowledge Base First!

If ima-knowledge-ai is not installed: Skip all "Read …" steps below; use only this SKILL's 📥 User Input Parsing (media type → task_type) and the Recommended Defaults / model tables for each media type.

BEFORE executing ANY multi-media generation task, you MUST:

1. Check for workflow complexity — Read ima-knowledge-ai/references/workflow-design.md if:

   • User mentions: "MV"、"宣传片"、"完整作品"、"配乐"、"soundtrack"
   • Task spans multiple media types (image + video, video + music, etc.)
   • Complex multi-step workflows that need task decomposition

2. Check for visual consistency needs — Read ima-knowledge-ai/references/visual-consistency.md if:

   • User mentions: "系列"、"多张"、"同一个"、"角色"、"续"、"series"、"same"
   • Task involves: multiple images/videos, character continuity, product shots
   • Second+ request about same subject (e.g., "旺财在游泳" after "生成旺财照片")

3. Check video modes — Read ima-knowledge-ai/references/video-modes.md if:

   • Any video generation task
   • Need to understand: image_to_video vs reference_image_to_video difference

4. Check model selection — Read ima-knowledge-ai/references/model-selection.md if:

   • Unsure which model to use
   • Need cost/quality trade-off guidance
   • User specifies budget or quality requirements

Why this matters:

• Multi-media workflows need proper task sequencing (e.g., video duration → matching music duration)
• AI generation defaults to 独立生成 each time — without reference images, results will be inconsistent
• Wrong video mode = wrong result (image_to_video ≠ reference_image_to_video)
• Model choice affects cost and quality significantly

Example multi-media workflow:

User: "帮我做个产品宣传MV，有背景音乐，主角是旺财小狗"

❌ Wrong: 
  1. Generate dog image (random look)
  2. Generate video (different dog)
  3. Generate music (unrelated)

✅ Right:
  1. Read workflow-design.md + visual-consistency.md
  2. Generate Master Reference: 旺财小狗图片
  3. Generate video shots using image_to_video with 旺财 as first frame
  4. Get video duration (e.g., 15s)
  5. Generate BGM with matching duration and mood

How to check:

# Step 0: Determine media type first (image / video / music / speech)
# From user request: "画"/"生成图"/"image" → image; "视频"/"video" → video; "音乐"/"歌"/"music"/"BGM" → music; "语音"/"朗读"/"TTS"/"speech" → speech
# Then choose task_type and model from the corresponding section (image: text_to_image/image_to_image; video: text_to_video/...; music: text_to_music; speech: text_to_speech)

# Step 1: Read knowledge base based on task type
if multi_media_workflow:
    read("~/.openclaw/skills/ima-knowledge-ai/references/workflow-design.md")

if "same subject" or "series" or "character":
    read("~/.openclaw/skills/ima-knowledge-ai/references/visual-consistency.md")

if video_generation:
    read("~/.openclaw/skills/ima-knowledge-ai/references/video-modes.md")

# Step 2: Execute with proper sequencing and reference images
# (see workflow-design.md for specific patterns)

No exceptions — for simple single-media requests, you can proceed directly. For complex multi-media workflows, read the knowledge base first.

📥 User Input Parsing (Media Type & Task Routing)

Purpose: So that any agent parses user intent consistently, first determine the media type from the user's request, then choose task_type and model.

1. User phrasing → media type (do this first)

If the request mixes media (e.g. "宣传片+配乐"), treat as multi-media workflow: read workflow-design.md, then plan image → video → music steps and use the correct task_type for each step.

2. Model and parameter parsing

• Image: For model name → model_id and size/aspect_ratio parsing, follow the same rules as in ima-image-ai skill (User Input Parsing section).

• Video: For task_type (t2v / i2v / first_last / reference), model alias → model_id, and duration/resolution/aspect_ratio, follow ima-video-ai skill (User Input Parsing section).

• Music: Suno (sonic) vs DouBao BGM/Song — infer from "BGM"/"背景音乐" → BGM; "带歌词"/"人声" → Suno or Song. Use model_id sonic, GenBGM, GenSong per "Recommended Defaults" and "Music Generation" tables below.

• Speech (TTS): Get model_id from GET /open/v1/product/list?category=text_to_speech or run script with --task-type text_to_speech --list-models. Map user intent to parameters using product form_config:

  User intent / phrasing	Parameter (if in form_config)	Notes
  女声 / 女声朗读 / female voice	voice_id / voice_type	Use value from form_config options
  男声 / 男声朗读 / male voice	voice_id / voice_type	Use value from form_config options
  语速快/慢 / speed up/slow	speed	e.g. 0.8–1.2
  音调 / pitch	pitch	If supported
  大声/小声 / volume	volume	If supported

  If the user does not specify, use form_config defaults. Pass extra params via --extra-params '{"speed":1.0}'. Only send parameters present in the product’s credit_rules/attributes or form_config (script reflection strips others on retry).

⚙️ How This Skill Works

For transparency: This skill uses a bundled Python script (scripts/ima_create.py) to call the IMA Open API. The script:

• Sends your prompt to two IMA-owned domains (see "Network Endpoints" below)
• Uses --user-id only locally as a key for storing your model preferences
• Returns image/video/music URLs when generation is complete

What gets sent to IMA servers:

• ✅ Your prompt/description (image/video/music)
• ✅ Model selection (SeeDream/Wan/Suno/etc.)
• ✅ Generation parameters (size, duration, style, etc.)
• ❌ NO API key in prompts (key is used for authentication only)
• ❌ NO user_id (it's only used locally)

What's stored locally:

• ~/.openclaw/memory/ima_prefs.json - Your model preferences (< 1 KB)
• ~/.openclaw/logs/ima_skills/ - Generation logs (auto-deleted after 7 days)

🌐 Network Endpoints Used

Key Points:

• Music tasks (text_to_music) and TTS tasks (text_to_speech) only use api.imastudio.com.
• Image/video tasks require imapi.liveme.com to obtain presigned URLs for uploading input images.
• Your API key is sent to both api.imastudio.com and imapi.liveme.com (both owned by IMA Studio).
• Verify network calls: tcpdump -i any -n 'host api.imastudio.com or host imapi.liveme.com'. See this document: 🌐 Network Endpoints Used and ⚠️ Credential Security Notice for full disclosure.

⚠️ Credential Security Notice

Your API key is sent to both IMA-owned domains:

1. Authorization: Bearer ima_xxx... → api.imastudio.com (main API)
2. Query param appUid=ima_xxx... → imapi.liveme.com (upload service)

Security best practices:

• 🧪 Use test keys for experiments: Generate a separate API key for testing.
• 🔍 Monitor usage: Check https://imastudio.com/dashboard for unauthorized activity.
• ⏱️ Rotate keys: Regenerate your API key periodically (monthly recommended).
• 📊 Review logs: Check ~/.openclaw/logs/ima_skills/ for unexpected API calls.

Why two domains? IMA Studio uses a microservices architecture:

• api.imastudio.com: Core AI generation API
• imapi.liveme.com: Specialized image/video upload service (shared infrastructure)

Both domains are operated by IMA Studio. The same API key grants access to both services.

Agent Execution (Internal Reference)

Note for users: You can review the script source at scripts/ima_create.py anytime.
The agent uses this script to simplify API calls. Music tasks use only api.imastudio.com, while image/video tasks also call imapi.liveme.com for file uploads (see "Network Endpoints" above).

Use the bundled script internally for all task types — it ensures correct parameter construction:

# ─── Image Generation ──────────────────────────────────────────────────────────

# Basic text-to-image (default model)
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type text_to_image \
  --model-id doubao-seedream-4.5 --prompt "a cute puppy on grass, photorealistic" \
  --user-id {user_id} --output-json

# Text-to-image with size override (Nano Banana2)
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type text_to_image \
  --model-id gemini-3.1-flash-image --prompt "city skyline at sunset, 4K" \
  --size 2k --user-id {user_id} --output-json

# Image-to-image with input URL
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type image_to_image \
  --model-id doubao-seedream-4.5 --prompt "turn into oil painting style" \
  --input-images https://example.com/photo.jpg --user-id {user_id} --output-json

# ─── Video Generation ──────────────────────────────────────────────────────────

# Basic text-to-video (default model, 5s 720P)
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type text_to_video \
  --model-id wan2.6-t2v --prompt "a puppy dancing happily, cinematic" \
  --user-id {user_id} --output-json

# Text-to-video with extra params (10s 1080P)
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type text_to_video \
  --model-id wan2.6-t2v --prompt "dramatic ocean waves, sunset" \
  --extra-params '{"duration":10,"resolution":"1080P","aspect_ratio":"16:9"}' \
  --user-id {user_id} --output-json

# Image-to-video (animate static image)
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type image_to_video \
  --model-id wan2.6-i2v --prompt "camera slowly zooms in, gentle movement" \
  --input-images https://example.com/photo.jpg --user-id {user_id} --output-json

# First-last frame video (two images)
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type first_last_frame_to_video \
  --model-id kling-video-o1 --prompt "smooth transition between frames" \
  --input-images https://example.com/frame1.jpg https://example.com/frame2.jpg \
  --user-id {user_id} --output-json

# ─── Music Generation ──────────────────────────────────────────────────────────

# Basic text-to-music (Suno default)
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type text_to_music \
  --model-id sonic --prompt "upbeat electronic music, 120 BPM, no vocals" \
  --user-id {user_id} --output-json

# Music with custom lyrics (Suno custom mode)
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type text_to_music \
  --model-id sonic --prompt "pop ballad, emotional" \
  --extra-params '{"custom_mode":true,"lyrics":"Your custom lyrics here...","vocal_gender":"female"}' \
  --user-id {user_id} --output-json

# Background music (DouBao BGM)
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type text_to_music \
  --model-id GenBGM --prompt "relaxing ambient music for meditation" \
  --user-id {user_id} --output-json

# ─── Text-to-Speech (TTS) ─────────────────────────────────────────────────────

# List TTS models first to get model_id, then generate speech
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type text_to_speech --list-models

# TTS: use model_id from list above (prompt = text to speak)
python3 {baseDir}/scripts/ima_create.py \
  --api-key $IMA_API_KEY --task-type text_to_speech \
  --model-id <model_id from list> --prompt "Text to be spoken here." \
  --user-id {user_id} --output-json

The script outputs JSON with url, model_name, credit — use these values in the UX protocol messages below. The script internals (product list query, parameter construction, polling) are invisible to users.

Overview

Call IMA Open API to create AI-generated content. All endpoints require an ima_* API key. The core flow is: query products → create task → poll until done.

🔒 Security & Transparency Policy

This skill is community-maintained and open for inspection.

✅ What Users CAN Do

Full transparency:

• ✅ Review all source code: Check scripts/ima_create.py and ima_logger.py anytime
• ✅ Verify network calls: Music tasks use api.imastudio.com only; image/video tasks also use imapi.liveme.com (see "Network Endpoints" section)
• ✅ Inspect local data: View ~/.openclaw/memory/ima_prefs.json and log files
• ✅ Control privacy: Delete preferences/logs anytime, or disable file writes (see below)

Configuration allowed:

• ✅ Set API key in environment or agent config:
  • Environment variable: export IMA_API_KEY=ima_your_key_here
  • OpenClaw/MCP config: Add IMA_API_KEY to agent's environment configuration
  • Get your key at: https://imastudio.com
• ✅ Use scoped/test keys: Test with limited API keys, rotate after testing
• ✅ Disable file writes: Make prefs/logs read-only or symlink to /dev/null

Data control:

• ✅ View stored data: cat ~/.openclaw/memory/ima_prefs.json
• ✅ Delete preferences: rm ~/.openclaw/memory/ima_prefs.json (resets to defaults)
• ✅ Delete logs: rm -rf ~/.openclaw/logs/ima_skills/ (auto-cleanup after 7 days anyway)

⚠️ Advanced Users: Fork & Modify

If you need to modify this skill for your use case:

1. Fork the repository (don't modify the original)
2. Update your fork with your changes
3. Test thoroughly with limited API keys
4. Document your changes for troubleshooting

Note: Modified skills may break API compatibility or introduce security issues. Official support only covers the unmodified version.

❌ What to AVOID (Security Risks)

Actions that could compromise security:

• ❌ Sharing API keys publicly or in skill files
• ❌ Modifying API endpoints to unknown servers
• ❌ Disabling SSL/TLS certificate verification
• ❌ Logging sensitive user data (prompts, IDs, etc.)
• ❌ Bypassing authentication or billing mechanisms

Why this matters:

1. API Compatibility: Skill logic aligns with IMA Open API schema
2. Security: Malicious modifications could leak credentials or bypass billing
3. Support: Modified skills may not be supported
4. Community: Breaking changes affect all users

📋 Privacy & Data Handling Summary

What this skill does with your data:

Privacy recommendations:

1. Use test/scoped API keys for initial testing
2. Note: --user-id is never sent to IMA servers - it's only used locally as a key for storing preferences in ~/.openclaw/memory/ima_prefs.json
3. Review source code at scripts/ima_create.py to verify network calls (search for create_task function)
4. Rotate API keys after testing or if compromised

Get your IMA API key: Visit https://imastudio.com to register and get started.

🔧 For Skill Maintainers Only

Version control:

• All changes must go through Git with proper version bumps (semver)
• CHANGELOG.md must document all changes
• Production deployments require code review

File checksums (optional):

# Verify skill integrity
sha256sum SKILL.md scripts/ima_create.py

If users report issues, verify file integrity first.

🧠 User Preference Memory (Image)

User preferences have highest priority when they exist. But preferences are only saved when users explicitly express model preferences — not from automatic model selection.

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

Single file, shared across all IMA skills:

{
  "user_{user_id}": {
    "text_to_image":  { "model_id": "doubao-seedream-4.5", "model_name": "SeeDream 4.5", "credit": 5,  "last_used": "2026-02-27T03:07:27Z" },
    "image_to_image": { "model_id": "doubao-seedream-4.5", "model_name": "SeeDream 4.5", "credit": 5,  "last_used": "2026-02-27T03:07:27Z" },
    "text_to_speech": { "model_id": "<from product list>", "model_name": "...", "credit": 2, "last_used": "..." }
  }
}

Model Selection Flow (Image Generation)

Step 1: Get knowledge-ai recommendation (if installed)

knowledge_recommended_model = read_ima_knowledge_ai()  # e.g., "SeeDream 4.5"

Step 2: Check user preference

user_pref = load_prefs().get(f"user_{user_id}", {}).get(task_type)  # e.g., {"model_id": "midjourney", ...}

Step 3: Decide which model to use

if user_pref exists:
    use_model = user_pref["model_id"]  # Highest priority
else:
    use_model = knowledge_recommended_model or fallback_default

Step 4: Check for mismatch (for later hint)

if user_pref exists and knowledge_recommended_model != user_pref["model_id"]:
    mismatch = True  # Will add hint in success message

When to Write (User Explicit Preference ONLY)

✅ Save preference when user explicitly specifies a model:

❌ Do NOT save when:

• Agent auto-selects from knowledge-ai → not user preference
• Agent uses fallback default → not user preference
• User says generic quality requests (see "Clear Preference" below) → clear preference instead

When to Clear (User Abandons Preference)

🗑️ Clear preference when user wants automatic selection:

Implementation:

del prefs[f"user_{user_id}"][task_type]
save_prefs(prefs)

⭐ Model Selection Priority (Image)

Selection flow:

1. User preference (if exists) → Highest priority, always respect
2. ima-knowledge-ai skill (if installed) → Professional recommendation based on task
3. Fallback defaults → Use table below (only if neither 1 nor 2 exists)

Important notes:

• User preference is only saved when user explicitly specifies a model (see "When to Write" above)
• Knowledge-ai is always consulted (even when user pref exists) to detect mismatches
• When mismatch detected → add gentle hint in success message (does NOT interrupt generation)

The defaults below are FALLBACK only. User preferences have highest priority, then knowledge-ai recommendations.

When using user preference for image generation, show a line like:

🎨 根据你的使用习惯，将用 [Model Name] 帮你生成…
• 模型：[Model Name]（你的常用模型）
• 预计耗时：[X ~ Y 秒]
• 消耗积分：[N pts]

Preference Change Confirmation

When user switches to a different model than their saved preference:

💡 你之前喜欢用 [Old Model]，这次换成了 [New Model]。
要把 [New Model] 设为以后的默认吗？
回复「是」保存 / 回复「否」仅本次使用

⭐ Recommended Defaults

These are fallback defaults — only used when no user preference exists.
Always default to the newest and most popular model. Do NOT default to the cheapest.

Premium options:

• Image: Nano Banana Pro — Highest quality with size control (1K/2K/4K), higher cost (10-18 pts for text_to_image, 10 pts for image_to_image)
• Video: Kling O1, Sora 2 Pro, Google Veo 3.1 — Premium quality with longer duration options

Quick selection guide (production as of 2026-02-27, sorted by popularity):

• Image (4 models available) → SeeDream 4.5 (5, default); artistic → Midjourney 🎨 (8-10); budget → Nano Banana2 (4, 512px); premium → Nano Banana Pro (10-18)
• 🔥 Video from text (most popular) → Wan 2.6 (25, balanced); premium → Hailuo 2.3 (38); budget → Vidu Q2 (5)
• 🔥 Video from image (most popular) → Wan 2.6 (25)
• Music → Suno (25); DouBao BGM/Song (30 each)
• Cheapest → Nano Banana2 512px (4) for image; Vidu Q2 (5) for video

Selection guide by use case:

Image Generation:

• General image generation → SeeDream 4.5 (5pts)
• Custom aspect ratio (16:9, 9:16, 4:3, etc.) → SeeDream 4.5 🌟 or Nano Banana Pro/2 🆕 (native support)
• Budget-conscious / fast generation → Nano Banana2 (4pts)
• Highest quality with size control (1K/2K/4K) → Nano Banana Pro (text_to_image: 10-18pts, image_to_image: 10pts)
• Artistic/creative styles, illustrations, paintings → Midjourney 🎨 (8-10pts)
• Style transfer / image editing → SeeDream 4.5 (5pts) or Midjourney 🎨 (artistic)

Video Generation:

• General video generation → Wan 2.6 (25pts, most popular)
• Premium cinematic quality → Google Veo 3.1 (70-330pts) or Sora 2 Pro (122+pts)
• Budget video → Vidu Q2 (5pts) or Hailuo 2.0 (5pts)
• With audio support → Kling O1 (48+pts) or Google Veo 3.1 (70+pts)
• First/last frame animation → Kling O1 (48+pts)
• Reference image consistency → Kling O1 (48+pts) or Google Veo 3.1 (70+pts)

Music Generation:

• Custom song with lyrics, vocals, style → Suno sonic-v5 (25pts, default, ~2min)
  • Full control: custom_mode, lyrics, vocal_gender, tags, negative_tags
  • Best for: complete songs, vocal tracks, artistic compositions
• Background music / ambient loop → DouBao BGM (30pts, ~30s)
  • Simplified: prompt-only, no advanced parameters
  • Best for: video backgrounds, ambient music, short loops
• Simple song generation → DouBao Song (30pts, ~30s)
  • Simplified: prompt-only
  • Best for: quick song generation, structured vocal compositions
• User explicitly asks for cheapest → DouBao BGM/Song (6pts each) — only if explicitly requested

Speech (TTS) Generation:

• Text-to-speech / 语音合成 / 朗读 → text_to_speech. Always query GET /open/v1/product/list?category=text_to_speech (or --list-models) to get current model_id and credit. No fixed default; use first available or user preference. Voice/speed/format parameters: see "Model and parameter parsing" (TTS table) and "Speech (TTS) — text_to_speech" in this document.

⚠️ Technical Note for Suno:

model_version inside parameters.parameters (e.g., "sonic-v5") is different from the outer model_version field (which is "sonic"). Always set both correctly when creating Suno tasks.

⚠️ Production Image Models (4 available):

• SeeDream 4.5 (doubao-seedream-4.5) — 5 pts, default
• Midjourney 🎨 (midjourney) — 8/10 pts for 480p/720p, artistic styles
• Nano Banana2 (gemini-3.1-flash-image) — 4/6/10/13 pts for 512px/1K/2K/4K
• Nano Banana Pro (gemini-3-pro-image) — 10/10/18 pts for 1K/2K/4K

All other image models mentioned in older documentation are no longer available in production.

🌟 Parameter Support Notes (All Task Types):

Image Models (text_to_image / image_to_image)

🆕 MAJOR UPDATE: Nano Banana series now has NATIVE aspect_ratio support!

• Nano Banana Pro: ✅ Supports aspect_ratio (1:1, 16:9, 9:16, 4:3, 3:4) NATIVELY
• Nano Banana2: ✅ Supports aspect_ratio (1:1, 16:9, 9:16, 4:3, 3:4) NATIVELY
• SeeDream 4.5: ✅ Supports 8 ratios via virtual params (1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2, 21:9)
• Midjourney: ❌ 1:1 only (fixed 1024x1024)

aspect_ratio support details:

• ✅ aspect_ratio:
  • SeeDream 4.5: ✅ Supports 8 ratios via virtual params (1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2, 21:9)
  • Nano Banana2: ✅ Native support for 5 ratios (1:1, 16:9, 9:16, 4:3, 3:4)
  • Nano Banana Pro: ✅ Native support for 5 ratios (1:1, 16:9, 9:16, 4:3, 3:4)
  • Midjourney: ❌ 1:1 only (fixed 1024x1024)
• ✅ size:
  • Nano Banana2: 512px, 1K, 2K, 4K (via different attribute_ids, 4-13 pts)
  • Nano Banana Pro: 1K, 2K, 4K (via different attribute_ids, 10-18 pts)
  • SeeDream 4.5: Adaptive default (5 pts)
  • Midjourney: 480p/720p (via attribute_id, 8/10 pts)
• ❌ 8K: No model supports 8K (max is 4K via Nano Banana Pro)
• ❌ Non-standard aspect ratios (7:3, 8:5, etc.): Not supported. Use closest supported ratio or video models.
• ✅ n: Multiple outputs supported (1-4), credit × n

When user requests unsupported combinations for images:

• Midjourney + aspect_ratio (16:9, etc.): Recommend SeeDream 4.5 or Nano Banana series instead

  ❌ Midjourney 暂不支持自定义 aspect_ratio（仅支持 1024x1024 方形）
  
  ✅ 推荐方案：
    1. SeeDream 4.5（支持虚拟参数 aspect_ratio）
       • 支持比例：1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2, 21:9
       • 成本：5 积分（性价比最佳）
    2. Nano Banana Pro/2（原生支持 aspect_ratio）
       • 支持比例：1:1, 16:9, 9:16, 4:3, 3:4
       • 成本：4-18 积分（按尺寸）
  
  需要我帮你用 SeeDream 4.5 生成吗？
  

• Any model + 8K: Inform user no model supports 8K, max is 4K (Nano Banana Pro)
• Any model + non-standard ratio (7:3, 8:5, etc.): Non-standard ratio, not supported. Suggest closest supported ratio (e.g., 21:9 for ultra-wide, 2:3 for portrait)

Video Models (text_to_video / image_to_video / first_last_frame / reference_image)

• ✅ resolution: 540P, 720P, 1080P, 2K, 4K (model-dependent, higher res = higher cost)
• ✅ aspect_ratio: 16:9, 9:16, 1:1, 4:3 (model-dependent, check form_config)
• ✅ duration: 4s, 5s, 10s, 15s (model-dependent, longer = higher cost)
• ⚠️ generate_audio: Supported by Veo 3.1, Kling O1, Hailuo (check form_config)
• ✅ prompt_extend: AI-powered prompt enhancement (most models support)
• ✅ negative_prompt: Content exclusion (most models support)
• ✅ shot_type: Single/multi-shot control (model-dependent)
• ✅ seed: Reproducibility control (most models support, -1 = random)
• ✅ n: Multiple outputs (1-4), credit × n

🆕 Special Case: Pixverse Model Parameter (v1.0.7+)

Auto-Inference Logic for Pixverse V5.5/V5/V4:

• Problem: Pixverse V5.5, V5, V4 lack model field in form_config from Product List API
• Backend Requirement: Backend requires model parameter (e.g., "v5.5", "v5", "v4")
• Auto-Fix: System automatically extracts version from model_name and injects it
  • Example: model_name: "Pixverse V5.5" → auto-inject model: "v5.5"
  • Example: model_name: "Pixverse V4" → auto-inject model: "v4"
• Note: V4.5 and V3.5 include model in form_config (no auto-inference needed)
• Relevant Task Types: All video modes (text_to_video, image_to_video, first_last_frame_to_video, reference_image_to_video)

Error Prevention:

• Without auto-inference: err_code=400017 err_msg=Invalid value for model
• With auto-inference (v1.0.7+): Pixverse V5.5/V5/V4 work seamlessly ✅

Music Models (text_to_music)

Suno sonic-v5 (Full-Featured):

• ✅ custom_mode: Suno only (enables vocal_gender, lyrics, tags support)
• ✅ vocal_gender: Suno only (male/female/mixed, requires custom_mode=True)
• ✅ lyrics: Suno only (custom lyrics support, requires custom_mode=True)
• ✅ make_instrumental: Suno only (force instrumental, no vocals)
• ✅ auto_lyrics: Suno only (AI-generated lyrics)
• ✅ tags: Suno only (genre/style tags)
• ✅ negative_tags: Suno only (exclude unwanted styles)
• ✅ title: Suno only (song title)
• ❌ duration: Fixed-length output (DouBao ~30s, Suno ~2min, not user-controllable)
• ✅ n: Multiple outputs supported (1-2), credit × n

DouBao BGM/Song (Simplified):

• ✅ prompt: Text description only
• ❌ No advanced parameters (no custom_mode, lyrics, vocal control)
• ❌ duration: Fixed ~30s output

🎵 Suno Prompt Writing Guide (for gpt_description_prompt):

When using Suno, structure your prompt with these elements:

1. Genre/Style:

   • Examples: "lo-fi hip hop", "orchestral cinematic", "upbeat pop", "dark ambient", "indie folk", "electronic dance"

2. Tempo/BPM:

   • Examples: "80 BPM", "fast tempo", "slow ballad", "moderate pace 110 BPM"

3. Vocals Control:

   • No vocals: "no vocals" → set make_instrumental=true
   • With vocals: "female vocals" → set vocal_gender="female"
   • Male vocals: "male vocals" → set vocal_gender="male"
   • Mixed: Set vocal_gender="mixed"

4. Mood/Emotion:

   • Examples: "happy and energetic", "melancholic", "tense and dramatic", "peaceful and calming"

5. Negative Tags (exclude styles):

   • Use negative_tags: "heavy metal, distortion, screaming" to exclude unwanted elements

6. Duration Hint:

   • Examples: "60 seconds", "30 second loop", "2 minute track"
   • Note: Suno typically generates ~2min, not strictly controllable

Example Suno prompts:

"upbeat lo-fi hip hop, 90 BPM, no vocals, relaxed and chill"
→ Set: make_instrumental=true

"emotional pop ballad, slow tempo, female vocals, melancholic"
→ Set: vocal_gender="female"

"orchestral cinematic trailer music, epic and dramatic, 120 BPM, no vocals"
→ Set: make_instrumental=true, tags="orchestral,cinematic,epic"

"acoustic indie folk, gentle guitar, male vocals, warm and nostalgic"
→ Set: vocal_gender="male", tags="acoustic,indie,folk"

⚠️ Technical Note for Suno:

model_version inside parameters.parameters (e.g., "sonic-v5") is different from the outer model_version field (which is "sonic"). Always set both correctly.

Common Parameter Patterns

• n (batch generation): Supported by ALL models. Cost = base_credit × n. Creates n independent resources.
• seed: Supported by most models (-1 = random, >0 = reproducible results)
• prompt_extend: AI-powered prompt enhancement (video models only)

Decision Tree: When User Requests Unsupported Features

User asks for custom aspect ratio image (e.g. "7:3 landscape")
  → ❌ Image models don't support custom ratios
  → ✅ Solution: "图片模型不支持自定义比例。建议用视频模型(Wan 2.6 t2v)生成16:9视频，然后截取首帧作为图片。"

User asks for 8K image
  → ❌ No model supports 8K
  → ✅ Solution: "当前最高支持4K分辨率(Nano Banana Pro，18积分)。要使用吗？"

User asks for video with audio
  → Check model: Veo 3.1 / Kling O1 / Hailuo have generate_audio
  → ✅ Solution: "Veo 3.1 和 Kling O1 支持音频生成(需在参数中设置 generate_audio=True)。要用哪个？"

User asks for long music (e.g. "5 minute track")
  → ❌ Duration not user-controllable
  → ✅ Solution: "Suno 生成约2分钟音乐。需要更长时长可以生成多段后拼接。"

User asks for 30s video
  → Check model: Most models max 15s
  → ✅ Solution: "当前最长15秒。可选模型：Wan 2.6(15s, 75积分), Kling O1(10s, 96积分)。"

When user requests unsupported combinations:

• Video + audio (unsupported model) → "该模型不支持音频。建议用 Veo 3.1 或 Kling O1 (支持 generate_audio 参数)"
• Music + custom duration → "音乐时长由模型固定(Suno约2分钟,DouBao约30秒),无法自定义"
• Video duration > 15s → "当前最长15秒。可选模型：Wan 2.6(15s, 75积分), Kling O1(10s, 96积分)"

Note: Image-specific unsupported combinations (Midjourney + aspect_ratio, 8K, non-standard ratios) are documented in the "Image Models" section above.

🧠 User Preference Memory (Video)

User preferences have highest priority when they exist. But preferences are only saved when users explicitly express model preferences — not from automatic model selection.

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

{
  "user_{user_id}": {
    "text_to_video":              { "model_id": "wan2.6-t2v",      "model_name": "Wan 2.6",  "credit": 25, "last_used": "..." },
    "image_to_video":             { "model_id": "wan2.6-i2v",      "model_name": "Wan 2.6",  "credit": 25, "last_used": "..." },
    "first_last_frame_to_video":  { "model_id": "kling-video-o1", "model_name": "Kling O1", "credit": 48, "last_used": "..." },
    "reference_image_to_video":   { "model_id": "kling-video-o1", "model_name": "Kling O1", "credit": 48, "last_used": "..." }
  }
}

Model Selection Flow (Video Generation)

Step 1: Get knowledge-ai recommendation (if installed)

knowledge_recommended_model = read_ima_knowledge_ai()  # e.g., "Wan 2.6"

Step 2: Check user preference

user_pref = load_prefs().get(f"user_{user_id}", {}).get(task_type)  # e.g., {"model_id": "kling-video-o1", ...}

Step 3: Decide which model to use

if user_pref exists:
    use_model = user_pref["model_id"]  # Highest priority
else:
    use_model = knowledge_recommended_model or fallback_default

Step 4: Check for mismatch (for later hint)

if user_pref exists and knowledge_recommended_model != user_pref["model_id"]:
    mismatch = True  # Will add hint in success message

When to Write (User Explicit Preference ONLY)

✅ Save preference when user explicitly specifies a model:

❌ Do NOT save when:

• Agent auto-selects from knowledge-ai → not user preference
• Agent uses fallback default → not user preference
• User says generic quality requests (see "Clear Preference" below) → clear preference instead

When to Clear (User Abandons Preference)

🗑️ Clear preference when user wants automatic selection:

Implementation:

d

…(truncated)