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 錯誤。

錯誤碼