DEV Community: Hommy

【剪映小助手】快速开始

Hommy — Mon, 16 Mar 2026 12:18:45 +0000

快速开始

简介

capcut-mate 是一个面向剪映（CapCut）的自动化辅助服务，提供草稿创建、媒体素材添加、字幕与特效处理、草稿保存以及视频生成等能力，并通过 OpenAPI 暴露接口。同时提供桌面客户端，帮助用户在本地管理草稿路径、下载与查看日志。

本"快速开始"指南将覆盖以下内容：

环境要求与安装方式（源码安装、Docker 部署、桌面客户端）
本地开发环境搭建、依赖安装、配置文件设置
首次运行验证与常见问题排查
新增中英文双语支持与语言切换功能

更新新增了中英文双语快速开始指南，用户可以通过顶部的语言切换链接在中文版和英文版之间自由切换。

项目结构

项目采用多模块组织方式：

后端服务：基于 Python/FastAPI 的 API 服务，路由集中在 v1 版本
桌面客户端：基于 Electron + React 的桌面应用，提供草稿路径设置、下载日志查看等功能
配置与模板：全局配置文件、草稿模板与贴纸配置
工具链：Dockerfile 与 docker-compose，便于容器化部署
新增国际化支持：响应中间件实现语言自动检测与切换

graph TB
subgraph "后端服务"
A_main["main.py<br/>启动FastAPI应用"]
A_router["src/router/v1.py<br/>路由与业务入口"]
A_cfg["config.py<br/>运行时配置"]
A_resp["src/middlewares/response.py<br/>响应中间件语言切换"]
end
subgraph "桌面客户端"
D_main["desktop-client/main.js<br/>Electron主进程"]
D_web_pkg["desktop-client/web/package.json<br/>前端依赖"]
D_cfg_page["ConfigCenter/index.jsx<br/>草稿路径设置页"]
D_ipc["nodeapi/ipcHandlers.js<br/>IPC处理器"]
end
subgraph "部署与打包"
C_docker["Dockerfile<br/>镜像构建"]
C_compose["docker-compose.yaml<br/>服务编排"]
end
A_main --> A_router
A_main --> A_cfg
A_main --> A_resp
D_main --> D_cfg_page
D_main --> D_ipc
C_docker --> A_main
C_compose --> C_docker

核心组件

FastAPI 应用与路由
- 应用在入口文件中创建并注册 v1 路由前缀，同时挂载中间件
- 路由集中于 v1 模块，覆盖草稿、媒体、字幕、特效、时间线、贴纸搜索等接口
新增响应中间件与语言切换
- 统一响应处理中间件，支持根据 Accept-Language 请求头自动检测语言
- 支持中文（zh）和英文（en）两种语言的错误消息和响应格式
- 自动处理422参数验证错误的多语言响应
配置中心
- 读取环境变量，提供草稿下载 URL、下载 URL 前缀、提示 URL、模板目录、腾讯云 COS 参数等
桌面客户端
- Electron 主进程负责窗口生命周期与 IPC；前端 React 页面提供配置中心与下载日志展示
- 通过 IPC 与后端交互，支持更新草稿路径、读取下载日志、打开外部链接等

架构总览

后端服务通过 FastAPI 暴露 REST 接口，桌面客户端通过 Electron 与后端进行 IPC 通信，实现草稿路径设置、下载日志查看与外部链接打开等本地化功能。新增的响应中间件负责统一处理 API 响应格式和语言切换。

sequenceDiagram
participant U as "用户"
participant UI as "桌面客户端界面"
participant M as "Electron主进程"
participant S as "后端FastAPI服务"
participant RM as "响应中间件"
U->>UI : 打开"配置中心"
UI->>M : 请求读取配置
M->>S : IPC调用读取配置数据
S->>RM : 统一响应处理语言检测
RM-->>S : 返回统一格式响应
S-->>M : 返回配置草稿路径等
M-->>UI : 返回配置数据
UI-->>U : 展示当前草稿路径
U->>UI : 点击"选择草稿路径"
UI->>M : IPC请求更新草稿路径
M-->>UI : 返回更新结果
UI-->>U : 更新界面显示

详细组件分析

后端服务（FastAPI）

应用创建与中间件
- 创建 FastAPI 实例，注册 v1 路由前缀
- 注册准备与响应中间件，便于统一处理请求与响应
路由与业务
- 路由集中在 v1 模块，涵盖草稿创建/保存、媒体添加（视频/音频/图片）、字幕、特效、遮罩、关键帧、贴纸、时间线计算、URL 提取、对象与字符串互转等
启动
- 本地开发可通过入口文件直接运行，监听 0.0.0.0:30000

flowchart TD
Start(["启动"]) --> CreateApp["创建FastAPI应用"]
CreateApp --> IncludeRouter["注册v1路由前缀"]
IncludeRouter --> AddMW["注册中间件"]
AddMW --> AddRespMW["注册响应中间件语言切换"]
AddRespMW --> PrintRoutes["打印路由信息"]
PrintRoutes --> Run["uvicorn运行服务"]
Run --> End(["就绪"])

新增响应中间件与语言切换

响应中间件实现了完整的语言切换功能：

语言检测机制
- 从 Accept-Language 请求头中提取用户的语言偏好
- 支持 zh、en 两种语言，其他语言默认返回中文
- 解析逻辑包含安全检查，防止请求头格式异常导致的问题
统一响应格式
- 所有成功的 API 响应都会包装为统一格式：包含 code、message 和原始数据
- 错误响应也统一为标准格式，便于前端处理
多语言错误处理
- 自动处理 422 参数验证错误，提供中英文混合的详细错误信息
- 支持自定义异常和通用异常的多语言响应
- 异常消息根据用户语言偏好自动切换

flowchart TD
Req["HTTP请求"] --> LangDetect["语言检测<br/>Accept-Language"]
LangDetect --> RespProc["响应处理"]
RespProc --> Success{"状态码=200?"}
Success --> |是| JSONCheck{"JSON响应?"}
Success --> |否| Non200["非200错误处理"]
JSONCheck --> |是| WrapResp["包装统一响应格式"]
JSONCheck --> |否| ReturnResp["直接返回"]
WrapResp --> LangSwitch["语言切换<br/>zh/en"]
LangSwitch --> ReturnResp
Non200 --> LangSwitch2["语言切换<br/>zh/en"]
ReturnResp --> End["响应返回"]

配置中心（config.py）

关键配置项
- 草稿下载 URL、下载 URL 前缀、提示 URL
- 草稿保存路径（云渲染场景需配置）
- 腾讯云 COS 参数（SecretId/SecretKey/Bucket/Region）
- API Key 启用开关
环境变量优先
- 通过环境变量覆盖默认值，便于容器化部署

桌面客户端（Electron + React）

主进程
- Electron 主进程负责窗口创建、生命周期管理、开发/生产模式加载
- 通过 IPC 注册处理器，提供读取下载日志、保存文件、打开外部链接、检测 URL 可达性、读取历史记录等能力
前端页面
- 配置中心页面提供草稿路径选择与展示
- 通过 electronService 适配浏览器与 Electron 环境差异
依赖与脚本
- 顶层 package.json 提供 Electron、打包与构建脚本
- web 子包管理 React 依赖与 Vite 构建

classDiagram
class ElectronMain {
+创建窗口()
+加载React应用()
+注册IPC处理器()
}
class IPC {
+get-download-log()
+save-file()
+open-external-url()
+check-url-access()
+get-history-record()
}
class ConfigPage {
+读取配置()
+选择草稿路径()
}
class ElectronService {
+getConfigData()
+getUrlJsonData()
+checkUrlAccess()
+openExternalUrl()
}
ElectronMain --> IPC : "注册处理器"
ElectronMain --> ConfigPage : "渲染页面"
ConfigPage --> ElectronService : "调用API"

依赖分析

后端依赖
- Python 版本要求：>=3.11
- 核心依赖：FastAPI、Uvicorn、requests、cos-python-sdk-v5、pymediainfo、email-validator
- 新增国际化支持：响应中间件依赖异常处理模块提供多语言支持
- 新增可选依赖：Windows 平台的 pywin32 和 uiautomation
桌面客户端依赖
- Electron、React、Vite、Bootstrap、axios、uuid、log4js 等
容器化
- 使用 uv 安装依赖，暴露 30000 端口，设置 PATH、HOME、UV_CACHE_DIR 等环境变量

更新新增了国际化支持依赖，响应中间件需要异常处理模块提供的多语言错误消息。

graph LR
P["Python 3.11+"] --> F["FastAPI"]
P --> U["Uvicorn"]
P --> R["requests"]
P --> C["cos-python-sdk-v5"]
P --> M["pymediainfo"]
P --> E["email-validator"]
subgraph "国际化支持"
EX["exceptions.py<br/>多语言错误消息"]
RM["response.py<br/>语言切换中间件"]
EX --> RM
end
subgraph "可选依赖"
W1["pywin32<br/>Windows API接口"]
W2["uiautomation<br/>UI自动化库"]
end
subgraph "桌面客户端"
E2["Electron"]
R2["React/Vite"]
AX["axios"]
L["log4js"]
U2["uuid"]
end
F --> W1
F --> W2
RM --> F

性能注意事项

容器资源限制
- docker-compose 中设置了内存上限与 CPU 限制，避免资源争用
日志与缓存
- uv 缓存目录与 PATH 需正确配置，避免频繁重建导致的冷启动延迟
并发与中间件
- 中间件顺序影响请求处理链路，建议按现有顺序使用
新增语言切换性能
- 响应中间件的语言检测开销极小，不会显著影响 API 性能
- 建议客户端在请求头中正确设置 Accept-Language，以获得最佳体验 ## 故障排查指南
无法访问后端服务
- 确认本地已运行入口文件，监听地址为 0.0.0.0，端口为 30000
- 若使用容器，确认端口映射与防火墙放行
桌面客户端无法读取配置或更新草稿路径
- 检查 Electron 主进程是否正常加载，确认 IPC 处理器已注册
- 在浏览器环境中，部分 API 会降级为模拟实现，需在桌面应用中使用
URL 可达性检测失败
- 浏览器环境使用 axios HEAD 请求检测，若超时或失败，检查网络与目标 URL
权限问题（macOS）
- 主进程捕获未捕获异常，若涉及沙箱与文件夹访问权限，弹窗提示前往系统偏好设置授权
新增语言切换问题
- 确认客户端请求头中包含正确的 Accept-Language 字段
- 支持的语言代码：zh（中文）、en（英文），其他语言将回退到中文
- 语言检测失败时，默认使用中文响应
新增响应格式问题
- 所有 API 响应都经过统一包装，包含 code、message 字段
- 成功响应的 data 字段包含原始业务数据
- 错误响应同样包含统一格式的 code 和 message 字段
新增跨平台依赖问题
- Windows 用户需要使用 pip install capcut-mate[windows] 安装额外依赖
- Linux 用户应使用基础依赖安装，避免导入 Windows 特定模块
- 使用 CI/CD 测试脚本验证跨平台兼容性

结论

通过本指南，您可以在本地快速搭建 capcut-mate 的开发与运行环境，掌握三种安装方式（源码、Docker、桌面客户端），并完成首次运行验证。新增的中英文双语支持让用户可以根据自己的语言偏好选择合适的文档版本。响应中间件实现了智能的语言切换功能，确保 API 响应的统一性和多语言支持。新的可选依赖系统使 Windows 用户能够获得完整的 UI 自动化功能，而 Linux 用户也能正常安装和使用核心功能。如需进一步扩展，可参考 OpenAPI 文档与路由模块，逐步接入草稿创建、媒体添加与视频生成等能力。

附录

环境要求

Python：>=3.11
Node.js：用于桌面客户端（随 Electron 依赖）
Windows/macOS：桌面客户端与剪映集成依赖
新增网络浏览器：支持 Accept-Language 请求头的语言检测功能

安装与运行步骤

方式一：源码安装（本地开发）

更新新增了跨平台安装选项和语言切换支持

1) Windows 平台（完整功能）

使用 uv 同步依赖或 pip 安装 Windows 特定依赖

   # 使用uv安装（推荐）
   uv sync

   # 或者使用pip安装Windows特定依赖
   pip install -e .[windows]

2) Linux 平台（基础功能）

使用 uv 同步依赖或 pip 安装基础依赖

   # 使用uv安装（推荐）
   uv sync

   # 或者使用pip安装基础依赖
   pip install -e .

3) 设置环境变量（可选）

如需自定义草稿下载 URL、下载 URL 前缀、COS 参数等，可在运行前设置对应环境变量

4) 启动后端服务

运行入口文件，服务监听 0.0.0.0:30000
使用 uvicorn main:app --host 0.0.0.0 --port 8000 启动

5) 访问 OpenAPI 文档

通过浏览器打开后端服务地址，查看接口说明与示例
新增在请求头中设置 Accept-Language: zh 或 Accept-Language: en 来测试语言切换

方式二：Docker 部署

更新新增了跨平台 Docker 配置

1) Windows Docker（推荐用于生产）

   FROM python:3.11-windowsservercore-ltsc2022

   WORKDIR /app
   COPY . .

   # 安装完整依赖
   RUN pip install -e .[windows]

   EXPOSE 8000
   CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

2) Linux Docker

   FROM python:3.11-slim

   WORKDIR /app
   COPY . .

   # 安装基础依赖
   RUN pip install -e .

   EXPOSE 8000
   CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

3) 构建镜像并启动容器

使用 docker-compose 启动服务，映射端口 30000，并挂载输出目录
在 compose 文件中设置草稿下载 URL、下载 URL 前缀、提示 URL 等

方式三：桌面客户端使用

1) 安装依赖

在桌面客户端根目录与 web 子目录分别安装依赖 2) 启动桌面应用
使用 Electron 启动主进程 3) 配置草稿路径
在"配置中心"页面选择剪映草稿保存路径 4) 下载与查看日志
通过 IPC 读取下载日志、保存文件、打开外部链接 ### 首次运行验证
- 后端验证
- 访问后端服务根路径，确认返回 API 列表与路由信息
- 调用任一接口（如获取草稿列表），确认返回结构符合预期
- 新增语言切换验证：在请求头中设置 Accept-Language: zh 或 Accept-Language: en 测试响应语言
- 桌面客户端验证
- 启动桌面应用，进入"配置中心"，选择草稿路径
- 触发 IPC 请求，确认返回成功或错误信息
- 新增跨平台功能验证
- Windows 平台：验证 UI 自动化功能可用
- Linux 平台：验证基础 API 功能正常，UI 自动化功能降级为占位符
- 新增国际化功能验证
- 验证响应中间件正确识别 Accept-Language 请求头
- 确认错误消息根据语言偏好自动切换
- 测试 422 参数验证错误的多语言响应 ### 常见问题与解决方案

更新新增了语言切换和国际化相关问题的解决方案

服务未启动或端口占用
- 检查端口 30000 是否被占用，更换端口或释放占用进程
草稿路径无效
- 确认路径存在且具备写入权限；在 macOS 沙箱环境下，按提示授予文件夹访问权限
URL 不可达
- 在浏览器环境使用 HEAD 请求检测 URL，检查网络与目标站点状态
容器内权限不足
- 确保挂载目录具备读写权限；核对容器内用户与缓存目录权限
新增语言切换问题
- 确认客户端正确设置 Accept-Language 请求头
- 支持的语言代码：zh（中文）、en（英文），其他语言将回退到中文
- 语言检测失败时，默认使用中文响应
- 验证响应格式包含统一的 code 和 message 字段
新增响应格式问题
- 所有 API 响应都经过统一包装，包含 code、message 字段
- 成功响应的 data 字段包含原始业务数据
- 错误响应同样包含统一格式的 code 和 message 字段
新增 Windows 依赖安装问题
- 使用 pip install capcut-mate[windows] 安装 Windows 特定依赖
- 确保系统为 Windows 平台，pywin32 和 uiautomation 会被正确安装
新增 Linux 依赖问题
- 使用基础依赖安装：pip install -e .
- 避免尝试安装 Windows 特定依赖，系统会自动跳过
新增跨平台兼容性测试
- 使用 python tests/test_ci_dependencies.py 验证依赖安装
- 使用 python tests/test_cross_platform.py 验证功能导入

跨平台功能对比

更新详细的跨平台功能对比表

功能特性	Windows 平台	Linux 平台
✅ 完整的视频导出自动化功能	✓	✗（需要手动导出）
✅ UI界面操作支持	✓	✗（占位符功能）
✅ 剪映应用控制	✓	✗（占位符功能）
✅ API服务功能	✓	✓
✅ 草稿管理	✓	✓
✅ 素材处理	✓	✓
✅ 视频自动导出功能	✓	✗
✅ UI自动化操作	✓	✗
✅ Windows特定依赖	✓ pywin32, uiautomation	✗ 无
✅ Linux兼容性	✗ 仅基础功能	✓ 完全兼容
新增 ✅ 多语言API支持	✓ 中文/英文	✓ 中文/英文
新增 ✅ 智能语言切换	✓ 基于Accept-Language	✓ 基于Accept-Language

语言切换使用指南

新增详细的中英文双语支持说明

语言检测机制
- 服务器通过 Accept-Language 请求头自动检测用户语言偏好
- 支持的语言代码：zh（中文）、en（英文）
- 其他语言将自动回退到中文
API响应格式
- 所有响应都经过统一包装，包含 code、message 字段
- 成功响应：code=0，message 为对应语言的成功消息
- 错误响应：code 为对应的错误码，message 为对应语言的错误描述
使用示例

  # 中文请求
  curl -H "Accept-Language: zh" http://localhost:30000/openapi/capcut-mate/v1/create_draft

  # 英文请求  
  curl -H "Accept-Language: en" http://localhost:30000/openapi/capcut-mate/v1/create_draft

错误处理
- 422 参数验证错误会返回详细的错误信息
- 错误信息包含字段名和具体验证失败原因
- 错误消息根据请求语言自动切换
接口文档： https://docs.jcaigc.cn
效果案例： https://www.jcaigc.cn/workflow
开源仓库： https://github.com/Hommy-master/capcut-mate

[JCAIGC]Save CapCut draft

Hommy — Fri, 28 Nov 2025 08:55:34 +0000

SAVE_DRAFT API Documentation

📋 Table of Contents

🔧 Interface Information
🎯 Function Description
📖 More Documentation
📥 Request Parameters
📤 Response Format
💻 Usage Examples
❌ Error Codes
⚠️ Notes
🔗 Related Interfaces

🔧 Interface Information

POST /openapi/capcut-mate/v1/save_draft

Function Description

Save CapCut draft. This interface is used to save the current draft state, ensuring that edited content is persistently stored. This interface is usually called after completing a series of editing operations to prevent loss of edited content.

Request Parameters

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}

Parameter Description

Parameter Name	Type	Required	Default Value	Description
draft_url	string	✅	-	Draft URL to be saved

Parameter Details

draft_url

Type: String
Required: Yes
Format: Complete draft URL, usually returned by the create_draft interface
Example: https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258" }``

Response Field Description

Field Name	Type	Description
draft_url	string	Saved draft URL, usually the same as the URL in the request

Error Response (4xx/5xx)

`json { "detail": "Error description" } `

Usage Examples

cURL Example

1. Basic Draft Save

`bash curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/save_draft \ -H "Content-Type: application/json" \ -d '{ "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258" }' `

JavaScript Example

`javascript
const saveDraft = async (draftUrl) => {
const response = await fetch('/openapi/capcut-mate/v1/save_draft', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ draft_url: draftUrl })
});
return response.json();
};

// Save draft
const draftUrl = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258";
const result = await saveDraft(draftUrl);
console.log('Draft saved successfully:', result.draft_url);
`

Advanced JavaScript Example

`javascript
class DraftManager {
constructor(baseUrl = 'https://capcut-mate.jcaigc.cn') {
this.baseUrl = baseUrl;
}

async saveDraft(draftUrl) {
const response = await fetch(${this.baseUrl}/openapi/capcut-mate/v1/save_draft, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ draft_url: draftUrl })
});

if (!response.ok) {
  throw new Error(`Failed to save draft: ${response.statusText}`);
}

return response.json();

}

// Auto-save function
async autoSave(draftUrl, intervalMs = 30000) {
const saveInterval = setInterval(async () => {
try {
await this.saveDraft(draftUrl);
console.log(Auto-save successful: ${new Date().toLocaleTimeString()});
} catch (error) {
console.error('Auto-save failed:', error);
}
}, intervalMs);

// Return function to stop auto-save
return () => clearInterval(saveInterval);

}

// Save during editing workflow
async editWorkflow(draftUrl, operations) {
const results = [];

for (const operation of operations) {
  try {
    // Execute editing operation (example here)
    const editResult = await operation();
    results.push(editResult);

    // Auto-save after each operation
    await this.saveDraft(draftUrl);
    console.log(`Operation completed and saved: ${operation.name}`);

  } catch (error) {
    console.error(`Operation failed: ${operation.name}`, error);
    results.push({ error: error.message });
  }
}

return results;

}

// Batch save multiple drafts
async saveMutipleDrafts(draftUrls) {
const results = {};

for (const [name, url] of Object.entries(draftUrls)) {
  try {
    const result = await this.saveDraft(url);
    results[name] = result;

    // Add delay to avoid too fast requests
    await new Promise(resolve => setTimeout(resolve, 100));
  } catch (error) {
    console.error(`Failed to save draft ${name}:`, error);
    results[name] = { error: error.message };
  }
}

return results;

}
}

// Usage example
const draftManager = new DraftManager();

// Basic save
const draftUrl = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258";
await draftManager.saveDraft(draftUrl);

// Start auto-save (save every 30 seconds)
const stopAutoSave = await draftManager.autoSave(draftUrl, 30000);

// Stop auto-save after editing is complete
setTimeout(() => {
stopAutoSave();
console.log('Auto-save stopped');
}, 300000); // Stop after 5 minutes

// Batch save multiple drafts
const multipleDrafts = {
"project1": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"project2": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
};
const saveResults = await draftManager.saveMutipleDrafts(multipleDrafts);
`

Python Example

`python
import requests
import time
import threading
from typing import Dict, List, Callable

class DraftSaver:
def init(self, base_url: str = "https://assets.jcaigc.cn"):
self.base_url = base_url
self._auto_save_threads = {}

def save_draft(self, draft_url: str) -> Dict:

    """Save draft"""

    response = requests.post(

        f'{self.base_url}/openapi/capcut-mate/v1/save_draft',

        headers={'Content-Type': 'application/json'},

        json={"draft_url": draft_url}

    )

    response.raise_for_status()

    return response.json()

def auto_save(self, draft_url: str, interval_seconds: int = 30) -> str:

    """Start auto-save, return thread ID for stopping"""

    def save_loop():

        while True:

            try:

                self.save_draft(draft_url)

                print(f"Auto-save successful: {time.strftime('%H:%M:%S')}")

                time.sleep(interval_seconds)

            except Exception as e:

                print(f"Auto-save failed: {e}")

                time.sleep(5)  # Wait 5 seconds before retry after error

thread_id = f"auto_save_{int(time.time())}"
thread = threading.Thread(target=save_loop, daemon=True)
thread.start()
self._auto_save_threads[thread_id] = thread

return thread_id



def stop_auto_save(self, thread_id: str):

    """Stop auto-save"""

    if thread_id in self._auto_save_threads:

        # Thread is daemon, will stop automatically when program ends

        del self._auto_save_threads[thread_id]

        print(f"Auto-save thread {thread_id} marked to stop")

def save_with_retry(self, draft_url: str, max_retries: int = 3) -> Dict:

    """Save with retry mechanism"""

    for attempt in range(max_retries):

        try:

            return self.save_draft(draft_url)

        except Exception as e:

            if attempt == max_retries - 1:

                raise e

            print(f"Save failed, attempt {attempt + 1} retry: {e}")

            time.sleep(2 ** attempt)  # Exponential backoff

Usage example

saver = DraftSaver()

Basic save

draft_url = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
result = saver.save_draft(draft_url)
print(f"Draft saved successfully: {result['draft_url']}")

Save with retry

try:
result = saver.save_with_retry(draft_url, max_retries=3)
print("Save successful (with retry mechanism)")
except Exception as e:
print(f"Save ultimately failed: {e}")

Start auto-save

auto_save_id = saver.auto_save(draft_url, interval_seconds=30)
print(f"Auto-save started, ID: {auto_save_id}")

Stop auto-save after 10 minutes

time.sleep(600)
saver.stop_auto_save(auto_save_id)
`

Error Codes

Error Code	Error Message	Description	Solution
400	draft_url is required	Missing draft URL parameter	Provide valid draft_url
400	Invalid draft_url format	URL format is incorrect	Check if URL format is correct
404	Draft does not exist	Specified draft cannot be found	Confirm if draft URL is correct and exists
500	Save failed	Internal service error	Contact technical support or retry later
503	Service unavailable	System under maintenance	Retry later

Notes

URL Validity: Ensure the draft_url passed in is valid and exists
Network Stability: Save operation requires stable network connection
Frequency Control: Avoid too frequent save operations
Auto-save: It is recommended to enable auto-save feature for long editing sessions
Error Handling: There should be retry mechanism when save fails
Concurrency Safety: Concurrent saves of the same draft may cause conflicts

Workflow

Validate draft_url parameter
Check if draft exists
Get current draft state
Persistently save draft data
Return save result

Best Practices

Regular Save: Save promptly after important operations
Auto-save: Set up auto-save for long editing sessions
Error Recovery: Provide retry mechanism when save fails
Status Display: Show save status to users
Backup Strategy: Consider multi-version backup mechanism

Related Interfaces

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

[JCAIGC]Get text entrance/exit animation list

Hommy — Fri, 28 Nov 2025 08:54:46 +0000

get_text_animations API Documentation

Interface Overview

Interface Name: get_text_animations

Interface URL: POST /openapi/capcut-mate/v1/get_text_animations

Function Description: Get text entrance/exit animation list, returns all supported text entrance/exit animations that meet the conditions. Supports filtering by animation type (entrance, exit, loop) and membership mode (all, VIP, free).

Request Parameters

Request Body (application/json)

Parameter Name	Type	Required	Default Value	Description
mode	integer	No	0	Animation mode: 0=all, 1=VIP, 2=free
type	string	Yes	-	Animation type: in=entrance, out=exit, loop=loop

Animation Mode Description

Mode Value	Mode Name	Description
0	All	Returns all animations (including VIP and free)
1	VIP	Returns only VIP animations
2	Free	Returns only free animations

Animation Type Description

Type Value	Type Name	Description
in	Entrance Animation	Animation effect when text appears
out	Exit Animation	Animation effect when text disappears
loop	Loop Animation	Continuous loop animation effect for text

Request Examples

Get All Entrance Animations

{
  "mode": 0,
  "type": "in"
}

Get VIP Exit Animations

{
  "mode": 1,
  "type": "out"
}

Get Free Loop Animations

{
  "mode": 2,
  "type": "loop"
}

Response Format

Success Response

{
  "effects": "[{\"resource_id\":\"7314291622525538843\",\"type\":\"in\",\"category_id\":\"ruchang\",\"category_name\":\"入场\",\"duration\":500000,\"id\":\"35395178\",\"name\":\"冰雪飘动\",\"request_id\":\"\",\"start\":0,\"icon_url\":\"https://lf5-hl-hw-effectcdn-tos.byteeffecttos.com/obj/ies.fe.effect/459c196951cadbd024456a63db89481f\",\"material_type\":\"sticker\",\"panel\":\"\",\"path\":\"\",\"platform\":\"all\"},{\"resource_id\":\"7397306443147252233\",\"type\":\"in\",\"category_id\":\"ruchang\",\"category_name\":\"入场\",\"duration\":500000,\"id\":\"77035159\",\"name\":\"变色输入\",\"request_id\":\"\",\"start\":0,\"icon_url\":\"https://lf5-hl-hw-effectcdn-tos.byteeffecttos.com/obj/ies.fe.effect/c15f5c313f8170c558043abf300a0692\",\"material_type\":\"sticker\",\"panel\":\"\",\"path\":\"\",\"platform\":\"all\"}]"
}

Animation Object Structure

Each animation object contains the following fields:

Field Name	Type	Description
resource_id	string	Animation resource ID
type	string	Animation type (in/out/loop)
category_id	string	Animation category ID
category_name	string	Animation category name
duration	integer	Animation duration (microseconds)
id	string	Animation unique identifier
name	string	Animation name
request_id	string	Request ID (usually empty)
start	integer	Animation start time
icon_url	string	Animation icon URL
material_type	string	Material type (usually "sticker")
panel	string	Panel information
path	string	Path information
platform	string	Supported platforms (usually "all")

Error Response

400 Bad Request - Parameter Validation Failed

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request parameter validation failed",
    "details": "type parameter must be in, out, or loop"
  }
}

500 Internal Server Error - Failed to Get Animations

{
  "error": {
    "code": "TEXT_ANIMATION_GET_FAILED",
    "message": "Failed to get text animations",
    "details": "Failed to get animation data"
  }
}

Error Codes

Error Code	HTTP Status Code	Description	Solution
VALIDATION_ERROR	400	Request parameter validation failed	Check if type parameter is in/out/loop and mode parameter is 0/1/2
TEXT_ANIMATION_GET_FAILED	500	Failed to get text animations	Check service status and try again later

Usage Instructions

Parameter Instructions

type parameter: Required parameter, can only choose one of "in", "out", "loop"
mode parameter: Optional parameter, default is 0 (all animations)
Response data: The effects field is in JSON string format and needs to be parsed before use

Animation Application Scenarios

Entrance Animation (in):
- Applicable for scenes where text appears
- Such as fade-in entrance, snow drift, color change input, etc.
- Usually lasts between 0.5-1 seconds
Exit Animation (out):
- Applicable for scenes where text disappears
- Such as fade-out exit, rotate disappear, etc.
- Usually lasts between 0.6-0.8 seconds
Loop Animation (loop):
- Applicable for text that needs to continuously attract attention
- Such as heartbeat, flashing effect, etc.
- Usually lasts between 1-1.2 seconds and can loop infinitely

Usage Recommendations

Choose appropriate animation types based on video content style
VIP animations usually have better effects but require membership privileges
It is recommended to first get all animations, then filter as needed
Can combine animation preview images (icon_url) for users to choose

Example Code

JavaScript Example

// Get all entrance animations
const getInAnimations = async () => {
  const response = await fetch('/openapi/capcut-mate/v1/get_text_animations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 0,
      type: 'in'
    })
  });

  const result = await response.json();
  const animations = JSON.parse(result.effects);
  console.log('Entrance animations list:', animations);
};

// Get free loop animations
const getFreeLoopAnimations = async () => {
  const response = await fetch('/openapi/capcut-mate/v1/get_text_animations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 2,
      type: 'loop'
    })
  });

  const result = await response.json();
  const animations = JSON.parse(result.effects);
  console.log('Free loop animations list:', animations);
};

Python Example

import requests
import json

def get_text_animations(mode=0, animation_type='in'):
    """Get text animations list"""
    url = 'http://localhost:8000/v1/get_text_animations'
    data = {
        'mode': mode,
        'type': animation_type
    }

    response = requests.post(url, json=data)
    if response.status_code == 200:
        result = response.json()
        animations = json.loads(result['effects'])
        return animations
    else:
        print(f"Request failed: {response.status_code}")
        return []

# Usage example
in_animations = get_text_animations(mode=0, animation_type='in')
print(f"Got {len(in_animations)} entrance animations")

vip_out_animations = get_text_animations(mode=1, animation_type='out')
print(f"Got {len(vip_out_animations)} VIP exit animations")

Related Interfaces

add_captions - Batch add subtitles (can use animation effects)
add_text_style - Create text rich text styles
add_effects - Add video effects

Technical Implementation

File Structure

src/
├── schemas/get_text_animations.py    # Request/response data models
├── service/get_text_animations.py    # Business logic implementation
└── router/v1.py                      # API route definition

Core Logic

Parameter Validation: Validate the validity of type and mode parameters
Data Filtering: Filter animation data based on type and mode parameters
Data Formatting: Convert animation data to JSON string format
Response Return: Return API response that conforms to specifications

Data Source

Currently using mock data, in actual projects should:

Get animation data from database
Or get animation resources from third-party API
Support dynamic updates of animation resources

Version Information: v1.0

Last Updated: 2024-09-24

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

[JCAIGC]Get image entrance/exit animation list

Hommy — Fri, 28 Nov 2025 08:53:41 +0000

get_image_animations API Documentation

Interface Overview

Interface Name: get_image_animations

Interface URL: POST /openapi/capcut-mate/v1/get_image_animations

Function Description: Get image entrance/exit animation list, returns all supported image entrance/exit animations that meet the conditions. Supports filtering by animation type (entrance, exit, loop) and membership mode (all, VIP, free).

Request Parameters

Request Body (application/json)

Parameter Name	Type	Required	Default Value	Description
mode	integer	No	0	Animation mode: 0=all, 1=VIP, 2=free
type	string	Yes	-	Animation type: in=entrance, out=exit, loop=loop

Animation Mode Description

Mode Value	Mode Name	Description
0	All	Returns all animations (including VIP and free)
1	VIP	Returns only VIP animations
2	Free	Returns only free animations

Animation Type Description

Type Value	Type Name	Description
in	Entrance Animation	Animation effect when image appears
out	Exit Animation	Animation effect when image disappears
loop	Loop Animation	Continuous loop animation effect for image

Request Examples

Get All Entrance Animations

{
  "mode": 0,
  "type": "in"
}

Get VIP Exit Animations

{
  "mode": 1,
  "type": "out"
}

Get Free Loop Animations

{
  "mode": 2,
  "type": "loop"
}

Response Format

Success Response

{
  "effects": "[{\"resource_id\":\"7314291622525538843\",\"type\":\"in\",\"category_id\":\"ruchang\",\"category_name\":\"入场\",\"duration\":500000,\"id\":\"35395178\",\"name\":\"冰雪飘动\",\"request_id\":\"\",\"start\":0,\"icon_url\":\"https://lf5-hl-hw-effectcdn-tos.byteeffecttos.com/obj/ies.fe.effect/459c196951cadbd024456a63db89481f\",\"material_type\":\"sticker\",\"panel\":\"\",\"path\":\"\",\"platform\":\"all\"},{\"resource_id\":\"7397306443147252233\",\"type\":\"in\",\"category_id\":\"ruchang\",\"category_name\":\"入场\",\"duration\":500000,\"id\":\"77035159\",\"name\":\"变色输入\",\"request_id\":\"\",\"start\":0,\"icon_url\":\"https://lf5-hl-hw-effectcdn-tos.byteeffecttos.com/obj/ies.fe.effect/c15f5c313f8170c558043abf300a0692\",\"material_type\":\"sticker\",\"panel\":\"\",\"path\":\"\",\"platform\":\"all\"}]"
}

Animation Object Structure

Each animation object contains the following fields:

Field Name	Type	Description
resource_id	string	Animation resource ID
type	string	Animation type (in/out/loop)
category_id	string	Animation category ID
category_name	string	Animation category name
duration	integer	Animation duration (microseconds)
id	string	Animation unique identifier
name	string	Animation name
request_id	string	Request ID (usually empty)
start	integer	Animation start time
icon_url	string	Animation icon URL
material_type	string	Material type (usually "sticker")
panel	string	Panel information
path	string	Path information
platform	string	Supported platforms (usually "all")

Error Response

400 Bad Request - Parameter Validation Failed

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request parameter validation failed",
    "details": "type parameter must be in, out, or loop"
  }
}

500 Internal Server Error - Failed to Get Animations

{
  "error": {
    "code": "IMAGE_ANIMATION_GET_FAILED",
    "message": "Failed to get image animations",
    "details": "Failed to get animation data"
  }
}

Error Codes

Error Code	HTTP Status Code	Description	Solution
VALIDATION_ERROR	400	Request parameter validation failed	Check if type parameter is in/out/loop and mode parameter is 0/1/2
IMAGE_ANIMATION_GET_FAILED	500	Failed to get image animations	Check service status and try again later

Usage Instructions

Parameter Instructions

type parameter: Required parameter, can only choose one of "in", "out", "loop"
mode parameter: Optional parameter, default is 0 (all animations)
Response data: The effects field is in JSON string format and needs to be parsed before use

Animation Application Scenarios

Entrance Animation (in):
- Applicable for scenes where images appear
- Such as fade-in effects, zoom entrance, slide entrance, etc.
- Usually lasts between 0.5-1 seconds
Exit Animation (out):
- Applicable for scenes where images disappear
- Such as fade-out effects, zoom out, rotate exit, etc.
- Usually lasts between 0.6-0.8 seconds
Loop Animation (loop):
- Applicable for images that need to continuously attract attention
- Such as slight shaking, zoom breathing effect, etc.
- Usually lasts between 1-1.2 seconds and can loop infinitely

Usage Recommendations

Choose appropriate animation types based on video content style
VIP animations usually have better effects but require membership privileges
It is recommended to first get all animations, then filter as needed
Can combine animation preview images (icon_url) for users to choose
Image animations should be more natural and smooth than text animations

Example Code

JavaScript Example

// Get all entrance animations
const getImageInAnimations = async () => {
  const response = await fetch('/openapi/capcut-mate/v1/get_image_animations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 0,
      type: 'in'
    })
  });

  const result = await response.json();
  const animations = JSON.parse(result.effects);
  console.log('Image entrance animations list:', animations);
};

// Get free loop animations
const getFreeImageLoopAnimations = async () => {
  const response = await fetch('/openapi/capcut-mate/v1/get_image_animations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 2,
      type: 'loop'
    })
  });

  const result = await response.json();
  const animations = JSON.parse(result.effects);
  console.log('Free image loop animations list:', animations);
};

Python Example

import requests
import json

def get_image_animations(mode=0, animation_type='in'):
    """Get image animations list"""
    url = 'http://localhost:8000/v1/get_image_animations'
    data = {
        'mode': mode,
        'type': animation_type
    }

    response = requests.post(url, json=data)
    if response.status_code == 200:
        result = response.json()
        animations = json.loads(result['effects'])
        return animations
    else:
        print(f"Request failed: {response.status_code}")
        return []

# Usage example
in_animations = get_image_animations(mode=0, animation_type='in')
print(f"Got {len(in_animations)} image entrance animations")

vip_out_animations = get_image_animations(mode=1, animation_type='out')
print(f"Got {len(vip_out_animations)} VIP image exit animations")

Related Interfaces

add_images - Batch add images (can use animation effects)
add_effects - Add video effects
get_text_animations - Get text entrance/exit animations

Technical Implementation

File Structure

src/
├── schemas/get_image_animations.py    # Request/response data models
├── service/get_image_animations.py    # Business logic implementation
└── router/v1.py                       # API route definition

Core Logic

Parameter Validation: Validate the validity of type and mode parameters
Data Filtering: Filter image animation data based on type and mode parameters
Data Formatting: Convert animation data to JSON string format
Response Return: Return API response that conforms to specifications

Data Source

Currently using mock data, in actual projects should:

Get image animation data from database
Or get animation resources from third-party API
Support dynamic updates of animation resources
Distinguish between different characteristics of image animations and text animations

Version Information: v1.0

Last Updated: 2024-09-24

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

[JCAIGC]Get draft file list

Hommy — Fri, 28 Nov 2025 08:52:28 +0000

GET_DRAFT API Documentation

📋 Table of Contents

🔧 API Information
🎯 Function Description
📖 More Documentation
📥 Request Parameters
📤 Response Format
💻 Usage Examples
❌ Error Code Description
⚠️ Notes
🔗 Related APIs

🔧 API Information

GET /openapi/capcut-mate/v1/get_draft

Function Description

Get draft file list. This interface is used to get all file lists corresponding to a specified draft ID, allowing you to view material files, configuration files, and other information contained in the draft. Typically used for draft content preview, file management, or status checking.

Request Parameters

Query Parameters

Parameter Name	Type	Required	Default	Description
draft_id	string	✅	-	Draft ID, length 20-32 characters

Parameter Details

draft_id

Type: string
Required: Yes
Length: 20-32 characters
Format: Usually UUID format or similar unique identifier
Example: 2f52a63b-8c6a-4417-8b01-1b2a569ccb6c
How to get: Usually extracted from draft_url or returned by create_draft interface

draft_id Extraction Method

Extract draft_id from draft_url:

// Example draft_url:
// https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"2f52a63b-8c6a-4417-8b01-1b2a569ccb6c"

Response Format

Success Response (200)

{
  "files": [
    "2f52a63b-8c6a-4417-8b01-1b2a569ccb6c.json",
    "video_123456789.mp4",
    "audio_987654321.mp3",
    "image_555666777.jpg",
    "thumbnail_888999000.png"
  ]
}

Response Field Description

Field Name	Type	Description
files	array	List of files related to the draft

File Type Description

The returned file list may contain the following types:

File Type	Extension	Description
Draft configuration file	.json	Main configuration file of the draft, containing all editing information
Video files	.mp4, .avi, .mov	Video materials used in the draft
Audio files	.mp3, .wav, .aac	Audio materials used in the draft
Image files	.jpg, .png, .gif	Image materials used in the draft
Thumbnail files	.png, .jpg	Thumbnail files of materials
Temporary files	.tmp	Temporary files during processing

Error Response (4xx/5xx)

{
  "detail": "Error message description"
}

Usage Examples

cURL Example

1. Basic get draft file list

curl -X GET "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2f52a63b-8c6a-4417-8b01-1b2a569ccb6c" \
  -H "Content-Type: application/json"

2. Use complete draft_id

curl -X GET "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=7e8f9a0b-1c2d-3e4f-5g6h-7i8j9k0l1m2n" \
  -H "Content-Type: application/json"

JavaScript Example

const getDraft = async (draftId) => {
  const response = await fetch(`/v1/get_draft?draft_id=${draftId}`, {
    method: 'GET',
    headers: { 'Content-Type': 'application/json' }
  });
  return response.json();
};

// Usage example
const draftId = "2f52a63b-8c6a-4417-8b01-1b2a569ccb6c";
const result = await getDraft(draftId);
console.log('Draft file list:', result.files);

// Extract draft_id from draft_url
function extractDraftId(draftUrl) {
  const match = draftUrl.match(/\/([^\/]+)\.json$/);
  return match ? match[1] : null;
}

const draftUrl = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258";
const extractedId = extractDraftId(draftUrl);

if (extractedId) {
  const files = await getDraft(extractedId);
  console.log('File list:', files);
}

Advanced JavaScript Example

class DraftManager {
  constructor(baseUrl = 'https://capcut-mate.jcaigc.cn') {
    this.baseUrl = baseUrl;
  }

  async getDraft(draftId) {
    const response = await fetch(`${this.baseUrl}/v1/get_draft?draft_id=${draftId}`, {
      method: 'GET',
      headers: { 'Content-Type': 'application/json' }
    });

    if (!response.ok) {
      throw new Error(`Failed to get draft: ${response.statusText}`);
    }

    return response.json();
  }

  // Extract draft_id from draft_url
  extractDraftId(draftUrl) {
    try {
      const url = new URL(draftUrl);
      const draftIdParam = url.searchParams.get('drafId');
      if (draftIdParam) {
        const match = draftIdParam.match(/\/([^\/]+)\.json$/);
        return match ? match[1] : null;
      }
      return null;
    } catch (error) {
      console.error('URL parsing failed:', error);
      return null;
    }
  }

  // Analyze file types
  analyzeFiles(files) {
    const analysis = {
      total: files.length,
      types: {
        config: [],
        video: [],
        audio: [],
        image: [],
        thumbnail: [],
        other: []
      }
    };

    files.forEach(file => {
      const ext = file.split('.').pop()?.toLowerCase();

      switch (ext) {
        case 'json':
          analysis.types.config.push(file);
          break;
        case 'mp4':
        case 'avi':
        case 'mov':
        case 'mkv':
          analysis.types.video.push(file);
          break;
        case 'mp3':
        case 'wav':
        case 'aac':
        case 'flac':
          analysis.types.audio.push(file);
          break;
        case 'jpg':
        case 'jpeg':
        case 'png':
        case 'gif':
        case 'bmp':
          if (file.includes('thumbnail')) {
            analysis.types.thumbnail.push(file);
          } else {
            analysis.types.image.push(file);
          }
          break;
        default:
          analysis.types.other.push(file);
      }
    });

    return analysis;
  }

  // Get draft details
  async getDraftDetails(draftUrl) {
    const draftId = this.extractDraftId(draftUrl);
    if (!draftId) {
      throw new Error('Unable to extract draft ID from URL');
    }

    const result = await this.getDraft(draftId);
    const analysis = this.analyzeFiles(result.files);

    return {
      draftId,
      draftUrl,
      files: result.files,
      analysis
    };
  }

  // Batch get multiple draft information
  async getBatchDrafts(draftUrls) {
    const results = {};

    for (const [name, url] of Object.entries(draftUrls)) {
      try {
        const details = await this.getDraftDetails(url);
        results[name] = details;

        // Add delay to avoid too fast requests
        await new Promise(resolve => setTimeout(resolve, 100));
      } catch (error) {
        console.error(`Failed to get draft ${name}:`, error);
        results[name] = { error: error.message };
      }
    }

    return results;
  }

  // Monitor draft file changes
  async monitorDraftChanges(draftId, callback, intervalMs = 5000) {
    let lastFileList = [];

    const checkChanges = async () => {
      try {
        const result = await this.getDraft(draftId);
        const currentFiles = result.files.sort();

        // Check if file list has changed
        if (JSON.stringify(currentFiles) !== JSON.stringify(lastFileList)) {
          const changes = {
            added: currentFiles.filter(f => !lastFileList.includes(f)),
            removed: lastFileList.filter(f => !currentFiles.includes(f)),
            current: currentFiles
          };

          callback(changes);
          lastFileList = currentFiles;
        }
      } catch (error) {
        console.error('Failed to monitor draft changes:', error);
      }
    };

    // Initial check
    await checkChanges();

    // Regular checks
    const interval = setInterval(checkChanges, intervalMs);

    // Return function to stop monitoring
    return () => clearInterval(interval);
  }
}

// Usage example
const draftManager = new DraftManager();

// Get single draft details
const draftUrl = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258";
const details = await draftManager.getDraftDetails(draftUrl);

console.log('Draft details:', {
  id: details.draftId,
  totalFiles: details.analysis.total,
  videoCount: details.analysis.types.video.length,
  audioCount: details.analysis.types.audio.length,
  imageCount: details.analysis.types.image.length
});

// Batch get draft information
const multipleDrafts = {
  "project1": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "project2": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
};

const batchResults = await draftManager.getBatchDrafts(multipleDrafts);
console.log('Batch draft information:', batchResults);

// Monitor draft file changes
const draftId = "2f52a63b-8c6a-4417-8b01-1b2a569ccb6c";
const stopMonitoring = await draftManager.monitorDraftChanges(draftId, (changes) => {
  console.log('Draft files changed:', changes);
  if (changes.added.length > 0) {
    console.log('Added files:', changes.added);
  }
  if (changes.removed.length > 0) {
    console.log('Removed files:', changes.removed);
  }
});

// Stop monitoring after 30 seconds
setTimeout(() => {
  stopMonitoring();
  console.log('Stopped monitoring draft changes');
}, 30000);

Python Example

import requests
import re
import time
import threading
from urllib.parse import urlparse, parse_qs
from typing import Dict, List, Optional, Callable

class DraftManager:
    def __init__(self, base_url: str = "https://api.assets.jcaigc.cn"):
        self.base_url = base_url

    def get_draft(self, draft_id: str) -> Dict:
        """Get draft file list"""
        response = requests.get(
            f'{self.base_url}/openapi/capcut-mate/v1/get_draft',
            params={'draft_id': draft_id},
            headers={'Content-Type': 'application/json'}
        )
        response.raise_for_status()
        return response.json()

    def extract_draft_id(self, draft_url: str) -> Optional[str]:
        """Extract draft_id from draft_url"""
        try:
            parsed_url = urlparse(draft_url)
            query_params = parse_qs(parsed_url.fragment.split('?')[1] if '?' in parsed_url.fragment else '')

            draft_id_param = query_params.get('drafId', [None])[0]
            if draft_id_param:
                match = re.search(r'/([^/]+)\.json$', draft_id_param)
                return match.group(1) if match else None
            return None
        except Exception as e:
            print(f"URL parsing failed: {e}")
            return None

    def analyze_files(self, files: List[str]) -> Dict:
        """Analyze file types"""
        analysis = {
            'total': len(files),
            'types': {
                'config': [],
                'video': [],
                'audio': [],
                'image': [],
                'thumbnail': [],
                'other': []
            }
        }

        for file in files:
            ext = file.split('.')[-1].lower() if '.' in file else ''

            if ext == 'json':
                analysis['types']['config'].append(file)
            elif ext in ['mp4', 'avi', 'mov', 'mkv']:
                analysis['types']['video'].append(file)
            elif ext in ['mp3', 'wav', 'aac', 'flac']:
                analysis['types']['audio'].append(file)
            elif ext in ['jpg', 'jpeg', 'png', 'gif', 'bmp']:
                if 'thumbnail' in file:
                    analysis['types']['thumbnail'].append(file)
                else:
                    analysis['types']['image'].append(file)
            else:
                analysis['types']['other'].append(file)

        return analysis

    def get_draft_details(self, draft_url: str) -> Dict:
        """Get draft details"""
        draft_id = self.extract_draft_id(draft_url)
        if not draft_id:
            raise ValueError('Unable to extract draft ID from URL')

        result = self.get_draft(draft_id)
        analysis = self.analyze_files(result['files'])

        return {
            'draft_id': draft_id,
            'draft_url': draft_url,
            'files': result['files'],
            'analysis': analysis
        }

    def get_batch_drafts(self, draft_urls: Dict[str, str]) -> Dict:
        """Batch get draft information"""
        results = {}

        for name, url in draft_urls.items():
            try:
                details = self.get_draft_details(url)
                results[name] = details
                time.sleep(0.1)  # Avoid too fast requests
            except Exception as e:
                print(f"Failed to get draft {name}: {e}")
                results[name] = {'error': str(e)}

        return results

    def monitor_draft_changes(self, draft_id: str, callback: Callable, interval_seconds: int = 5) -> str:
        """Monitor draft file changes"""
        last_file_list = []
        stop_event = threading.Event()

        def check_changes():
            nonlocal last_file_list
            while not stop_event.is_set():
                try:
                    result = self.get_draft(draft_id)
                    current_files = sorted(result['files'])

                    if current_files != last_file_list:
                        changes = {
                            'added': [f for f in current_files if f not in last_file_list],
                            'removed': [f for f in last_file_list if f not in current_files],
                            'current': current_files
                        }

                        callback(changes)
                        last_file_list = current_files

                except Exception as e:
                    print(f"Failed to monitor draft changes: {e}")

                stop_event.wait(interval_seconds)

        # Initial check
        try:
            result = self.get_draft(draft_id)
            last_file_list = sorted(result['files'])
        except Exception as e:
            print(f"Initial check failed: {e}")

        # Start monitoring thread
        thread = threading.Thread(target=check_changes, daemon=True)
        thread.start()

        # Return stop function
        def stop_monitoring():
            stop_event.set()
            thread.join(timeout=1)

        return stop_monitoring

# Usage example
manager = DraftManager()

# Get single draft
draft_url = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
details = manager.get_draft_details(draft_url)

print(f"Draft ID: {details['draft_id']}")
print(f"Total files: {details['analysis']['total']}")
print(f"Video files: {len(details['analysis']['types']['video'])} files")
print(f"Audio files: {len(details['analysis']['types']['audio'])} files")
print(f"Image files: {len(details['analysis']['types']['image'])} files")

# Batch get drafts
multiple_drafts = {
    "project1": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "project2": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}

batch_results = manager.get_batch_drafts(multiple_drafts)
for name, result in batch_results.items():
    if 'error' not in result:
        print(f"{name}: {result['analysis']['total']} files")

# Monitor draft changes
def on_change(changes):
    print(f"Draft files changed:")
    if changes['added']:
        print(f"Added: {changes['added']}")
    if changes['removed']:
        print(f"Removed: {changes['removed']}")

draft_id = "2f52a63b-8c6a-4417-8b01-1b2a569ccb6c"
stop_monitoring = manager.monitor_draft_changes(draft_id, on_change)

# Stop monitoring after 30 seconds
time.sleep(30)
stop_monitoring()
print("Stopped monitoring")

Error Code Description

Error Code	Error Message	Description	Solution
400	draft_id is required	Missing draft_id parameter	Provide valid draft_id
400	draft_id length is invalid	draft_id length not in 20-32 character range	Check if draft_id format is correct
400	draft_id format is invalid	draft_id format is incorrect	Ensure using correct draft ID format
404	Draft does not exist	Specified draft ID cannot be found	Confirm draft ID is correct and exists
500	Failed to get file list	Internal service error	Contact technical support or retry later
503	Service unavailable	System under maintenance	Retry later

Notes

Parameter format: Ensure draft_id format is correct and length is between 20-32 characters
ID extraction: Correctly extract draft_id from draft_url
File types: The returned file list contains multiple types of files
Permission verification: Ensure you have permission to access the specified draft
Real-time: File list may not be updated in real-time, there may be some delay
File status: Files in the list may be in different processing states

Workflow

Validate draft_id parameter
Check draft_id format and length
Find specified draft
Get all files associated with the draft
Return file list

Best Practices

ID validation: Validate draft_id validity before calling
Error handling: Properly handle cases where draft does not exist
File analysis: Classify and analyze the returned file list
Caching strategy: Consider appropriate caching for frequently queried drafts
Change monitoring: Implement change monitoring for scenarios requiring real-time updates

Related APIs

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

[JCAIGC]Get the duration of audio files

Hommy — Fri, 28 Nov 2025 08:51:42 +0000

get_audio_duration API Documentation

API Overview

API Name: get_audio_duration

API Endpoint: POST /openapi/capcut-mate/v1/get_audio_duration

Function Description: Get the duration of audio files, supporting various common audio formats. Uses FFprobe tool for precise audio analysis, returning the accurate duration of audio files in microseconds.

Request Parameters

Request Body (application/json)

Parameter	Type	Required	Default	Description
mp3_url	string	Yes	-	Audio file URL, supports common audio formats like mp3

Parameter Description

mp3_url: Complete URL address of the audio file
- Supported formats: mp3, wav, aac, flac and other common audio formats
- Need to ensure URL is accessible and file is complete
- Recommended file size not exceeding 100MB

Request Examples

Get MP3 File Duration

{
  "mp3_url": "https://assets.jcaigc.cn/audio/sample.mp3"
}

Get WAV File Duration

{
  "mp3_url": "https://assets.jcaigc.cn/audio/music.wav"
}

Response Format

Success Response

{
  "duration": 120000000
}

Response Field Description

Field	Type	Description
duration	integer	Audio duration, unit: microseconds. Example: 120000000 represents 120 seconds (2 minutes)

Duration Unit Conversion

Microseconds to seconds: duration ÷ 1,000,000
Microseconds to milliseconds: duration ÷ 1,000
Examples:
- 120000000 microseconds = 120 seconds = 2 minutes
- 30000000 microseconds = 30 seconds
- 5000000 microseconds = 5 seconds

Error Response

400 Bad Request - Parameter Validation Failed

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request parameter validation failed",
    "details": "mp3_url parameter cannot be empty"
  }
}

500 Internal Server Error - Failed to Get Audio Duration

{
  "error": {
    "code": "AUDIO_DURATION_GET_FAILED",
    "message": "Failed to get audio duration",
    "details": "Failed to download audio file or unsupported file format"
  }
}

Error Code Description

Error Code	HTTP Status Code	Description	Solution
VALIDATION_ERROR	400	Request parameter validation failed	Check if mp3_url parameter is correctly provided
AUDIO_DURATION_GET_FAILED	500	Failed to get audio duration	Check if audio URL is accessible and file format is supported

Usage Instructions

Parameter Requirements

mp3_url parameter: Required parameter, need to provide complete audio file URL
File format: Although parameter name is mp3_url, it actually supports multiple audio formats
File size: Recommended to control within reasonable range, large files may cause processing timeout

Usage Scenarios

Video Editing Preprocessing:
- Get audio duration before adding audio to video project
- Used for calculating reasonable segmentation of audio clips
Audio Material Management:
- Batch get duration information of files in audio library
- Used for classification and filtering of audio materials
Synchronization Processing:
- Ensure audio and video duration match
- Calculate duration of audio fade-in and fade-out effects

Technical Description

Duration calculation: Uses FFprobe tool for precise audio analysis
Accuracy: Returned duration is high-precision actual value, supports 6 decimal places precision
Performance: Interface will download audio file for analysis, processing time depends on file size and network speed

Example Code

JavaScript Example

// Get audio duration
const getAudioDuration = async (audioUrl) => {
  const response = await fetch('/openapi/capcut-mate/v1/get_audio_duration', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mp3_url: audioUrl
    })
  });

  const result = await response.json();

  if (response.ok) {
    const durationSeconds = result.duration / 1000000;
    console.log(`Audio duration: ${durationSeconds}seconds`);
    return result.duration;
  } else {
    console.error('Failed to get audio duration:', result.error);
    throw new Error(result.error.message);
  }
};

// Usage example
getAudioDuration('https://assets.jcaigc.cn/audio/sample.mp3')
  .then(duration => {
    console.log(`Audio duration (microseconds): ${duration}`);
    console.log(`Audio duration (seconds): ${duration / 1000000}`);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

Python Example

import requests

def get_audio_duration(mp3_url):
    """Get audio file duration"""
    url = 'https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_audio_duration'
    data = {
        'mp3_url': mp3_url
    }

    response = requests.post(url, json=data)
    if response.status_code == 200:
        result = response.json()
        duration_microseconds = result['duration']
        duration_seconds = duration_microseconds / 1_000_000
        return duration_microseconds, duration_seconds
    else:
        print(f"Request failed: {response.status_code}")
        print(response.json())
        return None

# Usage example
audio_url = "https://assets.jcaigc.cn/audio/sample.mp3"
duration_info = get_audio_duration(audio_url)

if duration_info:
    duration_microseconds, duration_seconds = duration_info
    print(f"Audio duration: {duration_seconds:.2f}seconds ({duration_microseconds}microseconds)")

    # Duration formatting
    minutes = int(duration_seconds // 60)
    seconds = int(duration_seconds % 60)
    print(f"Formatted duration: {minutes}minutes{seconds}seconds")

Batch Processing Example

import requests
import json
from concurrent.futures import ThreadPoolExecutor
import time

def get_audio_duration_batch(audio_urls):
    """Batch get audio duration"""
    def get_single_duration(url):
        try:
            response = requests.post(
                'http://localhost:8000/v1/get_audio_duration',
                json={'mp3_url': url},
                timeout=30
            )
            if response.status_code == 200:
                duration = response.json()['duration']
                return {'url': url, 'duration': duration, 'success': True}
            else:
                return {'url': url, 'error': response.json(), 'success': False}
        except Exception as e:
            return {'url': url, 'error': str(e), 'success': False}

    # Concurrent processing
    with ThreadPoolExecutor(max_workers=5) as executor:
        results = list(executor.map(get_single_duration, audio_urls))

    return results

# Usage example
audio_urls = [
    "https://assets.jcaigc.cn/audio1.mp3",
    "https://assets.jcaigc.cn/audio2.wav",
    "https://assets.jcaigc.cn/audio3.aac"
]

results = get_audio_duration_batch(audio_urls)

for result in results:
    if result['success']:
        duration_seconds = result['duration'] / 1_000_000
        print(f"✓ {result['url']}: {duration_seconds:.2f}seconds")
    else:
        print(f"✗ {result['url']}: {result['error']}")

Related Interfaces

add_audios - Batch add audio to CapCut draft
add_videos - Batch add video to CapCut draft
easy_create_material - Quickly create multimedia materials

Technical Implementation

File Structure

src/
├── schemas/get_audio_duration.py    # Request/response data models
├── service/get_audio_duration.py    # Business logic implementation
└── router/v1.py                     # API route definition

Core Logic

Parameter validation: Validate the validity of mp3_url parameter
File download: Download audio file from URL to temporary directory
FFprobe analysis: Use FFprobe tool to get precise audio metadata
Duration extraction: Extract duration data from format info or stream info
Resource cleanup: Clean up temporarily downloaded files
Response return: Return API response in compliance with specifications

Current Implementation Features

Uses FFprobe tool from FFmpeg project for audio analysis
Supports multiple audio formats (MP3, WAV, AAC, FLAC, etc.)
Provides high-precision duration data (microsecond level)
Complete error handling and resource cleanup mechanism
Supports timeout control to prevent long-term blocking

Advantages Description

Compared to the previous estimation method based on file size, the new FFprobe implementation provides:

Higher accuracy: Directly read duration from audio metadata
Wider support: Supports all audio formats that FFprobe can recognize
More reliable results: Does not rely on bitrate estimation, directly reads actual data

Version Information: v1.0

Last Updated: 2024-09-24

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

[JCAIGC]Submit video generation task

Hommy — Fri, 28 Nov 2025 08:51:02 +0000

gen_video API Documentation

📋 Table of Contents

🔧 API Overview
🎯 Function Description
📥 Request Parameters
📤 Response Format
💻 Usage Examples
❌ Error Code Description
⚠️ Notes
🔄 Workflow
➡️ Next Steps
🔗 Related Interfaces

🔧 API Overview

API Name: gen_video

API Endpoint: POST /openapi/capcut-mate/v1/gen_video

Function Description: Submit video generation task. This interface adopts asynchronous processing mode, immediately returns task ID, and video generation proceeds in the background. Supports task queuing to ensure system stability.

Request Parameters

Request Body (application/json)

Parameter	Type	Required	Default	Description
draft_url	string	Yes	-	Draft URL, format like: https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258

Request Example

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}

Response Format

Success Response

{
  "message": "Video generation task has been submitted, please use draft_url to check progress"
}

Response Field Description

Field	Type	Description
message	string	Response message

Error Response

400 Bad Request - Parameter Validation Failed

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request parameter validation failed",
    "details": "draft_url parameter cannot be empty"
  }
}

404 Not Found - Draft Does Not Exist

{
  "error": {
    "code": "INVALID_DRAFT_URL",
    "message": "Invalid draft URL",
    "details": "Cannot parse draft ID or draft does not exist"
  }
}

500 Internal Server Error - Task Submission Failed

{
  "error": {
    "code": "VIDEO_GENERATION_SUBMIT_FAILED",
    "message": "Video generation task submission failed",
    "details": "System internal error"
  }
}

Usage Examples

cURL Example

1. Basic Video Generation

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/gen_video \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
  }'

2. Request with Timeout Setting

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/gen_video \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL"
  }' \
  --max-time 300

JavaScript Example

const generateVideo = async (draftUrl) => {
  const response = await fetch('/openapi/capcut-mate/v1/gen_video', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ draft_url: draftUrl })
  });
  return response.json();
};

// Basic usage
const draftUrl = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258";
const result = await generateVideo(draftUrl);

if (result.video_url) {
  console.log('Video generated successfully:', result.video_url);

  // Create download link
  const downloadLink = document.createElement('a');
  downloadLink.href = result.video_url;
  downloadLink.download = 'generated_video.mp4';
  downloadLink.click();
} else {
  console.error('Video generation failed:', result.message);
}

Advanced JavaScript Example

class VideoGenerator {
  constructor(baseUrl = 'https://capcut-mate.jcaigc.cn') {
    this.baseUrl = baseUrl;
  }

  async generateVideo(draftUrl, options = {}) {
    const {
      timeout = 300000, // 5 minutes timeout
      onProgress = null
    } = options;

    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), timeout);

    try {
      const response = await fetch(`${this.baseUrl}/openapi/capcut-mate/v1/gen_video`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ draft_url: draftUrl }),
        signal: controller.signal
      });

      clearTimeout(timeoutId);

      if (!response.ok) {
        throw new Error(`Video generation failed: ${response.statusText}`);
      }

      return response.json();
    } catch (error) {
      clearTimeout(timeoutId);
      if (error.name === 'AbortError') {
        throw new Error('Video generation timeout');
      }
      throw error;
    }
  }

  // Polling-based video generation (suitable for long processing)
  async generateVideoWithPolling(draftUrl, options = {}) {
    const {
      pollInterval = 5000, // 5 seconds polling interval
      maxAttempts = 60, // Maximum attempts (5 minutes)
      onProgress = null
    } = options;

    // Start generation request
    let attempt = 0;

    while (attempt < maxAttempts) {
      try {
        const result = await this.generateVideo(draftUrl, { timeout: 30000 });

        if (result.video_url) {
          if (onProgress) onProgress({ status: 'completed', result });
          return result;
        }

        if (onProgress) {
          onProgress({ 
            status: 'processing', 
            attempt: attempt + 1, 
            maxAttempts,
            message: result.message 
          });
        }

        // Wait for next poll
        await new Promise(resolve => setTimeout(resolve, pollInterval));
        attempt++;

      } catch (error) {
        if (error.message.includes('timeout')) {
          // Timeout doesn't count as failure, continue polling
          if (onProgress) {
            onProgress({ 
              status: 'processing', 
              attempt: attempt + 1, 
              maxAttempts,
              message: 'Processing...' 
            });
          }
          await new Promise(resolve => setTimeout(resolve, pollInterval));
          attempt++;
        } else {
          throw error;
        }
      }
    }

    throw new Error('Video generation timeout, please try again later');
  }

  // Batch video generation
  async generateBatchVideos(draftUrls, options = {}) {
    const {
      concurrent = 2, // Concurrent count
      onProgress = null
    } = options;

    const results = {};
    const entries = Object.entries(draftUrls);

    // Batch processing
    for (let i = 0; i < entries.length; i += concurrent) {
      const batch = entries.slice(i, i + concurrent);

      const batchPromises = batch.map(async ([name, url]) => {
        try {
          if (onProgress) {
            onProgress({ name, status: 'starting', url });
          }

          const result = await this.generateVideoWithPolling(url, {
            onProgress: (progress) => {
              if (onProgress) {
                onProgress({ name, ...progress, url });
              }
            }
          });

          results[name] = result;

          if (onProgress) {
            onProgress({ name, status: 'completed', result, url });
          }

        } catch (error) {
          console.error(`Video generation failed ${name}:`, error);
          results[name] = { error: error.message };

          if (onProgress) {
            onProgress({ name, status: 'failed', error: error.message, url });
          }
        }
      });

      await Promise.all(batchPromises);

      // Add delay between batches
      if (i + concurrent < entries.length) {
        await new Promise(resolve => setTimeout(resolve, 1000));
      }
    }

    return results;
  }

  // Download generated video
  async downloadVideo(videoUrl, filename = 'generated_video.mp4') {
    try {
      const response = await fetch(videoUrl);
      const blob = await response.blob();

      const downloadUrl = window.URL.createObjectURL(blob);
      const link = document.createElement('a');
      link.href = downloadUrl;
      link.download = filename;

      document.body.appendChild(link);
      link.click();
      document.body.removeChild(link);

      window.URL.revokeObjectURL(downloadUrl);

      return true;
    } catch (error) {
      console.error('Download video failed:', error);
      return false;
    }
  }
}

// Usage example
const videoGenerator = new VideoGenerator();

// Single video generation
const draftUrl = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258";

try {
  const result = await videoGenerator.generateVideoWithPolling(draftUrl, {
    onProgress: (progress) => {
      console.log(`Generation progress: ${progress.status}`, progress);

      if (progress.status === 'processing') {
        console.log(`Processing... (${progress.attempt}/${progress.maxAttempts})`);
      }
    }
  });

  console.log('Video generated successfully:', result.video_url);

  // Download video
  await videoGenerator.downloadVideo(result.video_url, 'my_video.mp4');

} catch (error) {
  console.error('Generation failed:', error);
}

// Batch generate videos
const multipleDrafts = {
  "video1": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "video2": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "video3": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
};

const batchResults = await videoGenerator.generateBatchVideos(multipleDrafts, {
  concurrent: 2,
  onProgress: (progress) => {
    console.log(`${progress.name}: ${progress.status}`);
  }
});

// Download all successful videos
for (const [name, result] of Object.entries(batchResults)) {
  if (result.video_url && !result.error) {
    await videoGenerator.downloadVideo(result.video_url, `${name}.mp4`);
  }
}

Python Example

import requests
import time
import asyncio
import aiohttp
from typing import Dict, Optional, Callable

class VideoGenerator:
    def __init__(self, base_url: str = "https://api.assets.jcaigc.cn"):
        self.base_url = base_url

    def generate_video(self, draft_url: str, timeout: int = 300) -> Dict:
        """Generate video"""
        response = requests.post(
            f'{self.base_url}/openapi/capcut-mate/v1/gen_video',
            headers={'Content-Type': 'application/json'},
            json={"draft_url": draft_url},
            timeout=timeout
        )
        response.raise_for_status()
        return response.json()

    def generate_video_with_polling(self, draft_url: str, 
                                  poll_interval: int = 5, 
                                  max_attempts: int = 60,
                                  on_progress: Optional[Callable] = None) -> Dict:
        """Polling-based video generation"""
        attempt = 0

        while attempt < max_attempts:
            try:
                result = self.generate_video(draft_url, timeout=30)

                if result.get('video_url'):
                    if on_progress:
                        on_progress({'status': 'completed', 'result': result})
                    return result

                if on_progress:
                    on_progress({
                        'status': 'processing',
                        'attempt': attempt + 1,
                        'max_attempts': max_attempts,
                        'message': result.get('message', 'Processing...')
                    })

                time.sleep(poll_interval)
                attempt += 1

            except requests.exceptions.Timeout:
                if on_progress:
                    on_progress({
                        'status': 'processing',
                        'attempt': attempt + 1,
                        'max_attempts': max_attempts,
                        'message': 'Processing...'
                    })
                time.sleep(poll_interval)
                attempt += 1
            except Exception as e:
                raise e

        raise Exception('Video generation timeout, please try again later')

    def generate_batch_videos(self, draft_urls: Dict[str, str], 
                            concurrent: int = 2,
                            on_progress: Optional[Callable] = None) -> Dict:
        """Batch video generation"""
        results = {}
        entries = list(draft_urls.items())

        # Batch processing
        for i in range(0, len(entries), concurrent):
            batch = entries[i:i + concurrent]
            batch_results = {}

            for name, url in batch:
                try:
                    if on_progress:
                        on_progress({'name': name, 'status': 'starting', 'url': url})

                    def progress_callback(progress):
                        if on_progress:
                            on_progress({'name': name, **progress, 'url': url})

                    result = self.generate_video_with_polling(
                        url, 
                        on_progress=progress_callback
                    )

                    batch_results[name] = result

                    if on_progress:
                        on_progress({'name': name, 'status': 'completed', 'result': result, 'url': url})

                except Exception as e:
                    print(f"Video generation failed {name}: {e}")
                    batch_results[name] = {'error': str(e)}

                    if on_progress:
                        on_progress({'name': name, 'status': 'failed', 'error': str(e), 'url': url})

            results.update(batch_results)

            # Delay between batches
            if i + concurrent < len(entries):
                time.sleep(1)

        return results

    def download_video(self, video_url: str, filename: str = "generated_video.mp4") -> bool:
        """Download video"""
        try:
            response = requests.get(video_url, stream=True)
            response.raise_for_status()

            with open(filename, 'wb') as f:
                for chunk in response.iter_content(chunk_size=8192):
                    f.write(chunk)

            print(f"Video downloaded to: {filename}")
            return True

        except Exception as e:
            print(f"Download video failed: {e}")
            return False

# Usage example
generator = VideoGenerator()

# Single video generation
draft_url = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"

def on_progress(progress):
    print(f"Generation progress: {progress['status']}")
    if progress['status'] == 'processing':
        print(f"Processing... ({progress['attempt']}/{progress['max_attempts']})")

try:
    result = generator.generate_video_with_polling(
        draft_url, 
        on_progress=on_progress
    )

    print(f"Video generated successfully: {result['video_url']}")

    # Download video
    generator.download_video(result['video_url'], 'my_video.mp4')

except Exception as e:
    print(f"Generation failed: {e}")

# Batch generation
multiple_drafts = {
    "video1": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "video2": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}

def batch_progress(progress):
    print(f"{progress['name']}: {progress['status']}")

batch_results = generator.generate_batch_videos(
    multiple_drafts,
    concurrent=2,
    on_progress=batch_progress
)

# Download all successful videos
for name, result in batch_results.items():
    if 'video_url' in result and 'error' not in result:
        generator.download_video(result['video_url'], f'{name}.mp4')

Error Code Description

Error Code	Error Message	Description	Solution
400	draft_url is required	Missing draft_url parameter	Provide valid draft_url
400	draft_url format is invalid	URL format is incorrect	Check if URL format is correct
404	Draft does not exist	Specified draft cannot be found	Confirm if draft URL is correct and exists
400	Draft content is empty	No exportable content in draft	Ensure draft contains video, audio, or image materials
400	Material cannot be accessed	Material files in draft cannot be downloaded	Check if material URLs are valid
500	Video rendering failed	Error occurred during video processing	Check draft content or contact technical support
500	Audio processing failed	Error occurred during audio mixing	Check audio format or contact technical support
500	Encoding failed	Final video encoding failed	Contact technical support
503	Service busy	Rendering server load is too high	Retry later
504	Processing timeout	Video generation timeout	Simplify draft content or retry later

Notes

Processing Time: Video generation is a time-consuming operation, may take several minutes to tens of minutes
File Size: Draft complexity and material quantity will affect processing time
Network Stability: Ensure material URLs can be stably accessed
Timeout Setting: It is recommended to set longer timeout times or use polling mechanism
Concurrency Limit: Avoid generating large numbers of videos simultaneously
Storage Space: Generated video files may be large, pay attention to storage space
URL Validity: Generated video_url may have time limitations

Workflow

Validate draft_url parameter
Parse draft configuration file
Download all required material files
Arrange and process materials by timeline
Apply visual effects and transitions
Mix audio tracks
Render final video
Encode and upload video file
Return video URL

Best Practices

Polling Check: For long processing, use polling mechanism
Error Retry: Implement automatic retry mechanism
Progress Feedback: Show processing progress to users
Batch Processing: Reasonably control concurrent quantity
Resource Cleanup: Clean up temporary files in time
Quality Control: Verify completeness of draft content before generation

Related Interfaces

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

[JCAIGC]Add multiple types of material content

Hommy — Fri, 28 Nov 2025 08:50:03 +0000

easy_create_material API Documentation

API Overview

API Name: easy_create_material

API Endpoint: POST /openapi/capcut-mate/v1/easy_create_material

Description: Add multiple types of material content to an existing draft, including audio, video, images, and text. This interface can add various media materials to the draft at once, automatically handle material properties such as duration and dimensions, and intelligently manage different types of media tracks. It is one of the core interfaces for video creation.

Request Parameters

Request Body (application/json)

Parameter	Type	Required	Default	Description
draft_url	string	Yes	-	Complete URL of the target draft
audio_url	string	Yes	-	Audio file URL, cannot be empty or null
text	string	No	null	Text content to be added
img_url	string	No	null	Image file URL
video_url	string	No	null	Video file URL
text_color	string	No	"#ffffff"	Text color (hexadecimal format)
font_size	integer	No	15	Font size
text_transform_y	integer	No	0	Text Y-axis position offset

Material Type Description

Material Type	Supported Formats	Auto Processing	Duration Setting
Audio	MP3, WAV, AAC	Auto-get duration	Use audio original duration
Video	MP4, AVI, MOV	Auto-get properties	Fixed duration 5 seconds
Image	JPEG, PNG, GIF	Auto-get dimensions	Default duration 3 seconds
Text	UTF-8 text	Support style settings	Default duration 5 seconds

Request Examples

Add All Types of Materials

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "audio_url": "https://assets.jcaigc.cn/audio.mp3",
  "text": "Hello World",
  "img_url": "https://s.coze.cn/t/JTa5Ne6_liY/",
  "video_url": "https://assets.jcaigc.cn/video.mp4",
  "text_color": "#ff0000",
  "font_size": 20,
  "text_transform_y": 100
}

Add Only Audio and Text

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "audio_url": "https://assets.jcaigc.cn/background_music.mp3",
  "text": "Welcome to watch",
  "text_color": "#0066ff",
  "font_size": 18
}

Simplest Request (Audio Only)

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "audio_url": "https://assets.jcaigc.cn/audio.wav"
}

Response Format

Success Response

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}

Error Response

400 Bad Request - Parameter Validation Failed

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request parameter validation failed",
    "details": "audio_url cannot be empty"
  }
}

404 Not Found - Draft Does Not Exist

{
  "error": {
    "code": "DRAFT_NOT_FOUND", 
    "message": "Draft file does not exist",
    "details": "Cannot find the specified draft file"
  }
}

500 Internal Server Error - Material Creation Failed

{
  "error": {
    "code": "MATERIAL_CREATE_FAILED",
    "message": "Material creation failed", 
    "details": "Error occurred while adding audio material"
  }
}

Error Code Description

Error Code	HTTP Status Code	Description	Solution
VALIDATION_ERROR	400	Request parameter validation failed	Check if required parameters are provided and parameter format is correct
DRAFT_NOT_FOUND	404	Draft file does not exist	Confirm if the draft URL is correct and if the draft has been deleted
MATERIAL_CREATE_FAILED	500	Material creation failed	Check if the material URL is valid and network connection is normal
INVALID_URL	400	URL format is invalid	Confirm the provided URL format is correct and accessible

Usage Instructions

Parameter Description

draft_url: Must be a valid CapCut draft URL, format is https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258
audio_url: Required parameter, must provide a valid audio file URL, does not accept empty strings or null values
Optional Materials: text, img_url, video_url are all optional parameters, can be added as needed
Text Style: text_color supports hexadecimal color codes, font_size range recommended 10-50
Position Offset: text_transform_y is used to adjust the vertical position of text in the frame

Material Processing Rules

Audio Processing:
- Automatically parse audio duration
- Add to audio track
- Support multiple audio formats
Video Processing:
- Fixed display duration 5 seconds
- Maintain original resolution ratio
- Add to video track
Image Processing:
- Default display duration 3 seconds
- Automatically get image dimensions
- Add to image track
Text Processing:
- Default display duration 5 seconds
- Support color and font size settings
- Adjustable vertical position

Notes

Audio is a required parameter, other material types are optional
Material URLs must be publicly accessible, HTTPS protocol is recommended
Text color uses standard hexadecimal format (e.g., #ffffff, #000000)
All durations are calculated in microseconds internally
It is recommended to ensure stable network connection before adding materials

Application Scenarios

Quickly Create Multimedia Content: Add background music, video clips, images, and title text at once
Batch Material Import: Quickly add various types of basic materials to newly created drafts
Template-based Creation: Quickly generate video drafts based on fixed material type templates
Automated Workflow: Batch add preset material content in automated video production workflows

Related Interfaces

create_draft - Create new draft file
add_audios - Add audio materials separately
add_videos - Add video materials separately
add_images - Add image materials separately
save_draft - Save draft file

Technical Implementation

File Structure

src/
├── schemas/easy_create_material.py    # Request/response data models
├── service/easy_create_material.py    # Business logic implementation
└── router/v1.py                       # API route definition

Core Logic

Parameter Validation: Validate the validity of draft URL and audio URL
Draft Loading: Parse and load draft file from URL
Material Addition: Add audio, video, image, and text materials by type
Track Management: Automatically manage track allocation for different material types
File Saving: Save the updated draft file

Log Recording

The system will record logs for the following key operations:

Draft loading success/failure
Detailed process of adding each type of material
File saving results
Error exception information

Version Information: v1.0

Last Updated: 2024-09-24

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

[JCAIGC]Create a new CapCut draft

Hommy — Fri, 28 Nov 2025 08:49:00 +0000

CREATE_DRAFT API Interface Documentation

📋 Table of Contents

🔧 Interface Information
🎯 Function Description
📖 More Documentation
📥 Request Parameters
📤 Response Format
💻 Usage Examples
❌ Error Code Description
⚠️ Notes
🔄 Workflow
➡️ Next Steps
🔗 Related Interfaces

🔧 Interface Information

POST /openapi/capcut-mate/v1/create_draft

Function Description

Create a new CapCut draft. This interface is used to create a new video editing draft, supporting custom resolution, frame rate, background color, and other parameters. It is suitable for video editing, content creation, template production, and other scenarios.

Request Parameters

Request Body (application/json)

Parameter Name	Type	Required	Default Value	Description
title	string	❌	"Untitled Draft"	Draft title, supports Chinese, English, numbers, and special characters
resolution	object	❌	{"width": 1920, "height": 1080}	Video resolution configuration
fps	number	❌	30	Video frame rate, supports 24/25/30/48/50/60
background_color	string	❌	"#000000"	Background color, supports hex color codes
duration	number	❌	60	Default duration (seconds), range: 1-3600
aspect_ratio	string	❌	"16:9"	Aspect ratio, supports preset ratios or custom ratios
quality	string	❌	"high"	Video quality level
audio_sample_rate	number	❌	48000	Audio sampling rate (Hz)
audio_channels	number	❌	2	Number of audio channels

Resolution Configuration

{
  "resolution": {
    "width": 1920,
    "height": 1080
  }
}

Resolution Options

Resolution	Width	Height	Application Scenario
1080p	1920	1080	Standard HD, universal choice
720p	1280	720	Standard definition, small file size
4K	3840	2160	Ultra HD, high quality
1440p	2560	1440	2K HD, balanced choice
Vertical 1080p	1080	1920	Short video, mobile optimization
Square	1080	1080	Social media, square format

Aspect Ratio Options

Aspect Ratio	Description	Application Scenario
16:9	Widescreen	Standard video, YouTube
9:16	Vertical screen	Short video, TikTok
1:1	Square	Instagram, social media
4:3	Standard screen	Traditional video
21:9	Ultra-wide	Movie, wide screen
custom	Custom ratio	Special needs

Quality Options

Quality Level	Description	File Size	Processing Speed
low	Low quality	Small	Fast
medium	Medium quality	Medium	Medium
high	High quality	Large	Slow
ultra	Ultra high quality	Very large	Very slow

Frame Rate Options

Frame Rate	Description	Application Scenario
24	Movie standard	Film production
25	PAL standard	European TV
30	NTSC standard	American TV, network video
48	High frame rate	Smooth motion
50	PAL high frame rate	Sports broadcast
60	Game standard	Game recording, smooth motion

Audio Configuration

Parameter Name	Options	Description
audio_sample_rate	44100, 48000, 96000	Sampling rate, 48000 recommended
audio_channels	1, 2, 6	1=mono, 2=stereo, 6=5.1 surround

Response Format

Success Response (200)

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "draft_id": "2025092811473036584258",
  "title": "My Video Draft",
  "resolution": {
    "width": 1920,
    "height": 1080
  },
  "fps": 30,
  "duration": 60,
  "created_at": "2024-09-28T11:47:30Z",
  "updated_at": "2024-09-28T11:47:30Z",
  "tip_url": "https://help.assets.jcaigc.cn/draft-usage"
}

Response Field Description

Field Name	Type	Description
draft_url	string	Draft access URL, used for subsequent operations
draft_id	string	Unique identifier of the draft
title	string	Draft title
resolution	object	Video resolution configuration
fps	number	Video frame rate
duration	number	Video duration (seconds)
created_at	string	Creation time (ISO 8601 format)
updated_at	string	Last update time (ISO 8601 format)
tip_url	string	Draft usage help document URL

Error Response (4xx/5xx)

{
  "detail": "Error message description"
}

Usage Examples

cURL Example

1. Create basic draft

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Video",
    "resolution": {"width": 1920, "height": 1080},
    "fps": 30,
    "duration": 120
  }'

2. Create vertical video draft

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
  -H "Content-Type: application/json" \
  -d '{
    "title": "TikTok Short Video",
    "resolution": {"width": 1080, "height": 1920},
    "fps": 30,
    "aspect_ratio": "9:16",
    "background_color": "#FFFFFF",
    "duration": 60
  }'

3. Create high-quality 4K draft

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
  -H "Content-Type: application/json" \
  -d '{
    "title": "4K Professional Video",
    "resolution": {"width": 3840, "height": 2160},
    "fps": 60,
    "aspect_ratio": "16:9",
    "quality": "ultra",
    "duration": 180
  }'

JavaScript Example

// Create draft function
const createDraft = async (draftConfig) => {
  const response = await fetch('/openapi/capcut-mate/v1/create_draft', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(draftConfig)
  });
  return response.json();
};

// Usage example
(async () => {
  // Create standard HD draft
  const standardDraft = await createDraft({
    title: "My Video Project",
    resolution: { width: 1920, height: 1080 },
    fps: 30,
    duration: 90
  });

  console.log('Draft created successfully:', standardDraft);

  // Create short video draft
  const shortVideoDraft = await createDraft({
    title: "Short Video Content",
    resolution: { width: 1080, height: 1920 },
    aspect_ratio: "9:16",
    fps: 30,
    background_color: "#FF6B35",
    duration: 30
  });

  console.log('Short video draft created:', shortVideoDraft);
})();

Python Example

import requests

def create_draft(draft_config):
    """Create a new CapCut draft"""
    response = requests.post(
        'https://api.assets.jcaigc.cn/openapi/capcut-mate/v1/create_draft',
        headers={'Content-Type': 'application/json'},
        json=draft_config
    )
    return response.json()

# Usage example
# 1. Create basic video draft
basic_config = {
    "title": "Basic Video Draft",
    "resolution": {"width": 1920, "height": 1080},
    "fps": 30,
    "duration": 60
}

basic_draft = create_draft(basic_config)
print(f"Basic draft created: {basic_draft['draft_url']}")

# 2. Create social media draft
social_config = {
    "title": "Instagram Video",
    "resolution": {"width": 1080, "height": 1080},
    "aspect_ratio": "1:1",
    "fps": 30,
    "quality": "high",
    "duration": 30
}

social_draft = create_draft(social_config)
print(f"Social media draft created: {social_draft['draft_url']}")

# 3. Create professional 4K draft
professional_config = {
    "title": "Professional 4K Video",
    "resolution": {"width": 3840, "height": 2160},
    "fps": 60,
    "aspect_ratio": "16:9",
    "quality": "ultra",
    "audio_sample_rate": 48000,
    "audio_channels": 2,
    "duration": 120
}

professional_draft = create_draft(professional_config)
print(f"Professional 4K draft created: {professional_draft['draft_url']}")

Error Code Description

Error Code	Error Message	Description	Solution
400	Invalid resolution format	Resolution parameter format error	Use correct resolution object format
400	Invalid fps value	Frame rate value is out of range	Use preset frame rate values
400	Invalid background_color format	Background color format error	Use valid hex color codes
400	Invalid duration value	Duration value is out of range	Duration should be between 1-3600 seconds
400	Invalid aspect_ratio format	Aspect ratio format error	Use preset ratio values
400	Invalid quality value	Quality level error	Use preset quality values
400	Invalid audio_sample_rate	Audio sampling rate error	Use preset sampling rate values
400	Invalid audio_channels	Number of audio channels error	Use 1, 2, or 6
500	Draft creation failed	Internal service error	Contact technical support or try again later
503	Service unavailable	System under maintenance	Try again later

Notes

Title Setting: Use a descriptive title to facilitate subsequent management and search
Resolution Selection: Choose appropriate resolution based on target platform and usage scenario
Frame Rate Setting: Choose appropriate frame rate based on content type and target platform
Quality Balance: Balance video quality and file size, choose appropriate quality level
Duration Planning: Set reasonable default duration to avoid overly long or too short
Background Color: Choose appropriate background color to match video content style
Aspect Ratio: Choose appropriate aspect ratio based on target platform requirements
Audio Configuration: Set appropriate audio parameters to ensure sound quality
Network Stability: Draft creation requires network support, ensure stable network connection

Workflow

Verify request parameter format and validity
Create draft basic configuration
Generate unique draft_id
Initialize draft file structure
Set video basic parameters (resolution, frame rate, etc.)
Configure audio parameters
Create draft access URL
Return draft creation result

Next Steps

After creating the draft, you can use the following interfaces to add content:

add_videos: Add video materials
add_images: Add image materials
add_audios: Add audio materials
add_captions: Add subtitles
add_effects: Add special effects
add_masks: Add mask effects
save_draft: Save draft
gen_video: Export video

Related Interfaces

get_draft - Get draft information
save_draft - Save draft
add_videos - Add video materials
add_images - Add image materials
add_audios - Add audio materials
gen_video - Generate video

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

[JCAIGC]Batch add video materials

Hommy — Fri, 28 Nov 2025 08:48:05 +0000

ADD_VIDEOS API Interface Documentation

📋 Table of Contents

🔧 Interface Information
🎯 Function Description
📖 More Documentation
📥 Request Parameters
📤 Response Format
💻 Usage Examples
❌ Error Code Description
⚠️ Notes
🔄 Workflow
➡️ Next Steps
🔗 Related Interfaces

🔧 Interface Information

POST /openapi/capcut-mate/v1/add_videos

Function Description

Batch add video materials. This interface is used to add multiple video materials to CapCut draft at once, supporting mask effects, transition animations, volume control, and other advanced features. It is suitable for multi-track video editing, picture-in-picture effects, split-screen effects, and other scenarios.

Request Parameters

Request Body (application/json)

Parameter Name	Type	Required	Default Value	Description
draft_url	string	✅	-	Target draft URL, format: https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=xxx
videos	array	✅	-	Video material list, supports adding multiple videos at once

Video Object Structure

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "videos": [
    {
      "video_url": "https://example.com/video1.mp4",
      "duration": 10.0,
      "position": "center",
      "scale": 1.0,
      "rotation": 0,
      "opacity": 1.0,
      "start_time": 0,
      "volume": 1.0,
      "speed": 1.0,
      "mask": {
        "type": "circle",
        "size": 0.8,
        "feather": 0.2
      },
      "animation": {
        "in": "fade_in",
        "out": "fade_out",
        "duration": 1.0
      },
      "transition": {
        "type": "slide_left",
        "duration": 0.5
      }
    }
  ]
}

Video Parameter Description

Parameter Name	Type	Required	Default Value	Description
video_url	string	✅	-	Video file URL, supports MP4, MOV, AVI, MKV formats
duration	number	❌	Auto	Video display duration (seconds)
position	string	❌	"center"	Video position
scale	number	❌	1.0	Video scale, range: 0.1-5.0
rotation	number	❌	0	Video rotation angle, range: -360 to 360 degrees
opacity	number	❌	1.0	Video transparency, range: 0.0-1.0
start_time	number	❌	0	Start display time (seconds)
volume	number	❌	1.0	Volume, range: 0.0-2.0
speed	number	❌	1.0	Playback speed, range: 0.25-4.0
mask	object	❌	null	Mask effect configuration
animation	object	❌	null	Animation effect configuration
transition	object	❌	null	Transition effect configuration

Position Options

Position Value	Description	Coordinate Position
top_left	Top left corner	(0%, 0%)
top_center	Top center	(50%, 0%)
top_right	Top right corner	(100%, 0%)
center_left	Center left	(0%, 50%)
center	Absolute center	(50%, 50%)
center_right	Center right	(100%, 50%)
bottom_left	Bottom left corner	(0%, 100%)
bottom_center	Bottom center	(50%, 100%)
bottom_right	Bottom right corner	(100%, 100%)

Custom Position

In addition to using preset positions, you can also use custom coordinates:

{
  "position": {
    "x": 100,
    "y": 200,
    "unit": "px"
  }
}

Mask Effect Configuration

Mask Type	Description	Application Scenario
circle	Circular mask	Portrait highlighting, circular picture-in-picture
rectangle	Rectangular mask	Regular picture-in-picture, cropping
ellipse	Elliptical mask	Portrait beautification, soft transitions
star	Star mask	Creative transitions, special effects
heart	Heart-shaped mask	Romantic themes, emotional expression

Animation Effect Configuration

Animation Type	Description	Application Scenario
fade_in	Fade in	Natural transition
fade_out	Fade out	Natural transition
scale_in	Scale in	Highlight effect
scale_out	Scale out	Highlight effect
slide_left	Slide in from left	Dynamic entry
slide_right	Slide in from right	Dynamic entry
slide_up	Slide in from bottom	Dynamic entry
slide_down	Slide in from top	Dynamic entry
rotate	Rotation	Dynamic effect
bounce	Bounce	Lively effect

Transition Effect Configuration

Transition Type	Description	Application Scenario
slide_left	Slide left	Smooth transition
slide_right	Slide right	Smooth transition
slide_up	Slide up	Smooth transition
slide_down	Slide down	Smooth transition
fade	Fade	Natural transition
dissolve	Dissolve	Creative transition
wipe_left	Wipe left	Dynamic transition
wipe_right	Wipe right	Dynamic transition

Speed Parameter Description

Speed Range	Effect Description
0.25 - 0.5	Slow motion, suitable for detail display
0.5 - 0.9	Slow playback, suitable for emphasizing content
1.0	Normal speed, standard playback
1.1 - 2.0	Fast playback, suitable for time-lapse effects
2.1 - 4.0	High speed, suitable for fast-forward effects

Volume Parameter Description

Volume Range	Effect Description
0.0	Mute, no sound
0.1 - 0.3	Low volume, suitable for background music
0.4 - 0.7	Medium volume, suitable for normal dialogue
0.8 - 1.0	High volume, suitable for main content
1.1 - 2.0	Extra high volume, suitable for special needs

Response Format

Success Response (200)

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "tip_url": "https://help.assets.jcaigc.cn/draft-usage"
}

Response Field Description

Field Name	Type	Description
draft_url	string	Draft URL after adding videos, same as the request URL
tip_url	string	Draft usage help document URL

Error Response (4xx/5xx)

{
  "detail": "Error message description"
}

Usage Examples

cURL Example

1. Basic video addition

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "videos": [
      {
        "video_url": "https://example.com/main_video.mp4",
        "duration": 30.0,
        "position": "center",
        "scale": 1.0,
        "volume": 1.0,
        "start_time": 0
      }
    ]
  }'

2. Picture-in-picture effect

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "videos": [
      {
        "video_url": "https://example.com/background.mp4",
        "duration": 60.0,
        "position": "center",
        "scale": 1.0,
        "volume": 0.3,
        "start_time": 0
      },
      {
        "video_url": "https://example.com/overlay.mp4",
        "duration": 20.0,
        "position": "bottom_right",
        "scale": 0.3,
        "opacity": 0.9,
        "volume": 1.0,
        "start_time": 10.0,
        "mask": {
          "type": "circle",
          "size": 0.8,
          "feather": 0.2
        },
        "animation": {
          "in": "scale_in",
          "out": "fade_out",
          "duration": 1.0
        }
      }
    ]
  }'

3. Split-screen effect

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "videos": [
      {
        "video_url": "https://example.com/left_video.mp4",
        "duration": 30.0,
        "position": {
          "x": 25,
          "y": 50,
          "unit": "%"
        },
        "scale": 0.5,
        "volume": 1.0,
        "start_time": 0
      },
      {
        "video_url": "https://example.com/right_video.mp4",
        "duration": 30.0,
        "position": {
          "x": 75,
          "y": 50,
          "unit": "%"
        },
        "scale": 0.5,
        "volume": 1.0,
        "start_time": 0
      }
    ]
  }'

JavaScript Example

// Add video function
const addVideos = async (draftUrl, videoList) => {
  const response = await fetch('/openapi/capcut-mate/v1/add_videos', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      draft_url: draftUrl,
      videos: videoList
    })
  });
  return response.json();
};

// Usage example - Picture-in-picture effect
(async () => {
  const draftUrl = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258";

  const videoList = [
    {
      video_url: "https://example.com/background.mp4",
      duration: 60.0,
      position: "center",
      scale: 1.0,
      volume: 0.3,
      start_time: 0
    },
    {
      video_url: "https://example.com/overlay.mp4",
      duration: 20.0,
      position: "bottom_right",
      scale: 0.3,
      opacity: 0.9,
      volume: 1.0,
      start_time: 10.0,
      mask: {
        type: "circle",
        size: 0.8,
        feather: 0.2
      },
      animation: {
        in: "scale_in",
        out: "fade_out",
        duration: 1.0
      }
    }
  ];

  const result = await addVideos(draftUrl, videoList);
  console.log('Videos added successfully:', result);
})();

Python Example

import requests

def add_videos(draft_url, video_list):
    """Batch add video materials"""
    response = requests.post(
        'https://api.assets.jcaigc.cn/openapi/capcut-mate/v1/add_videos',
        headers={'Content-Type': 'application/json'},
        json={
            "draft_url": draft_url,
            "videos": video_list
        }
    )
    return response.json()

# Usage example - Split-screen effect
draft_url = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"

video_list = [
    {
        "video_url": "https://example.com/left_video.mp4",
        "duration": 30.0,
        "position": {
            "x": 25,
            "y": 50,
            "unit": "%"
        },
        "scale": 0.5,
        "volume": 1.0,
        "start_time": 0
    },
    {
        "video_url": "https://example.com/right_video.mp4",
        "duration": 30.0,
        "position": {
            "x": 75,
            "y": 50,
            "unit": "%"
        },
        "scale": 0.5,
        "volume": 1.0,
        "start_time": 0
    }
]

result = add_videos(draft_url, video_list)
print(f"Videos added successfully: {result['draft_url']}")

Error Code Description

Error Code	Error Message	Description	Solution
400	draft_url is required	Missing draft URL parameter	Provide a valid draft_url
400	videos parameter must be an array	videos parameter format error	Ensure videos is an array type
400	video_url cannot be empty	Video URL cannot be empty	Provide a valid video_url
400	Invalid duration value	Duration value is out of range	Duration should be greater than 0
400	Invalid scale value	Scale value is out of range	Scale should be between 0.1-5.0
400	Invalid rotation value	Rotation angle is out of range	Rotation should be between -360 to 360 degrees
400	Invalid opacity value	Transparency value is out of range	Opacity should be between 0.0-1.0
400	Invalid volume value	Volume value is out of range	Volume should be between 0.0-2.0
400	Invalid speed value	Speed value is out of range	Speed should be between 0.25-4.0
400	Invalid mask type	Mask type error	Use preset mask types
400	Invalid animation type	Animation type error	Use preset animation types
400	Invalid transition type	Transition type error	Use preset transition types
404	Draft does not exist	Specified draft cannot be found	Confirm the draft URL is correct and exists
500	Video addition failed	Internal service error	Contact technical support or try again later
503	Service unavailable	System under maintenance	Try again later

Notes

Video Format: Support MP4, MOV, AVI, MKV formats, MP4 recommended
Video Size: It is recommended that single video files do not exceed 500MB for better processing speed
Duration Setting: Set appropriate duration to ensure complete video content display
Position Layout: Choose appropriate positions to achieve the desired visual effect
Scale Control: Adjust the scale appropriately to achieve the best visual effect
Volume Control: Adjust volume appropriately to achieve the best audio effect
Speed Adjustment: Use speed adjustment moderately to achieve special effects
Mask Effects: Use mask effects appropriately to create creative visual effects
Animation Effects: Choose appropriate animation effects to enhance visual appeal
Transition Effects: Use transition effects appropriately to achieve smooth transitions
Network Stability: Adding videos requires network support, ensure stable network connection

Workflow

Verify draft_url and videos parameters
Validate video_url format and accessibility
Apply position, scale, rotation, and transparency settings
Configure volume and speed parameters
Apply mask, animation, and transition effects
Generate video material objects
Apply videos to the draft
Update draft configuration file
Return updated draft information

Next Steps

After adding video materials, you can continue to use the following interfaces to improve the video:

add_images: Add image materials
add_audios: Add audio materials
add_captions: Add subtitles
add_effects: Add special effects
add_masks: Add mask effects
save_draft: Save draft
gen_video: Export video

Related Interfaces

create_draft - Create a new draft
add_images - Add image materials
add_audios - Add audio materials
add_masks - Add mask effects
gen_video - Generate video

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

[JCAIGC]Create rich text styles

Hommy — Fri, 28 Nov 2025 08:47:21 +0000

ADD_TEXT_STYLE API Interface Documentation

📋 Table of Contents

🔧 Interface Information
🎯 Function Description
📖 More Documentation
📥 Request Parameters
📤 Response Format
💻 Usage Examples
❌ Error Code Description
⚠️ Notes
🔄 Workflow
➡️ Next Steps
🔗 Related Interfaces

🔧 Interface Information

POST /openapi/capcut-mate/v1/add_text_style

Function Description

Create rich text styles. This interface is used to create rich text styles with specific formatting, including keyword highlighting, color settings, font size adjustments, etc. It is suitable for video subtitle beautification, text highlighting, content emphasis, and other scenarios.

Request Parameters

Request Body (application/json)

Parameter Name	Type	Required	Default Value	Description
draft_url	string	✅	-	Target draft URL, format: https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=xxx
text_styles	array	✅	-	Rich text style list, supports creating multiple text styles at once

Text Style Object Structure

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "text_styles": [
    {
      "element_id": "text_001",
      "keyword": "important",
      "style": {
        "color": "#FF6B35",
        "font_size": 24,
        "font_weight": "bold",
        "background_color": "#FFE5CC",
        "border_color": "#FF6B35",
        "border_width": 2,
        "padding": 8,
        "border_radius": 12
      },
      "apply_to": "keyword"
    }
  ]
}

Text Style Parameter Description

Parameter Name	Type	Required	Default Value	Description
element_id	string	✅	-	Text element ID, used to identify the target text element
keyword	string	❌	-	Keyword, used to match specific text content
style	object	✅	-	Style configuration object
apply_to	string	❌	"all"	Application scope

Style Object Structure

Parameter Name	Type	Required	Default Value	Description
color	string	❌	"#000000"	Text color, supports hex color codes
font_size	number	❌	16	Font size, range: 8-72
font_weight	string	❌	"normal"	Font weight
background_color	string	❌	"transparent"	Background color
border_color	string	❌	"transparent"	Border color
border_width	number	❌	0	Border width, range: 0-10
padding	number	❌	0	Inner padding, range: 0-20
border_radius	number	❌	0	Border radius, range: 0-50
text_decoration	string	❌	"none"	Text decoration
text_shadow	string	❌	"none"	Text shadow
font_family	string	❌	"system"	Font family
line_height	number	❌	1.2	Line height, range: 0.8-3.0
letter_spacing	number	❌	0	Letter spacing, range: -5 to 20
text_align	string	❌	"left"	Text alignment

Apply Scope Options

Apply Scope	Description	Application Scenario
all	Apply to all text	Overall style modification
keyword	Apply only to matching keywords	Keyword highlighting
sentence	Apply to sentences containing keywords	Sentence emphasis
paragraph	Apply to paragraphs containing keywords	Paragraph highlighting

Font Weight Options

Font Weight	Description	Effect
normal	Normal font weight	Standard effect
bold	Bold	Emphasis effect
lighter	Lighter	Soft effect
bolder	Extra bold	Strong emphasis
100-900	Numeric weight	Precise control

Text Decoration Options

Decoration Type	Description
none	No decoration
underline	Underline
overline	Overline
line_through	Strikethrough
underline line_through	Underline and strikethrough

Text Alignment Options

Alignment	Description
left	Left aligned
center	Center aligned
right	Right aligned
justify	Justified

Text Shadow Options

{
  "text_shadow": "2px 2px 4px rgba(0,0,0,0.3)"
}

Font Family Options

Font Family	Description
system	System default font
serif	Serif font
sans_serif	Sans-serif font
monospace	Monospace font
cursive	Cursive font
fantasy	Fantasy font

Response Format

Success Response (200)

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "tip_url": "https://help.assets.jcaigc.cn/draft-usage"
}

Response Field Description

Field Name	Type	Description
draft_url	string	Draft URL after creating text styles, same as the request URL
tip_url	string	Draft usage help document URL

Error Response (4xx/5xx)

{
  "detail": "Error message description"
}

Usage Examples

cURL Example

1. Keyword highlighting

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_text_style \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "text_styles": [
      {
        "element_id": "text_001",
        "keyword": "important",
        "style": {
          "color": "#FF6B35",
          "font_size": 24,
          "font_weight": "bold",
          "background_color": "#FFE5CC",
          "border_color": "#FF6B35",
          "border_width": 2,
          "padding": 8,
          "border_radius": 12
        },
        "apply_to": "keyword"
      }
    ]
  }'

2. Multiple text styles

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_text_style \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "text_styles": [
      {
        "element_id": "text_001",
        "keyword": "title",
        "style": {
          "color": "#2E86AB",
          "font_size": 32,
          "font_weight": "bold",
          "text_align": "center",
          "text_shadow": "2px 2px 4px rgba(0,0,0,0.3)"
        },
        "apply_to": "keyword"
      },
      {
        "element_id": "text_001",
        "keyword": "warning",
        "style": {
          "color": "#F24236",
          "font_size": 20,
          "font_weight": "bold",
          "background_color": "#FFE5E5",
          "border_color": "#F24236",
          "border_width": 3,
          "border_radius": 8,
          "padding": 6
        },
        "apply_to": "keyword"
      },
      {
        "element_id": "text_002",
        "style": {
          "color": "#4ECDC4",
          "font_size": 18,
          "font_family": "sans_serif",
          "line_height": 1.5,
          "letter_spacing": 1
        },
        "apply_to": "all"
      }
    ]
  }'

JavaScript Example

// Create text style function
const addTextStyle = async (draftUrl, textStyleList) => {
  const response = await fetch('/openapi/capcut-mate/v1/add_text_style', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      draft_url: draftUrl,
      text_styles: textStyleList
    })
  });
  return response.json();
};

// Usage example
(async () => {
  const draftUrl = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258";

  const textStyleList = [
    {
      element_id: "text_001",
      keyword: "important",
      style: {
        color: "#FF6B35",
        font_size: 24,
        font_weight: "bold",
        background_color: "#FFE5CC",
        border_color: "#FF6B35",
        border_width: 2,
        padding: 8,
        border_radius: 12
      },
      apply_to: "keyword"
    },
    {
      element_id: "text_002",
      style: {
        color: "#4ECDC4",
        font_size: 18,
        font_family: "sans_serif",
        line_height: 1.5,
        letter_spacing: 1
      },
      apply_to: "all"
    }
  ];

  const result = await addTextStyle(draftUrl, textStyleList);
  console.log('Text styles created successfully:', result);
})();

Python Example

import requests

def add_text_style(draft_url, text_style_list):
    """Create rich text styles"""
    response = requests.post(
        'https://api.assets.jcaigc.cn/openapi/capcut-mate/v1/add_text_style',
        headers={'Content-Type': 'application/json'},
        json={
            "draft_url": draft_url,
            "text_styles": text_style_list
        }
    )
    return response.json()

# Usage example
draft_url = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"

text_style_list = [
    {
        "element_id": "text_001",
        "keyword": "important",
        "style": {
            "color": "#FF6B35",
            "font_size": 24,
            "font_weight": "bold",
            "background_color": "#FFE5CC",
            "border_color": "#FF6B35",
            "border_width": 2,
            "padding": 8,
            "border_radius": 12
        },
        "apply_to": "keyword"
    },
    {
        "element_id": "text_002",
        "style": {
            "color": "#4ECDC4",
            "font_size": 18,
            "font_family": "sans_serif",
            "line_height": 1.5,
            "letter_spacing": 1
        },
        "apply_to": "all"
    }
]

result = add_text_style(draft_url, text_style_list)
print(f"Text styles created successfully: {result['draft_url']}")

Error Code Description

Error Code	Error Message	Description	Solution
400	draft_url is required	Missing draft URL parameter	Provide a valid draft_url
400	text_styles parameter must be an array	text_styles parameter format error	Ensure text_styles is an array type
400	element_id cannot be empty	Element ID cannot be empty	Provide a valid element_id
400	Invalid color format	Color format error	Use valid hex color codes
400	Invalid font_size value	Font size is out of range	Font size should be between 8-72
400	Invalid font_weight value	Font weight error	Use preset font weight values
400	Invalid apply_to value	Application scope error	Use preset application scope values
404	Draft does not exist	Specified draft cannot be found	Confirm the draft URL is correct and exists
404	Text element does not exist	Specified text element cannot be found	Confirm the element_id is correct and exists
500	Text style creation failed	Internal service error	Contact technical support or try again later
503	Service unavailable	System under maintenance	Try again later

Notes

Element ID: Make sure the element_id exists and is unique, used to identify the target text element
Color Format: Use valid hex color codes (e.g., #FF6B35)
Font Size: Adjust font size appropriately to ensure text readability
Application Scope: Choose appropriate application scope to achieve precise style control
Keyword Matching: Keyword matching is case-sensitive, ensure accurate matching
Style Priority: When multiple styles conflict, the later created styles take precedence
Performance Optimization: Avoid creating too many text styles to prevent performance issues
Compatibility: Test style effects on different devices to ensure good compatibility
Network Stability: Creating text styles requires network support, ensure stable network connection

Workflow

Verify draft_url and text_styles parameters
Validate element_id and text element existence
Parse style configuration parameters
Apply keyword matching rules
Generate rich text style objects
Apply styles to the corresponding text elements
Update draft configuration file
Return updated draft information

Next Steps

After creating text styles, you can continue to use the following interfaces to improve the video:

add_videos: Add video materials
add_images: Add image materials
add_audios: Add audio materials
add_captions: Add subtitles
add_effects: Add special effects
save_draft: Save draft
gen_video: Export video

Related Interfaces

create_draft - Create a new draft
add_videos - Add video materials
add_images - Add image materials
add_audios - Add audio materials
gen_video - Generate video

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

[JCAIGC]Add sticker materials

Hommy — Fri, 28 Nov 2025 08:46:33 +0000

ADD_STICKER API Interface Documentation

📋 Table of Contents

🔧 Interface Information
🎯 Function Description
📖 More Documentation
📥 Request Parameters
📤 Response Format
💻 Usage Examples
❌ Error Code Description
⚠️ Notes
🔄 Workflow
➡️ Next Steps
🔗 Related Interfaces

🔧 Interface Information

POST /openapi/capcut-mate/v1/add_sticker

Function Description

Add sticker materials. This interface is used to add various sticker materials to CapCut draft, including emoji, decorative stickers, dynamic stickers, and other types. It is suitable for video beautification, emotional expression, content annotation, and other scenarios.

Request Parameters

Request Body (application/json)

Parameter Name	Type	Required	Default Value	Description
draft_url	string	✅	-	Target draft URL, format: https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=xxx
stickers	array	✅	-	Sticker material list, supports adding multiple stickers at once

Sticker Object Structure

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "stickers": [
    {
      "sticker_url": "https://example.com/sticker1.png",
      "duration": 5.0,
      "position": "center",
      "scale": 1.0,
      "rotation": 0,
      "opacity": 1.0,
      "start_time": 2.0,
      "animation": "fade_in"
    }
  ]
}

Sticker Parameter Description

Parameter Name	Type	Required	Default Value	Description
sticker_url	string	✅	-	Sticker image URL, supports PNG, JPG, GIF, WebP formats
duration	number	✅	-	Sticker display duration (seconds), minimum 0.1 seconds
position	string	❌	"center"	Sticker position
scale	number	❌	1.0	Sticker scale, range: 0.1-5.0
rotation	number	❌	0	Sticker rotation angle, range: -360 to 360 degrees
opacity	number	❌	1.0	Sticker transparency, range: 0.0-1.0
start_time	number	❌	0	Start display time (seconds)
animation	string	❌	"none"	Animation effect type

Position Options

Position Value	Description	Coordinate Position
top_left	Top left corner	(0%, 0%)
top_center	Top center	(50%, 0%)
top_right	Top right corner	(100%, 0%)
center_left	Center left	(0%, 50%)
center	Absolute center	(50%, 50%)
center_right	Center right	(100%, 50%)
bottom_left	Bottom left corner	(0%, 100%)
bottom_center	Bottom center	(50%, 100%)
bottom_right	Bottom right corner	(100%, 100%)

Custom Position

In addition to using preset positions, you can also use custom coordinates:

{
  "position": {
    "x": 100,
    "y": 200,
    "unit": "px"
  }
}

Animation Effect Types

Animation Type	Description	Application Scenario
none	No animation	Static sticker
fade_in	Fade in	Natural transition
scale_in	Scale in	Highlight effect
slide_in_left	Slide in from left	Dynamic entry
slide_in_right	Slide in from right	Dynamic entry
slide_in_top	Slide in from top	Dynamic entry
slide_in_bottom	Slide in from bottom	Dynamic entry
bounce	Bounce	Lively effect
rotate	Rotation	Dynamic effect

Sticker Type Description

Sticker Type	Format	Features
Static sticker	PNG, JPG	Small size, fast loading
Dynamic sticker	GIF, WebP	Animated effect, lively
Transparent sticker	PNG	Support transparency, good fusion
Emoji sticker	PNG, GIF	Rich expressions, strong interactivity
Decorative sticker	PNG, JPG	Beautiful appearance, strong decoration

Scale Parameter Description

Scale Range	Effect Description
0.1 - 0.3	Very small, suitable for detail decoration
0.3 - 0.6	Small size, suitable for auxiliary elements
0.6 - 1.0	Medium size, suitable for regular stickers
1.0 - 1.5	Large size, suitable for main elements
1.5 - 5.0	Extra large, suitable for special effects

Response Format

Success Response (200)

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "tip_url": "https://help.assets.jcaigc.cn/draft-usage"
}

Response Field Description

Field Name	Type	Description
draft_url	string	Draft URL after adding stickers, same as the request URL
tip_url	string	Draft usage help document URL

Error Response (4xx/5xx)

{
  "detail": "Error message description"
}

Usage Examples

cURL Example

1. Add single sticker

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_sticker \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "stickers": [
      {
        "sticker_url": "https://example.com/smile.png",
        "duration": 3.0,
        "position": "center",
        "scale": 1.0,
        "rotation": 0,
        "opacity": 1.0,
        "start_time": 0,
        "animation": "fade_in"
      }
    ]
  }'

2. Add multiple stickers

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_sticker \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
    "stickers": [
      {
        "sticker_url": "https://example.com/emoji1.png",
        "duration": 2.0,
        "position": "top_left",
        "scale": 0.8,
        "rotation": 15,
        "opacity": 0.9,
        "start_time": 1.0,
        "animation": "bounce"
      },
      {
        "sticker_url": "https://example.com/emoji2.gif",
        "duration": 3.5,
        "position": "bottom_right",
        "scale": 1.2,
        "rotation": -10,
        "opacity": 1.0,
        "start_time": 2.5,
        "animation": "scale_in"
      },
      {
        "sticker_url": "https://example.com/emoji3.png",
        "duration": 1.5,
        "position": "center",
        "scale": 0.6,
        "rotation": 0,
        "opacity": 0.7,
        "start_time": 0.5,
        "animation": "rotate"
      }
    ]
  }'

JavaScript Example

// Add sticker function
const addSticker = async (draftUrl, stickerList) => {
  const response = await fetch('/openapi/capcut-mate/v1/add_sticker', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      draft_url: draftUrl,
      stickers: stickerList
    })
  });
  return response.json();
};

// Usage example
(async () => {
  const draftUrl = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258";

  const stickerList = [
    {
      sticker_url: "https://example.com/smile.png",
      duration: 3.0,
      position: "center",
      scale: 1.0,
      rotation: 0,
      opacity: 1.0,
      start_time: 0,
      animation: "fade_in"
    },
    {
      sticker_url: "https://example.com/heart.gif",
      duration: 2.5,
      position: "top_right",
      scale: 0.8,
      rotation: 15,
      opacity: 0.9,
      start_time: 1.0,
      animation: "bounce"
    }
  ];

  const result = await addSticker(draftUrl, stickerList);
  console.log('Stickers added successfully:', result);
})();

Python Example

import requests

def add_sticker(draft_url, sticker_list):
    """Add sticker materials"""
    response = requests.post(
        'https://api.assets.jcaigc.cn/openapi/capcut-mate/v1/add_sticker',
        headers={'Content-Type': 'application/json'},
        json={
            "draft_url": draft_url,
            "stickers": sticker_list
        }
    )
    return response.json()

# Usage example
draft_url = "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"

sticker_list = [
    {
        "sticker_url": "https://example.com/smile.png",
        "duration": 3.0,
        "position": "center",
        "scale": 1.0,
        "rotation": 0,
        "opacity": 1.0,
        "start_time": 0,
        "animation": "fade_in"
    },
    {
        "sticker_url": "https://example.com/heart.gif",
        "duration": 2.5,
        "position": "top_right",
        "scale": 0.8,
        "rotation": 15,
        "opacity": 0.9,
        "start_time": 1.0,
        "animation": "bounce"
    }
]

result = add_sticker(draft_url, sticker_list)
print(f"Stickers added successfully: {result['draft_url']}")

Error Code Description

Error Code	Error Message	Description	Solution
400	draft_url is required	Missing draft URL parameter	Provide a valid draft_url
400	stickers parameter must be an array	stickers parameter format error	Ensure stickers is an array type
400	sticker_url cannot be empty	Sticker URL cannot be empty	Provide a valid sticker_url
400	Invalid duration value	Duration value is out of range	Duration should be greater than 0.1 seconds
400	Invalid scale value	Scale value is out of range	Scale should be between 0.1-5.0
400	Invalid rotation value	Rotation angle is out of range	Rotation should be between -360 to 360 degrees
400	Invalid opacity value	Transparency value is out of range	Opacity should be between 0.0-1.0
400	Invalid animation type	Animation type error	Use preset animation types
404	Draft does not exist	Specified draft cannot be found	Confirm the draft URL is correct and exists
500	Sticker addition failed	Internal service error	Contact technical support or try again later
503	Service unavailable	System under maintenance	Try again later

Notes

Sticker Format: Support PNG, JPG, GIF, WebP formats, PNG recommended for transparent effects
Image Size: It is recommended that sticker images do not exceed 2MB for better loading speed
Duration Setting: Set appropriate duration to ensure the sticker display effect
Position Layout: Choose appropriate positions to avoid blocking important content
Scale Control: Adjust the scale appropriately to achieve the best visual effect
Animation Effects: Choose appropriate animation effects to enhance visual appeal
Transparency Adjustment: Adjust transparency appropriately to achieve better fusion effects
Rotation Angle: Use rotation moderately to increase dynamic effects
Start Time: Set appropriate start time to achieve precise timing control
Network Stability: Adding stickers requires network support, ensure stable network connection

Workflow

Verify draft_url and stickers parameters
Validate sticker_url format and accessibility
Apply position, scale, rotation, and transparency settings
Generate sticker animation effects
Create sticker material objects
Apply stickers to the draft
Update draft configuration file
Return updated draft information

Next Steps

After adding sticker materials, you can continue to use the following interfaces to improve the video:

add_videos: Add video materials
add_images: Add image materials
add_audios: Add audio materials
add_captions: Add subtitles
add_effects: Add special effects
save_draft: Save draft
gen_video: Export video

Related Interfaces

create_draft - Create a new draft
add_videos - Add video materials
add_images - Add image materials
add_audios - Add audio materials
gen_video - Generate video

📚 Project Resources

GitHub: https://github.com/Hommy-master/capcut-mate

Gitee: https://gitee.com/taohongmin-gitee/capcut-mate

DEV Community: Hommy

【剪映小助手】快速开始

快速开始

目录

简介

项目结构

核心组件

架构总览

详细组件分析

后端服务（FastAPI）

新增 响应中间件与语言切换

配置中心（config.py）

桌面客户端（Electron + React）

依赖分析

性能注意事项

结论

附录

环境要求

安装与运行步骤

方式一：源码安装（本地开发）

方式二：Docker 部署

方式三：桌面客户端使用

跨平台功能对比

语言切换使用指南

[JCAIGC]Save CapCut draft

SAVE_DRAFT API Documentation

📋 Table of Contents

🔧 Interface Information

Function Description

More Documentation

Request Parameters

Parameter Description

Parameter Details

draft_url

Response Field Description

Error Response (4xx/5xx)

Usage Examples

cURL Example

1. Basic Draft Save

JavaScript Example

Advanced JavaScript Example

Python Example

Usage example

Basic save

Save with retry

Start auto-save

Stop auto-save after 10 minutes

Error Codes

Notes

Workflow

Best Practices

Related Interfaces

[JCAIGC]Get text entrance/exit animation list

get_text_animations API Documentation

Interface Overview

More Documentation

Request Parameters

Request Body (application/json)

Animation Mode Description

Animation Type Description

Request Examples

Get All Entrance Animations

Get VIP Exit Animations

Get Free Loop Animations

Response Format

Success Response

Animation Object Structure

Error Response

400 Bad Request - Parameter Validation Failed

500 Internal Server Error - Failed to Get Animations

Error Codes

Usage Instructions

Parameter Instructions

Animation Application Scenarios

Usage Recommendations

Example Code

JavaScript Example

Python Example

Related Interfaces

Technical Implementation

新增响应中间件与语言切换