hair_change_color/docs/API.md

发型更换H5项目API文档

1. 文档说明

本文档描述了发型更换H5项目的API接口规范，所有前后端交互都应遵循此文档。任何API变更都应先修改此文档，然后再进行代码实现。

1.1 文档版本

版本	日期	描述	作者
v1.0	2026-01-18	初始版本	系统生成
v1.1	2026-02-10	补充发色更换接口，修正数据格式	系统更新

1.2 基本信息

• API基础路径: /api
• 服务端口: 5000（Flask）
• 响应格式: JSON
• 字符编码: UTF-8
• 认证方式: 无需认证

2. 响应格式

2.1 成功响应

{
  "success": true,
  "data": {...}
}

2.2 失败响应

{
  "success": false,
  "message": "错误信息"
}

3. API接口列表

接口路径	方法	功能描述	请求参数	成功响应数据
/api/hairstyles	GET	获取发型列表	无	{ "hairstyles": [...] }
/api/change-hair	POST	更换发型	image: 文件 hairstyle_id: 字符串	{ "result_image": "data:image/jpeg;base64,..." }
/api/change-hair-color	POST	更换头发颜色	image: 文件 rgb: 字符串 ratio: 字符串	{ "result_image": "data:image/jpeg;base64,..." }

4. 详细接口说明

4.1 获取发型列表

4.1.1 请求信息

• 路径: /api/hairstyles
• 方法: GET
• 参数: 无

4.1.2 响应信息

• 状态码: 200 OK
• 响应示例:

{
  "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"
      }
    ]
  }
}

4.1.3 字段说明

字段名	类型	描述
id	字符串	发型唯一标识符（长数字串，来源于 hairId2url.txt）
name	字符串	发型名称（格式为 "发型" + ID后4位）
image_url	字符串	发型图片的阿里云 OSS URL

4.2 更换发型

4.2.1 请求信息

• 路径: /api/change-hair
• 方法: POST
• Content-Type: multipart/form-data
• 参数:

参数名	类型	必填	描述
image	File	是	用户上传的图片文件（支持 png/jpg/jpeg/gif，最大16MB）
hairstyle_id	String	是	要更换的发型ID

4.2.2 响应信息

• 状态码: 200 OK
• 响应示例:

{
  "success": true,
  "data": {
    "result_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
  }
}

4.2.3 字段说明

字段名	类型	描述
result_image	字符串	发型更换后的图片，Base64 Data URL 格式

4.2.4 备注

• 远程AI处理耗时较长，超时时间为120秒
• 如果远程API调用失败，会返回原始图片作为降级处理

4.3 更换头发颜色

4.3.1 请求信息

• 路径: /api/change-hair-color
• 方法: POST
• Content-Type: 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"

4.3.2 响应信息

• 状态码: 200 OK
• 响应示例:

{
  "success": true,
  "data": {
    "result_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
  }
}

4.3.3 字段说明

字段名	类型	描述
result_image	字符串	发色更换后的图片，Base64 Data URL 格式

4.3.4 备注

• 远程AI处理耗时较长，超时时间为120秒
• 如果远程API调用失败，会返回原始图片作为降级处理
• ratio 值越大，颜色替换效果越明显

5. 错误处理

5.1 常见错误状态码

状态码	接口	描述	示例消息
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	处理失败	"处理图片失败: [错误信息]"

5.2 错误响应示例

{
  "success": false,
  "message": "请上传图片"
}

6. API变更流程

1. 文档修改: 先修改本API文档，记录变更内容、原因和影响范围
2. 代码实现: 根据文档修改后端API实现
3. 前端适配: 前端根据文档修改进行适配
4. 测试验证: 测试新API的功能和兼容性
5. 部署上线: 按计划部署变更

7. 附录

7.1 数据结构定义

7.1.1 发型对象 (Hairstyle)

{
  "id": "1953267161121464322",
  "name": "发型4322",
  "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267161121464322.jpg"
}

7.1.2 更换发型请求 (ChangeHairRequest)

FormData:
- image: File
- hairstyle_id: string (例: "1953267161121464322")

7.1.3 更换发型响应 (ChangeHairResponse)

{
  "success": true,
  "data": {
    "result_image": "data:image/jpeg;base64,..."
  }
}

7.1.4 更换发色请求 (ChangeHairColorRequest)

FormData:
- image: File
- rgb: string (例: "[255, 106, 0]")
- ratio: string (例: "0.9")

7.1.5 更换发色响应 (ChangeHairColorResponse)

{
  "success": true,
  "data": {
    "result_image": "data:image/jpeg;base64,..."
  }
}

7.2 支持的图片格式

格式	MIME类型
PNG	image/png
JPG/JPEG	image/jpeg
GIF	image/gif

文件大小限制：16MB

7.3 开发工具推荐

• API测试: Postman, Insomnia
• 文档生成: Swagger, ReDoc
• 代码生成: OpenAPI Generator