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
2025-12-01 23:28:39 +08:00
parent ea8b74e0c0
commit 1ec28f81d4
1 changed files with 143 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/get_text_animations.md
+143 -204
View File
@@ -1,10 +1,14 @@
# get_text_animations 接口文档
# GET_TEXT_ANIMATIONS API 接口文档
## 接口概述
## 接口信息
**接口名称**：get_text_animations
**接口地址**：`POST /openapi/capcut-mate/v1/get_text_animations`
**功能描述**：获取文字出入场动画列表，返回所有支持的且满足条件的文字出入场动画。支持根据动画类型（入场、出场、循环）和会员模式（所有、VIP、免费）进行筛选。
```bash
POST /openapi/capcut-mate/v1/get_text_animations
```
## 功能描述
获取文字出入场动画列表，返回所有支持的且满足条件的文字出入场动画。支持根据动画类型（入场、出场、循环）和会员模式（所有、VIP、免费）进行筛选。
## 更多文档
@@ -12,33 +16,6 @@
## 请求参数
### 请求体 (application/json)
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| mode | integer | 否 | 0 | 动画模式：0=所有，1=VIP，2=免费 |
| type | string | 是 | - | 动画类型：in=入场，out=出场，loop=循环 |
### 动画模式说明
| 模式值 | 模式名称 | 描述 |
|--------|----------|------|
| 0 | 所有 | 返回所有动画（包括VIP和免费） |
| 1 | VIP | 仅返回VIP动画 |
| 2 | 免费 | 仅返回免费动画 |
### 动画类型说明
| 类型值 | 类型名称 | 描述 |
|--------|----------|------|
| in | 入场动画 | 文字出现时的动画效果 |
| out | 出场动画 | 文字消失时的动画效果 |
| loop | 循环动画 | 文字持续播放的循环动画效果 |
## 请求示例
### 获取所有入场动画
```json
{
"mode": 0,
@@ -46,35 +23,96 @@
}
```
### 获取VIP出场动画
### 参数说明
```json
{
"mode": 1,
"type": "out"
}
```
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| mode | integer | ❌ | 0 | 动画模式：0=所有，1=VIP，2=免费 |
| type | string | ✅ | - | 动画类型：in=入场，out=出场，loop=循环 |
### 获取免费循环动画
### 参数详解
```json
{
"mode": 2,
"type": "loop"
}
```
#### 动画模式参数
- **mode**: 动画筛选模式
- 0 = 返回所有动画（包括VIP和免费）
- 1 = 仅返回VIP动画
- 2 = 仅返回免费动画
- 默认值：0
#### 动画类型参数
- **type**: 动画类型，必填参数
- "in" = 入场动画（文字出现时的动画效果）
- "out" = 出场动画（文字消失时的动画效果）
- "loop" = 循环动画（文字持续播放的循环动画效果）
#### 动画模式说明
| 模式值 | 模式名称 | 描述 |
|--------|----------|------|
| 0 | 所有 | 返回所有动画（包括VIP和免费） |
| 1 | VIP | 仅返回VIP动画 |
| 2 | 免费 | 仅返回免费动画 |
#### 动画类型说明
| 类型值 | 类型名称 | 描述 |
|--------|----------|------|
| in | 入场动画 | 文字出现时的动画效果 |
| out | 出场动画 | 文字消失时的动画效果 |
| loop | 循环动画 | 文字持续播放的循环动画效果 |
## 响应格式
### 成功响应
### 成功响应 (200)
```json
{
"effects": "[{\"resource_id\":\"7314291622525538843\",\"type\":\"in\",\"category_id\":\"ruchang\",\"category_name\":\"入场\",\"duration\":500000,\"id\":\"35395178\",\"name\":\"冰雪飘动\",\"request_id\":\"\",\"start\":0,\"icon_url\":\"https://lf5-hl-hw-effectcdn-tos.byteeffecttos.com/obj/ies.fe.effect/459c196951cadbd024456a63db89481f\",\"material_type\":\"sticker\",\"panel\":\"\",\"path\":\"\",\"platform\":\"all\"},{\"resource_id\":\"7397306443147252233\",\"type\":\"in\",\"category_id\":\"ruchang\",\"category_name\":\"入场\",\"duration\":500000,\"id\":\"77035159\",\"name\":\"变色输入\",\"request_id\":\"\",\"start\":0,\"icon_url\":\"https://lf5-hl-hw-effectcdn-tos.byteeffecttos.com/obj/ies.fe.effect/c15f5c313f8170c558043abf300a0692\",\"material_type\":\"sticker\",\"panel\":\"\",\"path\":\"\",\"platform\":\"all\"}]"
"effects": [
{
"resource_id": "7314291622525538843",
"type": "in",
"category_id": "ruchang",
"category_name": "入场",
"duration": 500000,
"id": "35395178",
"name": "冰雪飘动",
"request_id": "",
"start": 0,
"icon_url": "https://lf5-hl-hw-effectcdn-tos.byteeffecttos.com/obj/ies.fe.effect/459c196951cadbd024456a63db89481f",
"material_type": "sticker",
"panel": "",
"path": "",
"platform": "all"
},
{
"resource_id": "7397306443147252233",
"type": "in",
"category_id": "ruchang",
"category_name": "入场",
"duration": 500000,
"id": "77035159",
"name": "变色输入",
"request_id": "",
"start": 0,
"icon_url": "https://lf5-hl-hw-effectcdn-tos.byteeffecttos.com/obj/ies.fe.effect/c15f5c313f8170c558043abf300a0692",
"material_type": "sticker",
"panel": "",
"path": "",
"platform": "all"
}
]
}
```
### 动画对象结构
### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| effects | array | 文字出入场动画对象数组 |
#### 动画对象结构
每个动画对象包含以下字段：
@@ -95,179 +133,80 @@
| path | string | 路径信息 |
| platform | string | 支持平台（通常为"all"） |
### 错误响应
#### 400 Bad Request - 参数验证失败
### 错误响应 (4xx/5xx)
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "请求参数验证失败",
"details": "type 参数必须为 in、out 或 loop"
}
"detail": "错误信息描述"
}
```
#### 500 Internal Server Error - 获取动画失败
## 使用示例
```json
{
"error": {
"code": "TEXT_ANIMATION_GET_FAILED",
"message": "获取文字动画失败",
"details": "动画数据获取失败"
}
}
### cURL 示例
#### 1. 获取所有入场动画
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_text_animations \
-H "Content-Type: application/json" \
-d '{
"mode": 0,
"type": "in"
}'
```
#### 2. 获取VIP出场动画
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_text_animations \
-H "Content-Type: application/json" \
-d '{
"mode": 1,
"type": "out"
}'
```
#### 3. 获取免费循环动画
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_text_animations \
-H "Content-Type: application/json" \
-d '{
"mode": 2,
"type": "loop"
}'
```
## 错误码说明
| 错误码 | HTTP状态码 | 描述 | 解决方案 |
|--------|------------|------|----------|
| VALIDATION_ERROR | 400 | 请求参数验证失败 | 检查type参数是否为in/out/loop，mode参数是否为0/1/2 |
| TEXT_ANIMATION_GET_FAILED | 500 | 获取文字动画失败 | 检查服务状态，稍后重试 |
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | type是必填项 | 缺少动画类型参数 | 提供有效的type参数 |
| 400 | mode参数无效 | mode参数超出范围 | 使用0、1或2作为mode值 |
| 400 | type参数无效 | type参数值不正确 | 使用in、out或loop作为type值 |
| 500 | 获取文字动画失败 | 内部处理错误 | 联系技术支持 |
## 使用说明
## 注意事项
### 参数说明
1. **参数要求**: type参数为必填项，mode参数为可选项
2. **动画类型**: type参数只能是"in"、"out"、"loop"中的一个
3. **动画模式**: mode参数只能是0、1、2中的一个
4. **响应格式**: 与旧版本不同，当前版本直接返回对象数组而非JSON字符串
5. **数据来源**: 当前使用模拟数据，生产环境中应从数据库或API获取
1. **type参数**：必填参数，只能选择 "in"、"out"、"loop" 中的一个
2. **mode参数**：可选参数，默认为0（所有动画）
3. **响应数据**：effects字段是JSON字符串格式，需要解析后使用
## 工作流程
### 动画应用场景
1. **入场动画（in）**：
- 适用于文字出现的场景
- 如渐显入场、冰雪飘动、变色输入等
- 通常时长在0.5-1秒之间
2. **出场动画（out）**：
- 适用于文字消失的场景
- 如渐隐出场、旋转消失等
- 通常时长在0.6-0.8秒之间
3. **循环动画（loop）**：
- 适用于需要持续吸引注意力的文字
- 如心跳跳动、闪烁效果等
- 通常时长在1-1.2秒之间，可无限循环
### 使用建议
- 根据视频内容风格选择合适的动画类型
- VIP动画通常效果更佳，但需要会员权限
- 建议先获取所有动画，再根据需要进行筛选
- 可以结合动画预览图（icon_url）让用户选择
## 示例代码
### JavaScript示例
```javascript
// 获取所有入场动画
const getInAnimations = async () => {
const response = await fetch('/openapi/capcut-mate/v1/get_text_animations', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
mode: 0,
type: 'in'
})
});
const result = await response.json();
const animations = JSON.parse(result.effects);
console.log('入场动画列表:', animations);
};
// 获取免费循环动画
const getFreeLoopAnimations = async () => {
const response = await fetch('/openapi/capcut-mate/v1/get_text_animations', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
mode: 2,
type: 'loop'
})
});
const result = await response.json();
const animations = JSON.parse(result.effects);
console.log('免费循环动画列表:', animations);
};
```
### Python示例
```python
import requests
import json
def get_text_animations(mode=0, animation_type='in'):
"""获取文字动画列表"""
url = 'http://localhost:8000/v1/get_text_animations'
data = {
'mode': mode,
'type': animation_type
}
response = requests.post(url, json=data)
if response.status_code == 200:
result = response.json()
animations = json.loads(result['effects'])
return animations
else:
print(f"请求失败: {response.status_code}")
return []
# 使用示例
in_animations = get_text_animations(mode=0, animation_type='in')
print(f"获取到 {len(in_animations)} 个入场动画")
vip_out_animations = get_text_animations(mode=1, animation_type='out')
print(f"获取到 {len(vip_out_animations)} 个VIP出场动画")
```
1. 验证必填参数（type）
2. 验证参数有效性（type和mode）
3. 根据type和mode筛选动画数据
4. 返回符合条件的动画列表
## 相关接口
- [add_captions](./add_captions.md) - 批量添加字幕（可使用动画效果）
- [add_text_style](./add_text_style.md) - 创建文本富文本样式
- [add_effects](./add_effects.md) - 添加视频特效
## 技术实现
### 文件结构
```
src/
├── schemas/get_text_animations.py # 请求/响应数据模型
├── service/get_text_animations.py # 业务逻辑实现
└── router/v1.py # API路由定义
```
### 核心逻辑
1. **参数验证**：验证type和mode参数的有效性
2. **数据筛选**：根据type和mode参数筛选动画数据
3. **数据格式化**：将动画数据转换为JSON字符串格式
4. **响应返回**：返回符合规范的API响应
### 数据来源
目前使用模拟数据，实际项目中应该：
- 从数据库获取动画数据
- 或从第三方API获取动画资源
- 支持动画资源的动态更新
---
**版本信息**：v1.0
**最后更新**：2024-09-24
- [添加字幕](./add_captions.md)
- [创建文本样式](./add_text_style.md)
- [获取图片动画](./get_image_animations.md)
---