tencent-mps

Tencent Cloud Media Processing Service (MPS)

💰 Cost notice: This Skill's calls to the Tencent Cloud MPS service will incur corresponding charges, including transcoding fees, AI processing fees, storage fees, etc. For specific billing standards, please refer to Tencent Cloud MPS pricing. Every time the MPS media processing/image processing/image generation/video generation features are used, a notice must be given.

Call the MPS API through the official Tencent Cloud Python SDK. All scripts are located in the scripts/ directory, all support --help and --dry-run。

Detailed parameters: see references/params.md Complete example set: see references/scripts-detail.md

Environment configuration

Check environment variables:

python scripts/load_env.py --check-only

Configuration (~/.profile or ~/.bashrc）：

# 必须（所有脚本）
export TENCENTCLOUD_SECRET_ID="your-secret-id"
export TENCENTCLOUD_SECRET_KEY="your-secret-key"

# 以下场景必须配置 COS 变量：
#   1. 输入源为 --cos-object（即 COS 对象路径，非 URL）
#   2. 使用 mps_cos_upload.py / mps_cos_download.py 上传/下载本地文件
#   3. 脚本需要将处理结果写回 COS（OutputStorage）
export TENCENTCLOUD_COS_BUCKET="your-bucket"        # COS 存储桶名
export TENCENTCLOUD_COS_REGION="your-bucket-region" # 存储桶地域，如 ap-guangzhou

Install dependencies:

pip install tencentcloud-sdk-python cos-python-sdk-v5

Local file processing workflow

MPS only accepts URLs or COS objects as input;local files must be uploaded first。

Automatic processing workflow when the user inputs a local file

When the user's request involves a local file path (such as ./video.mp4、/path/to/image.jpg), follow the steps below toautomatically process：

Step 1: Upload the file to COS

python scripts/mps_cos_upload.py --local-file <本地文件路径> --cos-key <目标路径>

• Use --cos-key to specify a reasonable storage path (default path input/）
• Record the COS information returned by the upload: bucket, region, key

Step 2: Execute the script using COS path parameters Depending on the script type, use the method for passing COS paths in each script, as follows:

Script	COS path parameter method	Example
mps_transcode.py	--cos-object <key>	--cos-object input/video.mp4
mps_enhance.py	--cos-object <key>	--cos-object input/video.mp4
mps_erase.py	--cos-object <key>	--cos-object input/video.mp4
mps_subtitle.py	--cos-object <key>	--cos-object input/video.mp4
mps_imageprocess.py	--cos-object <key>	--cos-object input/image.jpg
mps_qualitycontrol.py	--cos-object <key>	--cos-object input/video.mp4
mps_av_understand.py	--cos-object <key>	--cos-object input/video.mp4
mps_vremake.py	--cos-object <key>	--cos-object input/video.mp4
mps_narrate.py	--cos-object <key>	--cos-object input/video.mp4
mps_highlight.py	--cos-object <key>	--cos-object input/video.mp4
mps_aigc_image.py	--cos-input-bucket <b> --cos-input-region <r> --cos-input-key <k>	--cos-input-bucket xxx --cos-input-region ap-guangzhou --cos-input-key input/img.jpg
mps_aigc_video.py	--cos-input-bucket <b> --cos-input-region <r> --cos-input-key <k>	--cos-input-bucket xxx --cos-input-region ap-guangzhou --cos-input-key input/img.jpg

Note: Scripts using --cos-object depend on the environment variables TENCENTCLOUD_COS_BUCKET and TENCENTCLOUD_COS_REGION; AIGC-type scripts need to explicitly pass the complete COS information.

Step 3: Download the processing results (if needed)

python scripts/mps_cos_download.py --cos-key <输出key> --local-file <本地保存路径>

Input method description

Depending on the input source, two methods are supported:

Method 1: COS path method (recommended for locally uploaded files)

Use the --cos-object <key> parameter (or --cos-input-bucket/--cos-input-region/--cos-input-key）

• Applicable scenario: processing after the user uploads a local file to COS
• Reason: locally uploaded files may not have public read permission, and using the URL directly may fail
• Example:--cos-object input/video.mp4

Method 2: URL method (applicable to existing URLs)

Use the --url <url> parameter

• Applicable scenario: the user directly provides a file URL (including COS URLs from other accounts/sources, external links, etc.)
• Requirement: the URL must be publicly accessible or already carry a valid signature
• Example:--url https://example-bucket.cos.ap-guangzhou.myqcloud.com/video.mp4

⚠️ Note: If the URL comes from a locally uploaded COS file and does not have public permission, please use Method 1 (COS path method); the script will automatically generate a signed URL.

Manual processing example

If you need to execute manually, the complete workflow is as follows:

# 1. 上传
python scripts/mps_cos_upload.py --local-file ./video.mp4 --cos-key input/video.mp4
# 2. 执行任务（使用 COS 路径）
python scripts/mps_transcode.py --cos-object input/video.mp4
# 3. 下载结果
python scripts/mps_cos_download.py --cos-key output/result.mp4 --local-file ./result.mp4

When the returned result contains a link, return it to the user in Markdown format:[文件名](URL)

Asynchronous task description

All scripts automatically poll and wait for completion by default.

• Submit only without waiting: add --no-wait, and the script returns TaskId
• Manual query: for audio/video use mps_get_video_task.py, for images use mps_get_image_task.py

Script function mapping (responsibility boundaries)

💰 The following operations will call Tencent Cloud MPS services and incur charges.

When selecting scripts, strictly follow the mapping relationships;do not mix them：

User requirement type	Script to use	Description
Check image quality, detect blur/screen artifacts	mps_qualitycontrol.py	Sole quality inspection script，--definition 60(default)
Detect playback compatibility, stuttering, playback anomalies	mps_qualitycontrol.py	Sole quality inspection script，--definition 70
Audio quality detection, audio event detection	mps_qualitycontrol.py	Sole quality inspection script，--definition 50
Remove subtitles, erase watermarks, blur faces/license plates	mps_erase.py	Only for erasing/obscuring image content
Image quality enhancement, old film restoration, super-resolution	mps_enhance.py	Video image quality improvement
Transcoding, compression, format conversion	mps_transcode.py	Encoding format processing
Subtitle extraction, translation, subtitle-related speech recognition	mps_subtitle.py	Subtitle-related
Image processing (super-resolution/beautification/denoising)	mps_imageprocess.py	Image enhancement
AI image generation (text-to-image/image-to-image)	mps_aigc_image.py	AIGC image generation
AI video generation (text-to-video/image-to-video/storyboard generation)	mps_aigc_video.py	AIGC video generation,Kling models support the storyboard feature
Audio/video content understanding (scene/summary/analysis/speech recognition)	mps_av_understand.py	Large model understanding,must provide --mode and --prompt
Video deduplication (picture-in-picture/video extension/face swap/character swap, etc.)	mps_vremake.py	VideoRemake，must provide --mode
Usage statistics query	mps_usage.py	Call count/duration query
AI commentary secondary creation / short drama commentary / automatic short drama commentary video generation / short drama commentary mashup	mps_narrate.py	must be selected from the preset --scene ; custom scripts are not supported; for multi-episode videos, append in order via --extra-urls append
Highlights reel / highlight extraction / automatic editing of highlight clips / football goal highlights / basketball highlights / short drama highlights	mps_highlight.py	must be selected from the preset --scene ; assembling ExtendedParameter yourself is prohibited; live streams are not supported
Query audio/video processing task status	mps_get_video_task.py	ProcessMedia task query
Query image processing task status	mps_get_image_task.py	ProcessImage task query
Upload local files to COS	mps_cos_upload.py	Local → COS prerequisite step
Download files from COS	mps_cos_download.py	COS → local post-step
List COS Bucket files	mps_cos_list.py	View the COS file list, supporting path filtering and file name search

Important：mps_erase.py 's responsibility is toerase/obscure visual elements in the image, does not involve quality detection. "Quality detection", "blur", "screen corruption", "playback compatibility", "audio quality inspection" → must use mps_qualitycontrol.py。

Mandatory rules for generating commands

1. Script path prefix: all generated python commands must include the scripts/ path prefix, in the format python scripts/mps_xxx.py .... It is forbidden to generate python mps_xxx.py ...(missing the scripts/ prefix) commands.

2. Placeholders forbidden: all parameter values must be real values. If the user does not provide a required value,ask first, and do not use <视频URL>、YOUR_URL and other placeholders.

3. mps_qualitycontrol.py must contain --definition：

   • Audio quality inspection:--definition 50
   • Visual quality inspection (default):--definition 60
   • Playback compatibility:--definition 70

4. mps_av_understand.py must contain --mode and --prompt：

   • --mode video(understand video frames) or --mode audio(audio only; audio is automatically extracted from video)
   • --prompt controls the focus of the large model's understanding; if missing, the result may be empty

5. mps_narrate.py must contain --scene：

   • value must be one of the preset enumerations:short-drama | short-drama-no-erase
   • when the user says "has subtitles"/"with hard subtitles", default to selecting the scenario that includes erasure (short-drama）
   • when the user says "no subtitles"/"the original video has no subtitles"/"do not erase", select -no-erase scenario (short-drama-no-erase）
   • for multi-episode videos, use --url/--cos-objectfor the first episode and --extra-urls for subsequent episodes, appending in order
   • It is forbidden to pass in scriptUrls related parameters (custom script input is not supported in this version)

6. mps_highlight.py must contain --scene：

   • value must be one of the preset enumerations:vlog | vlog-panorama | short-drama | football | basketball | custom
   • when the user mentions keywords such as "basketball"/"football"/"short drama"/"VLOG", map directly to the corresponding --scene, without asking again
   • --prompt and --scenario take effect only when --scene custom , but neither is required
   • --top-clip is allowed only in the vlog / vlog-panorama / custom scenario
   • It is forbidden to generate ExtendedParameter fields or values outside the preset table
   • When the user requests processing live stream highlights, inform them that the current skill does not support live streams and that the MPS API must be called directly

Key script descriptions

Video enhancement (mps_enhance.py)

Large model enhancement template (--template), select by scenario + target resolution:

Scenario	720P	1080P	2K	4K
Real people (Real)	327001	327003	327005	327007
Anime (Anime)	327002	327004	327006	327008
Jitter optimization	327009	327010	327011	327012
Strongest detail	327013	327014	327015	327016
Face fidelity	327017	327018	327019	327020

Subtitle removal erasure (mps_erase.py)

Preset templates:101 subtitle removal | 102 subtitle removal + OCR | 201 advanced watermark removal | 301 face blur | 302 face + license plate blur

Large model audio-video understanding (mps_av_understand.py)

Controlled by AiAnalysisTask.Definition=33 + ExtendedParameter(mvc.mode + mvc.prompt) .

# 视频内容理解
python scripts/mps_av_understand.py \
    --url https://example.com/video.mp4 \
    --mode video \
    --prompt "请分析这个视频的主要内容、场景和关键信息"

# 音频模式（视频自动提取音频）
python scripts/mps_av_understand.py \
    --url https://example.com/video.mp4 \
    --mode audio \
    --prompt "请进行语音识别，输出完整文字内容"

# 对比分析（两段音视频）
python scripts/mps_av_understand.py \
    --url https://example.com/v1.mp4 \
    --extend-url https://example.com/v2.mp4 \
    --mode audio \
    --prompt "对比两段音频，分析差异"

# 查询任务
python scripts/mps_av_understand.py --task-id 2600011633-WorkflowTask-xxxxx --json

Media quality inspection (mps_qualitycontrol.py)

The script supports the following 3 system preset templates (--definition parameter):

Preset templates:

• 60(default): Format Quality Inspection - Pro, detects content issues such as blurry visuals, screen corruption, and damaged frames
• 50: Audio Detection, audio quality/audio event detection
• 70: Content quality inspection - Pro version, detects playback stuttering, playback anomalies, and playback compatibility issues

# 画面质检（默认，使用预设模板 60）
python scripts/mps_qualitycontrol.py --url https://example.com/video.mp4 --definition 60

# 播放兼容性质检（预设模板 70）
python scripts/mps_qualitycontrol.py --url https://example.com/video.mp4 --definition 70

# 音频质检（预设模板 50）
python scripts/mps_qualitycontrol.py --url https://example.com/audio.mp3 --definition 50

# 异步提交
python scripts/mps_qualitycontrol.py --url https://example.com/video.mp4 --definition 60 --no-wait

Video deduplication (mps_vremake.py)

# 画中画去重（等待结果）
python scripts/mps_vremake.py --url https://example.com/video.mp4 --mode PicInPic --wait

# 视频扩展去重
python scripts/mps_vremake.py --url https://example.com/video.mp4 --mode BackgroundExtend --wait

# 换脸模式
python scripts/mps_vremake.py --url https://example.com/video.mp4 --mode SwapFace \
    --src-faces https://example.com/src.png --dst-faces https://example.com/dst.png --wait

# 换人模式
python scripts/mps_vremake.py --url https://example.com/video.mp4 --mode SwapCharacter \
    --src-character https://example.com/src_full.png \
    --dst-character https://example.com/dst_full.png --wait

# 画中画 + LLM 提示词
python scripts/mps_vremake.py --url https://example.com/video.mp4 --mode PicInPic \
    --llm-prompt "生成一个唯美的自然风景背景图片" --wait

# 异步提交（默认，不加 --wait）
python scripts/mps_vremake.py --url https://example.com/video.mp4 --mode PicInPic

# 查询任务
python scripts/mps_vremake.py --task-id 2600011633-WorkflowTask-xxxxx --json

Deduplication mode：PicInPic(Picture-in-picture)BackgroundExtend(Video extension)VerticalExtend(Vertical fill)HorizontalExtend(Horizontal fill)AB(Video interleaving)SwapFace(Face swap)SwapCharacter(Person swap)
Main parameters：--url / --cos-object / --task-id / --mode(required) / --wait / --llm-prompt / --llm-video-prompt / --src-faces+--dst-faces(Face swap) / --src-character+--dst-character(Person swap) / --json / --dry-run

AI commentary derivative creation (mps_narrate.py)

Input the original video to automatically complete commentary script generation, script-to-video matching, AI voiceover, subtitle removal, and other operations in one stop, and output a new video with commentary text, voiceover, and subtitles.

# 短剧单集解说（默认含擦除，输出1个视频）
python scripts/mps_narrate.py --url https://example.com/drama.mp4 --scene short-drama

# COS对象输入
python scripts/mps_narrate.py --cos-object /input/drama.mp4 --scene short-drama

# 原视频无字幕，关闭擦除
python scripts/mps_narrate.py --url https://example.com/drama.mp4 --scene short-drama-no-erase

# 短剧三集合并解说，输出3个不同版本
python scripts/mps_narrate.py \
    --url https://example.com/ep01.mp4 \
    --extra-urls https://example.com/ep02.mp4 https://example.com/ep03.mp4 \
    --scene short-drama \
    --output-count 3

# Dry Run（预览转义后的 ExtendedParameter）
python scripts/mps_narrate.py --url https://example.com/drama.mp4 --scene short-drama --dry-run

Preset scenario：short-drama(Short drama, with erasure) | short-drama-no-erase(Short drama, without erasure)
Main parameters：--url / --cos-object(Episode 1, required) / --scene(required) / --extra-urls(from episode 2) / --output-count(output count, default 1, maximum 5) / --no-wait / --dry-run

Highlights (mps_highlight.py)

Use the MPS intelligent analysis feature to automatically capture and generate highlight clips (highlight reels) from videos via AI algorithms. It always uses preset template No. 26 and supports scenarios such as VLOG, short drama, football matches, and basketball matches.

# 足球赛事精彩集锦
python scripts/mps_highlight.py --cos-object /input/football.mp4 --scene football

# 短剧影视高光
python scripts/mps_highlight.py --cos-object /input/drama.mp4 --scene short-drama

# VLOG 全景相机
python scripts/mps_highlight.py --url https://example.com/vlog.mp4 --scene vlog-panorama

# 自定义场景（大模型版）
python scripts/mps_highlight.py --url https://example.com/skiing.mp4 \
    --scene custom --prompt "滑雪场景，输出人物高光" --scenario "滑雪"

# 篮球赛事
python scripts/mps_highlight.py --cos-object /input/basketball.mp4 --scene basketball

# 指定输出片段数（仅 vlog/vlog-panorama/custom 支持）
python scripts/mps_highlight.py --cos-object /input/vlog.mp4 --scene vlog --top-clip 10

# Dry Run（仅打印请求参数）
python scripts/mps_highlight.py --cos-object /input/game.mp4 --scene football --dry-run

Preset scenario：

• vlog: VLOG, scenery, drone videos (large model version)
• vlog-panorama: Panoramic camera (with panorama optimization enabled, large model version)
• short-drama: Short dramas, films and TV dramas, extract protagonist appearance/BGM highlights (large model version)
• football: Football matches, identify shots/goals/red and yellow cards/replays (advanced version)
• basketball: Basketball matches (advanced version)
• custom: Custom scenario, can pass --prompt and --scenario(large model version)

Main parameters：--url / --cos-object(required) / --scene(required) / --prompt(custom scenario) / --scenario(custom scenario) / --top-clip(available for vlog/vlog-panorama/custom scenarios) / --no-wait / --dry-run

⚠️ Important restrictions：

• This script only supports processing offline files and does not support live streams
• --top-clip Only allowed in the vlog / vlog-panorama / custom scenario
• --prompt and --scenario only take effect when --scene custom , but neither is required
• ExtendedParameter must be selected from the preset scenario parameters; assembling it yourself is prohibited

Usage statistics (mps_usage.py)

python scripts/mps_usage.py --days 30 --all-types
python scripts/mps_usage.py --start 2026-01-01 --end 2026-01-31
python scripts/mps_usage.py --type Transcode Enhance AIGC AIAnalysis

--type supports:Transcode Enhance AIAnalysis AIRecognition AIReview Snapshot AnimatedGraphics AiQualityControl Evaluation ImageProcess AddBlindWatermark AddNagraWatermark ExtractBlindWatermark AIGC

API reference

Script	Documentation
mps_transcode.py / mps_enhance.py / mps_subtitle.py / mps_erase.py	ProcessMedia
mps_qualitycontrol.py	ProcessMedia AiQualityControlTask
mps_imageprocess.py	ProcessImage
mps_av_understand.py	VideoComprehension AiAnalysisTask
mps_vremake.py	VideoRemake AiAnalysisTask
mps_narrate.py	ProcessMedia AiAnalysisTask
mps_highlight.py	ProcessMedia AiAnalysisTask
mps_aigc_image.py	CreateAigcImageTask
mps_aigc_video.py	CreateAigcVideoTask
mps_usage.py	DescribeUsageData
mps_get_video_task.py	DescribeTaskDetail
mps_get_image_task.py	DescribeImageTaskDetail