发型更换H5项目 API 文档

v1.1 · 2026-02-10

1. 文档说明

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

版本历史

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

基本信息

2. 响应格式

成功响应

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

失败响应

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

3. 接口列表总览

接口路径	方法	功能描述
/api/hairstyles	GET	获取发型列表
/api/change-hair	POST	更换发型
/api/change-hair-color	POST	更换头发颜色

4. 详细接口说明

4.1 获取发型列表

请求参数

无

响应示例

{
  "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 更换发型

请求参数 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 格式

4.3 更换头发颜色

请求参数 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 格式

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 变更流程

7. 附录

7.1 支持的图片格式

格式	MIME 类型	扩展名
PNG	image/png	.png
JPEG	image/jpeg	.jpg / .jpeg
GIF	image/gif	.gif

文件大小限制：16MB

7.2 开发工具推荐