辅助工具接口
目录
简介
辅助工具接口是 CapCut Mate 项目的核心功能模块，专注于提供基础的实用工具接口。该系统目前提供以下核心功能：
- 链接提取：从输入内容中提取链接信息，支持多值转单值返回
- 贴纸搜索：基于关键词的贴纸库检索和智能推荐
- 数据转换：多种数据格式之间的转换和批量处理能力
这些基础工具接口为视频制作流程提供了简洁高效的自动化支持，特别适用于内容创作者的日常素材管理和处理需求。
核心API接口
系统提供以下核心API接口，每个接口都经过精心设计以满足特定的使用场景：
graph TB
subgraph "核心API接口"
GET_URL[get_url接口]
SEARCH_STICKER[search_sticker接口]
STR_LIST_TO_OBJS[str_list_to_objs接口]
STR_TO_LIST[str_to_list接口]
OBJS_TO_STR_LIST[objs_to_str_list接口]
end
subgraph "服务层"
GET_URL_SERVICE[get_url服务]
SEARCH_SERVICE[search_sticker服务]
CONVERSION_SERVICE[转换服务]
end
GET_URL --> GET_URL_SERVICE
SEARCH_STICKER --> SEARCH_SERVICE
STR_LIST_TO_OBJS --> CONVERSION_SERVICE
STR_TO_LIST --> CONVERSION_SERVICE
OBJS_TO_STR_LIST --> CONVERSION_SERVICE
get_url接口
接口概述
get_url接口用于从输入内容中提取链接信息，将多值返回转换为单值返回。该接口虽然看似简单，但在数据处理流程中发挥着重要作用。
接口信息
POST /openapi/capcut-mate/v1/get_url
请求参数
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| output | string | ✅ | - | 需要提取链接的内容 |
响应格式
成功响应 (200)
{
"output": "提取结果内容"
}
使用示例
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_url \
-H "Content-Type: application/json" \
-d '{
"output": "[魂牵梦萦https://sf.com；中国人https://jcaigc.cn],\"[]\""
}'
错误码说明
| 错误码 | 错误信息 | 描述 | 解决方案 |
|---|---|---|---|
| 400 | output is required | 缺少output参数 | 提供有效的output参数 |
| 500 | 链接提取失败 | 内部处理错误 | 联系技术支持 |
search_sticker接口
接口概述
search_sticker接口用于根据用户提供的关键词搜索相关的贴纸素材，返回匹配的贴纸列表，包括详细的图像信息、尺寸、类型等。
接口信息
POST /openapi/capcut-mate/v1/search_sticker
请求参数
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| keyword | string | ✅ | - | 搜索关键词 |
响应格式
成功响应 (200)
{
"data": [
{
"sticker": {
"large_image": {
"image_url": "贴纸大图URL"
},
"preview_cover": "",
"sticker_package": {
"height_per_frame": 540,
"size": 305932,
"width_per_frame": 540
},
"sticker_type": 1,
"track_thumbnail": "缩略图URL"
},
"sticker_id": "贴纸ID",
"title": "贴纸标题"
}
]
}
使用示例
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/search_sticker \
-H "Content-Type: application/json" \
-d '{
"keyword": "人"
}'
错误码说明
| 错误码 | 错误信息 | 描述 | 解决方案 |
|---|---|---|---|
| 400 | keyword is required | 缺少keyword参数 | 提供有效的keyword参数 |
数据转换工具
接口概述
系统提供三种基本的数据转换工具，用于处理不同格式之间的数据转换需求：
- 字符串列表转换：将字符串列表转换为对象列表
- 字符串转列表：将字符串转换为列表格式
- 对象列表转换：将对象列表转换回字符串格式
str_list_to_objs接口
将字符串列表转换为对象列表，便于后续的数据处理和分析。
str_to_list接口
将字符串转换为列表格式，支持复杂的JSON字符串解析。
objs_to_str_list接口
将对象列表转换回字符串格式，满足不同场景下的数据传输需求。
集成指南
基础集成步骤
- 环境准备：确保系统已正确安装并启动
- API访问：通过HTTP POST请求访问相应的API端点
- 参数验证：确保所有必需参数都已正确提供
- 响应处理：根据API返回的JSON格式处理响应数据
错误处理最佳实践
- 始终检查HTTP状态码
- 验证响应数据的JSON格式
- 实现适当的重试机制
- 记录详细的错误日志
故障排除
常见问题及解决方案
get_url接口问题
问题症状：链接提取失败或返回空结果
可能原因：
- 输入内容格式不符合预期
- 网络连接问题
- 服务器内部错误
解决步骤：
- 验证输入内容的格式和完整性
- 检查网络连接状态
- 查看服务器日志获取详细错误信息
search_sticker接口问题
问题症状：贴纸搜索返回空结果或随机数据
可能原因：
- 关键词匹配规则过于严格
- 贴纸配置文件访问问题
- 数据库连接异常
解决步骤：
- 尝试使用不同的关键词组合
- 验证贴纸配置文件的可访问性
- 检查系统日志中的错误信息
数据转换接口问题
问题症状：数据转换失败或格式错误
可能原因：
- 输入数据格式不正确
- JSON解析错误
- 数据类型不匹配
解决步骤：
- 验证输入数据的JSON格式
- 检查数据类型的一致性
- 参考API文档的格式要求进行修正
性能优化建议
- 缓存机制：对于频繁使用的贴纸数据，建议实现本地缓存
- 批量处理：对于大量数据的转换操作，考虑批量处理以提高效率
- 连接复用：在高并发场景下，复用HTTP连接以减少开销
- 超时设置：合理设置API调用的超时时间，避免长时间阻塞
监控和日志
建议实现以下监控措施：
- 记录所有API调用的日志
- 监控响应时间和错误率
- 设置告警机制以及时发现异常
- 定期分析使用模式以优化性能
通过以上精简而实用的文档，用户可以快速理解和使用CapCut Mate的核心辅助工具接口，为视频制作流程提供可靠的自动化支持。
