IMA Video AI

When To Use

Use this repository for text-to-video, image-to-video, reference-image video generation, and first/last-frame interpolation. This repo is video-only; do not route image editing, audio, or non-video tasks here.

Quick Start

1. Get your API key at https://www.imaclaw.ai/imaclaw/apikey, then export it: export IMA_API_KEY="your-api-key"
2. Run a low-cost health probe before spending credits: python3 scripts/ima_runtime_doctor.py --task-type text_to_video
3. First-time setup: python3 scripts/ima_runtime_setup.py
4. Manual first-run alternative if you skip setup: in an interactive terminal, python3 scripts/ima_runtime_cli.py --task-type text_to_video --prompt "..." now prompts for a suggested model; non-interactive callers should still use --model-id or --list-models
5. Natural-language wrapper: python3 scripts/route_and_execute.py --request "做一个 10 秒的产品视频" for parse + validate + execute

First-Run Rules

• Runtime model resolution is fixed: --model-id -> saved preference -> interactive TTY prompt -> fail; there is no hidden default model.
• First use can run python3 scripts/ima_runtime_setup.py, accept the first-run CLI prompt in a terminal, or choose --model-id after --list-models; setup writes only ~/.openclaw/memory/ima_prefs.json, never IMA_API_KEY.
• Install Python dependencies with pip install -r requirements.txt; Pillow is used for image-dimension probing.
• Ensure ffprobe is on PATH for video/audio metadata probing and ffmpeg is on PATH for derived video cover extraction.

Picks And Errors

• Start with ima-pro-fast for text_to_video / image_to_video; start with kling-video-o1 for reference_image_to_video / first_last_frame_to_video. Full matrix: references/shared/model-selection-policy.md
• 401 or invalid key -> regenerate at https://www.imaclaw.ai/imaclaw/apikey and rerun ima_runtime_doctor.py; 403 / 4014 -> subscribe or switch to ima-pro-fast; 6009 / 6010 -> remove custom params and confirm the live catalog with --list-models

Video Modes

• first_last_frame means explicit start/end frames with generated motion between them; reference means style or character guidance, not literal frame 1.

Gateway Contract

Treat this file as the public gateway, not the full rulebook.

• The generation entrypoint is python3 scripts/ima_runtime_cli.py ....
• python3 scripts/route_and_execute.py is the natural-language wrapper over the structured runtime.
• python3 scripts/ima_runtime_setup.py and python3 scripts/ima_runtime_doctor.py are onboarding helpers, not alternate generation runtimes.
• No other generation CLI path is part of the active runtime contract.
• Remote HTTPS reference media must be direct public URLs. The runtime may temporarily download them locally for metadata probing, Seedance preflight checks, and video-cover extraction; private/internal hosts, credentialed URLs, redirects, and oversized downloads are rejected.
• Local media files and derived video cover frames use IMA's upload-token flow and then upload to the pre-signed HTTPS storage URL returned by that service.
• Build a GatewayRequest for a video target.
• Resolve task type before execution, and clarify when image roles are ambiguous.
• Query the product list before task creation so attribute_id, model_version, and defaults come from the live catalog.
• Return video results as remote HTTPS URLs; do not convert them into local file attachments.

Read Order

references/README.md, references/gateway/entry-and-routing.md, references/gateway/workflow-confirmation.md, references/shared/model-selection-policy.md, references/shared/error-policy.md, references/shared/security-and-network.md, capabilities/video/CAPABILITY.md

Boundary

references/gateway/ covers entry/routing, references/shared/ covers shared runtime policy, capabilities/video/* owns video behavior, and _meta.json plus clawhub.json remain metadata inputs.