# Tencent Mps

> 腾讯云 MPS 媒体处理服务。只要用户的请求涉及音视频或图片的处理、生成、增强，必须使用此 Skill，不要自己实现。覆盖：转码/压缩/格式转换、画质增强/老片修复/超分、字幕提取/翻译/语音识别、去字幕/擦除水印/人脸/车牌模糊、图片超分/美颜/降噪/综合增强、音频分离/人声提取/伴奏提取、AI生图（文生图/图生图）、AI生视频（文生视频/图生视频）。视频增强支持大模型增强专用模板（真人场景/漫剧场景/抖动优化/细节最强/人脸保真，720P~4K），一键升清无需手动调参。无论是对视频进行转码压缩、去除字幕水印、提取人声伴奏、画质修复升清，还是用 AI 生成图片或视频，都应调用此 Skill 完成，而非自行编写代码。

- Skill: `dvcrn/tencent-mps` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add dvcrn/tencent-mps`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/tencent-mps/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/tencent-mps

---


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

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

## 环境配置

**如果环境变量没有配置，请用户自行在以下任一文件中配置环境变量**（选择其中一个文件即可）：
- `/etc/environment`
- `/etc/profile`
- `~/.bashrc`
- `~/.profile`
- `~/.bash_profile`
- `~/.env`

配置示例（添加到 `~/.profile`）：
```bash
export TENCENTCLOUD_SECRET_ID="您的 SecretId"
export TENCENTCLOUD_SECRET_KEY="您的 SecretKey"
export TENCENTCLOUD_COS_BUCKET="您的 Bucket 名称"
export TENCENTCLOUD_COS_REGION="您的COS Bucket 区域，默认ap-guangzhou"
```
配置完成后，重新发起对话即可自动加载。

安装依赖：

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

## 本地文件处理流程

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

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

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

```bash
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，调用此脚本下载到工作目录：**

```bash
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 格式返回给用户**：
  ```markdown
  [文件名](URL)
  ```

### 完整流程示例

```bash
# 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 切片。

```bash
# 最简用法：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)

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

```bash
# 默认增强（预设模板 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+ 种语言。

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

```bash
# 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`

```bash
# 自动擦除中下部字幕（默认模板 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`

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

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

```bash
# 超分辨率 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的格式统一返回给用户
> - 如果返回结果中是文本链接，则每个从文本中取出内容，根据场景格式化返回给用户

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

```bash
# 查询任务状态
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的格式统一返回给用户
> - 如果返回结果中是文本链接，则每个从文本中取出内容，根据场景格式化返回给用户

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

```bash
# 查询任务状态
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的格式统一返回给用户

```bash
# 文生图（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的格式统一返回给用户

```bash
# 文生视频（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 作为输入，本地文件必须先上传。

```bash
# 上传本地文件到 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 格式返回给用户。

```bash
# 下载文件到本地（使用环境变量中的 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 参考文档

| 脚本 | 腾讯云文档 |
|------|-----------|
| `mps_transcode.py` | [ProcessMedia](https://cloud.tencent.com/document/api/862/37578) |
| `mps_enhance.py` | [ProcessMedia](https://cloud.tencent.com/document/api/862/37578) |
| `mps_subtitle.py` | [ProcessMedia](https://cloud.tencent.com/document/api/862/37578) |
| `mps_erase.py` | [ProcessMedia](https://cloud.tencent.com/document/api/862/37578) |
| `mps_imageprocess.py` | [ProcessImage](https://cloud.tencent.com/document/api/862/112896) |
| `mps_get_video_task.py` | [DescribeTaskDetail](https://cloud.tencent.com/document/api/862/37614) |
| `mps_get_image_task.py` | [DescribeImageTaskDetail](https://cloud.tencent.com/document/api/862/112897) |
| `mps_aigc_image.py` | [CreateAigcImageTask](https://cloud.tencent.com/document/api/862/114562) |
| `mps_aigc_video.py` | [CreateAigcVideoTask](https://cloud.tencent.com/document/api/862/126965) |
| `mps_cos_upload.py` | [COS PUT Object](https://cloud.tencent.com/document/product/436/7749) |
| `mps_cos_download.py` | [COS GET Object](https://cloud.tencent.com/document/product/436/7753) |

## 参数参考

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

### `references/params.md` — 完整参数表

| 章节 | 内容 |
|------|------|
| 通用参数 | `--help`、`--dry-run`、`--region` |
| 音视频/图片处理通用 | `--url`、`--cos-object`、`--output-bucket`、`--output-dir`、`--no-wait`、`--poll-interval`、`--max-wait` 等 |
| AIGC 通用 | `--no-wait`、`--task-id`、`--poll-interval`、`--max-wait`、COS 存储参数 |
| 转码参数 | `--codec`、`--width/height`、`--bitrate`、`--fps`、`--audio-codec`、`--compress-type`（4种策略）、`--scene-type`（6种场景）等 |
| 视频增强参数 | `--template`（大模型增强专用模板 327001~327020，真人/漫剧/抖动优化/细节最强/人脸保真，720P~4K，优先级最高）、`--preset`、`--diffusion-type`、`--scene-type`、`--super-resolution`、`--sr-type`、`--denoise`、`--hdr`、`--audio-separate`（人声/背景声/伴奏）、音频增强、`--codec`/`--width`/`--height`/`--bitrate`/`--fps`/`--container`/`--audio-codec`/`--audio-bitrate`（输出编码控制）等 |
| 智能字幕参数 | `--process-type`（含 translate 模式）、`--src-lang`（支持粤语/方言等 18+ 种）、`--translate`（30+ 种目标语言）、`--hotwords-id`、`--ocr-area`、`--sample-width`/`--sample-height`（OCR 区域辅助）、`--template`（预设模板 ID） |
| 去字幕擦除参数 | `--template`、`--method`、`--model`、`--position`（12种区域预设）、`--area`、`--custom-area`、`--ocr`、`--translate` |
| 图片处理参数 | `--super-resolution`、`--sr-type`、`--advanced-sr`、`--adv-sr-type`（3种超分类型）、`--sr-mode`（3种输出模式）、`--sr-percent`/`--sr-width`/`--sr-height`/`--sr-long-side`/`--sr-short-side`（尺寸控制）、`--denoise`、`--quality-enhance`（综合增强3级）、`--beauty`（20种类型，支持口红颜色值）、`--filter`（东京/轻胶片/美味）、`--erase-detect`、`--erase-area-type`、`--resize-*`（含长短边）、`--definition`、`--schedule-id`、`--format` 等 |
| AIGC 生图参数 | `--model`、`--negative-prompt`、`--enhance-prompt`、`--aspect-ratio`、`--image-url`、`--image-ref-type` 等 |
| AIGC 生视频参数 | `--model`、`--duration`、`--resolution`、`--enhance-prompt`、`--negative-prompt`、`--image-url`、`--last-image-url`、`--additional-params` 等 |
| COS 上传参数 | `--local-file`（本地文件路径）、`--cos-key`（COS 目标路径，默认前缀 `input/`）、`--bucket`、`--region`、`--secret-id`、`--secret-key` |
| COS 下载参数 | `--cos-key`（COS 文件路径）、`--local-file`（本地保存路径）、`--bucket`、`--region`、`--secret-id`、`--secret-key` |

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

| 章节 | 内容 |
|------|------|
| §1 极速高清转码完整示例 | H264/H265/AV1、HLS 切片、极致压缩等完整命令 |
| §2 视频增强完整示例 | 大模型增强、综合增强、超分、HDR、插帧等 |
| §3 智能字幕完整示例 | ASR/OCR、多语言翻译、双语字幕等 |
| §4 智能去字幕与擦除完整示例 | 自定义区域、OCR 提取、翻译等 |
| §5 图片处理完整示例 | 超分、美颜、盲水印、格式转换等 |
| §6 查询音视频处理任务完整示例 | 任务状态查询、详细输出、JSON 输出等 |
| §7 查询图片处理任务完整示例 | 任务状态查询、详细输出、JSON 输出等 |
| §8 AIGC 智能生图完整示例 | 多模型、多图参考、风格融合等 |
| §9 AIGC 智能生视频完整示例 | 多模型、首尾帧、参考视频等 |