CapCut Mate: a FastAPI service that writes Jianying draft files

What the service produces, and what it does not

CapCut Mate describes itself as an open-source and free Jianying draft automation assistant built on FastAPI, supporting independent deployment. The important word in that sentence is draft. The service generates draft project files, serves them for download, and manages the JSON structures that Jianying and CapCut read. It does not itself encode a final video.

Rendering is a separate step the README describes as connecting with Jianying to achieve cloud rendering, producing a finished video from a draft. So the shape of the system is: something upstream composes a timeline, the service writes it out as a draft, and either Jianying or another renderer turns that draft into video. For an agent or workflow tool, the draft is the useful artifact, because it is inspectable and editable after the fact.

The stated purpose is to give large models basic video editing ability by shipping video editing skills out of the box, and the project can be deployed on its own or combined with Coze or n8n to build automated workflows. There is a Coze plugin published in the Coze store, workflow examples on the project site, and an `openapi.yaml` at the repository root, which is the file you import into Coze.

The project is Apache-2.0 licensed, Python, on a main branch, not archived, last pushed on 2026-09-19. That matches the date of the most recent release, v8.1.1.

The endpoint surface follows the editing workflow

The API documentation section groups the endpoints by what they do to a timeline, and the grouping is the clearest description of what the service thinks a video project is.

Draft management has three calls: `create_draft` to create a new project and set the canvas size, `save_draft` to persist the current state so edits survive, and `get_draft` to list drafts and fetch details. Video materials have `add_videos` for batch adding with cropping, scaling and effects, `add_images` with animations and transitions, and `add_sticker`. Audio has `add_audios` supporting volume and fade in and out, plus `get_audio_duration` for precise duration information, which matters because timeline placement needs exact lengths rather than estimates.

Text is handled separately from captions. `add_captions` batch adds subtitles with keyword highlighting and style settings, while `add_text_style` creates rich text styles with keyword colors and fonts. That separation suggests the model of the data: captions are positioned on a timeline, while text styles are reusable definitions you point captions at.

Effects and animation are the largest group. `add_effects` covers visual effects such as filters, borders and dynamic effects. `add_masks` adds shape masks controlling visible areas of the screen, `add_keyframes` animates position, scale and rotation, and `get_text_animations` and `get_text_effects` are discovery calls that list the available text entrance, exit and loop animations. Discovery endpoints matter more than they look: a caller has to know what Jianying calls an animation before it can reference one.

The stack underneath is unremarkable in the way you want it to be. Python 3.11 or newer, FastAPI, Pydantic for request validation, Uvicorn as the ASGI server, and uv for package management. FastAPI generating the interactive documentation is listed as a feature rather than an afterthought, and Pydantic validation means a malformed timeline request is rejected at the boundary.

Mask keyframes and a deliberate choice about internals

The two most recent releases are about the same subsystem, and between them they show the project's engineering judgment better than any feature list would.

v8.1.0, published on 2026-09-19, added `add_mask_keyframes`, which animates an existing mask on a video clip. It covers three properties: position, feather and rotation, writable together at one timestamp. Units are pinned to match the existing `add_masks` call, with pixels for position, a 0 to 100 range for feather, degrees for rotation and microseconds for time. Writing the same property twice at the same timestamp overwrites rather than stacking duplicates.

The design note in those release notes is the interesting part. The implementation was written against real Jianying drafts, and the keyframes are stored on the clip rather than in the mask's static configuration. More importantly, the new endpoint is deliberately kept separate from `add_keyframes` so that CapCut's internal field names and its material coordinate system are never exposed to the caller. The project chose a narrow API over a general one.

The behavior is also strict where it should be. A clip must already have a mask, and calling `add_mask_keyframes` on a clip without one raises a clear error rather than silently creating a mask. Position is converted using material dimensions rather than canvas dimensions, and timestamps beyond the clip duration are truncated to the end.

v8.1.1, published hours later the same day, extended that endpoint to mask width and height, still in pixels, with a recommendation to pass both at the same timestamp. Rounded corner keyframes remain unsupported, and the notes say so. That release also filled out `add_beauty` to match Jianying's own beauty panel, adding ten named sliders including skin smoothing, whitening, teeth whitening and skin tone, all with defaults, and it fixed a syntax error in a route docstring that had been preventing the service from starting at all. Both releases added unit tests for the conversions and the exported draft fields.

Running it locally with uv

The prerequisites are Python 3.11 or newer and uv, which is installed separately on each platform. The README gives both installers, and the Unix one is a single line:

sh -c "$(curl -LsSf https://astral.sh/uv/install.sh)"

Then the project is cloned and dependencies synced:

uv sync
uv run main.py

There is one platform-specific extra. On Windows the README asks for an additional editable install of the `windows` extra, and pyproject.toml shows what that pulls in: `pywin32`, `pyautogui` and `uiautomation`, all gated on `sys_platform == 'win32'`. Those are GUI automation libraries rather than web libraries, which tells you that something in the project drives a desktop application directly on Windows.

Once the server starts, the documentation is at `http://localhost:30000/docs`, which is FastAPI's interactive page generated from the Pydantic models. That page is the real interface documentation, and it is generated, so it cannot drift from the code the way a hand-written API reference does.

The dependency list in pyproject.toml is worth a second look for what it implies about scope. Beyond the web stack there is `pymediainfo` for reading media metadata, `imageio`, and three cloud storage SDKs: `cos-python-sdk-v5`, `oss2` and `tos`, which are Tencent COS, Alibaba Cloud OSS and ByteDance TOS. The project is built with Chinese cloud object storage in mind rather than assuming a generic S3 endpoint, which matters if you are deploying this outside that ecosystem.

One inconsistency to know about: pyproject.toml declares the project version as 1.0.0 while the GitHub releases are numbered in the v8 series. The release tags are the useful version history; the package metadata is not.

Docker deployment with nginx in front

The recommended quick deployment is a compose file, and the README gives it as one command:

git clone https://github.com/Hommy-master/capcut-mate.git
cd capcut-mate
docker-compose pull && docker-compose up -d

The compose file is more informative than the README. The published image is `gogoshine/capcut-mate:latest`, pinned to the `linux/amd64` platform, which means on Apple Silicon or another ARM host this runs under emulation rather than natively. The service maps port 30000 and mounts two host directories, one for generated output at `./html/output` and one for logs at `./logs`.

The environment variables are where the operational decisions live. `DOWNLOAD_FILE_SIZE_LIMIT` defaults to 209715200 bytes, a 200MB cap on downloaded files. `DRAFT_CLEANUP_MAX_DRAFT_COUNT` sets how many drafts are retained, with the compose file overriding the code default of 1000 to 6000. `USE_REMOTE_MEDIA_URL` is the interesting one: false downloads media locally, which is the default, while true writes the URL into the draft without fetching anything. For a service processing large video files, that switch is the difference between a 200MB working set and a 200GB one.

A second compose service runs nginx to publish static files and proxy the API under the `/openapi/capcut-mate/` path. That path prefix is not incidental, because it matches the OpenAPI spec path used when importing into Coze, so the same URL works for a local deployment and for the published service.

Resource limits are set explicitly: 1GB of memory with an equal memswap limit, one CPU, `restart: unless-stopped`, and an `oom_score_adj` of -500 that makes the kernel favor killing other processes over this container. Given that the service runs `main.py` with four workers inside a 1GB limit, that last setting is a deliberate choice about which container should die first.

Where the approach has limits worth knowing

Three constraints follow from the architecture rather than from any documented caveat.

The first is that the draft format is Jianying's, not CapCut Mate's. Every endpoint exists to write a structure that Jianying will read, and the release notes show the project working directly against real draft files to match field names and coordinate conversions. That means the surface is only as stable as Jianying's format, and an upstream change could require code changes here rather than a configuration change on your side. The keyframe endpoints reduce how much of that format you have to care about, but the coupling does not go away.

The second is the Docker image's contents. The Dockerfile copies `dist/` from a directory built in CI and copies a single binary, `tools/ffprobe`, into `/app/bin/ffprobe`, then sets the PATH to include it. That ffprobe is what makes `get_audio_duration` and the media handling work, and it is supplied by the build pipeline rather than compiled locally. Anyone rebuilding the image from source has to produce that dist directory and that binary first, which the README does not walk through.

The third is the Windows automation path. The optional extra installs `pyautogui` and `uiautomation`, libraries that synthesize input events and read UI trees. That is the fragile category of dependency, since it depends on window state and accessibility permissions rather than on an API contract. The core API endpoints do not obviously need it, so on a Linux or macOS host the extra install is not required, and the README only mentions it for Windows.

Editorial conclusion

CapCut Mate is worth evaluating if your pipeline ends at a draft rather than at an encoded file, because the work it saves is the fiddly part: computing crop and scale against source media, timing captions, attaching audio with fades, and writing draft structures that Jianying will open without complaint. It does not remove Jianying from the loop, and the project's own release notes are careful about where the line sits, since cloud rendering requires connecting to Jianying separately while the service itself generates and serves drafts. Before deploying, settle two things: which Python you will run, because the project pins `>=3.11,<3.14` while the Docker image is built on 3.11, and whether your media stays local, because the remote media URL mode exists specifically to avoid downloading every input.

Frequently asked questions

Official sources

1. Hommy-master/capcut-mate on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases