image-to-video

Image to Video

Overview

Generate dynamic videos driven by images. 3 types of scenarios: single-image video generation (supports audio/aspect ratio/resolution, defaults to toffee with bonbon as fallback on failure), multi-image reference fusion (1–9 images), first/last frame transition (1–2 images). Duration 4–15s.

API Mapping

• Single-image default:video_toffee_i2v_v20
• Single-image fallback:video_bonbon_img2vid_v30(supports intelligent storyboarding/multi-shot, does not support aspect_ratio)
• Multi-image reference fusion (1–9 images):video_toffee_mi2v_v20
• First/last frame transition (1–2 images):video_toffee_flf_v20
• mode mapping:auto(default)/i2v/mi2v/flf
• model mapping:auto(default)/toffee/bonbon
• When mode and model are specified simultaneously and conflict,mode takes priority

Dependencies

• meitu-cli: >=2.0.6
• Credentials：CONFIG AKSK → meitu tools update; EXEC AKSK → actual execution (see root CONFIG.md）
• Environment variables：MEITU_OPENAPI_TOOL_TASK_MODE=command

Path alias:$VISUAL = {OPENCLAW_HOME}/workspace/visual/

Core Workflow

Preflight → Execute → Deliver

Preflight

1. meitu --version ≥ 2.0.6
2. Already ran with CONFIG AKSK meitu tools update
3. Current AKSK = EXEC,MEITU_OPENAPI_TOOL_TASK_MODE=command
4. output_dir：openclaw.yaml → ./output/ ｜else → $VISUAL/output/image-to-video/；mkdir -p

Execute

Trigger signals / routing rules

Core dimensions:mode (priority) → number of images + intent。

Condition	Number of images	Route
mode=i2v	Any	video_toffee_i2v_v20 → fallback on failure video_bonbon_img2vid_v30
mode=mi2v	Any	video_toffee_mi2v_v20
mode=flf	Any	video_toffee_flf_v20
mode=auto, 1 image, "reference element/character/style"	1	video_toffee_mi2v_v20
mode=auto, 1 image, other (default)	1	video_toffee_i2v_v20 → fallback video_bonbon_img2vid_v30
mode=auto, 2 images, fusion not mentioned (default)	2	video_toffee_flf_v20
mode=auto, 2 images, fusion/reference mentioned	2	video_toffee_mi2v_v20
mode=auto, 3–9 images	3–9	video_toffee_mi2v_v20

Parameter definitions (unified tool layer)

Parameter	Type	Required	Range	Default	Description
image_list	ARRAY[STRING]	Yes	1–9 images	--	List of input image URLs
prompt	STRING	Yes	--	--	Video content description
mode	STRING	No	auto / i2v / mi2v / flf	auto	Routing mode; mode takes priority when conflicting with model
model	STRING	No	auto / toffee / bonbon	auto	Underlying model
aspect_ratio	STRING	No	adaptive/1:1/3:4/4:3/9:16/16:9/21:9	adaptive	Aspect ratio (supported by i2v/mi2v/flf; not supported by bonbon)
video_duration	NUMBER	No	4–15	5	Duration (seconds). bonbon defaults to 5; i2v/mi2v/flf internally default to 10
sound	STRING	No	off / on	off	Whether to generate audio
multi_shot	BOOLEAN	No	true/false	true	Multi-shot switching (effective only for bonbon)

Other parameters (shot_type/resolution/reference_video_list/reference_audio_list etc.) are managed internally by combo-tool and not exposed externally.

Key points of API mapping:

• video_toffee_i2v_v20：sound→generate_audio（on→true/off→false BOOL），aspect_ratio→ratio，resolution internally defaults to 720p
• video_bonbon_img2vid_v30：image_list[0]→image_url，sound passed through directly as STRING,aspect_ratio silently discarded when downgrade is not supported
• video_toffee_mi2v_v20：image_list passed through directly (≤9),sound→generate_audio BOOL
• video_toffee_flf_v20：image_list 1–2 images ([0]=first frame, [1]=last frame optional)

Tool invocation

meitu image-to-video --image_list <img1>[,<img2>,...] --prompt "<desc>" [--mode auto] [--video_duration 5] [--sound off] [--aspect_ratio adaptive] --json --download-dir {output_dir} --skill_name skill_image-to-video

Error downgrade

Scenario	Handling method
mode invalid	Fall back to auto
model invalid	Fall back auto
mode=flf but image count >2	Prompt "First-last frame mode supports at most 2 images, currently {n} images"
prompt missing	Prompt "Please describe the video content you want to generate"
No image input	Reject, outside capability scope
Image count >9	Reject, outside capability scope
Duration <4s	Clamp to 4s and notify
Duration >15s	Clamp to 15s
Smart storyboard + i2v/mi2v/flf	Silently ignore storyboard parameters
video_toffee_i2v_v20 call failed	Degrade to video_bonbon_img2vid_v30（aspect_ratio discard,image_list[0]→image_url）
Any API call failure (including fallback)	Retry the same API once → if still failing, return an error
Timeout (>600s)	Reduce duration/size and retry once → if still failing, return an error
Some images inaccessible	Filter out inaccessible ones and rematch sub-capabilities with the remaining images
All images inaccessible	Return an error
mode + model conflict	mode takes precedence
mode=i2v + multiple images	Take image_list[0], ignore extra images
Content compliance interception	Directly return a compliance prompt, no retry, no degradation

Deliver

• Use the output_dir resolved by Preflight
• From downloaded_files[0].saved_path read the downloaded video file path
• mv {downloaded_files[0].saved_path} {output_dir}/{YYYY-MM-DD}_{descriptive}_image-to-video.mp4

Output

• Format：MP4
• Location: project → ./output/, one-time → $VISUAL/output/image-to-video/

Baseline Task ID

See the corresponding row in references/task-id-baseline.md .