Meicut Developer Documentation

Integrate Meicut video processing into your app via REST API or the MCP protocol — video editing, format conversion, compression, and more.

How It Works

Authentication

REST requests carry the API Key in a request header. Create an app under "Developer Center" in the console to get one; each key is bound to a user account and all charges are deducted from that account's balance.

X-API-Key: mv_your_api_key_here

How It Works

The base URL for all REST endpoints is https://meicut.com

All processing endpoints follow the same asynchronous job flow:

1. Submit a job (upload a file, then call a tool endpoint) and get a job_id
2. Poll GET /api/v1/job/{job_id}/status until it becomes completed or failed
3. Download the result from the returned download_url (presigned, no auth needed)

Video, audio and conversion tools each share a single endpoint: pick the function via the tool field in the request body, and pass its arguments in params.

{
  "stored_name": "a1b2c3....mp4",  // file id from the upload endpoint
  "tool": "cut-video",             // tool name — see each tool section
  "params": { ... }                // arguments for that tool — see its section
}

File Upload

Upload media files (video/audio/image) and receive a stored_name for use in later tool calls.

Request

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

Response

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

Job Status Query

# 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

Video Tools

Video processing exposes 2 endpoints: single-file operations go through the general endpoint, multi-video merging uses a dedicated one.

Endpoint 1: General Processing (13 tools)

General-purpose endpoint. Set the tool field in the request body to one of the values below and pass arguments via params. Supports 13 tools (all except merge):

Example — Cut Video

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 }
  }'

Endpoint 2: Merge Videos (dedicated)

Dedicated multi-video merge endpoint (no tool field in the body): pass at least 2 files in stored_names; optional params support resolution_mode / target_width / target_height — see the Merge Video section below.

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

Audio Tools

Audio processing exposes 2 endpoints: single-file operations go through the general endpoint, multi-audio merging uses a dedicated one.

Endpoint 1: General Processing (4 tools)

General-purpose endpoint. Set the tool field to cut-audio / speed-audio / volume-audio / audio-converter and pass arguments via params; per-tool parameters are documented in the sections below.

Endpoint 2: Merge Audio (dedicated)

Dedicated multi-audio merge endpoint (no tool field in the body): pass at least 2 files in stored_names — see the Merge Audio section below.

Format Conversion

Conversion endpoint. Set the tool field to video-converter or image-converter and pass arguments via params; per-tool parameters are documented in the sections below.

Video Compression

Parameters for this endpoint live at the top level of the request body (not nested in params):

{
  "stored_name": "a1b2c3....mp4",
  "quality": "medium",
  "resolution": "720p",
  "remove_audio": false
}

Integration Example (REST)

A complete runnable REST script (upload → call → poll → download) — replace the API Key with yours and run:

# 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")

Prefer runnable code? Tested Python/Node.js/MCP demos and the full open-source validation suite are on the API Examples page

Authentication

MCP uses the same API Key as REST (create an app under "Developer Center" in the console); send it according to the transport:

Streamable HTTP Endpoint (recommended)

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

Modern single-endpoint transport: POST JSON-RPC messages and get JSON responses directly. Authenticate with the Authorization header (or the api_key query parameter). After initialize, the server returns a Mcp-Session-Id header — send it back on subsequent requests.

SSE Endpoint (legacy)

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

About the MCP Protocol

Meicut supports the Model Context Protocol (MCP), allowing AI assistants (such as Claude and Cursor) to call video processing capabilities directly.

MCP is a standardized protocol that lets AI models discover and invoke external tools. The Meicut MCP Server exposes 25 tools covering all video and audio processing features.

How Parameters Are Passed

Parameter names and value ranges are identical to REST (see the tool sections above) — only the envelope differs: REST nests arguments in a params object with the tool name in the tool field; MCP has no wrapper, every argument is passed flat as the tool call arguments and the tool name is the method name (name). Merge tools are dedicated endpoints in REST (e.g. /video-tool/merge) but plain tools in MCP (merge_video). The same cut operation in both styles:

POST /api/v1/video-tool
{
  "stored_name": "a1b2c3....mp4",
  "tool": "cut-video",
  "params": { "start_time": 5, "duration": 10 }
}

{
  "method": "tools/call",
  "params": {
    "name": "cut_video",
    "arguments": {
      "stored_name": "a1b2c3....mp4",
      "start_time": 5,
      "duration": 10
    }
  }
}

MCP Tool List

MCP tools map one-to-one to the REST endpoints: names use snake_case (e.g. cut_video = cut-video) and take the same parameters documented in the REST sections above (only the conversion tools name the target format output_format instead of format). upload_file / upload_from_url correspond to file upload, get_job_status to job status polling.

MCP Integration Example

Add the following to your MCP config file:

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

Usage Flow

1. The AI assistant automatically discovers the list of available tools
2. Call upload_file to upload a file and get a stored_name
3. Call a specific tool (e.g., cut_video or compress_video) to get a job_id
4. Call get_job_status to check processing progress and results

Billing

API calls are deducted from the quota of the user account that owns the app. Each tool call consumes 1 quota. Quota amounts and billing rules depend on the developer plan the user subscribes to; query the current plan and remaining quota via GET /api/pricing/plans.

File uploads do not consume quota. Calls return a 402 error when quota is insufficient.

Error Codes