帧界未来 API 接口说明概要

1. 概述

帧界未来（Frame Future）提供图片处理、视频生成、字幕识别、AI模型代理等多种插件服务的开放API。本文档介绍API接口的鉴权方式、通用规范和使用说明。

基础信息：

接口风格：RESTful API

接口路径：/minimalist/api/**

认证方式：API Key

数据格式：JSON

编码格式：UTF-8

API文档：Knife4j (访问地址：/doc.html)

官网地址：https://framefuture.com/

2. API Key鉴权

所有API接口（/api/**）都需要通过API Key进行鉴权认证。

认证方式：在请求头中携带API Key

请求头：

注意事项：

API Key可通过管理后台生成和管理

免费API Key：76caed4ead074de39d6b6a4d9b41f6d9（用于测试和演示）

每个API Key都有对应的租户信息和权限配置

请求示例：

3. 统一返回格式

3.1 API接口返回格式 (AgentResponse)

所有API接口的响应VO类都继承自 AgentResponse 基类，确保统一的响应结构。

基础响应结构：

{
  "errorMessage": "成功",
  "code": 0,
  "aboutUrl": "https://framefuture.com/",
  "traceId": "1234567890abcdef",
  // ... 其他业务字段
}

字段说明：

errorMessage：错误信息，成功时为"成功"

code：业务状态码，0表示成功，非0表示失败

aboutUrl：帮助链接，指向官网

traceId：链路追踪ID，用于日志追踪和问题排查

成功响应示例（图片处理）：

{
  "errorMessage": "成功",
  "code": 0,
  "aboutUrl": "https://framefuture.com/",
  "traceId": "a1b2c3d4e5f6",
  "images": [
    {
      "url": "https://cdn.example.com/processed/image1.jpg",
      "width": 800,
      "height": 600,
      "format": "jpg",
      "size": 102400
    }
  ],
  "processingTime": 1500
}

失败响应示例：

{
  "errorMessage": "参数错误：图片URL不能为空",
  "code": 400,
  "aboutUrl": "https://framefuture.com/",
  "traceId": "a1b2c3d4e5f6"
}

3.2 分页返回格式

部分接口支持分页查询，分页结果会包含在响应的业务字段中：

{
  "errorMessage": "成功",
  "code": 0,
  "aboutUrl": "https://framefuture.com/",
  "traceId": "a1b2c3d4e5f6",
  "total": 100,
  "size": 10,
  "current": 1,
  "records": [
    // 数据列表
  ]
}

字段说明：

total：总记录数

size：每页大小

current：当前页码

records：当前页数据列表

4. 错误码定义

4.1 通用错误码

错误码	说明	描述
200	SUCCESS	操作成功
400	PARAM_ERROR	参数错误
401	REQUEST_UNAUTH	用户认证失败，请重新登录
403	NO_OPERATION_PERMISSION	暂无操作权限
500	FAILED	系统异常，请稍后再试
503	RESUBMIT_ERROR	请求已提交，请稍后重试

4.2 安全相关错误码

错误码	说明	描述
400	PARAM_XSS_ERROR	存在敏感数据，不能提交
400	TAMPER_WITH_DATA	请勿篡改数据

4.3 业务错误码

业务错误码由各模块自定义，通过 BusinessException 抛出：

常见业务错误：

文件相关：文件不存在、文件上传失败、文件不可用

用户相关：用户名或密码错误、账户已冻结、账户已过期

权限相关：无操作权限、租户未绑定

配置相关：参数配置不存在、存储配置不存在

5. 异常处理机制

系统通过全局异常处理器统一处理各类异常，所有异常都会转换为统一的响应格式返回。

5.1 参数验证异常

IllegalArgumentException：非法参数

MethodArgumentNotValidException：请求体参数验证失败

ConstraintViolationException：方法参数验证失败

MissingServletRequestParameterException：缺少必需的请求参数

响应示例：

{
  "code": 400,
  "errorMessage": "images: 图片列表不能为空，width: 宽度必须大于0",
  "aboutUrl": "https://framefuture.com/",
  "traceId": "a1b2c3d4e5f6"
}

5.2 认证/授权异常

API Key无效或过期

API Key缺失

无权限访问

响应示例：

{
  "code": 401,
  "errorMessage": "用户认证失败，请重新登录",
  "aboutUrl": "https://framefuture.com/",
  "traceId": "a1b2c3d4e5f6"
}

5.3 业务异常

BusinessException：自定义业务异常

响应示例：

{
  "code": 500,
  "errorMessage": "文件处理失败：不支持的文件格式",
  "aboutUrl": "https://framefuture.com/",
  "traceId": "a1b2c3d4e5f6"
}

5.4 XSS安全异常

检测到XSS攻击特征

存在敏感字符

响应示例：

{
  "code": 400,
  "errorMessage": "存在敏感数据，不能提交",
  "aboutUrl": "https://framefuture.com/",
  "traceId": "a1b2c3d4e5f6"
}

5.5 系统异常

其他未捕获的异常

响应示例：

{
  "code": 500,
  "errorMessage": "系统异常,请稍后再试",
  "aboutUrl": "https://framefuture.com/",
  "traceId": "a1b2c3d4e5f6"
}

6. 请求规范

6.1 请求头规范

必需请求头：

可选请求头：

6.2 请求参数验证

系统会自动对请求参数进行验证：

常见验证规则：

必填参数不能为空

数值范围限制

字符串长度限制

邮箱、URL格式验证

正则表达式匹配

验证失败响应示例：

{
  "code": 400,
  "errorMessage": "images: 图片列表不能为空，width: 宽度必须大于0",
  "aboutUrl": "https://framefuture.com/",
  "traceId": "a1b2c3d4e5f6"
}

6.3 XSS防护

系统自动检测和过滤XSS攻击：

自动转义HTML特殊字符

检测并拦截恶意脚本

返回 PARAM_XSS_ERROR 错误

7. 限流机制

7.1 API Key级别限流

系统对每个API Key实施请求频率限制：

限流规则：

基于API Key + 接口路径

使用令牌桶算法

默认等待时间：1秒

超出限制自动返回错误

限流超出响应：

{
  "code": 500,
  "errorMessage": "请求过于频繁，该接口每APIKEY每秒请求不能超过10次,请稍后再试",
  "aboutUrl": "https://framefuture.com/",
  "traceId": "a1b2c3d4e5f6"
}

7.2 接口级别限流

不同接口可配置不同的限流策略：

图片处理：较高的并发限制

AI模型调用：中等的并发限制

文件转换：较低的并发限制（资源密集型）

8. 链路追踪

8.1 TraceId机制

系统为每个请求自动生成唯一的TraceId：

生成时机：请求进入时自动生成

传递方式：通过MDC（Mapped Diagnostic Context）在整个调用链中传递

返回方式：在响应中返回，便于问题排查

TraceId格式：16位随机字符串（如：a1b2c3d4e5f6g7h8）

8.2 日志追踪

系统会自动记录每次API调用的详细日志，包含TraceId信息。

使用场景：

问题排查：根据TraceId查询完整请求链路

性能分析：追踪请求处理时间

错误定位：快速定位异常发生位置

8.3 TraceId的使用

每次API调用返回的响应中都包含TraceId：

{
  "errorMessage": "成功",
  "code": 0,
  "traceId": "a1b2c3d4e5f6",
  ...
}

遇到问题时，请提供TraceId以便技术支持快速定位问题。

9. 接口示例

9.1 图片处理接口

接口地址：POST /api/image/process

请求示例：

响应示例：

{
  "errorMessage": "成功",
  "code": 0,
  "aboutUrl": "https://framefuture.com/",
  "traceId": "a1b2c3d4e5f6",
  "images": [
    {
      "url": "https://cdn.example.com/processed/image1.jpg",
      "width": 800,
      "height": 600,
      "format": "jpg",
      "size": 102400
    },
    {
      "url": "https://cdn.example.com/processed/image2.jpg",
      "width": 800,
      "height": 600,
      "format": "jpg",
      "size": 98304
    }
  ],
  "processingTime": 1500
}

9.2 字幕生成接口

接口地址：POST /api/subtitle/generate

请求示例：

响应示例：

{
  "errorMessage": "成功",
  "code": 0,
  "aboutUrl": "https://framefuture.com/",
  "traceId": "b2c3d4e5f6g7",
  "subtitleUrl": "https://cdn.example.com/subtitle.srt",
  "duration": 120.5,
  "wordCount": 256
}

9.3 随机数生成接口

接口地址：GET /api/random/generate

请求示例：

响应示例：

{
  "errorMessage": "成功",
  "code": 0,
  "aboutUrl": "https://framefuture.com/",
  "traceId": "c3d4e5f6g7h8",
  "randomNumber": 42.68,
  "max": 100,
  "min": 0,
  "scale": 2
}

10. 最佳实践

10.1 错误处理

客户端应该：

检查响应中的 code 字段判断成功/失败

失败时显示 errorMessage 给用户

记录 traceId 便于问题反馈

示例代码（JavaScript）：

10.2 API Key管理

建议：

定期轮换API Key

不要在前端代码中硬编码API Key

使用环境变量存储API Key

监控API Key使用情况

为不同环境使用不同的API Key

10.3 性能优化

建议：

批量处理：尽量使用批量接口减少请求次数

缓存结果：对不变的数据进行客户端缓存

异步处理：耗时操作使用异步模式

合理超时：设置合理的请求超时时间

重试机制：实现指数退避的重试策略

10.4 安全建议

建议：

使用HTTPS加密传输

不要泄露API Key

验证输入参数

实施请求签名（如需要）

监控异常请求

11. 常见问题

Q1: 如何获取API Key？

A: 通过管理后台创建和管理API Key，每个租户可以创建多个API Key。

Q2: API Key有效期是多久？

A: API Key默认永久有效，除非手动禁用或删除。

Q3: 如何提高请求限制？

A: 联系管理员调整租户配置或升级套餐。

Q4: TraceId有什么用？

A: TraceId用于链路追踪，报告问题时提供TraceId可以帮助技术团队快速定位问题。

Q5: 接口返回500错误怎么办？

A: 记录TraceId并联系技术支持，我们会根据TraceId查询日志进行排查。

Q6: 如何处理超时？

检查网络连接

适当增加客户端超时时间

对于耗时操作，考虑使用异步接口

实施重试机制

Q7: 是否支持批量操作？

A: 大部分接口支持批量操作，建议优先使用批量接口提高效率。

Q8: 如何测试接口？

使用Knife4j在线文档：访问 /doc.html

使用Postman等API测试工具

使用免费API Key进行测试

12. 技术支持

12.1 联系方式

官网：https://framefuture.com/

邮箱：hi@framefuture.com

文档：https://docs.framefuture.com

12.2 API文档

Knife4j文档：{base_url}/doc.html

OpenAPI规范：{base_url}/v3/api-docs

12.3 错误报告

报告问题时请提供：

TraceId（链路追踪ID）

请求时间

接口地址

请求参数（脱敏后）

错误信息

13. 更新日志

版本	日期	说明
1.0.0	2025-11-25	初始版本，包含基础API规范说明

最后更新时间：2025-11-25

帧界未来 API 接口说明概要

1. 概述#

2. API Key鉴权#

3. 统一返回格式#

3.1 API接口返回格式 (AgentResponse)#

3.2 分页返回格式#

4. 错误码定义#

4.1 通用错误码#

4.2 安全相关错误码#

4.3 业务错误码#

5. 异常处理机制#

5.1 参数验证异常#

5.2 认证/授权异常#

5.3 业务异常#

5.4 XSS安全异常#

5.5 系统异常#

6. 请求规范#

6.1 请求头规范#

6.2 请求参数验证#

6.3 XSS防护#

7. 限流机制#

7.1 API Key级别限流#

7.2 接口级别限流#

8. 链路追踪#

8.1 TraceId机制#

8.2 日志追踪#

8.3 TraceId的使用#

9. 接口示例#

9.1 图片处理接口#

9.2 字幕生成接口#

9.3 随机数生成接口#

10. 最佳实践#

10.1 错误处理#

10.2 API Key管理#

10.3 性能优化#

10.4 安全建议#

11. 常见问题#

Q1: 如何获取API Key？#

Q2: API Key有效期是多久？#

Q3: 如何提高请求限制？#

Q4: TraceId有什么用？#

Q5: 接口返回500错误怎么办？#

Q6: 如何处理超时？#

Q7: 是否支持批量操作？#

Q8: 如何测试接口？#

12. 技术支持#

12.1 联系方式#

12.2 API文档#

12.3 错误报告#

13. 更新日志#

1. 概述

2. API Key鉴权

3. 统一返回格式

3.1 API接口返回格式 (AgentResponse)

3.2 分页返回格式

4. 错误码定义

4.1 通用错误码

4.2 安全相关错误码

4.3 业务错误码

5. 异常处理机制

5.1 参数验证异常

5.2 认证/授权异常

5.3 业务异常

5.4 XSS安全异常

5.5 系统异常

6. 请求规范

6.1 请求头规范

6.2 请求参数验证

6.3 XSS防护

7. 限流机制

7.1 API Key级别限流

7.2 接口级别限流

8. 链路追踪

8.1 TraceId机制

8.2 日志追踪

8.3 TraceId的使用

9. 接口示例

9.1 图片处理接口

9.2 字幕生成接口

9.3 随机数生成接口

10. 最佳实践

10.1 错误处理

10.2 API Key管理

10.3 性能优化

10.4 安全建议

11. 常见问题

Q1: 如何获取API Key？

Q2: API Key有效期是多久？

Q3: 如何提高请求限制？

Q4: TraceId有什么用？

Q5: 接口返回500错误怎么办？

Q6: 如何处理超时？

Q7: 是否支持批量操作？

Q8: 如何测试接口？

12. 技术支持

12.1 联系方式

12.2 API文档

12.3 错误报告

13. 更新日志