426 lines
15 KiB
Markdown
426 lines
15 KiB
Markdown
# AI媒体处理命令行工具
|
||
|
||
`媒体处理` `图像生成` `视频生成` `音频转录` `AI工具` `CLI`
|
||
|
||
# agent-media
|
||
|
||
面向 AI 代理的媒体处理命令行工具。
|
||
|
||
- **图像**：生成、编辑、去除背景、超分辨率放大、调整尺寸、格式转换、扩展画布、裁剪
|
||
- **视频**：生成（文本生成视频 & 图像生成视频）
|
||
- **音频**：从视频中提取、转录（支持说话人识别）
|
||
|
||
## 安装
|
||
|
||
### 全局安装
|
||
|
||
```bash
|
||
npm install -g agent-media@latest
|
||
```
|
||
|
||
### 从源码安装
|
||
|
||
```bash
|
||
git clone https://github.com/agntswrm/agent-media
|
||
cd agent-media
|
||
pnpm install && pnpm build && pnpm link --global
|
||
```
|
||
|
||
### 通过 bunx / npx 使用
|
||
|
||
无需安装，直接运行：
|
||
|
||
```bash
|
||
bunx agent-media@latest --help
|
||
npx agent-media@latest --help
|
||
```
|
||
|
||
### 为 AI 代理安装技能
|
||
|
||
将 agent-media 技能安装到你的编程代理（Claude Code、Cursor、Codex 等）：
|
||
|
||
```bash
|
||
npx skills add agntswrm/agent-media
|
||
```
|
||
|
||
这将为你的 AI 代理添加媒体处理技能，可自动调用。可用技能如下：
|
||
- `agent-media` - 所有功能概览
|
||
- `image-generate` - 从文本生成图像
|
||
- `image-edit` - 使用文本提示编辑图像
|
||
- `image-resize` - 调整图像尺寸
|
||
- `image-convert` - 转换图像格式
|
||
- `image-extend` - 通过填充扩展图像画布
|
||
- `image-remove-background` - 去除背景
|
||
- `image-crop` - 裁剪图像至指定尺寸
|
||
- `image-upscale` - 使用 AI 超分辨率放大图像
|
||
- `audio-extract` - 从视频中提取音频
|
||
- `audio-transcribe` - 将音频转录为文本
|
||
- `video-generate` - 从文本或图像生成视频
|
||
|
||
## 快速上手
|
||
|
||
```bash
|
||
# 生成图像
|
||
agent-media image generate --prompt "a robot" --out rob.png
|
||
|
||
# 去除背景
|
||
agent-media image remove-background --in rob.png --out rob_nobg.png
|
||
|
||
# 编辑图像
|
||
agent-media image edit --in rob_nobg.png --prompt "the robot is sitting on a bench next to a cat, in the background you can see the Eiffel Tower in Paris" --out rob_cat_paris.png
|
||
|
||
# 生成带音频的视频（猫叫声，机器人说话！）
|
||
agent-media video generate --in rob_cat_paris.png --prompt "the cat meows and the robot says: \"Yes, me too.\"" --audio --out rob_cat_video.mp4
|
||
|
||
# 从视频中提取音频
|
||
agent-media audio extract --in rob_cat_video.mp4 --out rob_cat_audio.mp3
|
||
|
||
# 转录音频
|
||
agent-media audio transcribe --in rob_cat_audio.mp3
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- Node.js >= 18.0.0
|
||
- 使用 AI 功能需要来自 [fal.ai](https://fal.ai/dashboard/keys)、[Replicate](https://replicate.com/account/api-tokens)、[Runpod](https://www.runpod.io/console/user/settings) 或 [AI Gateway](https://vercel.com/ai-gateway) 的 API 密钥
|
||
|
||
**本地处理**（无需 API 密钥）：调整尺寸、格式转换、扩展画布、裁剪、超分辨率放大、音频提取、去除背景、转录
|
||
|
||
**云端处理**（需要 API 密钥）：图像生成、图像编辑、超分辨率放大、视频生成、去除背景、转录
|
||
|
||
> **注意**：使用本地去除背景、放大或转录时，可能会看到 `mutex lock failed` 错误——忽略即可，若 JSON 显示 `"ok": true` 则输出正常。
|
||
|
||
---
|
||
|
||
## image（图像）
|
||
|
||
```bash
|
||
agent-media image resize --in <路径> [选项]
|
||
agent-media image convert --in <路径> --format <格式>
|
||
agent-media image extend --in <路径> --padding <像素> --color <十六进制颜色>
|
||
agent-media image crop --in <路径> --width <像素> --height <像素>
|
||
agent-media image generate --prompt <文本>
|
||
agent-media image edit --in <路径...> --prompt <文本>
|
||
agent-media image remove-background --in <路径>
|
||
agent-media image upscale --in <路径>
|
||
```
|
||
|
||
### resize（调整尺寸）
|
||
|
||
*本地处理*
|
||
|
||
```bash
|
||
agent-media image resize --in sunset-mountains.jpg --width 800
|
||
agent-media image resize --in sunset-mountains.jpg --height 600
|
||
agent-media image resize --in https://ytrzap04kkm0giml.public.blob.vercel-storage.com/sunset-mountains.jpg --width 800
|
||
```
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--in <路径>` | 输入文件路径或 URL（必填） |
|
||
| `--width <像素>` | 目标宽度（像素） |
|
||
| `--height <像素>` | 目标高度（像素） |
|
||
| `--out <路径>` | 输出路径、文件名或目录（默认：./） |
|
||
|
||
### convert（格式转换）
|
||
|
||
*本地处理*
|
||
|
||
```bash
|
||
agent-media image convert --in sunset-mountains.png --format webp
|
||
agent-media image convert --in sunset-mountains.jpg --format png
|
||
agent-media image convert --in https://ytrzap04kkm0giml.public.blob.vercel-storage.com/sunset-mountains.png --format jpg --quality 90
|
||
```
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--in <路径>` | 输入文件路径或 URL（必填） |
|
||
| `--format <格式>` | 输出格式：png、jpg、webp（必填） |
|
||
| `--quality <数值>` | 有损格式的质量 1-100（默认：80） |
|
||
| `--out <路径>` | 输出路径、文件名或目录（默认：./） |
|
||
|
||
### extend（扩展画布）
|
||
|
||
*本地处理*
|
||
|
||
在图像四周添加指定颜色的纯色填充，扩展画布尺寸。
|
||
|
||
```bash
|
||
agent-media image extend --in sunset-mountains.jpg --padding 50 --color "#E4ECF8"
|
||
agent-media image extend --in https://ytrzap04kkm0giml.public.blob.vercel-storage.com/sunset-mountains.png --padding 100 --color "#FFFFFF"
|
||
```
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--in <路径>` | 输入文件路径或 URL（必填） |
|
||
| `--padding <像素>` | 四周各添加的填充像素数（必填） |
|
||
| `--color <十六进制>` | 扩展区域的背景颜色（必填），同时会合并透明度。 |
|
||
| `--dpi <数值>` | 输出图像的 DPI/分辨率（默认：300） |
|
||
| `--out <路径>` | 输出路径、文件名或目录（默认：./） |
|
||
|
||
### crop（裁剪）
|
||
|
||
*本地处理*
|
||
|
||
以焦点为中心裁剪图像至指定尺寸。裁剪区域以焦点为中心计算，同时保持在图像边界内。
|
||
|
||
```bash
|
||
agent-media image crop --in sunset-mountains.jpg --width 800 --height 600
|
||
agent-media image crop --in sunset-mountains.jpg --width 800 --height 600 --focus-x 20 --focus-y 30
|
||
agent-media image crop --in https://ytrzap04kkm0giml.public.blob.vercel-storage.com/sunset-mountains.jpg --width 400 --height 400
|
||
```
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--in <路径>` | 输入文件路径或 URL（必填） |
|
||
| `--width <像素>` | 裁剪区域宽度（像素，必填） |
|
||
| `--height <像素>` | 裁剪区域高度（像素，必填） |
|
||
| `--focus-x <数值>` | 焦点 X 坐标 0-100（默认：50 = 居中） |
|
||
| `--focus-y <数值>` | 焦点 Y 坐标 0-100（默认：50 = 居中） |
|
||
| `--dpi <数值>` | 输出图像的 DPI/分辨率（默认：300） |
|
||
| `--out <路径>` | 输出路径、文件名或目录（默认：./） |
|
||
|
||
### generate（生成）
|
||
|
||
*需要 API 密钥*
|
||
|
||
```bash
|
||
agent-media image generate --prompt "a cat wearing a hat"
|
||
agent-media image generate --prompt "sunset over mountains" --width 1024 --height 768
|
||
```
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--prompt <文本>` | 文字描述（必填） |
|
||
| `--width <像素>` | 宽度（默认：1280） |
|
||
| `--height <像素>` | 高度（默认：720） |
|
||
| `--out <路径>` | 输出路径、文件名或目录（默认：./） |
|
||
| `--provider <名称>` | 服务商（fal、replicate、runpod、ai-gateway） |
|
||
| `--model <名称>` | 模型覆盖（如 `fal-ai/flux-2`、`bfl/flux-2-pro`） |
|
||
|
||
### edit（编辑）
|
||
|
||
*需要 API 密钥*
|
||
|
||
使用文本提示编辑一张或多张图像（图像到图像）。支持多张输入图像，用于融合风格、主体或场景。
|
||
|
||
```bash
|
||
agent-media image edit --in sunset-mountains.jpg --prompt "make the sky more vibrant"
|
||
agent-media image edit --in https://ytrzap04kkm0giml.public.blob.vercel-storage.com/man-portrait.png --prompt "add sunglasses"
|
||
agent-media image edit --in style.jpg content.jpg --prompt "apply the style of the first image to the second"
|
||
```
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--in <路径...>` | 一张或多张输入文件路径或 URL（必填） |
|
||
| `--prompt <文本>` | 所需编辑效果的文字描述（必填） |
|
||
| `--out <路径>` | 输出路径、文件名或目录（默认：./） |
|
||
| `--provider <名称>` | 服务商（fal、replicate、runpod、ai-gateway） |
|
||
| `--model <名称>` | 模型覆盖（如 `fal-ai/flux-2/edit`、`google/gemini-3-pro-image`） |
|
||
|
||
### remove-background（去除背景）
|
||
|
||
*本地或云端处理*
|
||
|
||
```bash
|
||
agent-media image remove-background --in man-portrait.png
|
||
agent-media image remove-background --in https://ytrzap04kkm0giml.public.blob.vercel-storage.com/man-portrait.png
|
||
```
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--in <路径>` | 输入文件路径或 URL（必填） |
|
||
| `--out <路径>` | 输出路径、文件名或目录（默认：./） |
|
||
| `--provider <名称>` | 服务商（local、fal、replicate） |
|
||
|
||
### upscale（超分辨率放大）
|
||
|
||
*本地或云端处理*
|
||
|
||
使用 AI 超分辨率技术放大图像，在提升分辨率的同时生成细节。
|
||
|
||
```bash
|
||
agent-media image upscale --in sunset-mountains.jpg
|
||
agent-media image upscale --in sunset-mountains.jpg --scale 4 --provider fal
|
||
agent-media image upscale --in https://ytrzap04kkm0giml.public.blob.vercel-storage.com/sunset-mountains.jpg --provider replicate
|
||
```
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--in <路径>` | 输入文件路径或 URL（必填） |
|
||
| `--scale <数值>` | 放大倍数：2 或 4（默认：2）。本地模式始终输出 4 倍。 |
|
||
| `--out <路径>` | 输出路径、文件名或目录（默认：./） |
|
||
| `--provider <名称>` | 服务商（local、fal、replicate） |
|
||
| `--model <名称>` | 模型覆盖 |
|
||
|
||
---
|
||
|
||
## video（视频）
|
||
|
||
```bash
|
||
# 从文本生成视频
|
||
agent-media video generate --prompt <文本>
|
||
|
||
# 从图像生成视频（为图像添加动效）
|
||
agent-media video generate --in <图像> --prompt <文本>
|
||
```
|
||
|
||
### generate（生成）
|
||
|
||
*需要 API 密钥*
|
||
|
||
从文本提示生成视频。可选择提供输入图像为其添加动效（图像生成视频）。提示词描述视频中应发生的内容。
|
||
|
||
```bash
|
||
# 文本生成视频
|
||
agent-media video generate --prompt "a cat walking through a garden"
|
||
|
||
# 图像生成视频（为图像添加动效）
|
||
agent-media video generate --in woman-portrait.png --prompt "person smiles and waves hello"
|
||
|
||
# 带音频/语音生成（runpod）
|
||
agent-media video generate --in woman-portrait.png --prompt "The woman says: \"Hello, welcome to our channel!\"" --audio --provider runpod
|
||
|
||
# 带环境音效（fal）
|
||
agent-media video generate --prompt "fireworks in the night sky" --audio --duration 10 --provider fal
|
||
|
||
# 更高分辨率
|
||
agent-media video generate --prompt "ocean waves" --resolution 1080p
|
||
```
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--prompt <文本>` | 视频的文字描述（必填） |
|
||
| `--in <路径>` | 图像生成视频的输入图像（可选） |
|
||
| `--duration <秒>` | 时长（默认：runpod 为 5 秒，其他为 6 秒） |
|
||
| `--resolution <分辨率>` | 分辨率：720p、1080p（默认：720p） |
|
||
| `--fps <数值>` | 帧率：25、50（默认：25） |
|
||
| `--audio` | 生成音轨（使用 runpod 时，引号中的文本将生成语音） |
|
||
| `--out <路径>` | 输出路径、文件名或目录（默认：./） |
|
||
| `--provider <名称>` | 服务商（fal、replicate、runpod） |
|
||
| `--model <名称>` | 模型覆盖 |
|
||
|
||
---
|
||
|
||
## audio（音频）
|
||
|
||
```bash
|
||
# 从视频中提取音频
|
||
agent-media audio extract --in <视频>
|
||
|
||
# 将音频转录为文本
|
||
agent-media audio transcribe --in <音频>
|
||
```
|
||
|
||
### extract（提取）
|
||
|
||
*本地处理*
|
||
|
||
从视频文件中提取音轨。
|
||
|
||
```bash
|
||
agent-media audio extract --in woman-greeting.mp4
|
||
agent-media audio extract --in woman-greeting.mp4 --format wav
|
||
agent-media audio extract --in https://ytrzap04kkm0giml.public.blob.vercel-storage.com/woman-greeting.mp4
|
||
```
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--in <路径>` | 输入视频文件路径或 URL（必填） |
|
||
| `--format <格式>` | 输出格式：mp3、wav（默认：mp3） |
|
||
| `--out <路径>` | 输出路径、文件名或目录（默认：./） |
|
||
|
||
### transcribe（转录）
|
||
|
||
*本地或云端处理（说话人识别需要云端）*
|
||
|
||
将音频转录为带时间戳的文本。说话人识别（分离）需要使用云端服务商。
|
||
|
||
```bash
|
||
agent-media audio transcribe --in woman-greeting.mp3
|
||
agent-media audio transcribe --in woman-greeting.mp3 --diarize --speakers 2
|
||
agent-media audio transcribe --in https://ytrzap04kkm0giml.public.blob.vercel-storage.com/woman-greeting.mp3
|
||
```
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--in <路径>` | 输入音频文件路径或 URL（必填） |
|
||
| `--diarize` | 启用说话人识别（仅限云端） |
|
||
| `--language <代码>` | 语言代码（未提供时自动检测） |
|
||
| `--speakers <数值>` | 说话人数量提示 |
|
||
| `--out <路径>` | 输出路径、文件名或目录（默认：./） |
|
||
| `--provider <名称>` | 服务商（local、fal、replicate） |
|
||
| `--model <名称>` | 模型覆盖 |
|
||
|
||
---
|
||
|
||
## 输出格式
|
||
|
||
所有命令均向标准输出返回 JSON：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"media_type": "image",
|
||
"action": "resize",
|
||
"provider": "local",
|
||
"output_path": "resized_123_abc.png",
|
||
"mime": "image/png",
|
||
"bytes": 45678
|
||
}
|
||
```
|
||
|
||
发生错误时：
|
||
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error": {
|
||
"code": "INVALID_INPUT",
|
||
"message": "At least one of width or height must be specified"
|
||
}
|
||
}
|
||
```
|
||
|
||
成功时退出码为 `0`，出错时为 `1`。
|
||
|
||
## 服务商
|
||
|
||
### 默认模型
|
||
|
||
| 服务商 | resize | convert | extend | crop | 图像生成 | 图像编辑 | 去除背景 | 放大 | 视频生成 | 转录 |
|
||
|--------|--------|---------|--------|------|----------|----------|----------|------|----------|------|
|
||
| **local** | ✓* | ✓* | ✓* | ✓* | - | - | `Xenova/modnet`** | `Xenova/swin2SR`** | - | `moonshine-base`** |
|
||
| **fal** | - | - | - | - | `fal-ai/flux-2` | `fal-ai/flux-2/edit` | `fal-ai/birefnet/v2` | `fal-ai/esrgan` | `fal-ai/ltx-2` | `fal-ai/wizper` |
|
||
| **replicate** | - | - | - | - | `black-forest-labs/flux-2-dev` | `black-forest-labs/flux-kontext-dev` | `men1scus/birefnet` | `nightmareai/real-esrgan` | `lightricks/ltx-video` | `whisper-diarization` |
|
||
| **runpod** | - | - | - | - | `alibaba/wan-2.6` | `google/nano-banana-pro-edit` | - | - | `wan-2.6` | - |
|
||
| **ai-gateway** | - | - | - | - | `bfl/flux-2-pro` | `google/gemini-3-pro-image` | - | - | - | - |
|
||
|
||
\* 由 [Sharp](https://sharp.pixelplumbing.com/) 驱动，提供快速图像处理
|
||
\** 由 [Transformers.js](https://huggingface.co/docs/transformers.js) 驱动，支持本地机器学习推理（首次使用时自动下载模型）
|
||
|
||
使用 `--model <名称>` 可覆盖任意命令的默认模型。
|
||
|
||
### 服务商选择规则
|
||
|
||
1. **显式标志**（最高优先级）：`--provider fal`
|
||
2. **环境变量自动检测**：设置 `FAL_API_KEY`、`REPLICATE_API_TOKEN`、`RUNPOD_API_KEY` 或 `AI_GATEWAY_API_KEY` 可自动选择对应服务商
|
||
3. **回退到本地**：未指定服务商时，resize/convert 使用本地处理
|
||
4. **首个支持的服务商**：用于 generate/remove-background
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 说明 | 获取密钥 |
|
||
|------|------|----------|
|
||
| `FAL_API_KEY` | fal.ai API 密钥 | [fal.ai](https://fal.ai/dashboard/keys) |
|
||
| `REPLICATE_API_TOKEN` | Replicate API 令牌 | [replicate.com](https://replicate.com/account/api-tokens) |
|
||
| `RUNPOD_API_KEY` | Runpod API 密钥 | [runpod.io](https://www.runpod.io/console/user/settings) |
|
||
| `AI_GATEWAY_API_KEY` | AI Gateway API 密钥 | [vercel.com](https://vercel.com/ai-gateway) |
|
||
| `AGENT_MEDIA_DIR` | 输出目录（默认：当前目录） | - |
|
||
|
||
## 路线图
|
||
|
||
- [x] 本地去除背景（无需任何 API 密钥）
|
||
- [x] 本地转录（无需任何 API 密钥）
|
||
- [x] 视频生成（文本生成视频 & 图像生成视频）
|
||
- [ ] 批量处理支持 |