opensource/capcut-mate
3
0
Fork 0
mirror of https://github.com/Hommy-master/capcut-mate.git synced 2026-08-28 23:27:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

添加国际化支持。

Browse Source
This commit is contained in:
Hommy
2026-03-01 09:47:20 +08:00
parent c500e69e20
commit e524808aed
18 changed files with 2488 additions and 791 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+123 -119
View File
@@ -1,38 +1,38 @@
# CapCut Mate API
## 项目简介
CapCut Mate API 是一个基于 FastAPI 构建的剪映草稿自动化助手，提供丰富的API接口来创建和编辑剪映草稿。支持创建草稿、添加视频/音频/图片/字幕/特效等素材、保存草稿及云端渲染等功能，可作为扣子插件一键部署使用。
## Project Introduction
CapCut Mate API is a Jianying draft automation assistant built on FastAPI, providing rich API interfaces to create and edit Jianying drafts. It supports creating drafts, adding materials such as videos/audio/images/subtitles/effects, saving drafts, and cloud rendering. It can be deployed as a Coze plugin with one-click setup.
## 项目相关资源
- [剪映小助手](https://github.com/Hommy-master/capcut-mate)
- [剪映小助手-扣子插件](https://www.coze.cn/store/plugin/7576197869707722771)
## Project Resources
- [Jianying Assistant](https://github.com/Hommy-master/capcut-mate)
- [Jianying Assistant - Coze Plugin](https://www.coze.cn/store/plugin/7576197869707722771)
⭐ 如果您觉得这个项目对您有点帮助，麻烦点个 Star 支持一下！您的支持是我持续维护和改进项目的最大动力 😊
⭐ If you find this project helpful, please give us a Star! Your support is the greatest motivation for me to continuously maintain and improve the project 😊
## 功能特点
- 🎬 草稿管理：创建草稿、获取草稿、保存草稿
- 🎥 素材添加：添加视频、音频、图片、贴纸、字幕、特效、遮罩等
- 🔧 高级功能：关键帧控制、文字样式、动画效果等
- 📤 视频导出：云端渲染生成最终视频
- 🛡️ 数据验证：使用 Pydantic 进行请求数据验证
- 📖 RESTful API：符合标准的 API 设计规范
- 📚 自动文档：FastAPI 自动生成交互式 API 文档
## Features
- 🎬 Draft Management: Create draft, get draft, save draft
- 🎥 Material Addition: Add videos, audios, images, stickers, subtitles, effects, masks, etc.
- 🔧 Advanced Functions: Keyframe control, text styles, animation effects, etc.
- 📤 Video Export: Cloud rendering to generate final video
- 🛡️ Data Validation: Using Pydantic for request data validation
- 📖 RESTful API: Compliant with standard API design specifications
- 📚 Auto Documentation: FastAPI automatically generates interactive API documentation
## 技术栈
## Tech Stack
- Python 3.11+
- FastAPI：高性能的 Web 框架
- Pydantic：数据验证和模型定义
- Passlib：密码加密（如果使用用户认证）
- Uvicorn：ASGI 服务器
- uv：Python 包管理器和项目管理工具
- FastAPI: High-performance web framework
- Pydantic: Data validation and model definition
- Passlib: Password encryption (if using user authentication)
- Uvicorn: ASGI server
- uv: Python package manager and project management tool
## 快速开始
## Quick Start
### 前提条件
### Prerequisites
- Python 3.11+
- uv：Python 包管理器和项目管理工具
- uv: Python package manager and project management tool
安装方法:
Installation:
#### Windows
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
@@ -43,135 +43,135 @@ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | ie
sh -c "$(curl -LsSf https://astral.sh/uv/install.sh)"
```
### 安装步骤
1. 克隆项目
### Installation Steps
1. Clone the project
```bash
git clone git@github.com:Hommy-master/capcut-mate.git
cd capcut-mate
```
2. 安装依赖
2. Install dependencies
```bash
# 安装依赖
# Install dependencies
uv sync
# windows额外执行
# Additional execution for Windows
uv pip install -e .[windows]
```
3. 启动服务器
3. Start the server
```bash
uv run main.py
```
4. 访问API文档
启动后访问 http://localhost:30000/docs 查看自动生成的交互式API文档
4. Access API documentation
After starting, visit http://localhost:30000/docs to view the automatically generated interactive API documentation
### 容器部署
### Container Deployment
```bash
docker pull gogoshine/capcut-mate:latest
docker run -p 30000:30000 gogoshine/capcut-mate:latest
```
或者使用 docker-compose:
Or use docker-compose:
```bash
docker-compose up -d
```
## 一键导入扣子插件
## One-Click Import Coze Plugin
1. 打开扣子平台：https://coze.cn/home
1. Open Coze platform: https://coze.cn/home
![步骤1](./assets/coze1.png)
![Step 1](./assets/coze1.png)
2. 添加插件
2. Add Plugin
![步骤2](./assets/coze2.png)
![Step 2](./assets/coze2.png)
3. 导入插件
3. Import Plugin
![步骤3](./assets/coze3.png)
![Step 3](./assets/coze3.png)
4. 上传当前工程目录下的openapi.yaml文件
4. Upload the openapi.yaml file in the current project directory
![步骤4](./assets/coze4.png)
![Step 4](./assets/coze4.png)
5. 完成文件上传
5. Complete file upload
![步骤5](./assets/coze5.png)
![Step 5](./assets/coze5.png)
6. 替换logo完成
6. Complete logo replacement
![步骤6](./assets/coze6.png)
![Step 6](./assets/coze6.png)
7. 启用插件
7. Enable Plugin
![步骤7](./assets/coze7.png)
![Step 7](./assets/coze7.png)
## API 接口文档
## API Documentation
以下是 CapCut Mate API 提供的核心接口，支持完整的视频创作工作流程：
The following are the core interfaces provided by CapCut Mate API, supporting a complete video creation workflow:
### 🏗️ 草稿管理
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **create_draft** | 创建草稿 | 创建新的剪映草稿项目，设置画布尺寸 | [📖 查看文档](./docs/create_draft.md) |
| **save_draft** | 保存草稿 | 保存当前草稿状态，确保编辑内容持久化 | [📖 查看文档](./docs/save_draft.md) |
| **get_draft** | 获取草稿 | 获取草稿文件列表和详细信息 | [📖 查看文档](./docs/get_draft.md) |
### 🏗️ Draft Management
| Interface | Function | Description | Documentation Link |
|-----------|----------|-------------|-------------------|
| **create_draft** | Create Draft | Create a new Jianying draft project, set canvas size | [📖 View Documentation](./docs/create_draft.md) |
| **save_draft** | Save Draft | Save current draft state, ensure edit content persistence | [📖 View Documentation](./docs/save_draft.md) |
| **get_draft** | Get Draft | Get draft file list and detailed information | [📖 View Documentation](./docs/get_draft.md) |
### 🎥 视频素材
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **add_videos** | 添加视频 | 批量添加视频素材，支持裁剪、缩放、特效 | [📖 查看文档](./docs/add_videos.md) |
| **add_images** | 添加图片 | 批量添加图片素材，支持动画和转场效果 | [📖 查看文档](./docs/add_images.md) |
| **add_sticker** | 添加贴纸 | 添加装饰贴纸，支持位置和大小调整 | [📖 查看文档](./docs/add_sticker.md) |
### 🎥 Video Materials
| Interface | Function | Description | Documentation Link |
|-----------|----------|-------------|-------------------|
| **add_videos** | Add Videos | Batch add video materials, support cropping, scaling, effects | [📖 View Documentation](./docs/add_videos.md) |
| **add_images** | Add Images | Batch add image materials, support animations and transition effects | [📖 View Documentation](./docs/add_images.md) |
| **add_sticker** | Add Stickers | Add decorative stickers, support position and size adjustment | [📖 View Documentation](./docs/add_sticker.md) |
### 🎵 音频处理
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **add_audios** | 添加音频 | 批量添加音频素材，支持音量和淡入淡出 | [📖 查看文档](./docs/add_audios.md) |
| **get_audio_duration** | 获取音频时长 | 获取音频文件的精确时长信息 | [📖 查看文档](./docs/get_audio_duration.md) |
### 🎵 Audio Processing
| Interface | Function | Description | Documentation Link |
|-----------|----------|-------------|-------------------|
| **add_audios** | Add Audios | Batch add audio materials, support volume and fade in/out | [📖 View Documentation](./docs/add_audios.md) |
| **get_audio_duration** | Get Audio Duration | Get precise duration information of audio files | [📖 View Documentation](./docs/get_audio_duration.md) |
### 📝 文本字幕
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **add_captions** | 添加字幕 | 批量添加字幕，支持关键词高亮和样式设置 | [📖 查看文档](./docs/add_captions.md) |
| **add_text_style** | 文本样式 | 创建富文本样式，支持关键词颜色和字体 | [📖 查看文档](./docs/add_text_style.md) |
### 📝 Text Subtitles
| Interface | Function | Description | Documentation Link |
|-----------|----------|-------------|-------------------|
| **add_captions** | Add Captions | Batch add captions, support keyword highlighting and style settings | [📖 View Documentation](./docs/add_captions.md) |
| **add_text_style** | Text Style | Create rich text styles, support keyword colors and fonts | [📖 View Documentation](./docs/add_text_style.md) |
### ✨ 特效动画
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **add_effects** | 添加特效 | 添加视觉特效，如滤镜、边框、动态效果 | [📖 查看文档](./docs/add_effects.md) |
| **add_keyframes** | 关键帧动画 | 创建位置、缩放、旋转等属性动画 | [📖 查看文档](./docs/add_keyframes.md) |
| **add_masks** | 遮罩效果 | 添加各种形状遮罩，控制画面可见区域 | [📖 查看文档](./docs/add_masks.md) |
### ✨ Effects & Animations
| Interface | Function | Description | Documentation Link |
|-----------|----------|-------------|-------------------|
| **add_effects** | Add Effects | Add visual effects, such as filters, borders, dynamic effects | [📖 View Documentation](./docs/add_effects.md) |
| **add_keyframes** | Keyframe Animation | Create property animations for position, scale, rotation, etc. | [📖 View Documentation](./docs/add_keyframes.md) |
| **add_masks** | Mask Effects | Add various shape masks, control visible areas of the screen | [📖 View Documentation](./docs/add_masks.md) |
### 🎨 动画资源
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **get_text_animations** | 文件动画 | 获取可用的文本入场、出场、循环动画 | [📖 查看文档](./docs/get_text_animations.md) |
| **get_image_animations** | 图片动画 | 获取可用的图片动画效果列表 | [📖 查看文档](./docs/get_image_animations.md) |
### 🎨 Animation Resources
| Interface | Function | Description | Documentation Link |
|-----------|----------|-------------|-------------------|
| **get_text_animations** | Text Animations | Get available text entrance, exit, and loop animations | [📖 View Documentation](./docs/get_text_animations.md) |
| **get_image_animations** | Image Animations | Get available image animation effects list | [📖 View Documentation](./docs/get_image_animations.md) |
### 🎬 视频生成
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **gen_video** | 生成视频 | 提交视频渲染任务，异步处理 | [📖 查看文档](./docs/gen_video.md) |
| **gen_video_status** | 查询状态 | 查询视频生成任务的进度和状态 | [📖 查看文档](./docs/gen_video_status.md) |
### 🎬 Video Generation
| Interface | Function | Description | Documentation Link |
|-----------|----------|-------------|-------------------|
| **gen_video** | Generate Video | Submit video rendering task, asynchronous processing | [📖 View Documentation](./docs/gen_video.md) |
| **gen_video_status** | Query Status | Query the progress and status of video generation tasks | [📖 View Documentation](./docs/gen_video_status.md) |
### 🚀 快速工具
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **easy_create_material** | 快速创建 | 一次性添加多种类型素材，简化创建流程 | [📖 查看文档](./docs/easy_create_material.md) |
### 🚀 Quick Tools
| Interface | Function | Description | Documentation Link |
|-----------|----------|-------------|-------------------|
| **easy_create_material** | Quick Creation | Add multiple types of materials at once, simplify creation process | [📖 View Documentation](./docs/easy_create_material.md) |
## API 使用示例
## API Usage Examples
### 创建草稿
### Create Draft
```bash
curl -X POST "http://localhost:30000/openapi/capcut-mate/v1/create_draft" \
-H "Content-Type: application/json" \
-d '{"width": 1080, "height": 1920}'
```
### 添加视频
### Add Videos
```bash
curl -X POST "http://localhost:30000/openapi/capcut-mate/v1/add_videos" \
-H "Content-Type: application/json" \
@@ -187,52 +187,56 @@ curl -X POST "http://localhost:30000/openapi/capcut-mate/v1/add_videos" \
}'
```
## API 文档
- 本地访问: http://localhost:30000/docs
- ReDoc 版本: http://localhost:30000/redoc
## API Documentation
- Local Access: http://localhost:30000/docs
- ReDoc Version: http://localhost:30000/redoc
## 剪映小助手客户端
## Jianying Assistant Client
剪映小助手客户端提供了桌面端的便捷操作界面，以下是启动方法：
The Jianying Assistant client provides a convenient desktop interface. Here are the startup methods:
### macOS 沙箱权限说明
### macOS Sandbox Permissions Guide
在 macOS 上运行时，应用可能会请求访问特定文件夹的权限。请按照以下步骤操作：
When running on macOS, the application may request access permissions for specific folders. Please follow these steps:
1. 如果首次运行时出现权限提示，请允许应用访问所需文件夹
2. 如需手动配置，请前往 `系统偏好设置 > 安全性与隐私 > 隐私 > 文件夹访问`
3. 确保 CapCut Mate 应用已被添加到允许列表中
1. If permission prompts appear during the first run, allow the application to access the required folders
2. For manual configuration, go to `System Preferences > Security & Privacy > Privacy > Folder Access`
3. Ensure the CapCut Mate application is added to the allowed list
更多详细信息，请参阅 [macOS 沙箱权限配置指南](./docs/macos_sandbox_setup.md)。
For more details, please refer to the [macOS Sandbox Permissions Configuration Guide](./docs/macos_sandbox_setup.md).
1. 安装依赖
1. Install Dependencies
```bash
# 切换npm镜像源 - 适用于windows
# Switch npm mirror source - for Windows
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
# 切换yarn镜像源 - 适用于linux 或 mac
# Switch yarn mirror source - for Linux or macOS
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
# 安装依赖
# Install dependencies
npm install --verbose
```
2. 启动项目
2. Start the Project
```bash
npm run web:dev
npm start
```
## 开源社区问题交流群
- 微信群：
## Open Source Community Discussion Group
- WeChat Group:
<img src="./assets/wechat-q.jpg" width="344" height="498" alt="剪映小助手">
<img src="./assets/wechat-q.jpg" width="344" height="498" alt="Jianying Assistant">
## 商业合作
- 微信：
## Business Cooperation
- WeChat:
<img src="./assets/wechat.jpg" width="220" height="220" alt="技术支持微信">
<img src="./assets/wechat.jpg" width="220" height="220" alt="Technical Support WeChat">
- 邮箱：taohongmin51@gmail.com
- Email: taohongmin51@gmail.com
---
### Language Switch
[中文版](README.zh.md) | [English](README.md)
README.zh.md
+242
View File
@@ -0,0 +1,242 @@
# CapCut Mate API
## 项目简介
CapCut Mate API 是一个基于 FastAPI 构建的剪映草稿自动化助手，提供丰富的API接口来创建和编辑剪映草稿。支持创建草稿、添加视频/音频/图片/字幕/特效等素材、保存草稿及云端渲染等功能，可作为扣子插件一键部署使用。
## 项目相关资源
- [剪映小助手](https://github.com/Hommy-master/capcut-mate)
- [剪映小助手-扣子插件](https://www.coze.cn/store/plugin/7576197869707722771)
⭐ 如果您觉得这个项目对您有点帮助，麻烦点个 Star 支持一下！您的支持是我持续维护和改进项目的最大动力 😊
## 功能特点
- 🎬 草稿管理：创建草稿、获取草稿、保存草稿
- 🎥 素材添加：添加视频、音频、图片、贴纸、字幕、特效、遮罩等
- 🔧 高级功能：关键帧控制、文字样式、动画效果等
- 📤 视频导出：云端渲染生成最终视频
- 🛡️ 数据验证：使用 Pydantic 进行请求数据验证
- 📖 RESTful API：符合标准的 API 设计规范
- 📚 自动文档：FastAPI 自动生成交互式 API 文档
## 技术栈
- Python 3.11+
- FastAPI：高性能的 Web 框架
- Pydantic：数据验证和模型定义
- Passlib：密码加密（如果使用用户认证）
- Uvicorn：ASGI 服务器
- uv：Python 包管理器和项目管理工具
## 快速开始
### 前提条件
- Python 3.11+
- uv：Python 包管理器和项目管理工具
安装方法:
#### Windows
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
#### Linux/macOS
```bash
sh -c "$(curl -LsSf https://astral.sh/uv/install.sh)"
```
### 安装步骤
1. 克隆项目
```bash
git clone git@github.com:Hommy-master/capcut-mate.git
cd capcut-mate
```
2. 安装依赖
```bash
# 安装依赖
uv sync
# windows额外执行
uv pip install -e .[windows]
```
3. 启动服务器
```bash
uv run main.py
```
4. 访问API文档
启动后访问 http://localhost:30000/docs 查看自动生成的交互式API文档
### 容器部署
```bash
docker pull gogoshine/capcut-mate:latest
docker run -p 30000:30000 gogoshine/capcut-mate:latest
```
或者使用 docker-compose:
```bash
docker-compose up -d
```
## 一键导入扣子插件
1. 打开扣子平台：https://coze.cn/home
![步骤1](./assets/coze1.png)
2. 添加插件
![步骤2](./assets/coze2.png)
3. 导入插件
![步骤3](./assets/coze3.png)
4. 上传当前工程目录下的openapi.yaml文件
![步骤4](./assets/coze4.png)
5. 完成文件上传
![步骤5](./assets/coze5.png)
6. 替换logo完成
![步骤6](./assets/coze6.png)
7. 启用插件
![步骤7](./assets/coze7.png)
## API 接口文档
以下是 CapCut Mate API 提供的核心接口，支持完整的视频创作工作流程：
### 🏗️ 草稿管理
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **create_draft** | 创建草稿 | 创建新的剪映草稿项目，设置画布尺寸 | [📖 查看文档](./docs/create_draft.md) |
| **save_draft** | 保存草稿 | 保存当前草稿状态，确保编辑内容持久化 | [📖 查看文档](./docs/save_draft.md) |
| **get_draft** | 获取草稿 | 获取草稿文件列表和详细信息 | [📖 查看文档](./docs/get_draft.md) |
### 🎥 视频素材
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **add_videos** | 添加视频 | 批量添加视频素材，支持裁剪、缩放、特效 | [📖 查看文档](./docs/add_videos.md) |
| **add_images** | 添加图片 | 批量添加图片素材，支持动画和转场效果 | [📖 查看文档](./docs/add_images.md) |
| **add_sticker** | 添加贴纸 | 添加装饰贴纸，支持位置和大小调整 | [📖 查看文档](./docs/add_sticker.md) |
### 🎵 音频处理
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **add_audios** | 添加音频 | 批量添加音频素材，支持音量和淡入淡出 | [📖 查看文档](./docs/add_audios.md) |
| **get_audio_duration** | 获取音频时长 | 获取音频文件的精确时长信息 | [📖 查看文档](./docs/get_audio_duration.md) |
### 📝 文本字幕
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **add_captions** | 添加字幕 | 批量添加字幕，支持关键词高亮和样式设置 | [📖 查看文档](./docs/add_captions.md) |
| **add_text_style** | 文本样式 | 创建富文本样式，支持关键词颜色和字体 | [📖 查看文档](./docs/add_text_style.md) |
### ✨ 特效动画
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **add_effects** | 添加特效 | 添加视觉特效，如滤镜、边框、动态效果 | [📖 查看文档](./docs/add_effects.md) |
| **add_keyframes** | 关键帧动画 | 创建位置、缩放、旋转等属性动画 | [📖 查看文档](./docs/add_keyframes.md) |
| **add_masks** | 遮罩效果 | 添加各种形状遮罩，控制画面可见区域 | [📖 查看文档](./docs/add_masks.md) |
### 🎨 动画资源
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **get_text_animations** | 文件动画 | 获取可用的文本入场、出场、循环动画 | [📖 查看文档](./docs/get_text_animations.md) |
| **get_image_animations** | 图片动画 | 获取可用的图片动画效果列表 | [📖 查看文档](./docs/get_image_animations.md) |
### 🎬 视频生成
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **gen_video** | 生成视频 | 提交视频渲染任务，异步处理 | [📖 查看文档](./docs/gen_video.md) |
| **gen_video_status** | 查询状态 | 查询视频生成任务的进度和状态 | [📖 查看文档](./docs/gen_video_status.md) |
### 🚀 快速工具
| 接口 | 功能 | 描述 | 文档链接 |
|------|------|------|----------|
| **easy_create_material** | 快速创建 | 一次性添加多种类型素材，简化创建流程 | [📖 查看文档](./docs/easy_create_material.md) |
## API 使用示例
### 创建草稿
```bash
curl -X POST "http://localhost:30000/openapi/capcut-mate/v1/create_draft" \
-H "Content-Type: application/json" \
-d '{"width": 1080, "height": 1920}'
```
### 添加视频
```bash
curl -X POST "http://localhost:30000/openapi/capcut-mate/v1/add_videos" \
-H "Content-Type: application/json" \
-d '{
"draft_url": "http://localhost:30000/openapi/capcut-mate/v1/get_draft?draft_id=20251126212753cab03392",
"video_infos": [
{
"url": "https://example.com/video.mp4",
"start": 0,
"end": 1000000
}
]
}'
```
## API 文档
- 本地访问: http://localhost:30000/docs
- ReDoc 版本: http://localhost:30000/redoc
## 剪映小助手客户端
剪映小助手客户端提供了桌面端的便捷操作界面，以下是启动方法：
### macOS 沙箱权限说明
在 macOS 上运行时，应用可能会请求访问特定文件夹的权限。请按照以下步骤操作：
1. 如果首次运行时出现权限提示，请允许应用访问所需文件夹
2. 如需手动配置，请前往 `系统偏好设置 > 安全性与隐私 > 隐私 > 文件夹访问`
3. 确保 CapCut Mate 应用已被添加到允许列表中
更多详细信息，请参阅 [macOS 沙箱权限配置指南](./docs/macos_sandbox_setup.md)。
1. 安装依赖
```bash
# 切换npm镜像源 - 适用于windows
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
# 切换yarn镜像源 - 适用于linux 或 mac
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
# 安装依赖
npm install --verbose
```
2. 启动项目
```bash
npm run web:dev
npm start
```
## 开源社区问题交流群
- 微信群：
<img src="./assets/wechat-q.jpg" width="344" height="498" alt="剪映小助手">
## 商业合作
- 微信：
<img src="./assets/wechat.jpg" width="220" height="220" alt="技术支持微信">
- 邮箱：taohongmin51@gmail.com
---
### 语言切换
[中文版](README.zh.md) | [English](README.md)
docs/add_audios.md
+95 -92
View File
@@ -1,20 +1,20 @@
# ADD_AUDIOS API 接口文档
# ADD_AUDIOS API Documentation
## 接口信息
## Interface Information
```
POST /openapi/capcut-mate/v1/add_audios
```
## 功能描述
## Function Description
批量向现有草稿中添加音频素材。该接口支持添加多个音频文件到剪映草稿，为视频创建背景音乐、音效、旁白等音频内容。音频将被添加到独立的音频轨道中，不会影响视频内容。
Batch add audio materials to existing drafts. This interface supports adding multiple audio files to Jianying drafts, creating background music, sound effects, narration and other audio content for videos. Audio will be added to separate audio tracks without affecting video content.
## 更多文档
## More Documentation
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
📖 For more detailed documentation and tutorials, please visit: [https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
## Request Parameters
```json
{
@@ -23,52 +23,52 @@ POST /openapi/capcut-mate/v1/add_audios
}
```
### 参数说明
### Parameter Description
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
| audio_infos | string | ✅ | - | 音频信息数组的JSON字符串 |
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| draft_url | string | ✅ | - | Complete URL of the target draft |
| audio_infos | string | ✅ | - | JSON string of audio information array |
### audio_infos 数组结构
### audio_infos Array Structure
audio_infos是一个JSON字符串，解析后为数组，每个元素包含以下字段：
audio_infos is a JSON string that resolves to an array, with each element containing the following fields:
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| audio_url | string | ✅ | - | 音频文件的URL地址 |
| start | number | ✅ | - | 音频开始播放时间(微秒) |
| end | number | ✅ | - | 音频结束播放时间(微秒) |
| duration | number | ❌ | 自动获取 | 音频总时长(微秒)，如果不提供将自动获取 |
| volume | number | ❌ | 1.0 | 音量大小(0.0-2.0) |
| audio_effect | string | ❌ | None | 音频效果名称 |
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| audio_url | string | ✅ | - | URL address of the audio file |
| start | number | ✅ | - | Audio start playback time (microseconds) |
| end | number | ✅ | - | Audio end playback time (microseconds) |
| duration | number | ❌ | Automatically obtained | Total audio duration (microseconds), automatically obtained if not provided |
| volume | number | ❌ | 1.0 | Volume size (0.0-2.0) |
| audio_effect | string | ❌ | None | Audio effect name |
### 参数详解
### Parameter Details
#### 时间参数
#### Time Parameters
- **start**: 音频在时间轴上的开始时间，单位为微秒（1秒 = 1,000,000微秒）
- **end**: 音频在时间轴上的结束时间，单位为微秒
- **duration**: 音频文件的总时长，用于素材创建，单位为微秒，如果不提供将自动获取
- **播放时长**: 实际播放时长 = end - start
- **start**: Start time of the audio on the timeline, unit microseconds (1 second = 1,000,000 microseconds)
- **end**: End time of the audio on the timeline, unit microseconds
- **duration**: Total duration of the audio file, used for material creation, unit microseconds, automatically obtained if not provided
- **Playback Duration**: Actual playback duration = end - start
#### 音量控制
#### Volume Control
- **volume**: 音频音量大小
- 1.0 = 原始音量
- 0.5 = 一半音量
- 0.0 = 静音
- 范围：0.0 - 2.0
- **volume**: Audio volume size
- 1.0 = Original volume
- 0.5 = Half volume
- 0.0 = Mute
- Range: 0.0 - 2.0
#### 音频效果
#### Audio Effects
- **audio_effect**: 音频效果名称
- None = 无音频效果
- 示例：`"reverb"`（混响效果）
- **audio_effect**: Audio effect name
- None = No audio effect
- Example: `"reverb"` (reverb effect)
## 响应格式
## Response Format
### 成功响应 (200)
### Success Response (200)
```json
{
@@ -78,27 +78,27 @@ audio_infos是一个JSON字符串，解析后为数组，每个元素包含以
}
```
### 响应字段说明
### Response Field Description
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 更新后的草稿URL |
| track_id | string | 音频轨道ID |
| audio_ids | array | 添加的音频ID列表 |
| Field | Type | Description |
|-------|------|-------------|
| draft_url | string | Updated draft URL |
| track_id | string | Audio track ID |
| audio_ids | array | List of added audio IDs |
### 错误响应 (4xx/5xx)
### Error Response (4xx/5xx)
```json
{
"detail": "错误信息描述"
"detail": "Error message description"
}
```
## 使用示例
## Usage Examples
### cURL 示例
### cURL Examples
#### 1. 基本音频添加
#### 1. Basic Audio Addition
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
@@ -109,7 +109,7 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
}'
```
#### 2. 多音频批量添加
#### 2. Batch Adding Multiple Audios
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
@@ -120,7 +120,7 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
}'
```
#### 3. 带淡入淡出效果的音频
#### 3. Audio with Fade In/Out Effects
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
@@ -131,57 +131,60 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
}'
```
## 错误码说明
## Error Code Description
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的草稿URL |
| 400 | audio_infos是必填项 | 缺少音频信息参数 | 提供有效的音频信息JSON |
| 400 | audio_infos格式错误 | JSON格式不正确 | 检查JSON字符串格式 |
| 400 | 音频配置验证失败 | 音频参数不符合要求 | 检查每个音频的参数 |
| 400 | audio_url是必填项 | 音频URL缺失 | 为每个音频提供URL |
| 400 | 时间范围无效 | end必须大于start | 确保结束时间大于开始时间 |
| 400 | 音量值无效 | volume不在0.0-2.0范围内 | 使用0.0-2.0之间的音量值 |
| 404 | 草稿不存在 | 指定的草稿URL无效 | 检查草稿URL是否正确 |
| 404 | 音频资源不存在 | 音频URL无法访问 | 检查音频URL是否可访问 |
| 500 | 音频处理失败 | 内部处理错误 | 联系技术支持 |
| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 400 | draft_url is required | Missing draft URL parameter | Provide a valid draft URL |
| 400 | audio_infos is required | Missing audio information parameter | Provide valid audio information JSON |
| 400 | audio_infos format error | JSON format is incorrect | Check JSON string format |
| 400 | Audio configuration validation failed | Audio parameters do not meet requirements | Check parameters for each audio |
| 400 | audio_url is required | Audio URL missing | Provide URL for each audio |
| 400 | Time range invalid | end must be greater than start | Ensure end time is greater than start time |
| 400 | Volume value invalid | volume not in 0.0-2.0 range | Use volume value between 0.0-2.0 |
| 404 | Draft does not exist | Specified draft URL invalid | Check if draft URL is correct |
| 404 | Audio resource does not exist | Audio URL inaccessible | Check if audio URL is accessible |
| 500 | Audio processing failed | Internal processing error | Contact technical support |
## 注意事项
## Notes
1. **JSON格式**: audio_infos必须是合法的JSON字符串
2. **时间单位**: 所有时间参数使用微秒（1秒 = 1,000,000微秒）
3. **音频格式**: 确保音频文件格式被支持（如MP3、WAV、AAC等）
4. **文件大小**: 大音频文件可能影响处理速度
5. **网络访问**: 音频URL必须可以正常访问
6. **音量范围**: 音量值必须在0.0-2.0范围内
7. **轨道限制**: 同一时间段可能存在音频重叠
1. **JSON Format**: audio_infos must be a valid JSON string
2. **Time Unit**: All time parameters use microseconds (1 second = 1,000,000 microseconds)
3. **Audio Format**: Ensure audio file format is supported (e.g., MP3, WAV, AAC, etc.)
4. **File Size**: Large audio files may affect processing speed
5. **Network Access**: Audio URL must be accessible
6. **Volume Range**: Volume value must be within 0.0-2.0 range
7. **Track Limitation**: Audio overlap may occur in the same time period
## 工作流程
## Workflow
1. 验证必填参数（draft_url, audio_infos）
2. 解析audio_infos JSON字符串
3. 验证每个音频的参数配置
4. 获取并解密草稿内容
5. 创建音频轨道
6. 添加音频片段到轨道
7. 应用音量和音频效果
8. 保存并加密草稿
9. 返回处理结果
1. Validate required parameters (draft_url, audio_infos)
2. Parse audio_infos JSON string
3. Validate parameter configuration for each audio
4. Obtain and decrypt draft content
5. Create audio track
6. Add audio segments to track
7. Apply volume and audio effects
8. Save and encrypt draft
9. Return processing result
## 相关接口
## Related Interfaces
- [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加图片](./add_images.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)
- [Create Draft](./create_draft.md)
- [Add Videos](./add_videos.md)
- [Add Images](./add_images.md)
- [Save Draft](./save_draft.md)
- [Generate Video](./gen_video.md)
---
<div align="right">
📚 **项目资源**
📚 **Project Resources**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
</div>
### Language Switch
[中文版](./add_audios.zh.md) | [English](./add_audios.md)
docs/add_audios.zh.md
+190
View File
@@ -0,0 +1,190 @@
# ADD_AUDIOS API 接口文档
## 接口信息
```
POST /openapi/capcut-mate/v1/add_audios
```
## 功能描述
批量向现有草稿中添加音频素材。该接口支持添加多个音频文件到剪映草稿，为视频创建背景音乐、音效、旁白等音频内容。音频将被添加到独立的音频轨道中，不会影响视频内容。
## 更多文档
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"audio_infos": "[{\"audio_url\":\"https://assets.jcaigc.cn/audio1.mp3\",\"start\":0,\"end\":5000000,\"duration\":10000000,\"volume\":1.0,\"audio_effect\":\"reverb\"}]"
}
```
### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
| audio_infos | string | ✅ | - | 音频信息数组的JSON字符串 |
### audio_infos 数组结构
audio_infos是一个JSON字符串，解析后为数组，每个元素包含以下字段：
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| audio_url | string | ✅ | - | 音频文件的URL地址 |
| start | number | ✅ | - | 音频开始播放时间(微秒) |
| end | number | ✅ | - | 音频结束播放时间(微秒) |
| duration | number | ❌ | 自动获取 | 音频总时长(微秒)，如果不提供将自动获取 |
| volume | number | ❌ | 1.0 | 音量大小(0.0-2.0) |
| audio_effect | string | ❌ | None | 音频效果名称 |
### 参数详解
#### 时间参数
- **start**: 音频在时间轴上的开始时间，单位为微秒（1秒 = 1,000,000微秒）
- **end**: 音频在时间轴上的结束时间，单位为微秒
- **duration**: 音频文件的总时长，用于素材创建，单位为微秒，如果不提供将自动获取
- **播放时长**: 实际播放时长 = end - start
#### 音量控制
- **volume**: 音频音量大小
- 1.0 = 原始音量
- 0.5 = 一半音量
- 0.0 = 静音
- 范围：0.0 - 2.0
#### 音频效果
- **audio_effect**: 音频效果名称
- None = 无音频效果
- 示例：`"reverb"`（混响效果）
## 响应格式
### 成功响应 (200)
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"track_id": "audio-track-uuid",
"audio_ids": ["audio1-uuid", "audio2-uuid", "audio3-uuid"]
}
```
### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 更新后的草稿URL |
| track_id | string | 音频轨道ID |
| audio_ids | array | 添加的音频ID列表 |
### 错误响应 (4xx/5xx)
```json
{
"detail": "错误信息描述"
}
```
## 使用示例
### cURL 示例
#### 1. 基本音频添加
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"audio_infos": "[{\"audio_url\":\"https://assets.jcaigc.cn/bgm.mp3\",\"start\":0,\"end\":10000000,\"duration\":15000000,\"volume\":0.8}]"
}'
```
#### 2. 多音频批量添加
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"audio_infos": "[{\"audio_url\":\"https://assets.jcaigc.cn/intro.mp3\",\"start\":0,\"end\":3000000,\"duration\":5000000,\"volume\":1.0},{\"audio_url\":\"https://assets.jcaigc.cn/bgm.mp3\",\"start\":3000000,\"end\":30000000,\"duration\":35000000,\"volume\":0.6}]"
}'
```
#### 3. 带淡入淡出效果的音频
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_audios \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"audio_infos": "[{\"audio_url\":\"https://assets.jcaigc.cn/outro.mp3\",\"start\":25000000,\"end\":30000000,\"duration\":8000000,\"volume\":0.9,\"audio_effect\":\"reverb\"}]"
}'
```
## 错误码说明
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的草稿URL |
| 400 | audio_infos是必填项 | 缺少音频信息参数 | 提供有效的音频信息JSON |
| 400 | audio_infos格式错误 | JSON格式不正确 | 检查JSON字符串格式 |
| 400 | 音频配置验证失败 | 音频参数不符合要求 | 检查每个音频的参数 |
| 400 | audio_url是必填项 | 音频URL缺失 | 为每个音频提供URL |
| 400 | 时间范围无效 | end必须大于start | 确保结束时间大于开始时间 |
| 400 | 音量值无效 | volume不在0.0-2.0范围内 | 使用0.0-2.0之间的音量值 |
| 404 | 草稿不存在 | 指定的草稿URL无效 | 检查草稿URL是否正确 |
| 404 | 音频资源不存在 | 音频URL无法访问 | 检查音频URL是否可访问 |
| 500 | 音频处理失败 | 内部处理错误 | 联系技术支持 |
## 注意事项
1. **JSON格式**: audio_infos必须是合法的JSON字符串
2. **时间单位**: 所有时间参数使用微秒（1秒 = 1,000,000微秒）
3. **音频格式**: 确保音频文件格式被支持（如MP3、WAV、AAC等）
4. **文件大小**: 大音频文件可能影响处理速度
5. **网络访问**: 音频URL必须可以正常访问
6. **音量范围**: 音量值必须在0.0-2.0范围内
7. **轨道限制**: 同一时间段可能存在音频重叠
## 工作流程
1. 验证必填参数（draft_url, audio_infos）
2. 解析audio_infos JSON字符串
3. 验证每个音频的参数配置
4. 获取并解密草稿内容
5. 创建音频轨道
6. 添加音频片段到轨道
7. 应用音量和音频效果
8. 保存并加密草稿
9. 返回处理结果
## 相关接口
- [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加图片](./add_images.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)
---
<div align="right">
📚 **项目资源**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
### 语言切换
[中文版](./add_audios.zh.md) | [English](./add_audios.md)
docs/add_images.md
+125 -122
View File
@@ -1,20 +1,20 @@
# ADD_IMAGES API 接口文档
# ADD_IMAGES API Documentation
## 接口信息
## Interface Information
```
POST /openapi/capcut-mate/v1/add_images
```
## 功能描述
## Function Description
向现有草稿中添加图片。该接口用于在指定的时间段内添加图片素材到剪映草稿中，支持图片的透明度、缩放和位置调整。图片可以用于增强视频的视觉效果，如背景图、水印、装饰图等。
Add images to existing drafts. This interface is used to add image materials to Jianying drafts within specified time periods, supporting transparency, scaling and position adjustments for images. Images can be used to enhance video visual effects, such as background images, watermarks, decorative images, etc.
## 更多文档
## More Documentation
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
📖 For more detailed documentation and tutorials, please visit: [https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
## Request Parameters
```json
{
@@ -28,84 +28,84 @@ POST /openapi/capcut-mate/v1/add_images
}
```
### 参数说明
### Parameter Description
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
| image_infos | string | ✅ | - | 图片信息数组的JSON字符串 |
| alpha | number | ❌ | 1.0 | 图片透明度，建议范围[0.0, 1.0] |
| scale_x | number | ❌ | 1.0 | 图片X轴缩放比例 |
| scale_y | number | ❌ | 1.0 | 图片Y轴缩放比例 |
| transform_x | number | ❌ | 0 | X轴位置偏移（像素） |
| transform_y | number | ❌ | 0 | Y轴位置偏移（像素） |
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| draft_url | string | ✅ | - | Complete URL of the target draft |
| image_infos | string | ✅ | - | JSON string of image information array |
| alpha | number | ❌ | 1.0 | Image transparency, recommended range [0.0, 1.0] |
| scale_x | number | ❌ | 1.0 | Image X-axis scaling ratio |
| scale_y | number | ❌ | 1.0 | Image Y-axis scaling ratio |
| transform_x | number | ❌ | 0 | X-axis position offset (pixels) |
| transform_y | number | ❌ | 0 | Y-axis position offset (pixels) |
### image_infos 数组结构
### image_infos Array Structure
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| image_url | string | ✅ | - | 图片文件的URL地址 |
| width | number | ✅ | - | 图片宽度(像素) |
| height | number | ✅ | - | 图片高度(像素) |
| start | number | ✅ | - | 图片开始显示时间(微秒) |
| end | number | ✅ | - | 图片结束显示时间(微秒) |
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| image_url | string | ✅ | - | URL address of the image file |
| width | number | ✅ | - | Image width (pixels) |
| height | number | ✅ | - | Image height (pixels) |
| start | number | ✅ | - | Image start display time (microseconds) |
| end | number | ✅ | - | Image end display time (microseconds) |
### 参数详解
### Parameter Details
#### 时间参数
#### Time Parameters
- **start**: 图片在时间轴上的开始时间，单位为微秒（1秒 = 1,000,000微秒）
- **end**: 图片在时间轴上的结束时间，单位为微秒
- **duration**: 图片显示时长 = end - start
- **start**: Start time of the image on the timeline, unit microseconds (1 second = 1,000,000 microseconds)
- **end**: End time of the image on the timeline, unit microseconds
- **duration**: Image display duration = end - start
#### 透明度参数
#### Transparency Parameters
- **alpha**: 图片的透明度
- 1.0 = 完全不透明
- 0.5 = 半透明
- 0.0 = 完全透明
- 建议范围：0.0 - 1.0
- **alpha**: Image transparency
- 1.0 = Fully opaque
- 0.5 = Semi-transparent
- 0.0 = Fully transparent
- Recommended range: 0.0 - 1.0
#### 缩放参数
#### Scaling Parameters
- **scale_x**: 图片在X轴方向的缩放比例
- 1.0 = 原始大小
- 0.5 = 缩小到一半
- 2.0 = 放大到两倍
- **scale_x**: Image scaling ratio in X-axis direction
- 1.0 = Original size
- 0.5 = Shrink to half
- 2.0 = Enlarge to double
- **scale_y**: 图片在Y轴方向的缩放比例
- 1.0 = 原始大小
- 0.5 = 缩小到一半
- 2.0 = 放大到两倍
- **scale_y**: Image scaling ratio in Y-axis direction
- 1.0 = Original size
- 0.5 = Shrink to half
- 2.0 = Enlarge to double
#### 位置参数
#### Position Parameters
- **transform_x**: 图片在X轴方向的位置偏移，单位为像素
- 正值向右移动
- 负值向左移动
- 以画布中心为原点
- 实际存储时会转换为半画布宽单位（假设画布宽度1920，即除以960）
- **transform_x**: Image position offset in X-axis direction, unit pixels
- Positive value moves right
- Negative value moves left
- Canvas center as origin
- Actually stored as half-canvas-width units (assuming canvas width 1920, divided by 960)
- **transform_y**: 图片在Y轴方向的位置偏移，单位为像素
- 正值向下移动
- 负值向上移动
- 以画布中心为原点
- 实际存储时会转换为半画布高单位（假设画布高度1080，即除以540）
- **transform_y**: Image position offset in Y-axis direction, unit pixels
- Positive value moves down
- Negative value moves up
- Canvas center as origin
- Actually stored as half-canvas-height units (assuming canvas height 1080, divided by 540)
#### 图片信息说明
#### Image Information Description
- **image_url**: 图片的URL地址
- 格式：有效的图片URL
- 示例：`"https://assets.jcaigc.cn/image1.jpg"`
- 支持格式：JPG、PNG等常见图片格式
- **image_url**: URL address of the image
- Format: Valid image URL
- Example: `"https://assets.jcaigc.cn/image1.jpg"`
- Supported formats: JPG, PNG and other common image formats
- **width/height**: 图片的原始尺寸
- 用于计算位置偏移的转换比例
- 单位：像素
- **width/height**: Original size of the image
- Used to calculate conversion ratio for position offset
- Unit: pixels
## 响应格式
## Response Format
### 成功响应 (200)
### Success Response (200)
```json
{
@@ -123,29 +123,29 @@ POST /openapi/capcut-mate/v1/add_images
}
```
### 响应字段说明
### Response Field Description
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 更新后的草稿URL |
| track_id | string | 视频轨道ID |
| image_ids | array | 图片ID列表 |
| segment_ids | array | 片段ID列表 |
| segment_infos | array | 片段信息列表，包含每个片段的ID、开始时间和结束时间 |
| Field | Type | Description |
|-------|------|-------------|
| draft_url | string | Updated draft URL |
| track_id | string | Video track ID |
| image_ids | array | List of image IDs |
| segment_ids | array | List of segment IDs |
| segment_infos | array | List of segment information, containing ID, start time and end time for each segment |
### 错误响应 (4xx/5xx)
### Error Response (4xx/5xx)
```json
{
"detail": "错误信息描述"
"detail": "Error message description"
}
```
## 使用示例
## Usage Examples
### cURL 示例
### cURL Examples
#### 1. 基本图片添加
#### 1. Basic Image Addition
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
@@ -156,7 +156,7 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
}'
```
#### 2. 带透明度的图片
#### 2. Image with Transparency
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
@@ -168,7 +168,7 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
}'
```
#### 3. 带缩放和位置偏移的图片
#### 3. Image with Scaling and Position Offset
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
@@ -183,59 +183,62 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
}'
```
## 错误码说明
## Error Code Description
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | image_infos是必填项 | 缺少图片信息参数 | 提供有效的image_infos |
| 400 | image_url是必填项 | 图片URL缺失 | 为每个图片提供URL |
| 400 | 图片尺寸无效 | width或height无效 | 提供正数的宽度和高度 |
| 400 | 时间范围无效 | end必须大于start | 确保结束时间大于开始时间 |
| 400 | 透明度无效 | alpha超出建议范围 | 使用0.0-1.0范围内的透明度值 |
| 404 | 草稿不存在 | 指定的草稿URL无效 | 检查草稿URL是否正确 |
| 404 | 图片不存在 | 指定的图片URL无效 | 确认图片URL是否正确 |
| 500 | 图片添加失败 | 内部处理错误 | 联系技术支持 |
| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 400 | draft_url is required | Missing draft URL parameter | Provide a valid draft_url |
| 400 | image_infos is required | Missing image information parameter | Provide valid image_infos |
| 400 | image_url is required | Image URL missing | Provide URL for each image |
| 400 | Image dimensions invalid | width or height invalid | Provide positive width and height |
| 400 | Time range invalid | end must be greater than start | Ensure end time is greater than start time |
| 400 | Transparency invalid | alpha exceeds recommended range | Use transparency value within 0.0-1.0 range |
| 404 | Draft does not exist | Specified draft URL invalid | Check if draft URL is correct |
| 404 | Image does not exist | Specified image URL invalid | Confirm if image URL is correct |
| 500 | Image addition failed | Internal processing error | Contact technical support |
## 注意事项
## Notes
1. **时间单位**: 所有时间参数使用微秒（1秒 = 1,000,000微秒）
2. **图片URL**: 确保使用有效的图片URL
3. **时间范围**: end必须大于start
4. **透明度范围**: alpha建议在0.0-1.0范围内
5. **位置参数**: transform_x和transform_y单位为像素，但内部会转换为半画布单位存储
- transform_x转换公式：实际值 / 960（假设画布宽度1920）
- transform_y转换公式：实际值 / 540（假设画布高度1080）
6. **轨道管理**: 系统自动创建视频轨道
7. **性能考虑**: 避免同时添加大量图片
1. **Time Unit**: All time parameters use microseconds (1 second = 1,000,000 microseconds)
2. **Image URL**: Ensure using valid image URL
3. **Time Range**: end must be greater than start
4. **Transparency Range**: alpha recommended within 0.0-1.0 range
5. **Position Parameters**: transform_x and transform_y unit is pixels, but internally converted to half-canvas units for storage
- transform_x conversion formula: actual value / 960 (assuming canvas width 1920)
- transform_y conversion formula: actual value / 540 (assuming canvas height 1080)
6. **Track Management**: System automatically creates video track
7. **Performance Consideration**: Avoid adding large number of images simultaneously
## 工作流程
## Workflow
1. 验证必填参数（draft_url, image_infos）
2. 检查时间范围的有效性
3. 从缓存中获取草稿
4. 创建视频轨道（图片作为VideoSegment）
5. 创建图像调节设置
6. 创建图片片段
7. 添加片段到轨道
8. 保存草稿
9. 返回图片信息
1. Validate required parameters (draft_url, image_infos)
2. Check validity of time ranges
3. Get draft from cache
4. Create video track (images as VideoSegment)
5. Create image adjustment settings
6. Create image segments
7. Add segments to track
8. Save draft
9. Return image information
## 相关接口
## Related Interfaces
- [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加贴纸](./add_sticker.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)
- [Create Draft](./create_draft.md)
- [Add Videos](./add_videos.md)
- [Add Audios](./add_audios.md)
- [Add Stickers](./add_sticker.md)
- [Save Draft](./save_draft.md)
- [Generate Video](./gen_video.md)
---
<div align="right">
📚 **项目资源**
📚 **Project Resources**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
</div>
### Language Switch
[中文版](./add_images.zh.md) | [English](./add_images.md)
docs/add_images.zh.md
+244
View File
@@ -0,0 +1,244 @@
# ADD_IMAGES API 接口文档
## 接口信息
```
POST /openapi/capcut-mate/v1/add_images
```
## 功能描述
向现有草稿中添加图片。该接口用于在指定的时间段内添加图片素材到剪映草稿中，支持图片的透明度、缩放和位置调整。图片可以用于增强视频的视觉效果，如背景图、水印、装饰图等。
## 更多文档
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"image_infos": "[{\"image_url\":\"https://assets.jcaigc.cn/image1.jpg\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000}]",
"alpha": 1.0,
"scale_x": 1.0,
"scale_y": 1.0,
"transform_x": 0,
"transform_y": 0
}
```
### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
| image_infos | string | ✅ | - | 图片信息数组的JSON字符串 |
| alpha | number | ❌ | 1.0 | 图片透明度，建议范围[0.0, 1.0] |
| scale_x | number | ❌ | 1.0 | 图片X轴缩放比例 |
| scale_y | number | ❌ | 1.0 | 图片Y轴缩放比例 |
| transform_x | number | ❌ | 0 | X轴位置偏移（像素） |
| transform_y | number | ❌ | 0 | Y轴位置偏移（像素） |
### image_infos 数组结构
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| image_url | string | ✅ | - | 图片文件的URL地址 |
| width | number | ✅ | - | 图片宽度(像素) |
| height | number | ✅ | - | 图片高度(像素) |
| start | number | ✅ | - | 图片开始显示时间(微秒) |
| end | number | ✅ | - | 图片结束显示时间(微秒) |
### 参数详解
#### 时间参数
- **start**: 图片在时间轴上的开始时间，单位为微秒（1秒 = 1,000,000微秒）
- **end**: 图片在时间轴上的结束时间，单位为微秒
- **duration**: 图片显示时长 = end - start
#### 透明度参数
- **alpha**: 图片的透明度
- 1.0 = 完全不透明
- 0.5 = 半透明
- 0.0 = 完全透明
- 建议范围：0.0 - 1.0
#### 缩放参数
- **scale_x**: 图片在X轴方向的缩放比例
- 1.0 = 原始大小
- 0.5 = 缩小到一半
- 2.0 = 放大到两倍
- **scale_y**: 图片在Y轴方向的缩放比例
- 1.0 = 原始大小
- 0.5 = 缩小到一半
- 2.0 = 放大到两倍
#### 位置参数
- **transform_x**: 图片在X轴方向的位置偏移，单位为像素
- 正值向右移动
- 负值向左移动
- 以画布中心为原点
- 实际存储时会转换为半画布宽单位（假设画布宽度1920，即除以960）
- **transform_y**: 图片在Y轴方向的位置偏移，单位为像素
- 正值向下移动
- 负值向上移动
- 以画布中心为原点
- 实际存储时会转换为半画布高单位（假设画布高度1080，即除以540）
#### 图片信息说明
- **image_url**: 图片的URL地址
- 格式：有效的图片URL
- 示例：`"https://assets.jcaigc.cn/image1.jpg"`
- 支持格式：JPG、PNG等常见图片格式
- **width/height**: 图片的原始尺寸
- 用于计算位置偏移的转换比例
- 单位：像素
## 响应格式
### 成功响应 (200)
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"track_id": "video-track-uuid",
"image_ids": ["image1-uuid", "image2-uuid"],
"segment_ids": ["segment1-uuid", "segment2-uuid"],
"segment_infos": [
{
"id": "segment1-uuid",
"start": 0,
"end": 5000000
}
]
}
```
### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 更新后的草稿URL |
| track_id | string | 视频轨道ID |
| image_ids | array | 图片ID列表 |
| segment_ids | array | 片段ID列表 |
| segment_infos | array | 片段信息列表，包含每个片段的ID、开始时间和结束时间 |
### 错误响应 (4xx/5xx)
```json
{
"detail": "错误信息描述"
}
```
## 使用示例
### cURL 示例
#### 1. 基本图片添加
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"image_infos": "[{\"image_url\":\"https://assets.jcaigc.cn/photo1.jpg\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000}]"
}'
```
#### 2. 带透明度的图片
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"image_infos": "[{\"image_url\":\"https://assets.jcaigc.cn/logo.png\",\"width\":800,\"height\":600,\"start\":1000000,\"end\":6000000}]",
"alpha": 0.8
}'
```
#### 3. 带缩放和位置偏移的图片
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"image_infos": "[{\"image_url\":\"https://assets.jcaigc.cn/watermark.png\",\"width\":300,\"height\":100,\"start\":2000000,\"end\":7000000}]",
"scale_x": 0.5,
"scale_y": 0.5,
"transform_x": 700,
"transform_y": -400
}'
```
## 错误码说明
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | image_infos是必填项 | 缺少图片信息参数 | 提供有效的image_infos |
| 400 | image_url是必填项 | 图片URL缺失 | 为每个图片提供URL |
| 400 | 图片尺寸无效 | width或height无效 | 提供正数的宽度和高度 |
| 400 | 时间范围无效 | end必须大于start | 确保结束时间大于开始时间 |
| 400 | 透明度无效 | alpha超出建议范围 | 使用0.0-1.0范围内的透明度值 |
| 404 | 草稿不存在 | 指定的草稿URL无效 | 检查草稿URL是否正确 |
| 404 | 图片不存在 | 指定的图片URL无效 | 确认图片URL是否正确 |
| 500 | 图片添加失败 | 内部处理错误 | 联系技术支持 |
## 注意事项
1. **时间单位**: 所有时间参数使用微秒（1秒 = 1,000,000微秒）
2. **图片URL**: 确保使用有效的图片URL
3. **时间范围**: end必须大于start
4. **透明度范围**: alpha建议在0.0-1.0范围内
5. **位置参数**: transform_x和transform_y单位为像素，但内部会转换为半画布单位存储
- transform_x转换公式：实际值 / 960（假设画布宽度1920）
- transform_y转换公式：实际值 / 540（假设画布高度1080）
6. **轨道管理**: 系统自动创建视频轨道
7. **性能考虑**: 避免同时添加大量图片
## 工作流程
1. 验证必填参数（draft_url, image_infos）
2. 检查时间范围的有效性
3. 从缓存中获取草稿
4. 创建视频轨道（图片作为VideoSegment）
5. 创建图像调节设置
6. 创建图片片段
7. 添加片段到轨道
8. 保存草稿
9. 返回图片信息
## 相关接口
- [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加贴纸](./add_sticker.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)
---
<div align="right">
📚 **项目资源**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
### 语言切换
[中文版](./add_images.zh.md) | [English](./add_images.md)
docs/add_videos.md
+132 -129
View File
@@ -1,25 +1,25 @@
# ADD_VIDEOS API 接口文档
# ADD_VIDEOS API Documentation
## 接口信息
## Interface Information
```
POST /openapi/capcut-mate/v1/add_videos
```
## 功能描述
## Function Description
批量向现有草稿中添加视频素材。该接口是一个功能强大的视频添加工具，支持多个视频的批量处理，包括时间范围控制、透明度调整、遮罩效果、转场动画、音量控制、缩放变换等高级功能。特别适合创建复杂的多视频组合场景，如画中画效果、视频拼接、过渡动画等。
Batch add video materials to existing drafts. This interface is a powerful video addition tool that supports batch processing of multiple videos, including time range control, transparency adjustment, mask effects, transition animations, volume control, scaling transformations, and other advanced features. Particularly suitable for creating complex multi-video combination scenes, such as picture-in-picture effects, video splicing, transition animations, etc.
## 更多文档
## More Documentation
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
📖 For more detailed documentation and tutorials, please visit: [https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
## Request Parameters
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1024,\"height\":1024,\"start\":0,\"end\":5000000,\"duration\":5000000,\"mask\":\"圆形\",\"transition\":\"淡入淡出\",\"transition_duration\":500000,\"volume\":0.8}]",
"video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1024,\"height\":1024,\"start\":0,\"end\":5000000,\"duration\":5000000,\"mask\":\"circle\",\"transition\":\"fade\",\"transition_duration\":500000,\"volume\":0.8}]",
"alpha": 0.5,
"scale_x": 1.0,
"scale_y": 1.0,
@@ -28,91 +28,91 @@ POST /openapi/capcut-mate/v1/add_videos
}
```
### 参数说明
### Parameter Description
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
| video_infos | string | ✅ | - | 视频信息数组的JSON字符串 |
| alpha | number | ❌ | 1.0 | 全局透明度(0-1) |
| scale_x | number | ❌ | 1.0 | X轴缩放比例 |
| scale_y | number | ❌ | 1.0 | Y轴缩放比例 |
| transform_x | number | ❌ | 0 | X轴位置偏移(像素) |
| transform_y | number | ❌ | 0 | Y轴位置偏移(像素) |
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| draft_url | string | ✅ | - | Complete URL of the target draft |
| video_infos | string | ✅ | - | JSON string of video information array |
| alpha | number | ❌ | 1.0 | Global transparency (0-1) |
| scale_x | number | ❌ | 1.0 | X-axis scaling ratio |
| scale_y | number | ❌ | 1.0 | Y-axis scaling ratio |
| transform_x | number | ❌ | 0 | X-axis position offset (pixels) |
| transform_y | number | ❌ | 0 | Y-axis position offset (pixels) |
### video_infos 数组结构
### video_infos Array Structure
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| video_url | string | ✅ | - | 视频文件的URL地址 |
| width | number | ❌ | - | 视频宽度(像素)，不传则自动获取视频文件尺寸 |
| height | number | ❌ | - | 视频高度(像素)，不传则自动获取视频文件尺寸 |
| start | number | ✅ | - | 视频开始播放时间(微秒) |
| end | number | ✅ | - | 视频结束播放时间(微秒) |
| duration | number | ❌ | end-start | 视频总时长(微秒) |
| mask | string | ❌ | - | 遮罩类型 |
| transition | string | ❌ | - | 转场效果名称 |
| transition_duration | number | ❌ | 500000 | 转场持续时间(微秒) |
| volume | number | ❌ | 1.0 | 音量大小(0-1) |
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| video_url | string | ✅ | - | URL address of the video file |
| width | number | ❌ | - | Video width (pixels), automatically obtained if not provided |
| height | number | ❌ | - | Video height (pixels), automatically obtained if not provided |
| start | number | ✅ | - | Video start playback time (microseconds) |
| end | number | ✅ | - | Video end playback time (microseconds) |
| duration | number | ❌ | end-start | Total video duration (microseconds) |
| mask | string | ❌ | - | Mask type |
| transition | string | ❌ | - | Transition effect name |
| transition_duration | number | ❌ | 500000 | Transition duration (microseconds) |
| volume | number | ❌ | 1.0 | Volume size (0-1) |
### 参数详解
### Parameter Details
#### 时间参数
#### Time Parameters
- **start**: 视频在时间轴上的开始时间，单位微秒（1秒 = 1,000,000微秒）
- **end**: 视频在时间轴上的结束时间，单位微秒
- **duration**: 视频文件的总时长，用于素材创建（可选参数，如果不传则默认为end-start）
- **播放时长**: 实际播放时长 = end - start
- **start**: Start time of the video on the timeline, unit microseconds (1 second = 1,000,000 microseconds)
- **end**: End time of the video on the timeline, unit microseconds
- **duration**: Total duration of the video file, used for material creation (optional parameter, defaults to end-start if not provided)
- **Playback Duration**: Actual playback duration = end - start
#### 透明度参数
#### Transparency Parameters
- **alpha**: 全局透明度，应用于所有添加的视频
- 1.0 = 完全不透明
- 0.5 = 半透明
- 0.0 = 完全透明
- 范围：0.0 - 1.0
- **alpha**: Global transparency, applied to all added videos
- 1.0 = Fully opaque
- 0.5 = Semi-transparent
- 0.0 = Fully transparent
- Range: 0.0 - 1.0
#### 缩放参数
#### Scaling Parameters
- **scale_x/scale_y**: X/Y轴方向的缩放比例
- 1.0 = 原始大小，0.5 = 缩小一半，2.0 = 放大两倍
- 建议范围：0.1 - 5.0
- **scale_x/scale_y**: Scaling ratios in X/Y axis directions
- 1.0 = Original size, 0.5 = Half size, 2.0 = Double size
- Recommended range: 0.1 - 5.0
#### 位置参数
#### Position Parameters
- **transform_x/transform_y**: X/Y轴方向的位置偏移，单位像素
- 正值向右/下移动，负值向左/上移动
- 以画布中心为原点
- **transform_x/transform_y**: Position offsets in X/Y axis directions, unit pixels
- Positive values move right/down, negative values move left/up
- Canvas center as origin
#### 遮罩类型
#### Mask Types
支持的遮罩类型：
- `圆形` - 圆形遮罩效果
- `爱心` - 爱心形状遮罩
- `星形` - 星形遮罩
- `矩形` - 矩形遮罩
- `线性` - 线性渐变遮罩
- `镜面` - 镜面反射遮罩
Supported mask types:
- `circle` - Circular mask effect
- `heart` - Heart-shaped mask
- `star` - Star-shaped mask
- `rectangle` - Rectangular mask
- `linear` - Linear gradient mask
- `mirror` - Mirror reflection mask
#### 转场效果
#### Transition Effects
- **transition**: 转场效果名称
- **transition_duration**: 转场持续时间
- 最小值：100,000微秒（0.1秒）
- 最大值：2,500,000微秒（2.5秒）
- 推荐值：500,000微秒（0.5秒）
- **transition**: Transition effect name
- **transition_duration**: Transition duration
- Minimum: 100,000 microseconds (0.1 seconds)
- Maximum: 2,500,000 microseconds (2.5 seconds)
- Recommended: 500,000 microseconds (0.5 seconds)
#### 音量控制
#### Volume Control
- **volume**: 视频音量大小
- 1.0 = 原始音量
- 0.5 = 一半音量
- 0.0 = 静音
- 范围：0.0 - 1.0
- **volume**: Video volume size
- 1.0 = Original volume
- 0.5 = Half volume
- 0.0 = Mute
- Range: 0.0 - 1.0
## 响应格式
## Response Format
### 成功响应 (200)
### Success Response (200)
```json
{
@@ -123,20 +123,20 @@ POST /openapi/capcut-mate/v1/add_videos
}
```
### 响应字段说明
### Response Field Description
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 更新后的草稿URL |
| track_id | string | 视频轨道ID |
| video_ids | array | 添加的视频ID列表 |
| segment_ids | array | 片段ID列表 |
| Field | Type | Description |
|-------|------|-------------|
| draft_url | string | Updated draft URL |
| track_id | string | Video track ID |
| video_ids | array | List of added video IDs |
| segment_ids | array | List of segment IDs |
## 使用示例
## Usage Examples
### cURL 示例
### cURL Examples
#### 1. 基本视频添加
#### 1. Basic Video Addition
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
@@ -147,7 +147,7 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
}'
```
#### 2. 多视频批量添加
#### 2. Batch Adding Multiple Videos
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
@@ -159,21 +159,21 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
}'
```
#### 3. 带遮罩和转场的视频
#### 3. Video with Mask and Transition
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1024,\"height\":1024,\"start\":0,\"end\":5000000,\"duration\":10000000,\"mask\":\"圆形\",\"transition\":\"淡入淡出\",\"transition_duration\":500000,\"volume\":0.8}]",
"video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1024,\"height\":1024,\"start\":0,\"end\":5000000,\"duration\":10000000,\"mask\":\"circle\",\"transition\":\"fade\",\"transition_duration\":500000,\"volume\":0.8}]",
"alpha": 1.0,
"scale_x": 1.2,
"scale_y": 1.2
}'
```
#### 4. 画中画效果
#### 4. Picture-in-Picture Effect
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
@@ -188,60 +188,63 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
}'
```
## 错误码说明
## Error Code Description
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的草稿URL |
| 400 | video_infos是必填项 | 缺少视频信息参数 | 提供有效的视频信息JSON |
| 400 | video_infos格式错误 | JSON格式不正确 | 检查JSON字符串格式 |
| 400 | video_url是必填项 | 视频URL缺失 | 为每个视频提供URL |
| 400 | 视频尺寸无效 | width或height无效 | 提供正数的宽度和高度 |
| 400 | 时间范围无效 | end必须大于start | 确保结束时间大于开始时间 |
| 400 | 透明度值无效 | alpha不在0-1范围内 | 使用0-1之间的透明度值 |
| 404 | 草稿不存在 | 指定的草稿URL无效 | 检查草稿URL是否正确 |
| 404 | 视频资源不存在 | 视频URL无法访问 | 检查视频URL是否可访问 |
| 500 | 视频处理失败 | 内部处理错误 | 联系技术支持 |
| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 400 | draft_url is required | Missing draft URL parameter | Provide a valid draft URL |
| 400 | video_infos is required | Missing video information parameter | Provide valid video information JSON |
| 400 | video_infos format error | JSON format is incorrect | Check JSON string format |
| 400 | video_url is required | Video URL missing | Provide URL for each video |
| 400 | Video dimensions invalid | width or height invalid | Provide positive width and height |
| 400 | Time range invalid | end must be greater than start | Ensure end time is greater than start time |
| 400 | Transparency value invalid | alpha not in 0-1 range | Use transparency value between 0-1 |
| 404 | Draft does not exist | Specified draft URL invalid | Check if draft URL is correct |
| 404 | Video resource does not exist | Video URL inaccessible | Check if video URL is accessible |
| 500 | Video processing failed | Internal processing error | Contact technical support |
## 注意事项
## Notes
1. **JSON格式**: video_infos必须是合法的JSON字符串
2. **时间单位**: 所有时间参数使用微秒（1秒 = 1,000,000微秒）
3. **视频格式**: 确保视频文件格式被支持（如MP4、AVI等）
4. **文件大小**: 大视频文件可能影响处理速度
5. **网络访问**: 视频URL必须可以正常访问
6. **遮罩限制**: 只支持预定义的遮罩类型
7. **转场限制**: 转场时长有固定范围限制
8. **性能考虑**: 批量添加大量视频可能影响性能
1. **JSON Format**: video_infos must be a valid JSON string
2. **Time Unit**: All time parameters use microseconds (1 second = 1,000,000 microseconds)
3. **Video Format**: Ensure video file format is supported (e.g., MP4, AVI, etc.)
4. **File Size**: Large video files may affect processing speed
5. **Network Access**: Video URL must be accessible
6. **Mask Limitation**: Only predefined mask types are supported
7. **Transition Limitation**: Transition duration has fixed range limitations
8. **Performance Consideration**: Batch adding a large number of videos may affect performance
## 工作流程
## Workflow
1. 验证必填参数（draft_url, video_infos）
2. 解析video_infos JSON字符串
3. 验证每个视频的参数配置
4. 获取并解密草稿内容
5. 创建视频轨道
6. 添加视频片段到轨道
7. 应用透明度、缩放和位置变换
8. 添加遮罩和转场效果
9. 设置音量
10. 保存并加密草稿
11. 返回处理结果
1. Validate required parameters (draft_url, video_infos)
2. Parse video_infos JSON string
3. Validate parameter configuration for each video
4. Obtain and decrypt draft content
5. Create video track
6. Add video segments to track
7. Apply transparency, scaling and position transformation
8. Add mask and transition effects
9. Set volume
10. Save and encrypt draft
11. Return processing result
## 相关接口
## Related Interfaces
- [创建草稿](./create_draft.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)
- [Create Draft](./create_draft.md)
- [Add Audios](./add_audios.md)
- [Add Images](./add_images.md)
- [Save Draft](./save_draft.md)
- [Generate Video](./gen_video.md)
---
<div align="right">
📚 **项目资源**
📚 **Project Resources**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
</div>
### Language Switch
[中文版](./add_videos.zh.md) | [English](./add_videos.md)
docs/add_videos.zh.md
+250
View File
@@ -0,0 +1,250 @@
# ADD_VIDEOS API 接口文档
## 接口信息
```
POST /openapi/capcut-mate/v1/add_videos
```
## 功能描述
批量向现有草稿中添加视频素材。该接口是一个功能强大的视频添加工具，支持多个视频的批量处理，包括时间范围控制、透明度调整、遮罩效果、转场动画、音量控制、缩放变换等高级功能。特别适合创建复杂的多视频组合场景，如画中画效果、视频拼接、过渡动画等。
## 更多文档
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1024,\"height\":1024,\"start\":0,\"end\":5000000,\"duration\":5000000,\"mask\":\"圆形\",\"transition\":\"淡入淡出\",\"transition_duration\":500000,\"volume\":0.8}]",
"alpha": 0.5,
"scale_x": 1.0,
"scale_y": 1.0,
"transform_x": 100,
"transform_y": 200
}
```
### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
| video_infos | string | ✅ | - | 视频信息数组的JSON字符串 |
| alpha | number | ❌ | 1.0 | 全局透明度(0-1) |
| scale_x | number | ❌ | 1.0 | X轴缩放比例 |
| scale_y | number | ❌ | 1.0 | Y轴缩放比例 |
| transform_x | number | ❌ | 0 | X轴位置偏移(像素) |
| transform_y | number | ❌ | 0 | Y轴位置偏移(像素) |
### video_infos 数组结构
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| video_url | string | ✅ | - | 视频文件的URL地址 |
| width | number | ❌ | - | 视频宽度(像素)，不传则自动获取视频文件尺寸 |
| height | number | ❌ | - | 视频高度(像素)，不传则自动获取视频文件尺寸 |
| start | number | ✅ | - | 视频开始播放时间(微秒) |
| end | number | ✅ | - | 视频结束播放时间(微秒) |
| duration | number | ❌ | end-start | 视频总时长(微秒) |
| mask | string | ❌ | - | 遮罩类型 |
| transition | string | ❌ | - | 转场效果名称 |
| transition_duration | number | ❌ | 500000 | 转场持续时间(微秒) |
| volume | number | ❌ | 1.0 | 音量大小(0-1) |
### 参数详解
#### 时间参数
- **start**: 视频在时间轴上的开始时间，单位微秒（1秒 = 1,000,000微秒）
- **end**: 视频在时间轴上的结束时间，单位微秒
- **duration**: 视频文件的总时长，用于素材创建（可选参数，如果不传则默认为end-start）
- **播放时长**: 实际播放时长 = end - start
#### 透明度参数
- **alpha**: 全局透明度，应用于所有添加的视频
- 1.0 = 完全不透明
- 0.5 = 半透明
- 0.0 = 完全透明
- 范围：0.0 - 1.0
#### 缩放参数
- **scale_x/scale_y**: X/Y轴方向的缩放比例
- 1.0 = 原始大小，0.5 = 缩小一半，2.0 = 放大两倍
- 建议范围：0.1 - 5.0
#### 位置参数
- **transform_x/transform_y**: X/Y轴方向的位置偏移，单位像素
- 正值向右/下移动，负值向左/上移动
- 以画布中心为原点
#### 遮罩类型
支持的遮罩类型：
- `圆形` - 圆形遮罩效果
- `爱心` - 爱心形状遮罩
- `星形` - 星形遮罩
- `矩形` - 矩形遮罩
- `线性` - 线性渐变遮罩
- `镜面` - 镜面反射遮罩
#### 转场效果
- **transition**: 转场效果名称
- **transition_duration**: 转场持续时间
- 最小值：100,000微秒（0.1秒）
- 最大值：2,500,000微秒（2.5秒）
- 推荐值：500,000微秒（0.5秒）
#### 音量控制
- **volume**: 视频音量大小
- 1.0 = 原始音量
- 0.5 = 一半音量
- 0.0 = 静音
- 范围：0.0 - 1.0
## 响应格式
### 成功响应 (200)
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"track_id": "video-track-uuid",
"video_ids": ["video1-uuid", "video2-uuid", "video3-uuid"],
"segment_ids": ["segment1-uuid", "segment2-uuid", "segment3-uuid"]
}
```
### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 更新后的草稿URL |
| track_id | string | 视频轨道ID |
| video_ids | array | 添加的视频ID列表 |
| segment_ids | array | 片段ID列表 |
## 使用示例
### cURL 示例
#### 1. 基本视频添加
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000,\"duration\":10000000}]"
}'
```
#### 2. 多视频批量添加
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000,\"duration\":10000000},{\"video_url\":\"https://assets.jcaigc.cn/video2.mp4\",\"width\":1280,\"height\":720,\"start\":5000000,\"end\":10000000,\"duration\":8000000}]",
"alpha": 0.8
}'
```
#### 3. 带遮罩和转场的视频
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/video1.mp4\",\"width\":1024,\"height\":1024,\"start\":0,\"end\":5000000,\"duration\":10000000,\"mask\":\"圆形\",\"transition\":\"淡入淡出\",\"transition_duration\":500000,\"volume\":0.8}]",
"alpha": 1.0,
"scale_x": 1.2,
"scale_y": 1.2
}'
```
#### 4. 画中画效果
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"video_infos": "[{\"video_url\":\"https://assets.jcaigc.cn/main.mp4\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":10000000,\"duration\":15000000},{\"video_url\":\"https://assets.jcaigc.cn/pip.mp4\",\"width\":640,\"height\":360,\"start\":2000000,\"end\":8000000,\"duration\":10000000}]",
"transform_x": 300,
"transform_y": -200,
"scale_x": 0.3,
"scale_y": 0.3
}'
```
## 错误码说明
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的草稿URL |
| 400 | video_infos是必填项 | 缺少视频信息参数 | 提供有效的视频信息JSON |
| 400 | video_infos格式错误 | JSON格式不正确 | 检查JSON字符串格式 |
| 400 | video_url是必填项 | 视频URL缺失 | 为每个视频提供URL |
| 400 | 视频尺寸无效 | width或height无效 | 提供正数的宽度和高度 |
| 400 | 时间范围无效 | end必须大于start | 确保结束时间大于开始时间 |
| 400 | 透明度值无效 | alpha不在0-1范围内 | 使用0-1之间的透明度值 |
| 404 | 草稿不存在 | 指定的草稿URL无效 | 检查草稿URL是否正确 |
| 404 | 视频资源不存在 | 视频URL无法访问 | 检查视频URL是否可访问 |
| 500 | 视频处理失败 | 内部处理错误 | 联系技术支持 |
## 注意事项
1. **JSON格式**: video_infos必须是合法的JSON字符串
2. **时间单位**: 所有时间参数使用微秒（1秒 = 1,000,000微秒）
3. **视频格式**: 确保视频文件格式被支持（如MP4、AVI等）
4. **文件大小**: 大视频文件可能影响处理速度
5. **网络访问**: 视频URL必须可以正常访问
6. **遮罩限制**: 只支持预定义的遮罩类型
7. **转场限制**: 转场时长有固定范围限制
8. **性能考虑**: 批量添加大量视频可能影响性能
## 工作流程
1. 验证必填参数（draft_url, video_infos）
2. 解析video_infos JSON字符串
3. 验证每个视频的参数配置
4. 获取并解密草稿内容
5. 创建视频轨道
6. 添加视频片段到轨道
7. 应用透明度、缩放和位置变换
8. 添加遮罩和转场效果
9. 设置音量
10. 保存并加密草稿
11. 返回处理结果
## 相关接口
- [创建草稿](./create_draft.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)
---
<div align="right">
📚 **项目资源**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
### 语言切换
[中文版](./add_videos.zh.md) | [English](./add_videos.md)
docs/create_draft.md
+75 -73
View File
@@ -1,20 +1,20 @@
# CREATE_DRAFT API 接口文档
# CREATE_DRAFT API Documentation
## 接口信息
## Interface Information
```
POST /openapi/capcut-mate/v1/create_draft
```
## 功能描述
## Function Description
创建剪映草稿。该接口用于创建一个新的剪映草稿项目，可以自定义视频的宽度和高度。创建成功后会返回草稿URL和帮助文档URL，为后续的视频编辑操作提供基础。
Create a Jianying draft. This interface is used to create a new Jianying draft project, allowing customization of video width and height. After successful creation, it returns the draft URL and help document URL, providing the foundation for subsequent video editing operations.
## 更多文档
## More Documentation
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
📖 For more detailed documentation and tutorials, please visit: [https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
## Request Parameters
```json
{
@@ -23,40 +23,40 @@ POST /openapi/capcut-mate/v1/create_draft
}
```
### 参数说明
### Parameter Description
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| width | number | ❌ | 1920 | 视频宽度(像素)，必须大于等于1 |
| height | number | ❌ | 1080 | 视频高度(像素)，必须大于等于1 |
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| width | number | ❌ | 1920 | Video width (pixels), must be greater than or equal to 1 |
| height | number | ❌ | 1080 | Video height (pixels), must be greater than or equal to 1 |
### 参数详解
### Parameter Details
#### 尺寸参数
#### Size Parameters
- **width**: 草稿视频的宽度
- 最小值：1像素
- 建议常用值：1920、1280、720
- 支持自定义尺寸
- **width**: Width of the draft video
- Minimum: 1 pixel
- Recommended common values: 1920, 1280, 720
- Supports custom sizes
- **height**: 草稿视频的高度
- 最小值：1像素
- 建议常用值：1080、720、480
- 支持自定义尺寸
- **height**: Height of the draft video
- Minimum: 1 pixel
- Recommended common values: 1080, 720, 480
- Supports custom sizes
#### 常用分辨率
#### Common Resolutions
| 分辨率名称 | 宽度 | 高度 | 适用场景 |
|------------|------|------|----------|
| 1080P | 1920 | 1080 | 高清视频制作 |
| 720P | 1280 | 720 | 标清视频制作 |
| 4K | 3840 | 2160 | 超高清视频制作 |
| 竖屏短视频 | 1080 | 1920 | 手机短视频 |
| 正方形 | 1080 | 1080 | 社交媒体内容 |
| Resolution Name | Width | Height | Application Scenario |
|-----------------|-------|--------|---------------------|
| 1080P | 1920 | 1080 | HD video production |
| 720P | 1280 | 720 | SD video production |
| 4K | 3840 | 2160 | Ultra HD video production |
| Vertical Short Video | 1080 | 1920 | Mobile short videos |
| Square | 1080 | 1080 | Social media content |
## 响应格式
## Response Format
### 成功响应 (200)
### Success Response (200)
```json
{
@@ -65,26 +65,26 @@ POST /openapi/capcut-mate/v1/create_draft
}
```
### 响应字段说明
### Response Field Description
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 新创建的草稿URL，用于后续的编辑操作 |
| tip_url | string | 草稿使用帮助文档URL |
| Field | Type | Description |
|-------|------|-------------|
| draft_url | string | Newly created draft URL, used for subsequent editing operations |
| tip_url | string | Draft usage help documentation URL |
### 错误响应 (4xx/5xx)
### Error Response (4xx/5xx)
```json
{
"detail": "错误信息描述"
"detail": "Error message description"
}
```
## 💻 使用示例
## 💻 Usage Examples
### cURL 示例
### cURL Examples
#### 1. 创建默认分辨率草稿
#### 1. Create Draft with Default Resolution
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
@@ -92,7 +92,7 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
-d '{}'
```
#### 2. 创建自定义分辨率草稿
#### 2. Create Draft with Custom Resolution
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
@@ -103,7 +103,7 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
}'
```
#### 3. 创建竖屏短视频草稿
#### 3. Create Vertical Short Video Draft
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
@@ -115,47 +115,49 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
```
## Error Code Description
## 错误码说明
| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 400 | width must be greater than or equal to 1 | Invalid width parameter | Provide a width value greater than or equal to 1 |
| 400 | height must be greater than or equal to 1 | Invalid height parameter | Provide a height value greater than or equal to 1 |
| 400 | Parameter type error | Parameter type is incorrect | Ensure width and height are numeric types |
| 500 | Draft creation failed | Internal service error | Contact technical support |
| 503 | Service unavailable | System maintenance | Retry later |
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | width必须大于等于1 | 宽度参数无效 | 提供大于等于1的宽度值 |
| 400 | height必须大于等于1 | 高度参数无效 | 提供大于等于1的高度值 |
| 400 | 参数类型错误 | 参数类型不正确 | 确保width和height为数字类型 |
| 500 | 草稿创建失败 | 内部服务错误 | 联系技术支持 |
| 503 | 服务不可用 | 系统维护中 | 稍后重试 |
## Notes
## 注意事项
1. **Parameter Validation**: width and height must be positive integers
2. **Resolution Recommendation**: Suggest using common video resolutions to ensure compatibility
3. **Performance Consideration**: Ultra-high resolution may affect subsequent processing performance
4. **Storage Usage**: High-resolution drafts will occupy more storage space
5. **URL Validity**: The returned draft_url has a certain validity period
1. **参数验证**: width和height必须为正整数
2. **分辨率建议**: 建议使用常见的视频分辨率以确保兼容性
3. **性能考虑**: 超高分辨率可能影响后续处理性能
4. **存储占用**: 高分辨率草稿会占用更多存储空间
5. **URL有效期**: 返回的draft_url具有一定的有效期
## Workflow
## 工作流程
1. Receive and validate request parameters
2. Create draft basic structure
3. Set canvas size
4. Generate draft URL
5. Return draft information and help document link
1. 接收并验证请求参数
2. 创建草稿基础结构
3. 设置画布尺寸
4. 生成草稿URL
5. 返回草稿信息和帮助文档链接
## Related Interfaces
## 相关接口
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)
- [Add Videos](./add_videos.md)
- [Add Audios](./add_audios.md)
- [Add Images](./add_images.md)
- [Save Draft](./save_draft.md)
- [Generate Video](./gen_video.md)
---
<div align="right">
📚 **项目资源**
📚 **Project Resources**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
</div>
### Language Switch
[中文版](./create_draft.zh.md) | [English](./create_draft.md)
docs/create_draft.zh.md
+163
View File
@@ -0,0 +1,163 @@
# CREATE_DRAFT API 接口文档
## 接口信息
```
POST /openapi/capcut-mate/v1/create_draft
```
## 功能描述
创建剪映草稿。该接口用于创建一个新的剪映草稿项目，可以自定义视频的宽度和高度。创建成功后会返回草稿URL和帮助文档URL，为后续的视频编辑操作提供基础。
## 更多文档
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
```json
{
"width": 1920,
"height": 1080
}
```
### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| width | number | ❌ | 1920 | 视频宽度(像素)，必须大于等于1 |
| height | number | ❌ | 1080 | 视频高度(像素)，必须大于等于1 |
### 参数详解
#### 尺寸参数
- **width**: 草稿视频的宽度
- 最小值：1像素
- 建议常用值：1920、1280、720
- 支持自定义尺寸
- **height**: 草稿视频的高度
- 最小值：1像素
- 建议常用值：1080、720、480
- 支持自定义尺寸
#### 常用分辨率
| 分辨率名称 | 宽度 | 高度 | 适用场景 |
|------------|------|------|----------|
| 1080P | 1920 | 1080 | 高清视频制作 |
| 720P | 1280 | 720 | 标清视频制作 |
| 4K | 3840 | 2160 | 超高清视频制作 |
| 竖屏短视频 | 1080 | 1920 | 手机短视频 |
| 正方形 | 1080 | 1080 | 社交媒体内容 |
## 响应格式
### 成功响应 (200)
```json
{
"draft_url": "https://cm.jcaigc.cn/openapi/v1/get_draft?draft_id=2025092811473036584258",
"tip_url": "https://help.assets.jcaigc.cn/draft-usage"
}
```
### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 新创建的草稿URL，用于后续的编辑操作 |
| tip_url | string | 草稿使用帮助文档URL |
### 错误响应 (4xx/5xx)
```json
{
"detail": "错误信息描述"
}
```
## 💻 使用示例
### cURL 示例
#### 1. 创建默认分辨率草稿
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
-H "Content-Type: application/json" \
-d '{}'
```
#### 2. 创建自定义分辨率草稿
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
-H "Content-Type: application/json" \
-d '{
"width": 1280,
"height": 720
}'
```
#### 3. 创建竖屏短视频草稿
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/create_draft \
-H "Content-Type: application/json" \
-d '{
"width": 1080,
"height": 1920
}'
```
## 错误码说明
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | width必须大于等于1 | 宽度参数无效 | 提供大于等于1的宽度值 |
| 400 | height必须大于等于1 | 高度参数无效 | 提供大于等于1的高度值 |
| 400 | 参数类型错误 | 参数类型不正确 | 确保width和height为数字类型 |
| 500 | 草稿创建失败 | 内部服务错误 | 联系技术支持 |
| 503 | 服务不可用 | 系统维护中 | 稍后重试 |
## 注意事项
1. **参数验证**: width和height必须为正整数
2. **分辨率建议**: 建议使用常见的视频分辨率以确保兼容性
3. **性能考虑**: 超高分辨率可能影响后续处理性能
4. **存储占用**: 高分辨率草稿会占用更多存储空间
5. **URL有效期**: 返回的draft_url具有一定的有效期
## 工作流程
1. 接收并验证请求参数
2. 创建草稿基础结构
3. 设置画布尺寸
4. 生成草稿URL
5. 返回草稿信息和帮助文档链接
## 相关接口
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)
---
<div align="right">
📚 **项目资源**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
### 语言切换
[中文版](./create_draft.zh.md) | [English](./create_draft.md)
docs/gen_video.md
+75 -72
View File
@@ -1,20 +1,20 @@
# GEN_VIDEO API 接口文档
# GEN_VIDEO API Documentation
## 接口信息
## Interface Information
```
POST /openapi/capcut-mate/v1/gen_video
```
## 功能描述
## Function Description
提交视频生成任务。该接口采用异步处理模式，立即返回任务提交状态，视频生成在后台进行。支持任务排队，确保系统稳定性。
Submit video generation task. This interface uses asynchronous processing mode, immediately returning task submission status, with video generation performed in the background. Supports task queuing to ensure system stability.
## 更多文档
## More Documentation
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
📖 For more detailed documentation and tutorials, please visit: [https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
## Request Parameters
```json
{
@@ -22,50 +22,50 @@ POST /openapi/capcut-mate/v1/gen_video
}
```
### 参数说明
### Parameter Description
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| draft_url | string | ✅ | - | Complete URL of the target draft |
### 参数详解
### Parameter Details
#### 草稿URL参数
#### Draft URL Parameter
- **draft_url**: 草稿的完整URL地址
- 格式：`https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id={草稿ID}`
- 示例：`"https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"`
- 获取方式：通过[创建草稿](./create_draft.md)或[保存草稿](./save_draft.md)接口获取
- **draft_url**: Complete URL address of the draft
- Format: `https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id={draft_ID}`
- Example: `"https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"`
- Acquisition Method: Obtained via [Create Draft](./create_draft.md) or [Save Draft](./save_draft.md) interfaces
## 响应格式
## Response Format
### 成功响应 (200)
### Success Response (200)
```json
{
"message": "视频生成任务已提交，请使用draft_url查询进度"
"message": "Video generation task submitted, please use draft_url to check progress"
}
```
### 响应字段说明
### Response Field Description
| 字段名 | 类型 | 说明 |
|--------|------|------|
| message | string | 响应消息 |
| Field | Type | Description |
|-------|------|-------------|
| message | string | Response message |
### 错误响应 (4xx/5xx)
### Error Response (4xx/5xx)
```json
{
"detail": "错误信息描述"
"detail": "Error message description"
}
```
## 使用示例
## Usage Examples
### cURL 示例
### cURL Examples
#### 1. 基本视频生成
#### 1. Basic Video Generation
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/gen_video \
@@ -75,61 +75,64 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/gen_video \
}'
```
## 错误码说明
## Error Code Description
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | draft_url格式无效 | URL格式不正确 | 检查URL格式是否正确 |
| 404 | 草稿不存在 | 指定的草稿无法找到 | 确认草稿URL是否正确且存在 |
| 400 | 草稿内容为空 | 草稿中没有可导出的内容 | 确保草稿包含视频、音频或图片素材 |
| 400 | 素材无法访问 | 草稿中的素材文件无法下载 | 检查素材URL是否有效 |
| 500 | 视频渲染失败 | 视频处理过程中出错 | 检查草稿内容或联系技术支持 |
| 500 | 音频处理失败 | 音频混合过程中出错 | 检查音频格式或联系技术支持 |
| 500 | 编码失败 | 最终视频编码失败 | 联系技术支持 |
| 503 | 服务繁忙 | 渲染服务器负载过高 | 稍后重试 |
| 504 | 处理超时 | 视频生成超时 | 简化草稿内容或稍后重试 |
| 500 | 视频生成任务提交失败 | 内部处理错误 | 联系技术支持 |
| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 400 | draft_url is required | Missing draft URL parameter | Provide a 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 that draft URL is correct and exists |
| 400 | Draft content is empty | Draft contains no exportable content | Ensure draft contains video, audio or image materials |
| 400 | Material inaccessible | 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 overloaded | Retry later |
| 504 | Processing timeout | Video generation timed out | Simplify draft content or retry later |
| 500 | Video generation task submission failed | Internal processing error | Contact technical support |
## 注意事项
## Notes
1. **处理时间**: 视频生成是耗时操作，可能需要几分钟到几十分钟
2. **文件大小**: 草稿复杂度和素材数量会影响处理时间
3. **网络稳定**: 确保素材URL可以稳定访问
4. **超时设置**: 建议设置较长的超时时间或使用轮询机制
5. **并发限制**: 避免同时生成大量视频
6. **存储空间**: 生成的视频文件可能很大，注意存储空间
7. **URL有效期**: 生成的video_url可能有时效性限制
8. **系统要求**: 视频生成功能仅在Windows系统上可用
1. **Processing Time**: Video generation is time-consuming, may take minutes to tens of minutes
2. **File Size**: Draft complexity and number of materials affect processing time
3. **Network Stability**: Ensure material URLs are stably accessible
4. **Timeout Settings**: Suggest setting longer timeout or using polling mechanism
5. **Concurrency Limit**: Avoid generating large numbers of videos simultaneously
6. **Storage Space**: Generated video files may be large, pay attention to storage space
7. **URL Validity**: Generated video_url may have time-based restrictions
8. **System Requirements**: Video generation feature only available on Windows systems
## 工作流程
## Workflow
1. 验证draft_url参数
2. 解析草稿配置文件
3. 下载所有必需的素材文件
4. 按时间轴排列和处理素材
5. 应用视觉效果和转场
6. 混合音频轨道
7. 渲染最终视频
8. 编码并上传视频文件
9. 返回视频URL
1. Validate draft_url parameter
2. Parse draft configuration file
3. Download all required material files
4. Arrange and process materials according to timeline
5. Apply visual effects and transitions
6. Mix audio tracks
7. Render final video
8. Encode and upload video file
9. Return video URL
## 相关接口
## Related Interfaces
- [创建草稿](./create_draft.md)
- [保存草稿](./save_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [获取草稿](./get_draft.md)
- [查询视频生成状态](./gen_video_status.md)
- [Create Draft](./create_draft.md)
- [Save Draft](./save_draft.md)
- [Add Videos](./add_videos.md)
- [Add Audios](./add_audios.md)
- [Add Images](./add_images.md)
- [Get Draft](./get_draft.md)
- [Query Video Generation Status](./gen_video_status.md)
---
<div align="right">
📚 **项目资源**
📚 **Project Resources**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
</div>
### Language Switch
[中文版](./gen_video.zh.md) | [English](./gen_video.md)
docs/gen_video.zh.md
+138
View File
@@ -0,0 +1,138 @@
# GEN_VIDEO API 接口文档
## 接口信息
```
POST /openapi/capcut-mate/v1/gen_video
```
## 功能描述
提交视频生成任务。该接口采用异步处理模式，立即返回任务提交状态，视频生成在后台进行。支持任务排队，确保系统稳定性。
## 更多文档
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}
```
### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
### 参数详解
#### 草稿URL参数
- **draft_url**: 草稿的完整URL地址
- 格式：`https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id={草稿ID}`
- 示例：`"https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"`
- 获取方式：通过[创建草稿](./create_draft.md)或[保存草稿](./save_draft.md)接口获取
## 响应格式
### 成功响应 (200)
```json
{
"message": "视频生成任务已提交，请使用draft_url查询进度"
}
```
### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| message | string | 响应消息 |
### 错误响应 (4xx/5xx)
```json
{
"detail": "错误信息描述"
}
```
## 使用示例
### cURL 示例
#### 1. 基本视频生成
```bash
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"
}'
```
## 错误码说明
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | draft_url格式无效 | URL格式不正确 | 检查URL格式是否正确 |
| 404 | 草稿不存在 | 指定的草稿无法找到 | 确认草稿URL是否正确且存在 |
| 400 | 草稿内容为空 | 草稿中没有可导出的内容 | 确保草稿包含视频、音频或图片素材 |
| 400 | 素材无法访问 | 草稿中的素材文件无法下载 | 检查素材URL是否有效 |
| 500 | 视频渲染失败 | 视频处理过程中出错 | 检查草稿内容或联系技术支持 |
| 500 | 音频处理失败 | 音频混合过程中出错 | 检查音频格式或联系技术支持 |
| 500 | 编码失败 | 最终视频编码失败 | 联系技术支持 |
| 503 | 服务繁忙 | 渲染服务器负载过高 | 稍后重试 |
| 504 | 处理超时 | 视频生成超时 | 简化草稿内容或稍后重试 |
| 500 | 视频生成任务提交失败 | 内部处理错误 | 联系技术支持 |
## 注意事项
1. **处理时间**: 视频生成是耗时操作，可能需要几分钟到几十分钟
2. **文件大小**: 草稿复杂度和素材数量会影响处理时间
3. **网络稳定**: 确保素材URL可以稳定访问
4. **超时设置**: 建议设置较长的超时时间或使用轮询机制
5. **并发限制**: 避免同时生成大量视频
6. **存储空间**: 生成的视频文件可能很大，注意存储空间
7. **URL有效期**: 生成的video_url可能有时效性限制
8. **系统要求**: 视频生成功能仅在Windows系统上可用
## 工作流程
1. 验证draft_url参数
2. 解析草稿配置文件
3. 下载所有必需的素材文件
4. 按时间轴排列和处理素材
5. 应用视觉效果和转场
6. 混合音频轨道
7. 渲染最终视频
8. 编码并上传视频文件
9. 返回视频URL
## 相关接口
- [创建草稿](./create_draft.md)
- [保存草稿](./save_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [获取草稿](./get_draft.md)
- [查询视频生成状态](./gen_video_status.md)
---
<div align="right">
📚 **项目资源**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
### 语言切换
[中文版](./gen_video.zh.md) | [English](./gen_video.md)
docs/gen_video_status.md
+71 -68
View File
@@ -1,20 +1,20 @@
# GEN_VIDEO_STATUS API 接口文档
# GEN_VIDEO_STATUS API Documentation
## 接口信息
## Interface Information
```bash
POST /openapi/capcut-mate/v1/gen_video_status
```
## 功能描述
## Function Description
查询视频生成任务的状态和进度。配合 [gen_video](./gen_video.md) 接口使用，用于实时跟踪视频生成任务的执行情况，包括任务状态、进度百分比、完成结果等信息。
Query the status and progress of video generation tasks. Used together with the [gen_video](./gen_video.md) interface to track the execution of video generation tasks in real-time, including task status, progress percentage, completion results, and other information.
## 更多文档
## More Documentation
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
📖 For more detailed documentation and tutorials, please visit: [https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
## Request Parameters
```json
{
@@ -22,26 +22,26 @@ POST /openapi/capcut-mate/v1/gen_video_status
}
```
### 参数说明
### Parameter Description
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 草稿URL，与提交任务时使用的URL相同 |
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| draft_url | string | ✅ | - | Draft URL, same as the URL used when submitting the task |
### 参数详解
### Parameter Details
#### 草稿URL参数
#### Draft URL Parameter
- **draft_url**: 草稿的完整URL，用于标识要查询状态的视频生成任务
- 格式：必须是有效的URL格式
- 示例：`"https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"`
- 获取方式：通过 [gen_video](./gen_video.md) 接口提交任务后返回的draft_url
- **draft_url**: Complete URL of the draft, used to identify the video generation task to query status for
- Format: Must be a valid URL format
- Example: `"https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"`
- Acquisition Method: draft_url returned after submitting task via [gen_video](./gen_video.md) interface
## 响应格式
## Response Format
### 成功响应 (200)
### Success Response (200)
#### 任务等待中
#### Task Waiting
```json
{
@@ -56,7 +56,7 @@ POST /openapi/capcut-mate/v1/gen_video_status
}
```
#### 任务处理中
#### Task Processing
```json
{
@@ -71,7 +71,7 @@ POST /openapi/capcut-mate/v1/gen_video_status
}
```
#### 任务已完成
#### Task Completed
```json
{
@@ -86,7 +86,7 @@ POST /openapi/capcut-mate/v1/gen_video_status
}
```
#### 任务失败
#### Task Failed
```json
{
@@ -94,49 +94,49 @@ POST /openapi/capcut-mate/v1/gen_video_status
"status": "failed",
"progress": 0,
"video_url": "",
"error_message": "导出草稿失败: 剪映导出结束但目标文件未生成，请检查磁盘空间或剪映版本",
"error_message": "Export draft failed: Jianying export ended but target file was not generated, please check disk space or Jianying version",
"created_at": "2024-09-24T10:30:00.000Z",
"started_at": "2024-09-24T10:30:05.000Z",
"completed_at": "2024-09-24T10:32:15.000Z"
}
```
### 响应字段说明
### Response Field Description
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 草稿URL |
| status | string | 任务状态：pending/processing/completed/failed |
| progress | integer | 任务进度（0-100） |
| video_url | string | 生成的视频URL（仅在completed状态时有值） |
| error_message | string | 错误信息（仅在failed状态时有值） |
| created_at | string | 任务创建时间（ISO格式） |
| started_at | string\|null | 任务开始时间（ISO格式） |
| completed_at | string\|null | 任务完成时间（ISO格式） |
| Field | Type | Description |
|-------|------|-------------|
| draft_url | string | Draft URL |
| status | string | Task status: pending/processing/completed/failed |
| progress | integer | Task progress (0-100) |
| video_url | string | Generated video URL (only has value in completed status) |
| error_message | string | Error message (only has value in failed status) |
| created_at | string | Task creation time (ISO format) |
| started_at | string|null | Task start time (ISO format) |
| completed_at | string|null | Task completion time (ISO format) |
### 错误响应 (4xx/5xx)
### Error Response (4xx/5xx)
#### 404 Not Found - 任务不存在
#### 404 Not Found - Task Does Not Exist
```json
{
"detail": "视频生成任务未找到"
"detail": "Video generation task not found"
}
```
#### 500 Internal Server Error - 查询失败
#### 500 Internal Server Error - Query Failed
```json
{
"detail": "视频任务状态查询失败"
"detail": "Video task status query failed"
}
```
## 使用示例
## Usage Examples
### cURL 示例
### cURL Examples
#### 1. 查询任务状态
#### 1. Query Task Status
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/gen_video_status \
@@ -146,43 +146,46 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/gen_video_stat
}'
```
## 错误码说明
## Error Code Description
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | 无效的草稿URL | draft_url格式不正确 | 检查草稿URL格式是否正确 |
| 404 | 视频生成任务未找到 | 指定的草稿URL没有对应的视频生成任务 | 确认是否已通过gen_video接口提交任务 |
| 500 | 视频任务状态查询失败 | 内部处理错误 | 稍后重试或联系技术支持 |
| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 400 | draft_url is required | Missing draft URL parameter | Provide a valid draft_url |
| 400 | Invalid draft URL | draft_url format is incorrect | Check if draft URL format is correct |
| 404 | Video generation task not found | Specified draft URL has no corresponding video generation task | Confirm if task has been submitted via gen_video interface |
| 500 | Video task status query failed | Internal processing error | Retry later or contact technical support |
## 注意事项
## Notes
1. **轮询间隔**: 建议每5-10秒查询一次任务状态
2. **超时设置**: 建议设置总超时时间（如10分钟）
3. **状态处理**: 根据不同状态提供不同的用户反馈
4. **错误处理**: 妥善处理任务失败情况
5. **进度显示**: 利用progress字段显示进度条
6. **任务唯一性**: 同一草稿URL只能有一个进行中的任务
1. **Polling Interval**: Suggest querying task status every 5-10 seconds
2. **Timeout Settings**: Suggest setting total timeout time (e.g. 10 minutes)
3. **Status Handling**: Provide different user feedback based on different statuses
4. **Error Handling**: Properly handle task failure situations
5. **Progress Display**: Utilize progress field to display progress bar
6. **Task Uniqueness**: Same draft URL can only have one ongoing task
## 工作流程
## Workflow
1. 验证必填参数（draft_url）
2. 从任务管理器中查询任务状态
3. 将内部状态转换为API响应格式
4. 返回任务状态信息
1. Validate required parameters (draft_url)
2. Query task status from task manager
3. Convert internal status to API response format
4. Return task status information
## 相关接口
## Related Interfaces
- [gen_video](./gen_video.md) - 提交视频生成任务
- [create_draft](./create_draft.md) - 创建新的草稿文件
- [save_draft](./save_draft.md) - 保存草稿文件
- [gen_video](./gen_video.md) - Submit video generation task
- [create_draft](./create_draft.md) - Create new draft file
- [save_draft](./save_draft.md) - Save draft file
---
<div align="right">
📚 **项目资源**
📚 **Project Resources**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
</div>
### Language Switch
[中文版](./gen_video_status.zh.md) | [English](./gen_video_status.md)
docs/gen_video_status.zh.md
+191
View File
@@ -0,0 +1,191 @@
# GEN_VIDEO_STATUS API 接口文档
## 接口信息
```bash
POST /openapi/capcut-mate/v1/gen_video_status
```
## 功能描述
查询视频生成任务的状态和进度。配合 [gen_video](./gen_video.md) 接口使用，用于实时跟踪视频生成任务的执行情况，包括任务状态、进度百分比、完成结果等信息。
## 更多文档
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}
```
### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 草稿URL，与提交任务时使用的URL相同 |
### 参数详解
#### 草稿URL参数
- **draft_url**: 草稿的完整URL，用于标识要查询状态的视频生成任务
- 格式：必须是有效的URL格式
- 示例：`"https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"`
- 获取方式：通过 [gen_video](./gen_video.md) 接口提交任务后返回的draft_url
## 响应格式
### 成功响应 (200)
#### 任务等待中
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"status": "pending",
"progress": 0,
"video_url": "",
"error_message": "",
"created_at": "2024-09-24T10:30:00.000Z",
"started_at": null,
"completed_at": null
}
```
#### 任务处理中
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"status": "processing",
"progress": 65,
"video_url": "",
"error_message": "",
"created_at": "2024-09-24T10:30:00.000Z",
"started_at": "2024-09-24T10:30:05.000Z",
"completed_at": null
}
```
#### 任务已完成
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"status": "completed",
"progress": 100,
"video_url": "https://video-output.assets.jcaigc.cn/generated/video_abc123def456ghi789.mp4",
"error_message": "",
"created_at": "2024-09-24T10:30:00.000Z",
"started_at": "2024-09-24T10:30:05.000Z",
"completed_at": "2024-09-24T10:35:30.000Z"
}
```
#### 任务失败
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"status": "failed",
"progress": 0,
"video_url": "",
"error_message": "导出草稿失败: 剪映导出结束但目标文件未生成，请检查磁盘空间或剪映版本",
"created_at": "2024-09-24T10:30:00.000Z",
"started_at": "2024-09-24T10:30:05.000Z",
"completed_at": "2024-09-24T10:32:15.000Z"
}
```
### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 草稿URL |
| status | string | 任务状态：pending/processing/completed/failed |
| progress | integer | 任务进度（0-100） |
| video_url | string | 生成的视频URL（仅在completed状态时有值） |
| error_message | string | 错误信息（仅在failed状态时有值） |
| created_at | string | 任务创建时间（ISO格式） |
| started_at | string|null | 任务开始时间（ISO格式） |
| completed_at | string|null | 任务完成时间（ISO格式） |
### 错误响应 (4xx/5xx)
#### 404 Not Found - 任务不存在
```json
{
"detail": "视频生成任务未找到"
}
```
#### 500 Internal Server Error - 查询失败
```json
{
"detail": "视频任务状态查询失败"
}
```
## 使用示例
### cURL 示例
#### 1. 查询任务状态
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/gen_video_status \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL"
}'
```
## 错误码说明
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | 无效的草稿URL | draft_url格式不正确 | 检查草稿URL格式是否正确 |
| 404 | 视频生成任务未找到 | 指定的草稿URL没有对应的视频生成任务 | 确认是否已通过gen_video接口提交任务 |
| 500 | 视频任务状态查询失败 | 内部处理错误 | 稍后重试或联系技术支持 |
## 注意事项
1. **轮询间隔**: 建议每5-10秒查询一次任务状态
2. **超时设置**: 建议设置总超时时间（如10分钟）
3. **状态处理**: 根据不同状态提供不同的用户反馈
4. **错误处理**: 妥善处理任务失败情况
5. **进度显示**: 利用progress字段显示进度条
6. **任务唯一性**: 同一草稿URL只能有一个进行中的任务
## 工作流程
1. 验证必填参数（draft_url）
2. 从任务管理器中查询任务状态
3. 将内部状态转换为API响应格式
4. 返回任务状态信息
## 相关接口
- [gen_video](./gen_video.md) - 提交视频生成任务
- [create_draft](./create_draft.md) - 创建新的草稿文件
- [save_draft](./save_draft.md) - 保存草稿文件
---
<div align="right">
📚 **项目资源**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
### 语言切换
[中文版](./gen_video_status.zh.md) | [English](./gen_video_status.md)
docs/get_draft.md
+63 -62
View File
@@ -1,43 +1,41 @@
# GET_DRAFT API 接口文档
# GET_DRAFT API Documentation
## 接口信息
## Interface 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 the specified draft ID, allowing you to view material files, configuration files, etc. in the draft. Usually used for draft content preview, file management or status checking.
## 功能描述
## More Documentation
获取草稿文件列表。该接口用于获取指定草稿ID对应的所有文件列表，可以查看草稿中包含的素材文件、配置文件等信息。通常用于草稿内容的预览、文件管理或状态检查。
📖 For more detailed documentation and tutorials, please visit: [https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 更多文档
## Request Parameters
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
### Query Parameters
## 请求参数
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| draft_id | string | ✅ | - | Draft ID, length 20-32 characters |
### Query参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_id | string | ✅ | - | 草稿ID，长度为20-32位字符 |
### 参数详解
### Parameter Details
#### draft_id
- **类型**: 字符串
- **必填**: 是
- **长度**: 20-32位字符
- **格式**: 通常为UUID格式或类似的唯一标识符
- **示例**: `2f52a63b-8c6a-4417-8b01-1b2a569ccb6c`
- **获取方式**: 通常从draft_url中提取或由create_draft接口返回
- **Type**: String
- **Required**: Yes
- **Length**: 20-32 characters
- **Format**: Usually UUID format or similar unique identifier
- **Example**: `2f52a63b-8c6a-4417-8b01-1b2a569ccb6c`
- **Acquisition Method**: Usually extracted from draft_url or returned by create_draft interface
## 响应格式
## Response Format
### 成功响应 (200)
### Success Response (200)
```json
{
@@ -51,81 +49,84 @@ GET /openapi/capcut-mate/v1/get_draft
}
```
### 响应字段说明
### Response Field Description
| 字段名 | 类型 | 说明 |
|--------|------|------|
| files | array | 草稿相关的文件列表 |
| Field | Type | Description |
|-------|------|-------------|
| files | array | List of files related to the draft |
### 错误响应 (4xx/5xx)
### Error Response (4xx/5xx)
```json
{
"detail": "错误信息描述"
"detail": "Error message description"
}
```
## 使用示例
## Usage Examples
### cURL 示例
### cURL Examples
#### 1. 基本获取草稿文件列表
#### 1. Basic Get Draft File List
```bash
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. 使用完整的draft_id
#### 2. Using Complete draft_id
```bash
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"
```
## 错误码说明
## Error Code Description
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_id是必填项 | 缺少draft_id参数 | 提供有效的draft_id |
| 400 | draft_id长度无效 | draft_id长度不在20-32位范围内 | 检查draft_id格式是否正确 |
| 400 | draft_id格式无效 | draft_id格式不正确 | 确保使用正确的草稿ID格式 |
| 404 | 草稿不存在 | 指定的草稿ID无法找到 | 确认草稿ID是否正确且存在 |
| 500 | 获取文件列表失败 | 内部服务错误 | 联系技术支持或稍后重试 |
| 503 | 服务不可用 | 系统维护中 | 稍后重试 |
| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 400 | draft_id is required | Missing draft_id parameter | Provide a valid draft_id |
| 400 | Invalid draft_id length | draft_id length not within 20-32 characters range | Check if draft_id format is correct |
| 400 | Invalid draft_id format | draft_id format is incorrect | Ensure using correct draft ID format |
| 404 | Draft does not exist | Specified draft ID cannot be found | Confirm that 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 maintenance | Retry later |
## 注意事项
## Notes
1. **参数格式**: 确保draft_id格式正确且长度在20-32位之间
2. **ID提取**: 从draft_url正确提取draft_id
3. **文件类型**: 返回的文件列表包含多种类型的文件
4. **权限验证**: 确保有权限访问指定的草稿
5. **实时性**: 文件列表可能不是实时更新的，存在一定延迟
6. **文件状态**: 列表中的文件可能处于不同的处理状态
1. **Parameter Format**: Ensure draft_id format is correct and length is between 20-32 characters
2. **ID Extraction**: Correctly extract draft_id from draft_url
3. **File Types**: Returned file list contains multiple types of files
4. **Permission Verification**: Ensure permission to access specified draft
5. **Timeliness**: File list may not be updated in real-time, with some delay
6. **File Status**: Files in the list may be in different processing states
## 工作流程
## Workflow
1. 验证draft_id参数
2. 检查draft_id格式和长度
3. 查找指定的草稿
4. 获取草稿关联的所有文件
5. 返回文件列表
1. Validate draft_id parameter
2. Check draft_id format and length
3. Find specified draft
4. Get all files associated with the draft
5. Return file list
## 相关接口
## Related Interfaces
- [创建草稿](./create_draft.md)
- [保存草稿](./save_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [生成视频](./gen_video.md)
- [Create Draft](./create_draft.md)
- [Save Draft](./save_draft.md)
- [Add Videos](./add_videos.md)
- [Add Audios](./add_audios.md)
- [Add Images](./add_images.md)
- [Generate Video](./gen_video.md)
---
<div align="right">
📚 **项目资源**
📚 **Project Resources**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
### Language Switch
[中文版](./get_draft.zh.md) | [English](./get_draft.md)
docs/get_draft.zh.md
+132
View File
@@ -0,0 +1,132 @@
# GET_DRAFT API 接口文档
## 接口信息
```
GET /openapi/capcut-mate/v1/get_draft
```
## 功能描述
获取草稿文件列表。该接口用于获取指定草稿ID对应的所有文件列表，可以查看草稿中包含的素材文件、配置文件等信息。通常用于草稿内容的预览、文件管理或状态检查。
## 更多文档
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
### Query参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_id | string | ✅ | - | 草稿ID，长度为20-32位字符 |
### 参数详解
#### draft_id
- **类型**: 字符串
- **必填**: 是
- **长度**: 20-32位字符
- **格式**: 通常为UUID格式或类似的唯一标识符
- **示例**: `2f52a63b-8c6a-4417-8b01-1b2a569ccb6c`
- **获取方式**: 通常从draft_url中提取或由create_draft接口返回
## 响应格式
### 成功响应 (200)
```json
{
"files": [
"2f52a63b-8c6a-4417-8b01-1b2a569ccb6c.json",
"video_123456789.mp4",
"audio_987654321.mp3",
"image_555666777.jpg",
"thumbnail_888999000.png"
]
}
```
### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| files | array | 草稿相关的文件列表 |
### 错误响应 (4xx/5xx)
```json
{
"detail": "错误信息描述"
}
```
## 使用示例
### cURL 示例
#### 1. 基本获取草稿文件列表
```bash
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. 使用完整的draft_id
```bash
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"
```
## 错误码说明
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_id是必填项 | 缺少draft_id参数 | 提供有效的draft_id |
| 400 | draft_id长度无效 | draft_id长度不在20-32位范围内 | 检查draft_id格式是否正确 |
| 400 | draft_id格式无效 | draft_id格式不正确 | 确保使用正确的草稿ID格式 |
| 404 | 草稿不存在 | 指定的草稿ID无法找到 | 确认草稿ID是否正确且存在 |
| 500 | 获取文件列表失败 | 内部服务错误 | 联系技术支持或稍后重试 |
| 503 | 服务不可用 | 系统维护中 | 稍后重试 |
## 注意事项
1. **参数格式**: 确保draft_id格式正确且长度在20-32位之间
2. **ID提取**: 从draft_url正确提取draft_id
3. **文件类型**: 返回的文件列表包含多种类型的文件
4. **权限验证**: 确保有权限访问指定的草稿
5. **实时性**: 文件列表可能不是实时更新的，存在一定延迟
6. **文件状态**: 列表中的文件可能处于不同的处理状态
## 工作流程
1. 验证draft_id参数
2. 检查draft_id格式和长度
3. 查找指定的草稿
4. 获取草稿关联的所有文件
5. 返回文件列表
## 相关接口
- [创建草稿](./create_draft.md)
- [保存草稿](./save_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [生成视频](./gen_video.md)
---
<div align="right">
📚 **项目资源**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
### 语言切换
[中文版](./get_draft.zh.md) | [English](./get_draft.md)
docs/save_draft.md
+57 -54
View File
@@ -1,20 +1,20 @@
# SAVE_DRAFT API 接口文档
# SAVE_DRAFT API Documentation
## 接口信息
## Interface Information
```
POST /openapi/capcut-mate/v1/save_draft
```
## 功能描述
## Function Description
保存剪映草稿。该接口用于保存当前的草稿状态，确保编辑的内容得到持久化存储。通常在完成一系列编辑操作后调用此接口，以防止编辑内容丢失。
Save Jianying draft. This interface is used to save the current draft state, ensuring that edited content is persistently stored. Usually called after completing a series of editing operations to prevent loss of edited content.
## 更多文档
## More Documentation
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
📖 For more detailed documentation and tutorials, please visit: [https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
## Request Parameters
```json
{
@@ -22,24 +22,24 @@ POST /openapi/capcut-mate/v1/save_draft
}
```
### 参数说明
### Parameter Description
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 要保存的草稿URL |
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| draft_url | string | ✅ | - | Draft URL to be saved |
### 参数详解
### Parameter Details
#### draft_url
- **类型**: 字符串
- **必填**: 是
- **格式**: 完整的草稿URL，通常由create_draft接口返回
- **示例**: `https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258`
- **Type**: String
- **Required**: Yes
- **Format**: Complete draft URL, usually returned by create_draft interface
- **Example**: `https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258`
## 响应格式
## Response Format
### 成功响应 (200)
### Success Response (200)
```json
{
@@ -47,25 +47,25 @@ POST /openapi/capcut-mate/v1/save_draft
}
```
### 响应字段说明
### Response Field Description
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 保存后的草稿URL，通常与请求中的URL相同 |
| Field | Type | Description |
|-------|------|-------------|
| draft_url | string | Saved draft URL, usually the same as the URL in the request |
### 错误响应 (4xx/5xx)
### Error Response (4xx/5xx)
```json
{
"detail": "错误信息描述"
"detail": "Error message description"
}
```
## 使用示例
## Usage Examples
### cURL 示例
### cURL Examples
#### 1. 基本保存草稿
#### 1. Basic Save Draft
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/save_draft \
@@ -75,45 +75,48 @@ curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/save_draft \
}'
```
## 错误码说明
## Error Code Description
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | draft_url格式无效 | URL格式不正确 | 检查URL格式是否正确 |
| 404 | 草稿不存在 | 指定的草稿无法找到 | 确认草稿URL是否正确且存在 |
| 500 | 保存失败 | 内部服务错误 | 联系技术支持或稍后重试 |
| 503 | 服务不可用 | 系统维护中 | 稍后重试 |
| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 400 | draft_url is required | Missing draft URL parameter | Provide a 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 that draft URL is correct and exists |
| 500 | Save failed | Internal service error | Contact technical support or retry later |
| 503 | Service unavailable | System maintenance | Retry later |
## 注意事项
## Notes
1. **URL有效性**: 确保传入的draft_url是有效且存在的
2. **网络稳定性**: 保存操作需要稳定的网络连接
3. **频率控制**: 避免过于频繁的保存操作
4. **并发安全**: 同一草稿的并发保存可能导致冲突
1. **URL Validity**: Ensure the passed draft_url is valid and exists
2. **Network Stability**: Save operation requires stable network connection
3. **Frequency Control**: Avoid overly frequent save operations
4. **Concurrency Safety**: Concurrent saves of the same draft may cause conflicts
## 工作流程
## Workflow
1. 验证draft_url参数
2. 检查草稿是否存在
3. 获取当前草稿状态
4. 持久化保存草稿数据
5. 返回保存结果
1. Validate draft_url parameter
2. Check if draft exists
3. Get current draft state
4. Persistently save draft data
5. Return save result
## 相关接口
## Related Interfaces
- [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [生成视频](./gen_video.md)
- [Create Draft](./create_draft.md)
- [Add Videos](./add_videos.md)
- [Add Audios](./add_audios.md)
- [Add Images](./add_images.md)
- [Generate Video](./gen_video.md)
---
<div align="right">
📚 **项目资源**
📚 **Project Resources**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
</div>
### Language Switch
[中文版](./save_draft.zh.md) | [English](./save_draft.md)
docs/save_draft.zh.md
+122
View File
@@ -0,0 +1,122 @@
# SAVE_DRAFT API 接口文档
## 接口信息
```
POST /openapi/capcut-mate/v1/save_draft
```
## 功能描述
保存剪映草稿。该接口用于保存当前的草稿状态，确保编辑的内容得到持久化存储。通常在完成一系列编辑操作后调用此接口，以防止编辑内容丢失。
## 更多文档
📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)
## 请求参数
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}
```
### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 要保存的草稿URL |
### 参数详解
#### draft_url
- **类型**: 字符串
- **必填**: 是
- **格式**: 完整的草稿URL，通常由create_draft接口返回
- **示例**: `https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258`
## 响应格式
### 成功响应 (200)
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}
```
### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 保存后的草稿URL，通常与请求中的URL相同 |
### 错误响应 (4xx/5xx)
```json
{
"detail": "错误信息描述"
}
```
## 使用示例
### cURL 示例
#### 1. 基本保存草稿
```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"
}'
```
## 错误码说明
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | draft_url格式无效 | URL格式不正确 | 检查URL格式是否正确 |
| 404 | 草稿不存在 | 指定的草稿无法找到 | 确认草稿URL是否正确且存在 |
| 500 | 保存失败 | 内部服务错误 | 联系技术支持或稍后重试 |
| 503 | 服务不可用 | 系统维护中 | 稍后重试 |
## 注意事项
1. **URL有效性**: 确保传入的draft_url是有效且存在的
2. **网络稳定性**: 保存操作需要稳定的网络连接
3. **频率控制**: 避免过于频繁的保存操作
4. **并发安全**: 同一草稿的并发保存可能导致冲突
## 工作流程
1. 验证draft_url参数
2. 检查草稿是否存在
3. 获取当前草稿状态
4. 持久化保存草稿数据
5. 返回保存结果
## 相关接口
- [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [生成视频](./gen_video.md)
---
<div align="right">
📚 **项目资源**
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)
</div>
### 语言切换
[中文版](./save_draft.zh.md) | [English](./save_draft.md)