> ## 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 能够正常处理您的图片，请确保上传的图片符合以下要求。

## 📎 基本要求

| 项目       | 要求                     | 推荐        |
| -------- | ---------------------- | --------- |
| **文件格式** | PNG、JPG、JPEG           | JPG（文件较小） |
| **文件大小** | 最大3MB                  | 1MB以下     |
| **分辨率**  | 200x200 \~ 1999x1999px | 512x512px |

## 👤 人脸要求

<Columns cols={2}>
  <Card title="人脸完整性">
    <div>
      <ul>
        <li>图片中必须包含清晰的人脸</li>
        <li>人脸不应被遮挡（如口罩、墨镜等）</li>
        <li>人脸不应被裁剪或模糊</li>
      </ul>
    </div>
  </Card>

  <Card title="人脸占比 & 角度">
    <div>
      <table>
        <tr><td><strong>占比范围</strong></td><td>20% \~ 80%</td></tr>
        <tr><td><strong>偏航角</strong></td><td>±45°</td></tr>
        <tr><td><strong>俯仰角</strong></td><td>±30°</td></tr>
      </table>
    </div>
  </Card>
</Columns>

## 🌅 图片质量要求

<Columns cols={2}>
  <Card title="☀️ 光线条件">
    <div>
      <ul>
        <li>光线充足，避免过暗或过亮</li>
        <li>避免强烈的逆光或阴影</li>
        <li>确保人脸清晰可见</li>
      </ul>
    </div>
  </Card>

  <Card title="🌆 背景要求">
    <div>
      <ul>
        <li>背景简洁，避免复杂图案</li>
        <li>避免与肤色相近的背景色</li>
        <li>确保人脸与背景有足够对比度</li>
      </ul>
    </div>
  </Card>
</Columns>

## 🖼️ 示例图片

<div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '30px'}}>
  <div>
    <h3 style={{color: '#22c55e'}}>✅ 有效图片示例</h3>

    <div style={{display: 'grid', gap: '15px'}}>
      <div style={{border: '2px solid #22c55e', borderRadius: '8px', padding: '10px', textAlign: 'center'}}>
        <img src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/valid-1.webp" alt="有效图片1" style={{width: '100px', height: '100px', objectFit: 'cover', borderRadius: '4px'}} />

        <p style={{margin: '8px 0 0 0', fontSize: '14px'}}>清晰人脸，角度合适，光线充足</p>
      </div>

      <div style={{border: '2px solid #22c55e', borderRadius: '8px', padding: '10px', textAlign: 'center'}}>
        <img src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/valid-2.webp" alt="有效图片2" style={{width: '100px', height: '100px', objectFit: 'cover', borderRadius: '4px'}} />

        <p style={{margin: '8px 0 0 0', fontSize: '14px'}}>人脸占比适中，背景简洁</p>
      </div>
    </div>
  </div>

  <div>
    <h3 style={{color: '#ef4444'}}>❌ 无效图片示例</h3>

    <div style={{display: 'grid', gap: '15px'}}>
      <div style={{border: '2px solid #ef4444', borderRadius: '8px', padding: '10px', textAlign: 'center'}}>
        <img src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/no-face-1.webp" alt="无效图片1" style={{width: '100px', height: '100px', objectFit: 'cover', borderRadius: '4px'}} />

        <p style={{margin: '8px 0 0 0', fontSize: '14px', color: '#ef4444'}}>无人脸或人脸不清晰</p>
      </div>

      <div style={{border: '2px solid #ef4444', borderRadius: '8px', padding: '10px', textAlign: 'center'}}>
        <img src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/face-incomplete-1.webp" alt="无效图片2" style={{width: '100px', height: '100px', objectFit: 'cover', borderRadius: '4px'}} />

        <p style={{margin: '8px 0 0 0', fontSize: '14px', color: '#ef4444'}}>人脸不完整或被遮挡</p>
      </div>

      <div style={{border: '2px solid #ef4444', borderRadius: '8px', padding: '10px', textAlign: 'center'}}>
        <img src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/face-blocked-1.webp" alt="无效图片3" style={{width: '100px', height: '100px', objectFit: 'cover', borderRadius: '4px'}} />

        <p style={{margin: '8px 0 0 0', fontSize: '14px', color: '#ef4444'}}>人脸被遮挡或模糊</p>
      </div>
    </div>
  </div>
</div>

## ⚠️ 常见错误

<Card title="❎ 文件格式错误">
  ```json theme={null}
  {
      "error_code": 422,
      "error_code_str": "UNSUPPORTED_PARAMETER_VALUES",
      "error_detail": {
          "status_code": 422,
          "code": "UNSUPPORTED_PARAMETER_VALUES",
          "code_message": "Invalid parameter values.",
          "message": "Invalid parameter values. - image: Only PNG, JPG, JPEG, BMP are supported."
      },
      "error_msg": "Invalid parameter values. - image: Only PNG, JPG, JPEG, BMP are supported.",
      "log_id": "76947772",
      "request_id": "76947772"
  }
  ```
</Card>

<Card title="🚫 无人脸检测">
  ```json theme={null}
  {
      "error_code": 422,
      "error_code_str": "FILE_CONTENT_NON_COMPLIANCE",
      "error_detail": {
          "code": "ERROR_NO_FACE_IN_FILE",
          "message": "pic not has face",
          "status_code": 422,
          "code_message": "No face detected in the file."
      },
      "error_msg": "File content does not meet requirements. - 222202 - pic not has face",
      "log_id": "76947794",
      "request_id": "3645368010"
  }
  ```
</Card>

<Card title="📦 文件大小超限">
  ```json theme={null}
  {
      "error_code": 413,
      "error_code_str": "FILE_SIZE_EXCEEDS_LIMIT",
      "error_detail": {
          "status_code": 413,
          "code": "FILE_SIZE_EXCEEDS_LIMIT",
          "code_message": "File size exceeds limit.",
          "message": "File size exceeds limit. - image: No larger than 8 M."
      },
      "error_msg": "File size exceeds limit. - image: No larger than 8 M.",
      "log_id": "76947844",
      "request_id": "76947844"
  }
  ```
</Card>

## 💡 最佳实践

<div style={{display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(250px, 1fr))', gap: '15px'}}>
  <div style={{padding: '15px', border: '1px solid #e5e7eb', borderRadius: '8px', backgroundColor: '#f9fafb'}}>
    <h4>🔍 预处理图片</h4>
    <p>在上传前对图片进行适当的裁剪和调整</p>
  </div>

  <div style={{padding: '15px', border: '1px solid #e5e7eb', borderRadius: '8px', backgroundColor: '#f9fafb'}}>
    <h4>✅ 检查质量</h4>
    <p>确保图片清晰，人脸完整可见</p>
  </div>

  <div style={{padding: '15px', border: '1px solid #e5e7eb', borderRadius: '8px', backgroundColor: '#f9fafb'}}>
    <h4>🧪 测试验证</h4>
    <p>使用人脸分析 API 预先验证图片质量</p>
    <a target="_blank" href="https://vision.aliyun.com/experience/detail?spm=a2cvz.27720474.J_9219321920.10.35ae5d53b1RSLb&tagName=facebody&children=DetectFace">阿里云人脸检测</a>
  </div>

  <div style={{padding: '15px', border: '1px solid #e5e7eb', borderRadius: '8px', backgroundColor: '#f9fafb'}}>
    <h4>📦 批量处理</h4>
    <p>对于批量处理，确保所有图片都符合要求</p>
  </div>
</div>

***