meicut 开发者文档

通过 REST API 或 MCP 协议接入 meicut 视频处理能力,在你的应用中集成视频剪辑、格式转换、压缩等功能。

REST API

标准 HTTP 接口,支持所有主流编程语言接入

MCP 协议

Model Context Protocol,AI 原生接入方式

20+ 工具

视频剪辑、合并、压缩、格式转换、音频处理等

通用调用流程

1

创建应用

登录控制台「开发者中心」创建应用,获得 API Key——这是所有调用的前提,REST 与 MCP 共用同一个 Key。

2

上传文件

上传视频/音频/图片文件,获得 stored_name——REST 调用 POST /api/v1/upload,MCP 调用 upload_file 工具。

3

调用工具

用 stored_name 调用需要的处理工具,获得 job_id——REST 提交到对应端点,MCP 调用同名工具(下划线命名)。

4

获取结果

任务异步执行,用 job_id 查询状态——REST 调用 GET /api/v1/job//status,MCP 调用 get_job_status;完成后获得 download_url。

认证方式

REST 请求通过请求头携带 API Key。登录控制台「开发者中心」创建应用获取;每个 Key 绑定一个用户账号,所有费用从该账号余额中扣除。

HTTP Header
X-API-Key: mv_your_api_key_here

调用方式

所有 REST 接口的基础地址(Base URL)为 https://meicut.com

所有处理类接口都是异步任务模式,调用流程统一为:

  1. 提交任务(上传文件后调用工具接口),返回 job_id
  2. 用 GET /api/v1/job/{job_id}/status 轮询任务状态,直到变为 completed 或 failed
  3. 任务完成后,从返回的 download_url 直接下载结果文件(预签名地址,无需鉴权)

视频、音频、格式转换三大类工具各自共用一个端点:通过请求体中的 tool 字段指定具体功能,该功能的参数放在 params 中传递。

POST /api/v1/video-tool
{
  "stored_name": "a1b2c3....mp4",  // 上传后返回的文件标识
  "tool": "cut-video",             // 工具名,取值见各工具小节
  "params": { ... }                // 该工具的参数,见对应小节
}

文件上传

POST/api/v1/upload

上传媒体文件(视频/音频/图片),返回 stored_name 供后续工具使用。

请求

curl -X POST https://meicut.com/api/v1/upload \
  -H "X-API-Key: mv_your_api_key" \
  -F "file=@/path/to/video.mp4"

响应

JSON
{
  "file_id": "uuid",
  "filename": "video.mp4",
  "stored_name": "uuid.mp4",
  "size": 10485760,
  "media_info": { "duration": 30.5, "width": 1920, "height": 1080 }
}

任务状态查询

GET/api/v1/job/{job_id}/status
# Poll every 3s until "status" becomes "completed" or "failed"
curl https://meicut.com/api/v1/job/<job_id>/status \
  -H "X-API-Key: mv_your_api_key"
响应
{
  "job_id": "uuid",
  "status": "completed",
  "progress": 100,
  "output_file": "exports/uuid.mp4",
  "download_url": "https://meicut.com/minio-upload/meicut-files/exports/uuid.mp4?X-Amz-..."
}

completed

视频工具

视频处理提供 2 个端点:13 种单文件处理走通用端点,多视频合并走专用端点。

端点 1:通用处理(13 种工具)

POST/api/v1/video-tool

通用处理端点。在请求体 tool 字段填入工具取值指定功能,参数通过 params 传递。支持以下 13 种工具(合并除外):

请求示例 - 视频裁剪

curl -X POST https://meicut.com/api/v1/video-tool \
  -H "X-API-Key: mv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "stored_name": "a1b2c3....mp4",
    "tool": "cut-video",
    "params": { "start_time": 5, "duration": 10 }
  }'

端点 2:视频合并(专用)

POST/api/v1/video-tool/merge

多视频合并专用端点(请求体不含 tool 字段):stored_names 传入至少 2 个待合并文件;可选 params 支持 resolution_mode / target_width / target_height,详见下方「合并视频」小节。

JSON
{
  "stored_names": ["uuid1.mp4", "uuid2.mp4"],
  "params": { "resolution_mode": "auto" }
}

剪辑视频 cut-video

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
start_timenumber可选0
≥ 0
5
开始时间(秒)
durationnumber可选—
> 0
10
时长(秒)
segmentsarray可选—[{"start": 0, "end": 5}]多段剪辑:[{start, end}, ...](秒)。提供后覆盖 start_time/duration
fade_inboolean可选false
true / false
true
淡入效果
fade_outboolean可选false
true / false
true
淡出效果

合并视频 merge-video

POST/api/v1/video-tool/merge
参数类型必填默认值取值范围 / 示例说明
stored_namesarray必填—
至少 2 个
["uuid1.mp4", "uuid2.mp4"]
待合并视频的 stored_name 列表
resolution_modestring可选auto
fit / crop / stretch / auto
fit
分辨率不一致时的统一方式
target_widthinteger可选—
正整数
1920
统一目标宽度(像素),缺省自动检测
target_heightinteger可选—
正整数
1080
统一目标高度(像素),缺省自动检测

REST 使用独立端点 POST /api/v1/video-tool/merge(无需 tool 字段)。

视频缩放 resize-video

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
widthinteger必填—
正整数
1280
目标宽度(像素)
heightinteger必填—
正整数
720
目标高度(像素)
fit_modestring可选fit
fit / fill / stretch
fill
fit 留边 / fill 裁剪 / stretch 拉伸
bg_colorstring可选#000000
#RRGGBB
#FFFFFF
留边背景色(fit 模式)
pan_xnumber可选00水平裁剪偏移
pan_ynumber可选00垂直裁剪偏移

裁剪视频 crop-video

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
crop_winteger必填—
正整数
640
裁剪宽度(像素)
crop_hinteger必填—
正整数
360
裁剪高度(像素)
crop_xinteger可选0
≥ 0
100
裁剪起点 X 偏移
crop_yinteger可选0
≥ 0
50
裁剪起点 Y 偏移

旋转视频 rotate-video

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
angleinteger可选—
90 / 180 / 270
180
旋转角度

翻转视频 flip-video

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
flip_hboolean可选—
true / false
true
水平翻转
flip_vboolean可选—
true / false
false
垂直翻转

调整视频速度 speed-video

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
speednumber必填—
> 0
1.5
速度倍率,如 0.5 为半速、2.0 为两倍速

视频倒放 reverse-video

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识

循环视频 loop-video

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
loopsinteger可选2
≥ 1
3
循环次数

静音视频 mute-video

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识

添加音乐 add-audio

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
audio_stored_namestring可选—b2c3d4....mp3单个音频的 stored_name(与 audios[] 二选一)
audiosarray可选—[{"audio_stored_name": "b2....mp3", "volume": 0.8}]多音轨:[{audio_stored_name, trim_start, trim_end, start_time, volume}]——trim 为音轨内裁剪秒数,start_time 为该音轨延迟播放秒数,volume 默认 1.0
mixboolean可选false
true / false
true
与视频原声混音(默认只保留新增音轨)

添加字幕 add-subtitles

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
subtitle_stored_namestring必填—c3d4e5....srt字幕文件的 stored_name(SRT / ASS)

添加文字 add-text

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
textstring可选—Hello单条文字内容(与 texts[] 二选一)
textsarray可选—[{"text": "Hello", "x": 50, "y": 50}]多条文字:[{text, x, y, font_size, font_color, opacity, stroke_width, stroke_color, shadow_color, shadow_x, shadow_y, start_time, end_time}]
xinteger可选50100X 坐标
yinteger可选5080Y 坐标
font_sizeinteger可选48
正整数
36
字号
font_colorstring可选white#FFDD00字体颜色
font_filestring可选—fonts/NotoSansSC.ttfTTF/OTF 字体文件路径(缺省用默认字体)
opacitynumber可选1.0
0.0 – 1.0
0.8
不透明度
stroke_widthinteger可选0
≥ 0
2
描边宽度
stroke_colorstring可选black#000000描边颜色
start_timenumber可选—
≥ 0
2
文字出现时间(秒),缺省全程
end_timenumber可选—
> start_time
8
文字消失时间(秒),缺省全程

滤镜视频 filter-video

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
filterstring可选—
12 种预设之一(见说明)
sepia
预设滤镜:grayscale / sepia / blur / sharpen / brightness_up / brightness_down / contrast_up / saturation_up / vintage / invert / warm / cool
custom_vfstring可选—eq=brightness=0.2自定义 FFmpeg 视频滤镜表达式(提供后覆盖预设)

视频马赛克 mosaic-video

POST/api/v1/video-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
modestring可选—
full / region
region
full = 整屏像素化,region = 选中区域(默认 full)
shapestring可选—
rect / ellipse
ellipse
仅 region 模式:区域形状(默认 rect;椭圆宽高相等即为正圆)
intensityinteger可选—
1-10
5
块大小(默认 5,约 17px 块)
x / y / width / heightnumber可选—
0-100(占帧百分比)
25, 25, 50, 50
仅 region 模式:马赛克区域,占帧百分比(默认 25/25/50/50)
frequencynumber可选—
0-3600 秒
10
马赛克出现间隔秒数;0 = 全程持续(默认 0)
effect_durationnumber可选—2每次出现持续秒数(默认 1,仅 frequency>0 时生效)

音频工具

音频处理提供 2 个端点:单文件处理走通用端点,多音频合并走专用端点。

端点 1:通用处理(4 种工具)

POST/api/v1/audio-tool

通用处理端点。在请求体 tool 字段填入工具取值指定功能(cut-audio / speed-audio / volume-audio / audio-converter),参数通过 params 传递,各工具参数见下方对应小节。

端点 2:音频合并(专用)

POST/api/v1/audio-tool/merge

多音频合并专用端点(请求体不含 tool 字段):stored_names 传入至少 2 个待合并音频,详见下方「合并音频」小节。

剪辑音频 cut-audio

POST/api/v1/audio-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
start_timenumber可选0
≥ 0
5
开始时间(秒)
durationnumber可选—
> 0
10
时长(秒)
segmentsarray可选—[{"start": 0, "end": 5}]多段剪辑:[{start, end}, ...](秒)。提供后覆盖 start_time/duration
fade_inboolean可选false
true / false
true
淡入效果
fade_outboolean可选false
true / false
true
淡出效果
bitratestring可选192k128k音频码率

合并音频 merge-audio

POST/api/v1/audio-tool/merge
参数类型必填默认值取值范围 / 示例说明
stored_namesarray必填—
至少 2 个
["a1....mp3", "b2....mp3"]
待合并音频的 stored_name 列表

REST 使用独立端点 POST /api/v1/audio-tool/merge(无需 tool 字段)。

音频转换 audio-converter

POST/api/v1/audio-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
formatstring可选mp3
mp3 / wav / ogg / m4a / aac / flac
wav
目标格式(MCP 中名为 output_format)

调整音频速度 speed-audio

POST/api/v1/audio-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
speednumber必填—
> 0
1.5
速度倍率,如 0.5 为半速、2.0 为两倍速
bitratestring可选192k128k音频码率

音量调整 volume-audio

POST/api/v1/audio-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
volume_dbnumber可选—-6音量调整(dB),负值减小、正值增大。mute=true 时忽略
muteboolean可选false
true / false
true
完全静音
bitratestring可选192k128k音频码率

格式转换

POST/api/v1/convert-tool

格式转换端点。在请求体 tool 字段填入 video-converter 或 image-converter,参数通过 params 传递,各工具参数见下方对应小节。

视频转换 video-converter

POST/api/v1/convert-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
formatstring可选mp4
mp4 / avi / mov / mkv / webm / gif
webm
目标格式(MCP 中名为 output_format)

图片转换 image-converter

POST/api/v1/convert-tool
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
formatstring可选png
jpg / png / webp / gif / bmp / svg
webp
目标格式(MCP 中名为 output_format)
svg_modestring可选—
truecolor / detailed / posterized1-3 / curvy / sharp / smoothed / grayscale
detailed
SVG 矢量化模式(仅输出 svg 时有效)
numberofcolorsinteger可选64
2 – 256
128
SVG 输出颜色数
pathomitinteger可选0
0 – 20
8
SVG 路径简化(越小细节越多)
ltresnumber可选1.01.0SVG 线性阈值
qtresnumber可选1.01.0SVG 四叉阈值

图片加水印 image-watermark

POST/v1/image-watermark
参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
contentstring必填—© Meicut水印文字,支持 \n 多行
layoutstring可选single
single / tile
tile
single=单条水印;tile=全图平铺
pos_xnumber可选bottom-right
0 – 100
50
水印块中心 X(占图宽百分比,仅 single 布局;缺省右下 3% 边距)
font_familystring可选ArialNoto Sans SC字体(内置 OFL 字体 + 系统字体兜底)
font_size_pctnumber可选5
1 – 50
8
字号占图高百分比(批量不同分辨率自动等比)
font_colorstring可选#ffffff#ffcc00文字颜色(十六进制)
opacitynumber可选0.6
0 – 1
0.4
水印不透明度
rotationnumber可选0
-180 – 180
-30
旋转角度(顺时针为正)
font_weightinteger可选400
300 – 900
700
字重
pos_ynumber可选bottom-right
0 – 100
50
水印块中心 Y(占图高百分比,仅 single 布局;缺省右下 3% 边距)
tile_gapnumber可选50
10 – 300
80
平铺间距(占文字块尺寸百分比,tile 布局)
stroke_colorstring可选—#000000描边颜色(十六进制)
stroke_widthinteger可选0
0 – 20
2
描边宽度(像素)
shadowboolean可选false
true / false
true
文字投影
output_formatstring可选original
original / png / jpg / webp
webp
输出格式;original 保持原格式

视频压缩

POST/api/v1/compress

该接口参数位于请求体顶层(不使用 params 嵌套):

参数类型必填默认值取值范围 / 示例说明
stored_namestring必填—a1b2c3....mp4上传接口返回的文件标识
qualitystring可选medium
low / medium / high
high
压缩质量
resolutionstring可选original
original / 1080p / 720p / 480p
720p
目标分辨率
remove_audioboolean可选false
true / false
true
移除音轨
JSON
{
  "stored_name": "a1b2c3....mp4",
  "quality": "medium",
  "resolution": "720p",
  "remove_audio": false
}

接入示例(REST)

REST 完整可运行脚本(上传 → 调用 → 轮询 → 下载),把代码中的 API Key 换成你的即可直接运行:

# Meicut quickstart — Python 3.8+, standard library only.
# Set your key first:  export MEICUT_API_KEY=mv_your_api_key
import json
import os
import time
import urllib.request

API_KEY = os.environ["MEICUT_API_KEY"]
API = "https://meicut.com/api"


def call(method, path, payload=None, raw=None, content_type="application/json"):
    if raw is not None:
        data = raw
    elif payload is not None:
        data = json.dumps(payload).encode()
    else:
        data = None
    req = urllib.request.Request(API + path, data=data, method=method, headers={
        "X-API-Key": API_KEY,
        "Content-Type": content_type,
    })
    with urllib.request.urlopen(req, timeout=120) as r:
        return json.loads(r.read())


# 1. Upload a file (multipart/form-data) -> stored_name
boundary = "----meicut"
content = open("video.mp4", "rb").read()
body = (
    ("--" + boundary + "\r\n"
     'Content-Disposition: form-data; name="file"; filename="video.mp4"' + "\r\n"
     "Content-Type: application/octet-stream\r\n\r\n").encode()
    + content
    + ("\r\n--" + boundary + "--\r\n").encode()
)
up = call("POST", "/v1/upload", raw=body,
          content_type="multipart/form-data; boundary=" + boundary)
stored_name = up["stored_name"]

# 2. Submit a cut job -> job_id (all video/audio tools use this same pattern)
job = call("POST", "/v1/video-tool", {
    "stored_name": stored_name,
    "tool": "cut-video",
    "params": {"start_time": 0, "duration": 10},
})
job_id = job["job_id"]

# 3. Poll every 3s until the job finishes
while True:
    st = call("GET", "/v1/job/" + job_id + "/status")
    if st["status"] in ("completed", "failed"):
        break
    time.sleep(3)
if st["status"] == "failed":
    raise SystemExit("Job failed: " + str(st.get("error")))

# 4. Download — download_url is presigned, no auth header needed
urllib.request.urlretrieve(st["download_url"], "result.mp4")
print("Done -> result.mp4")

认证方式

MCP 使用与 REST 相同的 API Key(控制台「开发者中心」创建应用获取),按传输方式携带:

Streamable HTTP 接入地址(推荐)

HTTP
POST https://meicut.com/mcp
Authorization: Bearer mv_your_api_key

新版单端点传输:POST JSON-RPC 消息,直接返回 JSON 响应。用 Authorization 头鉴权(也可用 api_key 查询参数)。initialize 后服务端返回 Mcp-Session-Id 头,后续请求请带上。

SSE 接入地址(旧版)

URL
https://meicut.com/mcp/sse?api_key=mv_your_api_key

MCP 协议说明

meicut 支持 Model Context Protocol (MCP),允许 AI 助手(如 Claude、Cursor 等)直接调用视频处理能力。

MCP 是一种标准化协议,让 AI 模型能够发现和调用外部工具。meicut MCP Server 暴露了 25 个工具,覆盖所有视频/音频处理功能。

参数传递方式

参数名称、取值范围与 REST 完全一致(见上文各工具小节),区别仅在包装方式:REST 把参数放进 params 对象、工具名放进 tool 字段;MCP 不做包装,所有参数平铺为工具调用的 arguments,工具名即方法名(name)。合并类工具在 REST 是专用端点(如 /video-tool/merge),在 MCP 中则是普通工具(merge_video)。下例是同一个剪辑操作的两种写法:

REST
POST /api/v1/video-tool
{
  "stored_name": "a1b2c3....mp4",
  "tool": "cut-video",
  "params": { "start_time": 5, "duration": 10 }
}
MCP tools/call
{
  "method": "tools/call",
  "params": {
    "name": "cut_video",
    "arguments": {
      "stored_name": "a1b2c3....mp4",
      "start_time": 5,
      "duration": 10
    }
  }
}

MCP 工具列表

MCP 工具与 REST 接口一一对应:工具名为下划线命名(如 cut_video 对应 cut-video),参数与上文 REST 各小节一致(仅格式转换类工具的目标格式参数在 MCP 中名为 output_format)。upload_file / upload_from_url 对应 REST 的文件上传,get_job_status 对应任务状态查询。

MCP 接入示例

在 MCP 配置文件中添加:

{
  "mcpServers": {
    "meicut": {
      "url": "https://meicut.com/mcp",
      "headers": {
        "Authorization": "Bearer mv_your_api_key"
      }
    }
  }
}

使用流程

  1. AI 助手自动发现可用工具列表
  2. 调用 upload_file 上传文件,获取 stored_name
  3. 调用具体工具(如 cut_video、compress_video),获取 job_id
  4. 调用 get_job_status 查询处理进度和结果

计费说明

API 调用从应用所属用户账号额度中扣除。每次工具调用消耗 1 个配额(quota),具体配额额度与计费规则取决于用户订阅的开发者套餐,可通过 GET /api/pricing/plans 接口查询当前套餐与配额剩余。

文件上传不消耗配额。配额不足时调用将返回 402 错误。

错误码