发型更换H5项目 API 文档
v1.3 · 2026-08-101. 文档说明
本文档描述了发型更换H5项目的API接口规范，所有前后端交互都应遵循此文档。任何API变更都应先修改此文档，然后再进行代码实现。
版本历史
| 版本 | 日期 | 描述 | 作者 |
|---|---|---|---|
| v1.0 | 2026-01-18 | 初始版本 | 系统生成 |
| v1.1 | 2026-02-10 | 补充发色更换接口，修正数据格式 | 系统更新 |
| v1.2 | 2026-08-10 | 生产域名 /hair 前缀；发型预览图改为本机静态路径 | 系统更新 |
| v1.3 | 2026-08-10 | 补充全部发型预览图完整链接；分辨率更新为 634×950 | 系统更新 |
基本信息
- 生产域名：
https://meida.xiangsilian.com - H5 页面：
https://meida.xiangsilian.com/hair/ - API基础路径（对外）：
/hair/api - 完整 API 前缀：
https://meida.xiangsilian.com/hair/api - 后端内部监听：127.0.0.1:5000（Gunicorn，经 Nginx 反代）
- 响应格式：JSON
- 字符编码：UTF-8
- 认证方式：无需认证
接入方请使用对外路径 /hair/api/...。直连本机 5000 端口时可用 /api/...（仅限服务器本机调试）。
2. 响应格式
成功响应
{
"success": true,
"data": { ... }
}失败响应
{
"success": false,
"message": "错误信息"
}3. 接口列表总览
| 接口路径 | 方法 | 功能描述 |
|---|---|---|
/hair/api/hairstyles |
GET | 获取发型列表 |
/hair/api/change-hair |
POST | 更换发型 |
/hair/api/change-hair-color |
POST | 更换头发颜色 |
4. 详细接口说明
4.1 获取发型列表
GET
/hair/api/hairstyles
请求参数
无
示例：GET https://meida.xiangsilian.com/hair/api/hairstyles
响应示例
{
"success": true,
"data": {
"hairstyles": [
{
"id": "1953267161121464322",
"name": "发型4322",
"image_url": "/hair/images/hairstyles/1953267161121464322.jpg"
},
{
"id": "1953267288284372994",
"name": "发型2994",
"image_url": "/hair/images/hairstyles/1953267288284372994.jpg"
}
]
}
}字段说明
| 字段名 | 类型 | 描述 |
|---|---|---|
id | String | 发型唯一标识符（长数字串，来源于 hairId2url.txt） |
name | String | 发型名称（格式："发型" + ID后4位） |
image_url | String | 发型预览图本机相对路径，完整访问为 https://meida.xiangsilian.com + image_url |
图片存放在服务器 frontend/images/hairstyles/，分辨率 634 × 950（原图 60%）。完整链接见 7.2。
4.2 更换发型
POST
/hair/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
/hair/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 | /hair/api/change-hair | 缺少图片 | 请上传图片 |
| 400 | /hair/api/change-hair | 缺少发型ID | 请选择发型 |
| 400 | /hair/api/change-hair | 文件类型不合法 | 不支持的文件类型，请上传图片文件 |
| 400 | /hair/api/change-hair-color | 缺少图片 | 请上传图片 |
| 400 | /hair/api/change-hair-color | 缺少颜色值 | 请选择颜色 |
| 400 | /hair/api/change-hair-color | 缺少替换比例 | 请设置更换比例 |
| 400 | /hair/api/change-hair-color | 文件类型不合法 | 不支持的文件类型，请上传图片文件 |
| 500 | /hair/api/hairstyles | 服务器内部错误 | 获取发型列表失败: [错误信息] |
| 500 | /hair/api/change-hair | 处理失败 | 处理图片失败: [错误信息] |
| 500 | /hair/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 发型预览图完整链接（本机）
- 分辨率：634 × 950（原图 1056 × 1584 的 60%）
- 目录：
frontend/images/hairstyles/ - URL 规则：
https://meida.xiangsilian.com/hair/images/hairstyles/{id}.jpg - 数量：60
7.2 开发工具推荐
- API 测试：Postman、Insomnia
- 文档生成：Swagger、ReDoc
- 代码生成：OpenAPI Generator
发型更换H5项目 API 文档 · v1.3 · 最后更新 2026-08-10