IMA Studio Video Generation

IMA Video AI Creation

⚙️ How This Skill Works

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

• Sends your prompt to IMA's servers (two domains, see below)
• Uses --user-id only locally as a key for storing your model preferences
• Returns a video URL when generation is complete

🌐 Network Endpoints Used

This skill connects to two domains owned by IMA Studio for complete functionality:

Why two domains?

• api.imastudio.com: IMA's video 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

Privacy implications:

• Your IMA API key is sent to both domains for authentication
• Image files are uploaded to imapi.liveme.com to obtain CDN URLs (for image_to_video, first_last_frame_to_video, reference_image_to_video tasks)
• Video generation happens on api.imastudio.com using the CDN URLs
• For text_to_video tasks (no image input), only api.imastudio.com is contacted

Security verification:

# List all network endpoints in the code:
grep -n "https://" scripts/ima_video_create.py

# Expected output:
# 57: DEFAULT_BASE_URL = "https://api.imastudio.com"
# 58: DEFAULT_IM_BASE_URL = "https://imapi.liveme.com"

If you're concerned about the two-domain architecture:

1. Review IMA Studio's privacy policy at https://imastudio.com/privacy
2. Contact IMA technical support to confirm domain ownership: support@imastudio.com
3. Use a test/scoped API key first (see security notice below)
4. Monitor network traffic during first run (instructions in SECURITY.md)

⚠️ Credential Security Notice

Your IMA API key is sent to TWO domains:

1. api.imastudio.com — Main video generation API
2. imapi.liveme.com — Image upload service (only when using image-to-video tasks)

Both domains are owned by IMA Studio, but if you're concerned about credential exposure:

✅ Best practices:

• Use a test/scoped API key for initial testing (create at https://imastudio.com/api-keys)
• Set a low quota (e.g., 100 credits) for the test key
• Rotate your key after testing if needed
• Monitor network traffic during first run (see SECURITY.md § "Network Traffic Verification")
• Contact IMA support to confirm domain ownership: support@imastudio.com

❌ Do NOT:

• Use a production key if you're uncomfortable with the two-domain architecture
• Share your API key with others
• Commit your API key to version control

What gets sent to IMA servers:

• ✅ Your video prompt/description
• ✅ Model selection (Wan/Hailuo/Kling/etc.)
• ✅ Video parameters (duration, resolution, etc.)
• ✅ Image files (for image-to-video tasks, uploaded to imapi.liveme.com)
• ✅ IMA API key (for authentication to both domains)
• ❌ 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

Agent Execution (Internal Reference)

Note for users: You can review the script source at scripts/ima_video_create.py anytime.
The agent uses this script to simplify API calls. Network requests go to two IMA Studio domains: api.imastudio.com (API) and imapi.liveme.com (image uploads).

Use the bundled script internally to ensure correct parameter construction:

# Text to video
python3 {baseDir}/scripts/ima_video_create.py \
  --api-key  $IMA_API_KEY \
  --task-type text_to_video \
  --model-id  wan2.6-t2v \
  --prompt   "a puppy runs across a sunny meadow, cinematic" \
  --user-id  {user_id} \
  --output-json

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

# First-last frame to video
python3 {baseDir}/scripts/ima_video_create.py \
  --api-key      $IMA_API_KEY \
  --task-type    first_last_frame_to_video \
  --model-id     kling-video-o1 \
  --prompt       "smooth transition" \
  --input-images https://example.com/first.jpg https://example.com/last.jpg \
  --user-id      {user_id} \
  --output-json

The script outputs JSON — parse it to get the result URL and pass it to the user via the UX protocol messages below.

🚨 CRITICAL: How to send the video to user (Feishu/Discord/IM)

# ✅ CORRECT: Use the remote URL directly
video_url = json_output["url"]
message(
    action="send",
    media=video_url,  # Direct HTTPS URL → renders inline video player
    caption="✅ 视频生成成功！\n• 模型：[Model Name]\n• 耗时：[X]s\n• 消耗积分：[N pts]"
)

# ❌ WRONG: Download to local file first
# curl -o /tmp/video.mp4 {video_url}
# message(media="/tmp/video.mp4")  # Shows as file attachment (📎 path), NOT playable

Why this matters:

• ✅ Remote URL → Feishu renders inline video player with ▶ button
• ❌ Local file path → Feishu shows file attachment (📎 /tmp/...), not playable

Always use the remote URL directly. Never download the video to local storage.

Overview

🛡️ Model-Specific Notes

Sora 2 Pro — Content Safety Policy

⚠️ Important: Sora 2 Pro has strict content safety policies (OpenAI policy).

Content Restrictions:

• ❌ Cannot generate: people, celebrities, IP assets (e.g., Mickey Mouse)
• ❌ Strict prompt moderation
• ✅ Safe themes: landscapes, abstract patterns, animals, nature scenes

Recommended Prompts:

• ✅ "A sunset over mountains"
• ✅ "Abstract colorful flowing patterns"
• ✅ "A bird flying through clouds"

Avoid:

• ❌ "A person walking" (people)
• ❌ "Mickey Mouse dancing" (IP asset)
• ❌ Celebrity names or recognizable figures

If your prompt is rejected, try using more abstract or nature-focused descriptions.

Call IMA Open API to create AI-generated videos. 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_video_create.py and ima_logger.py anytime
• ✅ Verify network calls: Network requests go to two IMA Studio domains: api.imastudio.com (API) and imapi.liveme.com (image uploads). See "🌐 Network Endpoints Used" section above for full details.
• ✅ 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_video_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_video_create.py

Verify skill integrity

sha256sum SKILL.md scripts/ima_video_create.py

If users report issues, verify file integrity first.

---

## 🧠 User Preference Memory

> User preferences **override** recommended defaults. If a user has generated before, use their preferred model — not the system default.

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

```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": "..." }
  }
}

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

When to Read (Before Every Generation)

1. Load ~/.openclaw/memory/ima_prefs.json (silently, no error if missing)
2. Look up user_{user_id}.{task_type}
3. If found → use that model; mention it:

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

4. If not found → use the ⭐ Recommended Default

When to Write (After Every Successful Generation)

Save the used model to ~/.openclaw/memory/ima_prefs.json under user_{user_id}.{task_type}.
See ima-image-ai/SKILL.md → "User Preference Memory" for the full Python write snippet.

When to Update (User Explicitly Changes 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.

Selection guide (production credits, sorted by popularity):

• 🔥 Most popular text-to-video → Wan 2.6 (25 pts, balanced cost & quality)
• Premium text-to-video → Hailuo 2.3 (38 pts, higher quality)
• Budget text-to-video → Vidu Q2 (5 pts) or Hailuo 2.0 (12 pts)
• 🔥 Most popular image_to_video → Wan 2.6 (25 pts)
• first_last_frame / reference → Kling O1 (48 pts)
• User specifies cheapest → Vidu Q2 (5 pts) — only if explicitly requested

💬 User Experience Protocol (IM / Feishu / Discord)

Video generation takes 1~6 minutes. Never let users wait in silence.
Always follow all 4 steps below, every single time.

🚫 Never Say to Users

Only tell users: model name · estimated time · credits · result URL · plain-language status.

Estimated Generation Time per Model

estimated_max_seconds = upper bound of the range (e.g. 180 for Kling 2.1 Master, 360 for Kling O1).

Step 1 — Pre-Generation Notification (with Cost Transparency)

Before calling the create API, send this message immediately:

🎬 开始生成视频，请稍候…
• 模型：[Model Name]
• 预计耗时：[X ~ Y 秒]（约 [X/60 ~ Y/60] 分钟）
• 消耗积分：[N pts]

视频生成需要一定时间，我会每隔一段时间汇报进度 🙏

Cost transparency (critical for video):

• For balanced/default models (25 pts): "使用 Wan 2.6（25 积分，最新 Wan）"
• For premium models (>50 pts):
  • If auto-selected: "使用 Wan 2.6（25 积分）。若需更高质量可选 Kling 2.1 Master（150 积分）"
  • If user explicit: "使用高端模型 Kling 2.1 Master（150 积分），质量最佳"
• For budget (user explicit): "使用 Vidu Q2（5 积分，最省钱选项）"

Adapt language to match the user. For expensive models (>50 pts), always mention cheaper alternatives unless user explicitly requested premium quality.

Adapt language to match the user. English → 🎬 Starting video generation, this may take [X~Y] seconds. I'll update you on progress…

Step 2 — Progress Updates

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

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

Progress formula:

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

• Cap at 95% — never show 100% until the API returns success
• If elapsed > estimated_max: keep P at 95% and append 「快了，稍等一下…」
• Example: elapsed=120s, max=180s → P = min(95, floor(120/180*100)) = min(95, 66) = 66%
• Example: elapsed=200s, max=180s → P = 95%（冻结 + 「快了，稍等一下…」）

Step 3 — Success Notification (Push video via message tool)

When task status = success:

3.1 Send video player first (Feishu will render inline player):

# Get result URL from script output or task detail API
result = get_task_result(task_id)
video_url = result["medias"][0]["url"]

# Send video with caption
message(
    action="send",
    media=video_url,  # ⚠️ Use HTTPS URL directly, NOT local file path
    caption="""✅ 视频生成成功！
• 模型：[Model Name]
• 耗时：预计 [X~Y]s，实际 [actual]s
• 消耗积分：[N pts]

[视频描述]"""
)

3.2 Then send link as text (for copying/sharing):

# Send link message immediately after
message(
    action="send",
    message=f"""🔗 视频链接（方便复制分享）：
{video_url}"""
)

Critical:

• Use the remote HTTPS URL directly as media parameter. Do NOT download to local file first.
• Send video first (for inline playback), then send link text (for copying/sharing).

For Feishu: Direct video URL → inline video player with play button. Local file path → file attachment (📎 path).

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: Video 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
5. Video-specific:
   • For Sora content policy errors, recommend Wan 2.6 or Kling O1 (more permissive)
   • For timeout errors, recommend faster models (Vidu Q2, Hailuo 2.0)
   • For image input errors, suggest checking image format (HTTPS URL, valid JPEG/PNG)

Failure fallback table:

Supported Models

⚠️ Production Environment: Model availability validated against production API on 2026-02-27.

text_to_video (14 models)

image_to_video (14 models)

first_last_frame_to_video (10 models)

reference_image_to_video (9 models)

Production Notes (2026-02-27):

• ❌ Removed models: Vidu Q2 Turbo (viduq2-turbo), Wan 2.5, Kling 1.6/2.1/2.5, Sora 2 (non-Pro), Veo 3.0/3.1 Fast, SeeDance 1.0, Vidu Q1
• ✅ Active models: 14 t2v, 14 i2v, 10 first_last_frame, 9 reference_image
• 🔥 Most popular: Wan 2.6 (both t2v and i2v)
• 🌟 Recommended defaults: Wan 2.6 (balanced), Kling O1 (premium with audio)

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

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

# Step 1: Query product list for the target category
GET /open/v1/product/list?app=ima&platform=web&category=text_to_video
# (or image_to_video / first_last_frame_to_video / reference_image_to_video)

# Step 2: Walk the V2 tree to find your 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_name    = version["name"]
            form_defaults = {f["field"]: f["value"] for f in version["form_config"]}

Quick Reference: Known attribute_ids

⚠️ Production warning: attribute_id and credit values change frequently. Always call /open/v1/product/list at runtime; table below is pre-queried reference (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 rule's attributes. If the match fails, you get error 6010.

Fix: The bundled script now checks these video-specific parameters for smart credit_rule selection. Always use the script, not manual API construction.

Core Flow

1. GET /open/v1/product/list?app=ima&platform=web&category=<type>
   → REQUIRED: Get attribute_id, credit, model_version, form_config defaults

[image_to_video / first_last_frame / reference_image tasks only]
2. Upload input image(s) → get public HTTPS URL(s)
   → See "Image Upload" section below

3. POST /open/v1/tasks/create
   → Must include: attribute_id, model_name, model_version, credit, cast, prompt (nested!)

4. POST /open/v1/tasks/detail  {task_id: "..."}
   → Poll every 8s until medias[].resource_status == 1
   → Extract url (mp4) and cover (thumbnail) from completed media

Video generation is slower than image — poll every 8s and set timeout to 600s.

Image Upload (Required for Video Tasks with Image Input)

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

For image_to_video, first_last_frame_to_video, reference_image_to_video: when a user provides an image (local file, base64, or non-public URL), upload it first to get a URL.

def prepare_image_url(source) -> str:
    """Convert any image source to a public HTTPS URL.
    
    - If source is already a public HTTPS URL: return as-is
    - If source is a local file path or bytes: upload to hosting first
    """
    if isinstance(source, str) and source.startswith("https://"):
        return source  # already public, use directly

    # Option 1: IMA OSS (requires OSS credentials)
    #   objectName = f"aiagent/src/d/{date}/in/{uuid}.jpg"
    #   bucket.put_object(objectName, image_bytes)
    #   return f"https://ima.esxscloud.com/{objectName}"

    # Option 2: Any public image hosting (imgbb example)
    import base64, requests
    if isinstance(source, str):
        with open(source, "rb") as f:
            b64 = base64.b64encode(f.read()).decode()
    else:
        b64 = base64.b64encode(source).decode()
    r = requests.post("https://api.imgbb.com/1/upload",
                      data={"key": IMGBB_API_KEY, "image": b64})
    r.raise_for_status()
    return r.json()["data"]["url"]

# For first_last_frame: prepare both frames
first_url = prepare_image_url("/path/to/first.jpg")
last_url  = prepare_image_url("/path/to/last.jpg")
src_img_url = [first_url, last_url]  # index 0 = first, index 1 = last

Note: URLs must be publicly accessible — not localhost, private network, or auth-gated endpoints.

Supported Task Types

Detail API status values

Important: Treat resource_status: null as 0. Stop only when all medias have resource_status == 1. Check status != "failed" when rs=1.

API 1: Product List

GET /open/v1/product/list?app=ima&platform=web&category=text_to_video

Returns a V2 tree structure: type=2 nodes are model groups, type=3 nodes are versions (leaves). Only type=3 nodes contain credit_rules and form_config.

How to pick a version:

1. Traverse nodes to find type=3 leaves
2. Use model_id and id (= model_version) from the leaf
3. Pick credit_rules[].attribute_id matching desired quality
4. Use form_config[].value as default parameters values (duration, resolution, aspect_ratio, etc.)

API 2: Create Task

POST /open/v1/tasks/create

text_to_video — Verified ✅

No image input. src_img_url: [], input_images: [].

{
  "task_type": "text_to_video",
  "enable_multi_model": false,
  "src_img_url": [],
  "parameters": [{
    "attribute_id":  4838,
    "model_id":      "wan2.6-t2v",
    "model_name":    "Wan 2.6",
    "model_version": "wan2.6-t2v",
    "app":           "ima",
    "platform":      "web",
    "category":      "text_to_video",
    "credit":        25,
    "parameters": {
      "prompt":          "a puppy dancing happily, sunny meadow",
      "negative_prompt": "",
      "prompt_extend":   false,
      "duration":        5,
      "resolution":      "1080P",
      "aspect_ratio":    "16:9",
      "shot_type":       "single",
      "seed":            -1,
      "n":               1,
      "input_images":    [],
      "cast":            {"points": 3, "attribute_id": 4838}
    }
  }]
}

Video-specific fields from form_config: duration (seconds), resolution, aspect_ratio, shot_type, negative_prompt, prompt_extend. Response medias[].cover = first-frame thumbnail JPEG.

image_to_video

Input image goes in top-level src_img_url and parameters.input_images:

{
  "task_type": "image_to_video",
  "enable_multi_model": false,
  "src_img_url": ["https://example.com/scene.jpg"],
  "parameters": [{
    "attribute_id":  "<from credit_rules>",
    "model_id":      "<model_id>",
    "model_name":    "<model_name>",
    "model_version": "<version_id>",
    "app":           "ima",
    "platform":      "web",
    "category":      "image_to_video",
    "credit":        "<points>",
    "parameters": {
      "prompt":       "bring this landscape alive",
      "n":            1,
      "input_images": ["https://example.com/scene.jpg"],
      "cast":         {"points": "<points>", "attribute_id": "<attribute_id>"}
    }
  }]
}

first_last_frame_to_video

Provide exactly 2 images: index 0 = first frame, index 1 = last frame:

{
  "task_type": "first_last_frame_to_video",
  "src_img_url": ["https://example.com/first.jpg", "https://example.com/last.jpg"],
  "parameters": [{
    "category": "first_last_frame_to_video",
    "parameters": {
      "prompt": "smooth transition",
      "n": 1,
      "input_images": ["https://example.com/first.jpg", "https://example.com/last.jpg"],
      "cast": {"points": "<points>", "attribute_id": "<attribute_id>"}
    }
  }]
}

reference_image_to_video

Provide 1 or more reference images in src_img_url:

{
  "task_type": "reference_image_to_video",
  "src_img_url": ["https://example.com/ref.jpg"],
  "parameters": [{
    "category": "reference_image_to_video",
    "parameters": {
      "prompt": "dynamic video based on reference",
      "n": 1,
      "input_images": ["https://example.com/ref.jpg"],
      "cast": {"points": "<points>", "attribute_id": "<attribute_id>"}
    }
  }]
}

Key fields:

Response: data.id = task ID for polling.

API 3: Task Detail (Poll)

POST /open/v1/ta

…(truncated)