发型更换H5项目 API 文档
+ v1.1 · 2026-02-10 + + +1. 文档说明
+本文档描述了发型更换H5项目的API接口规范，所有前后端交互都应遵循此文档。任何API变更都应先修改此文档，然后再进行代码实现。
+ +版本历史
+| 版本 | 日期 | 描述 | 作者 |
|---|---|---|---|
| v1.0 | 2026-01-18 | 初始版本 | 系统生成 |
| v1.1 | 2026-02-10 | 补充发色更换接口，修正数据格式 | 系统更新 |
基本信息
+
+
+
+
+ -
+
- API基础路径：
/api
+ - 服务端口：5000（Flask） +
- 响应格式：JSON +
- 字符编码：UTF-8 +
- 认证方式：无需认证 +
2. 响应格式
+ +成功响应
+{
+ "success": true,
+ "data": { ... }
+}失败响应
+{
+ "success": false,
+ "message": "错误信息"
+}3. 接口列表总览
+| 接口路径 | 方法 | 功能描述 |
|---|---|---|
/api/hairstyles |
+ GET | +获取发型列表 | +
/api/change-hair |
+ POST | +更换发型 | +
/api/change-hair-color |
+ POST | +更换头发颜色 | +
4. 详细接口说明
+ + +4.1 获取发型列表
+
+ GET
+ /api/hairstyles
+
+
+ 请求参数
+无
+ +响应示例
+{
+ "success": true,
+ "data": {
+ "hairstyles": [
+ {
+ "id": "1953267161121464322",
+ "name": "发型4322",
+ "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267161121464322.jpg"
+ },
+ {
+ "id": "1953267288284372994",
+ "name": "发型2994",
+ "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267288284372994.jpg"
+ }
+ ]
+ }
+}字段说明
+| 字段名 | 类型 | 描述 |
|---|---|---|
id | String | 发型唯一标识符（长数字串，来源于 hairId2url.txt） |
name | String | 发型名称（格式："发型" + ID后4位） |
image_url | String | 发型图片的阿里云 OSS URL |
4.2 更换发型
+
+ POST
+ /api/change-hair
+
+
+ 请求参数 multipart/form-data
+ | 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
image | File | 是 | 用户上传的图片文件（支持 png/jpg/jpeg/gif，最大 16MB） |
hairstyle_id | String | 是 | 要更换的发型ID |
响应示例
+{
+ "success": true,
+ "data": {
+ "result_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
+ }
+}响应字段
+| 字段名 | 类型 | 描述 |
|---|---|---|
result_image | String | 发型更换后的图片，Base64 Data URL 格式 |
+
+
+
+ 注意事项
+ -
+
- 远程 AI 处理耗时较长，超时时间为 120 秒 +
- 如果远程 API 调用失败，会返回原始图片作为降级处理 +
4.3 更换头发颜色
+
+ POST
+ /api/change-hair-color
+
+
+ 请求参数 multipart/form-data
+ | 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
image | File | 是 | 用户上传的图片文件（支持 png/jpg/jpeg/gif，最大 16MB） |
rgb | String | 是 | RGB颜色值，格式为 "[R, G, B]"，例如 "[255, 106, 0]" |
ratio | String | 是 | 颜色替换强度，范围 0.0 ~ 1.0，例如 "0.9" |
响应示例
+{
+ "success": true,
+ "data": {
+ "result_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
+ }
+}响应字段
+| 字段名 | 类型 | 描述 |
|---|---|---|
result_image | String | 发色更换后的图片，Base64 Data URL 格式 |
+
+
+
+ 注意事项
+ -
+
- 远程 AI 处理耗时较长，超时时间为 120 秒 +
- 如果远程 API 调用失败，会返回原始图片作为降级处理 +
ratio值越大，颜色替换效果越明显
+
5. 错误处理
+ +错误响应格式
+{
+ "success": false,
+ "message": "请上传图片"
+}错误状态码列表
+| 状态码 | 接口 | 触发条件 | 错误消息 |
|---|---|---|---|
| 400 | /api/change-hair | 缺少图片 | 请上传图片 |
| 400 | /api/change-hair | 缺少发型ID | 请选择发型 |
| 400 | /api/change-hair | 文件类型不合法 | 不支持的文件类型，请上传图片文件 |
| 400 | /api/change-hair-color | 缺少图片 | 请上传图片 |
| 400 | /api/change-hair-color | 缺少颜色值 | 请选择颜色 |
| 400 | /api/change-hair-color | 缺少替换比例 | 请设置更换比例 |
| 400 | /api/change-hair-color | 文件类型不合法 | 不支持的文件类型，请上传图片文件 |
| 500 | /api/hairstyles | 服务器内部错误 | 获取发型列表失败: [错误信息] |
| 500 | /api/change-hair | 处理失败 | 处理图片失败: [错误信息] |
| 500 | /api/change-hair-color | 处理失败 | 处理图片失败: [错误信息] |
6. API 变更流程
+
+
+
+
+ -
+
- 文档修改 — 先修改本 API 文档，记录变更内容、原因和影响范围 +
- 代码实现 — 根据文档修改后端 API 实现 +
- 前端适配 — 前端根据文档修改进行适配 +
- 测试验证 — 测试新 API 的功能和兼容性 +
- 部署上线 — 按计划部署变更 +
7. 附录
+ +7.1 支持的图片格式
+| 格式 | MIME 类型 | 扩展名 |
|---|---|---|
| PNG | image/png | .png |
| JPEG | image/jpeg | .jpg / .jpeg |
| GIF | image/gif | .gif |
文件大小限制：16MB
+ +7.2 开发工具推荐
+
+
+
+ -
+
- API 测试：Postman、Insomnia +
- 文档生成：Swagger、ReDoc +
- 代码生成：OpenAPI Generator +
+ 发型更换H5项目 API 文档 · v1.1 · 最后更新 2026-02-10
+
+