> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihairstyle.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 图片验证指南

> 了解如何在前端验证图片，确保符合发型编辑API的要求

# 图片验证指南

为了确保用户上传的图片符合发型编辑 API 的要求，建议将工作流程分为两个阶段：**[人脸分析](https://vision.aliyun.com/experience/detail?spm=a2cvz.27720474.J_9219321920.10.35ae5d53b1RSLb\&tagName=facebody\&children=DetectFace)**和**发型处理**。这种方法通过在前端验证图片来确认其符合 API 标准，然后再进行发型处理，从而最小化错误等待时间，提升整体用户体验。

## 前端验证要求

在调用发型编辑 API 之前，前端应进行以下验证：

1. **图片分辨率和大小**：确保图片符合 API 的分辨率和文件大小要求，以获得最佳处理质量。
2. **人脸检测**：[人脸检测](https://vision.aliyun.com/experience/detail?spm=a2cvz.27720474.J_9219321920.10.35ae5d53b1RSLb\&tagName=facebody\&children=DetectFace)验证人脸的存在、人脸数量、人脸与图片的比例，以及人脸角度是否符合要求标准。

## 具体验证详情

### 1. 人脸和人脸与图片比例验证

* **无人脸或多个人脸**：如果图片中未检测到人脸或检测到多个人脸，前端应返回错误消息，提示用户重新拍摄或上传合适的照片。
* **不符合人脸与图片比例**：如果人脸占图片的比例小于指定百分比（通常为 15%），则在前端裁剪图片以满足要求的人脸与图片比例。

### 2. 验证方法

为了完成上述验证，前端可以使用[人脸检测](https://vision.aliyun.com/experience/detail?spm=a2cvz.27720474.J_9219321920.10.35ae5d53b1RSLb\&tagName=facebody\&children=DetectFace)获取关键人脸数据，用于评估人脸数量、人脸与图片比例和人脸角度。

### 3. 验证标准

* **人脸数量**：
  * `face_num == 0`：未检测到人脸，返回错误。
  * `face_num != 1`：检测到多个人脸，返回错误。

* **人脸与图片比例**：
  * 计算公式：(`location.width` \* `location.height`) / (`image.width` \* `image.height`) > `0.15`
  * 如果比例小于 `0.15`，则不符合要求。使用 `location` 的 `left`、`top`、`width` 和 `height` 值以及整体图片尺寸，确定适当的裁剪区域以调整人脸与图片比例。

* **人脸角度**：
  * 验证标准：如果任何标准不符合，返回错误消息，提示用户重新拍摄或上传照片。
    * `angle.yaw` 的绝对值应小于 `30`
    * `angle.pitch` 的绝对值应小于 `30`
    * `angle.roll` 的绝对值应小于 `30`

## 推荐工作流程

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    async function validateAndProcessImage(imageFile) {
      try {
        // 1. 调用人脸分析 API
        const analysisResult = await analyzeFace(imageFile);
        
        // 2. 验证人脸数量
        if (analysisResult.face_num !== 1) {
          throw new Error('请使用包含且仅包含一个人脸的照片');
        }
        
        // 3. 验证人脸占比
        const faceInfo = analysisResult.face_info[0];
        const faceProportion = faceInfo.face_proportion;
        
        if (faceProportion < 0.2 || faceProportion > 0.8) {
          throw new Error('人脸占比应在20%-80%之间');
        }
        
        // 4. 验证人脸角度
        const { yaw, pitch, roll } = faceInfo.face_angle;
        if (Math.abs(yaw) > 30 || Math.abs(pitch) > 30 || Math.abs(roll) > 30) {
          throw new Error('请使用正面照片，人脸角度不应过大');
        }
        
        // 5. 调用发型编辑 API
        const hairstyleResult = await processHairstyle(imageFile, 'BuzzCut');
        
        return hairstyleResult;
        
      } catch (error) {
        console.error('图片验证失败:', error.message);
        // 显示错误信息给用户
        showErrorToUser(error.message);
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    def validate_and_process_image(image_file, api_key):
        try:
            # 1. 调用人脸分析 API
            analysis_result = analyze_face(image_file, api_key)
            
            # 2. 验证人脸数量
            if analysis_result['result']['face_num'] != 1:
                raise ValueError('请使用包含且仅包含一个人脸的照片')
            
            # 3. 验证人脸占比
            face_info = analysis_result['result']['face_info'][0]
            face_proportion = face_info['face_proportion']
            
            if face_proportion < 0.2 or face_proportion > 0.8:
                raise ValueError('人脸占比应在20%-80%之间')
            
            # 4. 验证人脸角度
            face_angle = face_info['face_angle']
            yaw, pitch, roll = face_angle['yaw'], face_angle['pitch'], face_angle['roll']
            
            if abs(yaw) > 30 or abs(pitch) > 30 or abs(roll) > 30:
                raise ValueError('请使用正面照片，人脸角度不应过大')
            
            # 5. 调用发型编辑 API
            hairstyle_result = process_hairstyle(image_file, 'BuzzCut', api_key)
            
            return hairstyle_result
            
        except Exception as error:
            print(f'图片验证失败: {error}')
            return None
    ```
  </Tab>
</Tabs>

## 最佳实践

### 1. 用户体验优化

* **实时验证**：在用户选择图片后立即进行验证
* **清晰提示**：提供具体的错误信息和改进建议
* **预览功能**：显示裁剪后的图片预览
* **进度指示**：显示验证和处理进度

### 2. 性能优化

* **图片压缩**：在上传前压缩图片以减少传输时间
* **缓存结果**：缓存验证结果避免重复验证

### 3. 错误处理

* **网络错误**：处理网络连接问题
* **API 限制**：处理 API 调用频率限制
* **文件格式**：验证文件格式和大小

## 相关链接

* [发型编辑 API](/api-reference/hairstyle-editor-pro)
* [图片要求](/essentials/image-requirements)
* [错误处理](/essentials/error-handling)