腾讯云媒体处理服务（MPS）

通过腾讯云官方 Python SDK（tencentcloud-sdk-python）调用 MPS API，实现音视频转码、视频增强、智能字幕、智能去字幕与擦除、图片处理、AIGC 智能生图、AIGC 智能生视频等全面的媒体处理能力。

环境配置

执行任何脚本前，建议先检查环境变量是否已正确加载：

python scripts/load_env.py --check-only

如果环境变量没有配置，请用户自行在以下任一文件中配置环境变量（选择其中一个文件即可）：

• /etc/environment
• /etc/profile
• ~/.bashrc
• ~/.profile
• ~/.bash_profile
• ~/.env

配置示例（添加到 ~/.profile）：

export TENCENTCLOUD_SECRET_ID="您的 SecretId"
export TENCENTCLOUD_SECRET_KEY="您的 SecretKey"
export TENCENTCLOUD_COS_BUCKET="您的COS Bucket 名称"
export TENCENTCLOUD_COS_REGION="您的COS Bucket 区域，默认ap-guangzhou"

配置完成后，重新发起对话即可自动加载。

安装依赖：

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

本地文件处理流程

重要：MPS 服务只接受 COS 上的文件作为输入。如果用户提供的是本地文件路径，必须按以下流程处理：

1. 上传本地文件到 COS — scripts/mps_cos_upload.py

执行任何 MPS 任务前，如果输入是本地文件，先调用此脚本上传：

python scripts/mps_cos_upload.py --local-file /path/to/local/video.mp4 --cos-key input/video.mp4 --verbose

• --local-file：本地文件路径（必填）
• --cos-key：COS 上的目标路径，默认前缀使用 input/（必填）
• 上传成功后，脚本会返回文件的 COS URL，用于后续的 MPS 处理

2. 下载处理结果到本地 — scripts/mps_cos_download.py

MPS 任务完成后，如果结果包含 COS URL，调用此脚本下载到工作目录：

python scripts/mps_cos_download.py --cos-key output/result.mp4 --local-file ./result.mp4 --verbose

• --cos-key：COS 上的文件路径（从 MPS 返回结果中获取）
• --local-file：本地保存路径（建议保存到工作目录 /data/workspace/ 下）
• 下载成功后，将文件的 URL 按 Markdown 格式返回给用户：

  [文件名](URL)
  

完整流程示例

# 1. 上传本地文件
python scripts/mps_cos_upload.py --local-file ./my-video.mp4 --cos-key input/my-video.mp4

# 2. 使用上传后的 COS URL 执行 MPS 任务（如转码）
python scripts/mps_transcode.py --url https://<bucket>.cos.<region>.myqcloud.com/input/my-video.mp4

# 3. 任务完成后，下载结果
python scripts/mps_cos_download.py --cos-key output/my-video-transcoded.mp4 --local-file ./my-video-transcoded.mp4

# 4. 向用户返回 Markdown 格式的结果链接

可用脚本

所有脚本位于 scripts/ 目录下，均支持 --help 查看完整参数、--dry-run 模式仅打印请求参数不实际调用。

⏳ 异步任务说明：音视频处理类脚本（转码、增强、字幕、擦除）和图片处理脚本均为异步接口，提交后在后台执行。 脚本默认会自动轮询等待，直到任务完成后打印结果，无需 Agent 手动启动查询。

• 如果只想提交不等待，加 --no-wait 参数，脚本会打印 TaskId 后立即退出
• 需要手动查询时：音视频任务用 mps_get_video_task.py，图片任务用 mps_get_image_task.py
• 默认轮询间隔：音视频 10 秒，图片 5 秒；可通过 --poll-interval 和 --max-wait 调整

1. 极速高清转码 — scripts/mps_transcode.py

在保证画质的基础上最大限度压缩码率和文件大小，节约带宽与存储成本。默认使用 100305 预设模板（极速高清-H265-MP4-1080P）。

适用场景：视频转码压缩、格式转换、分辨率/码率调整、HLS 切片。

# 最简用法：URL 输入 + 默认模板
python scripts/mps_transcode.py --url https://example.com/video.mp4

# 自定义：H265 + 1080P + 3000kbps
python scripts/mps_transcode.py --url https://example.com/video.mp4 \
    --codec h265 --width 1920 --height 1080 --bitrate 3000

2. 视频增强 — scripts/mps_enhance.py

支持大模型增强、综合增强、去毛刺三种预设模式，以及超分、降噪、色彩增强、HDR、插帧、音频增强等丰富能力。音频分离支持提取人声、背景声、伴奏三种模式。

新增：大模型增强专用模板（327001 至 327020），内置降噪+超分+综合增强，按场景和分辨率细分，直接用 --template 指定即可，无需手动组合参数：

• 真人场景（Real）：适合真人实拍，保护人脸与文字区域 → 327001(720P) 327003(1080P) 327005(2K) 327007(4K)
• 漫剧场景（Anime）：适合动漫风格，增强线条色块特征 → 327002(720P) 327004(1080P) 327006(2K) 327008(4K)
• 抖动优化（JitterOpt）：减少帧间抖动与纹理跳变 → 327009(720P) 327010(1080P) 327011(2K) 327012(4K)
• 细节最强（DetailMax）：最大化纹理细节还原 → 327013(720P) 327014(1080P) 327015(2K) 327016(4K)
• 人脸保真（FaceFidelity）：最大程度保留人脸五官细节 → 327017(720P) 327018(1080P) 327019(2K) 327020(4K)

适用场景：老片修复、画质提升、低光照增强、游戏视频优化、人声/伴奏提取、真人/动漫超清修复。

# 默认增强（预设模板 321002）
python scripts/mps_enhance.py --url https://example.com/video.mp4

# 大模型增强专用模板：真人场景升至 1080P（推荐用于真人实拍视频）
python scripts/mps_enhance.py --url https://example.com/video.mp4 --template 327003

# 大模型增强专用模板：漫剧场景升至 4K（推荐用于动漫视频）
python scripts/mps_enhance.py --url https://example.com/video.mp4 --template 327008

# 大模型增强专用模板：人脸保真升至 2K（推荐用于人像/写真视频）
python scripts/mps_enhance.py --url https://example.com/video.mp4 --template 327019

# 大模型增强（效果最强，自定义参数模式）
python scripts/mps_enhance.py --url https://example.com/video.mp4 --preset diffusion --diffusion-type strong

# 超分 + 降噪 + 色彩增强（注意：--super-resolution 和 --denoise 不可与 --preset diffusion 同时使用）
python scripts/mps_enhance.py --url https://example.com/video.mp4 --super-resolution --denoise --color-enhance

# 音频分离：提取人声
python scripts/mps_enhance.py --url https://example.com/video.mp4 --audio-separate vocal

# 音频分离：提取伴奏
python scripts/mps_enhance.py --url https://example.com/video.mp4 --audio-separate accompaniment

3. 智能字幕 — scripts/mps_subtitle.py

基于 ASR 语音识别、OCR 文字识别提取字幕，支持大模型翻译为 30+ 种语言。

适用场景：视频译制、短剧出海、字幕提取、多语言翻译。

# ASR 识别字幕（默认）
python scripts/mps_subtitle.py --url https://example.com/video.mp4

# ASR + 翻译为英文（双语字幕）
python scripts/mps_subtitle.py --url https://example.com/video.mp4 --src-lang zh --translate en

4. 智能去字幕与擦除 — scripts/mps_erase.py

自动识别视频中的文字内容并进行无痕擦除，支持去字幕、去水印、人脸/车牌模糊等多种模板，以及自定义区域、OCR 提取、字幕翻译。

适用场景：视频译制去原字幕、短剧出海、去除水印/LOGO、人脸隐私保护、车牌打码。

预设模板（--template）：

• 101 去字幕（默认）— 自动擦除 + 标准模型
• 102 去字幕并提取OCR字幕 — 自动擦除 + OCR提取
• 201 去水印-高级版 — 高级水印擦除
• 301 人脸模糊 — 自动识别并模糊人脸
• 302 人脸和车牌模糊 — 自动识别并模糊人脸和车牌

区域预设（--position，仅模板 101/102 支持）：

• 默认识别视频中下部区域（不传 --position 即可）；若字幕位置不在中下部，需通过 --position 或 --area 指定
• 支持 12 种预设：top、bottom、left、right、center、top-left、top-right、bottom-left、bottom-right、top-half、bottom-half、fullscreen

# 自动擦除中下部字幕（默认模板 101）
python scripts/mps_erase.py --url https://example.com/video.mp4

# 去字幕并提取OCR字幕（模板 102）
python scripts/mps_erase.py --url https://example.com/video.mp4 --template 102

# 去水印-高级版（模板 201）
python scripts/mps_erase.py --url https://example.com/video.mp4 --template 201

# 人脸模糊（模板 301）
python scripts/mps_erase.py --url https://example.com/video.mp4 --template 301

# 人脸和车牌模糊（模板 302）
python scripts/mps_erase.py --url https://example.com/video.mp4 --template 302

# 去字幕 + OCR 提取 + 翻译为英文
python scripts/mps_erase.py --url https://example.com/video.mp4 --ocr --translate en

# 指定字幕位置（底部/顶部/左右/四角等12种预设）
python scripts/mps_erase.py --url https://example.com/video.mp4 --position bottom
python scripts/mps_erase.py --url https://example.com/video.mp4 --position top-right

5. 图片处理 — scripts/mps_imageprocess.py

支持图片增强、超分辨率、降噪、美颜、滤镜、擦除、盲水印、缩放等全面的图片处理能力。

适用场景：图片画质提升、人像美化、水印擦除、盲水印保护、格式转换与缩放。

# 超分辨率 2 倍放大
python scripts/mps_imageprocess.py --url https://example.com/image.jpg --super-resolution

# 综合增强（整体画质提升）
python scripts/mps_imageprocess.py --url https://example.com/image.jpg --quality-enhance normal

# 自动擦除水印/logo/文字
python scripts/mps_imageprocess.py --url https://example.com/image.jpg --erase-detect watermark

# 添加隐形盲水印（版权保护）；水印文字最多 4 字节（约 1 个中文字或 4 个 ASCII 字符）
python scripts/mps_imageprocess.py --url https://example.com/image.jpg --add-watermark "MPS"

# 格式转换为 WebP + 质量 80（网页优化）
python scripts/mps_imageprocess.py --url https://example.com/image.jpg --format WebP --quality 80

# 缩放至指定尺寸（等比缩放至宽 1920）
python scripts/mps_imageprocess.py --url https://example.com/image.jpg --resize-long-side 1920

# 美颜（美白 + 瘦脸 + 大眼）
python scripts/mps_imageprocess.py --url https://example.com/image.jpg \
    --beauty Whiten:50 --beauty BeautyThinFace:30 --beauty EnlargeEye:40

6. 查询音视频处理任务状态 — scripts/mps_get_video_task.py

查询由 ProcessMedia 接口（转码、增强、字幕、擦除等脚本）提交的异步任务的执行状态和结果详情。最多可查询 7 天内的任务。

⚠️ 任务 ID 格式说明：此脚本仅适用于 1234567890-WorkflowTask-xxxxxx 格式的任务 ID（音视频处理任务）。

• AIGC 生视频任务的 ID 格式为 1234567890-xxxxxx，应使用 mps_aigc_video.py --task-id 查询
• 图片处理任务的 ID 格式为 1234567890-xxxxxx，应使用 mps_get_image_task.py 查询
• 如果返回结果中是图片/视频链接，则每个URL包装成markdown的格式统一返回给用户
• 如果返回结果中是文本链接，则每个从文本中取出内容，根据场景格式化返回给用户

适用场景：手动查询任务进度（各处理脚本已内置自动轮询，通常无需手动调用）。

# 查询任务状态
python scripts/mps_get_video_task.py --task-id 2600011633-WorkflowTask-80108cc3380155d98b2e3573a48a

# 输出完整 JSON 响应（含所有子任务详情）
python scripts/mps_get_video_task.py --task-id <TaskId> --verbose

# 仅输出原始 JSON（方便程序解析，不打印格式化摘要）
python scripts/mps_get_video_task.py --task-id <TaskId> --json

7. 查询图片处理任务状态 — scripts/mps_get_image_task.py

查询由 ProcessImage 接口（图片处理脚本）提交的异步任务的执行状态和结果详情。最多可查询 7 天内的任务。

⚠️ 任务 ID 格式说明：此脚本仅适用于 1234567890-xxxxxx 格式的任务 ID（图片处理任务）。

• AIGC 生图任务的 ID 格式为 1234567890-xxxxxx，应使用 mps_aigc_image.py --task-id 查询
• 音视频处理任务的 ID 格式为 1234567890-xxxxxx，应使用 mps_get_video_task.py 查询
• 如果返回结果中是图片/视频链接，则每个URL包装成markdown的格式统一返回给用户
• 如果返回结果中是文本链接，则每个从文本中取出内容，根据场景格式化返回给用户

适用场景：手动查询任务进度（图片处理脚本已内置自动轮询，通常无需手动调用）。

# 查询任务状态
python scripts/mps_get_image_task.py --task-id 2600011633-ImageTask-80108cc3380155d98b2e3573a48a

# 输出完整 JSON 响应（含所有子任务详情）
python scripts/mps_get_image_task.py --task-id <TaskId> --verbose

# 仅输出原始 JSON（方便程序解析，不打印格式化摘要）
python scripts/mps_get_image_task.py --task-id <TaskId> --json

8. AIGC 智能生图 — scripts/mps_aigc_image.py

通过文本描述和/或参考图片生成图片，汇聚 Hunyuan、GEM、Qwen 三大模型能力。

适用场景：文生图、图生图、多图风格融合、创意设计、营销海报。

⏳ 异步任务：脚本默认自动轮询等待生成完成（约 10 至 60 秒），结果直接打印。加 --no-wait 可仅提交不等待，之后用 --task-id <TaskId> 如果返回结果中是图片/视频链接，则每个URL包装成markdown的格式统一返回给用户

# 文生图（Hunyuan 默认）
python scripts/mps_aigc_image.py --prompt "一只可爱的橘猫在阳光下打盹"

# 图生图（参考图片 + 描述）
python scripts/mps_aigc_image.py --prompt "将这张照片变成油画风格" \
    --image-url https://example.com/photo.jpg

9. AIGC 智能生视频 — scripts/mps_aigc_video.py

通过文本、图片、视频等输入生成视频，汇聚 Hunyuan、Hailuo、Kling、Vidu、OS、GV 六大模型能力。

适用场景：文生视频、图生视频、首尾帧动画、视频风格化、产品展示、短视频创作。

⏳ 异步任务：脚本默认自动轮询等待生成完成（约 1 至 5 分钟），结果直接打印。加 --no-wait 可仅提交不等待，之后用 --task-id <TaskId> 查询结果。如果返回结果中是图片/视频链接，则每个URL包装成markdown的格式统一返回给用户

# 文生视频（Hunyuan 默认）
python scripts/mps_aigc_video.py --prompt "一只猫在阳光下伸懒腰"

# 图生视频（首帧图片 + 描述）
python scripts/mps_aigc_video.py --prompt "让画面动起来" \
    --image-url https://example.com/photo.jpg

10. COS 文件上传 — scripts/mps_cos_upload.py

将本地文件上传到腾讯云 COS，供 MPS 处理使用。

适用场景：上传本地视频/图片到 COS，作为 MPS 任务的输入。

注意：所有音视频/图片处理脚本只接受 COS URL 作为输入，本地文件必须先上传。

# 上传本地文件到 COS（使用环境变量中的 bucket）
python scripts/mps_cos_upload.py --local-file ./video.mp4 --cos-key input/video.mp4 --verbose

# 指定 bucket 和 region
python scripts/mps_cos_upload.py --local-file ./video.mp4 --cos-key input/video.mp4 \
    --bucket mybucket-125xxx --region ap-guangzhou

# 使用自定义密钥（覆盖环境变量）
python scripts/mps_cos_upload.py --local-file ./video.mp4 --cos-key input/video.mp4 \
    --secret-id AKIDxxx --secret-key xxxxx

11. COS 文件下载 — scripts/mps_cos_download.py

从腾讯云 COS 下载文件到本地工作目录。

适用场景：MPS 任务完成后，将处理结果下载到本地。

注意：下载完成后，将文件 URL 按 Markdown 格式返回给用户。

# 下载文件到本地（使用环境变量中的 bucket）
python scripts/mps_cos_download.py --cos-key output/result.mp4 --local-file ./result.mp4 --verbose

# 指定 bucket 和 region
python scripts/mps_cos_download.py --cos-key output/result.mp4 --local-file ./result.mp4 \
    --bucket mybucket-125xxx --region ap-guangzhou

# 使用自定义密钥（覆盖环境变量）
python scripts/mps_cos_download.py --cos-key output/result.mp4 --local-file ./result.mp4 \
    --secret-id AKIDxxx --secret-key xxxxx

API 参考文档

参数参考

需要查看详细参数时，请读取以下 references 文档：

references/params.md — 完整参数表

references/scripts-detail.md — 各脚本完整示例集