xsl/hair_change_color
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

save

Browse Source
This commit is contained in:
Ubuntu
2026-08-10 22:38:12 +08:00
parent 624be459a3
commit b6e25b8a9c
74 changed files with 255 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+52 -23
View File
@@ -10,15 +10,23 @@
|------|------|------|------|
| v1.0 | 2026-01-18 | 初始版本 | 系统生成 |
| v1.1 | 2026-02-10 | 补充发色更换接口，修正数据格式 | 系统更新 |
| v1.2 | 2026-08-10 | 生产域名 `/hair` 前缀；发型预览图改为本机静态路径 | 系统更新 |
| v1.3 | 2026-08-10 | 补充全部发型预览图完整链接；分辨率更新为 634×950 | 系统更新 |
### 1.2 基本信息
- **API基础路径**: `/api`
- **服务端口**: 5000（Flask）
- **生产域名**: `https://meida.xiangsilian.com`
- **H5 页面**: `https://meida.xiangsilian.com/hair/`
- **在线 API 文档**: `https://meida.xiangsilian.com/hair/api-doc.html`
- **API基础路径（对外）**: `/hair/api`
- **完整 API 前缀**: `https://meida.xiangsilian.com/hair/api`
- **后端内部监听**: `127.0.0.1:5000`（Gunicorn，经 Nginx 反代；应用内路由仍为 `/api/...`）
- **响应格式**: JSON
- **字符编码**: UTF-8
- **认证方式**: 无需认证
> 接入方请使用对外路径 `/hair/api/...`。直连本机 `5000` 端口时可用 `/api/...`（仅限服务器本机调试）。
## 2. 响应格式
### 2.1 成功响应
@@ -43,18 +51,19 @@
| 接口路径 | 方法 | 功能描述 | 请求参数 | 成功响应数据 |
|---------|------|----------|---------|-------------|
| `/api/hairstyles` | GET | 获取发型列表 | 无 | `{ "hairstyles": [...] }` |
| `/api/change-hair` | POST | 更换发型 | image: 文件<br>hairstyle_id: 字符串 | `{ "result_image": "data:image/jpeg;base64,..." }` |
| `/api/change-hair-color` | POST | 更换头发颜色 | image: 文件<br>rgb: 字符串<br>ratio: 字符串 | `{ "result_image": "data:image/jpeg;base64,..." }` |
| `/hair/api/hairstyles` | GET | 获取发型列表 | 无 | `{ "hairstyles": [...] }` |
| `/hair/api/change-hair` | POST | 更换发型 | image: 文件<br>hairstyle_id: 字符串 | `{ "result_image": "data:image/jpeg;base64,..." }` |
| `/hair/api/change-hair-color` | POST | 更换头发颜色 | image: 文件<br>rgb: 字符串<br>ratio: 字符串 | `{ "result_image": "data:image/jpeg;base64,..." }` |
## 4. 详细接口说明
### 4.1 获取发型列表
#### 4.1.1 请求信息
- **路径**: `/api/hairstyles`
- **路径**: `/hair/api/hairstyles`
- **方法**: GET
- **参数**: 无
- **示例**: `GET https://meida.xiangsilian.com/hair/api/hairstyles`
#### 4.1.2 响应信息
- **状态码**: 200 OK
@@ -68,12 +77,12 @@
{
"id": "1953267161121464322",
"name": "发型4322",
"image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267161121464322.jpg"
"image_url": "/hair/images/hairstyles/1953267161121464322.jpg"
},
{
"id": "1953267288284372994",
"name": "发型2994",
"image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267288284372994.jpg"
"image_url": "/hair/images/hairstyles/1953267288284372994.jpg"
}
]
}
@@ -86,12 +95,14 @@
|-------|------|------|
| `id` | 字符串 | 发型唯一标识符（长数字串，来源于 hairId2url.txt） |
| `name` | 字符串 | 发型名称（格式为 "发型" + ID后4位） |
| `image_url` | 字符串 | 发型图片的阿里云 OSS URL |
| `image_url` | 字符串 | 发型预览图本机相对路径，完整访问为 `https://meida.xiangsilian.com` + `image_url` |
图片文件存放在服务器 `frontend/images/hairstyles/`，分辨率 **634 × 950**（原图 60%），完整链接列表见 [7.3](#73-发型预览图完整链接本机)。
### 4.2 更换发型
#### 4.2.1 请求信息
- **路径**: `/api/change-hair`
- **路径**: `/hair/api/change-hair`
- **方法**: POST
- **Content-Type**: `multipart/form-data`
- **参数**:
@@ -127,7 +138,7 @@
### 4.3 更换头发颜色
#### 4.3.1 请求信息
- **路径**: `/api/change-hair-color`
- **路径**: `/hair/api/change-hair-color`
- **方法**: POST
- **Content-Type**: `multipart/form-data`
- **参数**:
@@ -168,16 +179,16 @@
| 状态码 | 接口 | 描述 | 示例消息 |
|-------|------|------|---------|
| 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` | 处理失败 | "处理图片失败: [错误信息]" |
| 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` | 处理失败 | "处理图片失败: [错误信息]" |
### 5.2 错误响应示例
@@ -206,7 +217,7 @@
{
"id": "1953267161121464322",
"name": "发型4322",
"image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267161121464322.jpg"
"image_url": "/hair/images/hairstyles/1953267161121464322.jpg"
}
```
@@ -259,7 +270,25 @@ FormData:
文件大小限制：16MB
### 7.3 开发工具推荐
### 7.3 接入示例（curl）
```bash
# 发型列表
curl -s https://meida.xiangsilian.com/hair/api/hairstyles
# 更换发型
curl -s -X POST https://meida.xiangsilian.com/hair/api/change-hair \
-F "image=@/path/to/face.jpg" \
-F "hairstyle_id=1953267161121464322"
# 更换发色
curl -s -X POST https://meida.xiangsilian.com/hair/api/change-hair-color \
-F "image=@/path/to/face.jpg" \
-F 'rgb=[255, 106, 0]' \
-F "ratio=0.9"
```
### 7.4 开发工具推荐
- **API测试**: Postman, Insomnia
- **文档生成**: Swagger, ReDoc