video-audio-add

Video Audio Add

Overview

Forexisting videoadd an audio track, covering 2 types of scenarios that can be chained:

1. Add background music (BGM): the tool internally searches the material library for matching music based on the prompt description, or uses a custom audio_url；video_volume default 1(does not lower the original audio).
2. Add voiceover narration: the tool internally searches voice material based on the voice description in prompt ;video_volume default 0(lowers the original audio to highlight the narration).

When BGM + narration need to be added at the same time, execute in sequence video_bgm_add → video_narration_add。

Not handled: video concatenation, integrated concatenation + music, pure music/song generation, video content/frame editing.

API Mapping

Scenario	API name
Add background music	video_bgm_add
Add voiceover narration	video_narration_add

Dependencies

• meitu-cli: >=2.0.6
• Credentials：CONFIG AKSK → meitu tools update; EXEC AKSK → run command
• Environment variables：MEITU_OPENAPI_TOOL_TASK_MODE=command

Path alias: In the following, $VISUAL = {OPENCLAW_HOME}/workspace/visual/

Core Workflow

Preflight → Execute → Deliver

Preflight

1. meitu --version → if not installed, prompt to install
2. meitu auth verify --json → if credentials are invalid, guide configuration
3. Detect whether MEITU_OPENAPI_TOOL_TASK_MODE=command is set
4. Resolve output_dir: project mode → ./output/; one-off → $VISUAL/output/video-audio-add/；mkdir -p

Execute

Trigger signals and routing

User's exact words	Route
Add BGM / add some background music / change background music (no audio_url）	video_bgm_add(internally search material based on prompt )
"use this audio as the music" (has audio_url）	video_bgm_add(skip internal search, directly use audio_url）
Add narration / add voiceover / add commentary / add voice-over	video_narration_add，prompt contains narration script + voice preference
Voiceover and music / add BGM and narration	Chain: first video_bgm_add → then video_narration_add

Parameter definitions

Common parameters:

Parameter	Type	Required	Range	Default	Description
video_list	ARRAY[STRING]	Yes	—	—	List of video addresses
prompt	STRING	Yes	—	—	BGM: music style preference; narration: narration script + voice

video_bgm_add additional:

Parameter	Type	Required	Range	Default	Description
audio_url	STRING	No	—	—	Custom audio URL; when present, skip internal material search
music_volume	NUMBER	No	0–1	1	Background music volume
video_volume	NUMBER	No	0–1	1	Original audio volume (not lowered by default)

video_narration_add additional:

Parameter	Type	Required	Range	Default	Description
video_volume	NUMBER	No	0–1	0	Original audio volume (lowered by default)

Note:bgm_material_id / voice_material_id not used as an external input parameter, determined internally by the tool based on prompt Automatic retrieval; if no match, use default assets/voice.

Tool invocation

# BGM
meitu video-audio-add --video_list {urls} --prompt "{风格}" [--audio_url {url}] [--music_volume 1] [--video_volume 1] --json --download-dir {output_dir} --skill_name skill_video-audio-add

# 旁白
meitu video-audio-add --video_list {urls} --prompt "{旁白文案 + 音色}" [--video_volume 0] --json --download-dir {output_dir} --skill_name skill_video-audio-add

# 串联：BGM → 旁白（第一步失败则停止串联）

Error degradation

Scenario	Handling
video_list Missing	Prompt "Please provide a video link", do not invoke
video_list Any one inaccessible	Return error directly, do not retry
Narration scenario prompt Missing	Prompt "Please provide voiceover copy"
audio_url Inaccessible (BGM)	Fall back to internal retrieval default music
No match in tool internal retrieval	Continue using default assets/voice
First step of chaining failed	Stop chaining, return error
API call failed	Retry once, if still failing return error
Content compliance interception	Return compliance prompt directly, do not retry

Deliver

mv {file} {output_dir}/{date}_{name}_audio-add.mp4

Output

• Format：MP4
• Naming：{YYYY-MM-DD}_{descriptive-name}_audio-add.mp4
• Location: Project mode → ./output/; One-time → $VISUAL/output/video-audio-add/

Baseline Task ID

t_mt1a3i5n7b55cdc12e-cdeb-46fd-a95d-28a7546bf033