IMA Studio

IMA AI Creation

⚙️ 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)
• See SECURITY.md for complete privacy policy

🌐 Network Endpoints Used

Key Points:

• Music tasks (text_to_music) 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 SECURITY.md).

⚠️ 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

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)
• ✅ Review security: See SECURITY.md for complete privacy policy

⚠️ 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

如果你需要定制功能，请：

1. Fork 这个 Skill 创建私有版本（不保证兼容性）
2. 或者联系 IMA 技术支持申请企业定制

### 🔧 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):**
```bash
# Verify skill integrity
sha256sum SKILL.md scripts/ima_create.py

If users report issues, verify file integrity first.

🧠 User Preference Memory

User preferences override recommended defaults across ALL task types.
If a user has generated before, use their preferred model — not the system default.

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_video":             { "model_id": "wan2.6-t2v",           "model_name": "Wan 2.6",         "credit": 25, "last_used": "2026-02-27T10:00:00Z" },
    "image_to_video":            { "model_id": "wan2.6-i2v",          "model_name": "Wan 2.6",         "credit": 25, "last_used": "2026-02-27T10:00:00Z" },
    "first_last_frame_to_video": { "model_id": "kling-video-o1",      "model_name": "Kling O1",        "credit": 48, "last_used": "2026-02-26T08:00:00Z" },
    "reference_image_to_video":  { "model_id": "kling-video-o1",      "model_name": "Kling O1",        "credit": 48, "last_used": "2026-02-26T08:00:00Z" },
    "text_to_music":             { "model_id": "sonic",               "model_name": "Suno",            "credit": 25, "last_used": "2026-02-26T06:00:00Z" }
  }
}

If the file or key doesn't exist, fall back to the ⭐ Recommended Defaults below.

Model Selection Priority (Strict Order)

1. User explicitly specifies a model in this message
      → use it, save as new preference, confirm if different from old preference
2. User has a saved preference for this task type
      → use it, mention "根据你的使用习惯"
3. No preference exists
      → use ⭐ Recommended Default, save after success

When to Read (Before Every Generation)

import json, os

prefs_path = os.path.expanduser("~/.openclaw/memory/ima_prefs.json")
try:
    with open(prefs_path) as f:
        prefs = json.load(f)
    user_pref = prefs.get(f"user_{user_id}", {}).get(task_type)
except (FileNotFoundError, json.JSONDecodeError):
    user_pref = None

if user_pref:
    model_id   = user_pref["model_id"]
    model_name = user_pref["model_name"]
    credit     = user_pref["credit"]
    source     = "preference"   # pre-generation message: "根据你的使用习惯"
else:
    model_id, model_name, credit = RECOMMENDED_DEFAULTS[task_type]
    source = "default"

When to Write (After Every Successful Generation)

os.makedirs(os.path.dirname(prefs_path), exist_ok=True)
try:
    with open(prefs_path) as f:
        prefs = json.load(f)
except (FileNotFoundError, json.JSONDecodeError):
    prefs = {}

from datetime import datetime, timezone
prefs.setdefault(f"user_{user_id}", {})[task_type] = {
    "model_id":   model_id,
    "model_name": model_name,
    "credit":     credit,
    "last_used":  datetime.now(timezone.utc).isoformat(),
}
with open(prefs_path, "w") as f:
    json.dump(prefs, f, ensure_ascii=False, indent=2)

When to Update (User Explicitly Changes Model)

Pre-Generation Notification (with preference)

When using a saved preference, mention it naturally:

🎨 根据你的使用习惯，将用 [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.

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

• Image (3 models available) → SeeDream 4.5 (5, default); 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

⚠️ Production Image Models (3 available):

• SeeDream 4.5 (doubao-seedream-4.5) — 5 pts, default
• 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)

• ❌ aspect_ratio: NOT supported by any production image model (all produce 1:1 or fixed aspect ratio only)
• ✅ 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 only (no size control, 5 pts)
• ❌ 8K: No model supports 8K (max is 4K via Nano Banana Pro)
• ❌ Custom aspect ratios (7:3, 4:5, etc.): Not supported. Use video models as workaround.
• ✅ n: Multiple outputs supported (1-4), credit × n

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

Music Models (text_to_music)

• ✅ custom_mode: Suno only (enables vocal_gender, lyrics support)
• ✅ vocal_gender: Suno only (male/female/mixed, requires custom_mode=True)
• ✅ lyrics: Suno only (custom lyrics support, requires custom_mode=True)
• ❌ duration: Fixed-length output (DouBao ~30s, Suno ~2min, not user-controllable)
• ✅ n: Multiple outputs supported (1-2), credit × n

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:

• Any image model + custom aspect_ratio → "不支持自定义比例,建议用视频模型(Wan 2.6)生成后截取首帧"
• Any model + 8K → "最高支持4K (Nano Banana Pro, 18 pts)"
• Image model + 7:3 → "图片模型不支持,建议用 Wan 2.6 视频模型(支持16:9/9:16)生成后截帧"
• Video + audio (unsupported model) → "该模型不支持音频。建议用 Veo 3.1 或 Kling O1 (支持 generate_audio 参数)"
• Music + custom duration → "音乐时长由模型固定(Suno约2分钟,DouBao约30秒),无法自定义"

💬 User Experience Protocol (IM / Feishu / Discord)

This skill runs inside IM platforms (Feishu, Discord via OpenClaw).
Generation takes 10 seconds (music) up to 6 minutes (video). Never let users wait in silence.
Always follow all 4 steps below, every single time.

🚫 Never Say to Users

The following are internal implementation details. Never mention them in any user-facing message, under any circumstances:

User messages must only contain: model name, estimated/actual time, credits consumed, result URL, and natural language status updates.

Estimated Generation Time (All Task Types)

estimated_max_seconds = upper bound of the range (e.g. 60 for SeeDream 4.5, 40 for Nano Banana2, 120 for Nano Banana Pro, 180 for Kling 2.6, 360 for Kling O1).

Step 1 — Pre-Generation Notification

Before calling the create API, immediately send:

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

Emoji by content type:

• 图片 → 🎨
• 视频 → 🎬（加注:视频生成需要较长时间，我会定时汇报进度）
• 音乐 → 🎵

Cost transparency (new requirement):

• Always show credit cost with model tier context
• For expensive models (>50 pts), offer cheaper alternative proactively
• Examples:
  • Balanced (default): "使用 Wan 2.6（25 积分，最新 Wan）"
  • Premium (user explicit): "使用高端模型 Kling O1（48-120 积分），质量最佳"
  • Premium (auto-selected): "使用 Wan 2.6（25 积分）。若需更高质量可选 Kling O1（48 积分起）"
  • Budget (user asked): "使用 Vidu Q2（5 积分，最省钱）"

Adapt language to match the user (Chinese / English). For video, always add a note that it takes longer. For expensive models, always mention cheaper alternatives unless user explicitly requested premium.

Step 2 — Progress Updates

Poll the task detail API every [Poll Every] seconds per the table.
Send a progress update every [Send Progress Every] seconds.

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

Progress formula:

P = min(95, floor(elapsed_seconds / estimated_max_seconds * 100))

• Cap at 95% — never reach 100% until the API confirms success
• If elapsed > estimated_max: freeze at 95%, append 「快了，稍等一下…」
• For video with max=360s: at 120s → 33%, at 250s → 69%, at 400s → 95% (frozen)

Step 3 — Success Notification

When task status = success, send:

✅ [内容类型]生成成功！
• 模型：[Model Name]
• 耗时：预计 [X~Y]s，实际 [actual]s
• 消耗积分：[N pts]

[结果链接]

Step 4 — Failure Notification

When task status = failed or any API/network error, send:

❌ [内容类型]生成失败
• 原因：[natural_language_error_message]
• 建议改用：
  - [Alt Model 1]（[特点]，[N pts]）
  - [Alt Model 2]（[特点]，[N pts]）

需要我帮你用其他模型重试吗？

⚠️ CRITICAL: Error Message Translation

NEVER show technical error messages to users. Always translate API errors into natural language:

Generic fallback (when error is unknown):

• Chinese: 生成过程遇到问题，请稍后重试或换个模型试试
• English: Generation encountered an issue, please try again or use another model

Best Practices:

1. Focus on user action: Tell users what to do next, not what went wrong technically
2. Be reassuring: Use phrases like "建议换个模型试试" instead of "失败了"
3. Avoid blame: Never say "你的提示词有问题" → say "提示词需要调整一下"
4. Provide alternatives: Always suggest 1-2 alternative models in the failure message

Failure fallback by task type:

Supported Models at a Glance

Source: production GET /open/v1/product/list (2026-02-27). Model count reduced significantly. Always query product list API at runtime.

Image Generation (3 models each)

Nano Banana2 size options: 512px (4pts), 1K (6pts), 2K (10pts), 4K (13pts)
Nano Banana Pro size options: 1K (10pts), 2K (10pts), 4K (18pts for t2i / 10pts for i2i)

❌ Removed: SeeDream 3.0/4.0, Nano Banana (gemini-2.5), GPT Image 1.0/1.5, Wan 2.6 t2i/i2i, Midjourney, Imagen 4, SeedEdit 3.0

Video Generation

❌ Removed video models: Vidu Q2 Turbo (viduq2-turbo), Wan 2.5/2.2 Plus, Kling 1.6/2.1/2.5, Sora 2 (non-Pro), Veo 3.0/3.1 Fast, SeeDance 1.0, Vidu Q1, Hailuo 2.3 Fast | text_to_video | SeeDance 1.5 Pro / 1.0 Pro | doubao-seedance-1.5-pro / doubao-seedance-1.0-pro | 16 / 15 pts | | text_to_video | Sora 2 Pro / Sora 2 | sora-2-pro / sora-2 | 120 / 35 pts | | text_to_video | Kling O1 / 2.6 / 2.5 Turbo / 1.6 | kling-video-o1 / kling-v2-6 / kling-v2-5-turbo / kling-v1-6 | 48 / 80 / 24 / 32 pts | | text_to_video | Google Veo 3.1 Fast / 3.1 / 3.0 | veo-3.1-fast-generate-preview / veo-3.1-generate-preview / veo-3.0-generate-preview | 55 / 140 / 280 pts | | text_to_video | Pixverse V3.5–V5.5 | pixverse | 12 pts | | image_to_video | Wan 2.6 / 2.6 Flash / 2.5 / 2.2 Plus | wan2.6-i2v / wan2.6-i2v-flash / wan2.5-i2v-preview / wan2.2-i2v-plus | 25 / 12 / 12 / 10 pts | | image_to_video | Kling 2.1 Master | kling-v2-1-master | 150 pts | | first_last_frame_to_video | Kling O1 | kling-video-o1 | 70 pts | | reference_image_to_video | Kling O1 / Vidu Q2 / Q1 | kling-video-o1 / viduq2 / viduq1 | 48 / 10 / 25 pts |

Music Generation

Always call GET /open/v1/product/list?category=<type> first to get the live attribute_id and form_config defaults required for task creation.

There are two equivalent route systems serving the same backend logic:

This skill documents the /open/v1/ Open API. All business logic (credit validation, N-flattening, risk control) runs identically on both paths.

Environment

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

Required/recommended headers for all /open/v1/ endpoints:

Authorization: Bearer ima_your_api_key_here
x-app-source: ima_skills
x_app_language: en

📤 When to Upload Images (Quick Reference)

The IMA Open API does NOT accept raw bytes or base64 images. All image inputs must be public HTTPS URLs.

Upload flow:

1. User provides local file path or bytes → call prepare_image_url() (see section below)
2. User provides HTTPS URL → use directly, no upload needed
3. Use the returned CDN URL (fdl) as the value for input_images / src_img_url

Example workflow (image_to_image):

# User provides local file
image_url = prepare_image_url("/path/to/photo.jpg", api_key)
# → Returns: https://ima-ga.esxscloud.com/webAgent/privite/2026/02/27/..._uuid.jpeg

# Then create task with this URL
create_task(
    task_type="image_to_image",
    input_images=[image_url],  # Use uploaded URL
    prompt="turn into oil painting"
)

⚠️ MANDATORY: Always Query Product List First

CRITICAL: You MUST call /open/v1/product/list BEFORE creating any task.
The attribute_id field is REQUIRED in the create request. If it is 0 or missing, you get:
"Invalid product attribute" → "Insufficient points" → task fails completely.
NEVER construct a create request from the model table alone. Always fetch the product first.

How to get attribute_id (all task types)

# Query product list with the correct category
GET /open/v1/product/list?app=ima&platform=web&category=<task_type>
# task_type: text_to_image | image_to_image | text_to_video | image_to_video |
#            first_last_frame_to_video | reference_image_to_video | text_to_music

# Walk the V2 tree to find your target model (type=3 leaf nodes only)
for group in response["data"]:
    for version in group.get("children", []):
        if version["type"] == "3" and version["model_id"] == target_model_id:
            attribute_id  = version["credit_rules"][0]["attribute_id"]
            credit        = version["credit_rules"][0]["points"]
            model_version = version["id"]    # = version_id / model_version
            model_name    = version["name"]
            form_defaults = {f["field"]: f["value"] for f in version["form_config"]}
            break

Quick Reference: Known attribute_ids

Pre-queried values for convenience. Always call the product list at runtime for accuracy.

⚠️ Production warning: attribute_id and credit values change frequently in production. Always call /open/v1/product/list at runtime; above table is pre-queried reference only (2026-02-27).

Common Mistakes (and resulting errors)

⚠️ Critical for Google Veo 3.1 and multi-rule models:

Models like Google Veo 3.1 have multiple credit_rules, each with a different attribute_id for different parameter combinations:

• 720p + 4s + optimized → attribute_id A
• 720p + 8s + optimized → attribute_id B
• 4K + 4s + high → attribute_id C

The script automatically selects the correct attribute_id by matching your parameters (duration, resolution, compression_quality, generate_audio) against each

…(truncated)