> ## 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

> 基于稳定扩散模型，支持数十种不同的发型和颜色，每个生成的结果都是独特的。可以同时生成多达四张结果图片，方便比较和选择最合适的发型。

export const baseUrl = 'https://api.aihairstyle.cn';

## 请求

* **URL**: {baseUrl}/portrait/effects/hairstyle-editor-pro
* **方法**: `POST`
* **Content-Type**: `multipart/form-data`

<Tip>
  **照片验证指南**

  为了确保用户上传的照片符合发型处理 API 的要求，我们建议将工作流分为两个阶段：**人脸分析**和**发型处理**。这种方法通过在前端验证图像来最大程度地减少错误等待时间，确保它们在进行发型处理之前符合 API 标准。这可以增强整体用户体验。

  有关详细信息，请参阅[照片验证指南](/essentials/photo-validation-guide)。

  如果您需要参考图发型迁移或参考图发色，请使用[发型设计专业版 API](/api-reference/hairstyle-editor-premium)。
</Tip>

### 图片要求

* **图片格式**: `PNG` `JPG` `JPEG`
* **图片大小**: 不超过3MB。
* **图片分辨率**: 大于200x200px，小于1999x1999px。
* **最小面部比例**: 为确保效果，图像中面部的比例不能小于20%。
* **面部完整性**: 为确保效果，图像中的面部理想情况下不应被遮挡。
* **面部角度**: 为确保效果，图像中的面部理想情况下应为正面，向左或向右旋转不超过45度。

<table border="2" style={{'border-collapse': 'collapse', 'text-align': 'center'}}>
  <tr>
    <th style={{'text-align':'center'}}>有效性</th>
    <th style={{'text-align':'center'}}>示例图片</th>
    <th style={{'text-align':'center'}}>无效原因</th>
  </tr>

  <tr>
    <td style={{'text-align':'center'}}>✅</td>

    <td>
      <div style={{'display':'flex','flex-wrap':'wrap','justify-content':'space-around'}}>
        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/valid-2.webp" />
        </div>

        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/valid-3.webp" />
        </div>
      </div>
    </td>

    <td style={{'text-align':'center'}}>有效</td>
  </tr>

  <tr>
    <td style={{'text-align':'center'}} rowspan="5">❌</td>

    <td>
      <div style={{'display':'flex','flex-wrap':'wrap','justify-content':'space-around'}}>
        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/no-face-1.webp" />
        </div>

        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/no-face-2.webp" />
        </div>
      </div>
    </td>

    <td style={{'text-align':'center'}}>不包含人脸</td>
  </tr>

  <tr>
    <td>
      <div style={{'display':'flex','flex-wrap':'wrap','justify-content':'space-around'}}>
        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/face-incomplete-1.webp" />
        </div>

        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/face-incomplete-2.webp" />
        </div>
      </div>
    </td>

    <td style={{'text-align':'center'}}>面部不完整</td>
  </tr>

  <tr>
    <td>
      <div style={{'display':'flex','flex-wrap':'wrap','justify-content':'space-around'}}>
        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/face-blocked-1.webp" />
        </div>

        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/face-blocked-2.webp" />
        </div>
      </div>
    </td>

    <td style={{'text-align':'center'}}>面部被遮挡</td>
  </tr>

  <tr>
    <td>
      <div style={{'display':'flex','flex-wrap':'wrap','justify-content':'space-around'}}>
        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/face-small-1.webp" />
        </div>

        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/face-small-2.webp" />
        </div>
      </div>
    </td>

    <td style={{'text-align':'center'}}>面部比例过小</td>
  </tr>

  <tr>
    <td>
      <div style={{'display':'flex','flex-wrap':'wrap','justify-content':'space-around'}}>
        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/face-big-1.webp" />
        </div>

        <div style={{'max-width':'100px','margin':'5px'}}>
          <img alt="Hairstyle Changer Pro" src="https://ai-resource.ailabtools.com/hairstyle-changer-pro/valid-invalid-examples/face-big-2.webp" />
        </div>
      </div>
    </td>

    <td style={{'text-align':'center'}}>面部比例过大</td>
  </tr>
</table>

### 请求头

| 字段                 | 必填 | 类型       | 描述                                               |
| :----------------- | :- | :------- | :----------------------------------------------- |
| `ailabapi-api-key` | 是  | `string` | 应用 API KEY。 [获取 API KEY](/common/authentication) |

### 请求体参数

#### 固定字段

| 字段           | 必填 | 类型        | 选项                 | 默认  | 描述                   |
| :----------- | :- | :-------- | :----------------- | :-- | :------------------- |
| `task_type`  | 是  | `string`  | `async`            | -   | 任务类型。 `async`: 异步任务。 |
| `auto`       | 是  | `integer` | `1`                | `1` | 模式。 `1`: 自动模式。       |
| `image`      | 是  | `file`    | -                  | -   | 主图片。                 |
| `hair_style` | 是  | `string`  | [查看选项](#发型选项)      | -   | 发型选择。                |
| `color`      | 否  | `string`  | [查看选项](#发色)        | -   | 发色选择。                |
| `image_size` | 否  | `integer` | `1`, `2`, `3`, `4` | `1` | 返回图片数量。              |

#### 发型选项

<Tabs>
  <Tab title="男性发型">
    | 值                     | 描述     |
    | :-------------------- | :----- |
    | TinfoilPerm           | 锡纸烫    |
    | Chestnut              | 栗子头    |
    | ChoppyBangs           | 碎盖刘海   |
    | SlickBack             | 背头     |
    | BuzzCut               | 寸头     |
    | CurlyShag             | 凌乱卷发   |
    | UnderCut              | 削边     |
    | WavyShag              | 波浪卷发   |
    | LowFade               | 低切     |
    | ManGreased            | 男士油头   |
    | FauxHawk              | 伪莫霍克发型 |
    | HighTightFade         | 高渐变发型  |
    | Comma\_Hair           | 蓬松分头   |
    | Korean\_Wavy\_Crop    | 韩式波浪分  |
    | Smooth\_Crop          | 齐刘海    |
    | Natural\_Middle\_Part | 自然中分   |
    | Side-Part\_Crop       | 商务侧分   |
    | FreshSide-Parted      | 清新侧分   |
    | FluffyMiddlePart      | 蓬松中分   |
    | Natural\_Side-Part    | 自然微分   |
    | Wolf\_Crop            | 美式前刺   |
    | Wind-Tousled\_Crop    | 明星三七分  |
    | Side-Parted\_Textured | 韩式碎盖   |
    | WavyMiddlePart        | 烫发中分   |
  </Tab>

  <Tab title="女性发型">
    | 值                          | 描述        |
    | :------------------------- | :-------- |
    | ShortCurlyPixie            | 短卷精灵头     |
    | JapaneseShort              | 日系短发      |
    | MediumLongLayered          | 中长层次发     |
    | ShortNeatBob               | 干练短鲍勃头    |
    | DoubleBun                  | 双丸子头      |
    | PixieCut                   | 精灵短发      |
    | LongHimeCut                | 长公主切      |
    | BobCut                     | 波波头       |
    | CurlyBob                   | 卷发波波头     |
    | LongCurly                  | 长卷发       |
    | LongWavy                   | 长波浪卷      |
    | FishtailBraid              | 鱼尾辫       |
    | ShortPixieWithShavedSides  | 短精灵剃边     |
    | Updo                       | 盘发        |
    | BluntBowlCut               | 碗头        |
    | Chignon                    | 发簪        |
    | SlickedBack                | 长背头       |
    | StackedCurlsInShortBob     | 叠层卷波波     |
    | WavyFrenchBobVibesfrom1920 | 复古波波      |
    | ShortTwintails             | 短双马尾      |
    | LongStraight               | 长直发       |
    | TwinBraids                 | 双鱼尾       |
    | Ponytail                   | 高马尾       |
    | LongTwintails              | 长双马尾      |
    | BoxBraids                  | 盒子辫       |
    | FrenchBangs                | 法式刘海      |
    | ShoulderLengthHair         | 齐肩发       |
    | Side-Parted\_Waves         | 三七分卷发(女)  |
    | Magic\_Perm                | 魔术烫发(女)   |
    | Vintage\_Curls             | 复古齐耳卷发(女) |
    | Mushroom\_Curl             | 短碎蘑菇卷发(女) |
    | Textured\_Crop             | 短碎发(女)    |
    | Side\_Flip\_Perm           | 单边反翘烫发(女) |
    | Layered\_Waves             | 波浪卷发 (女)  |
  </Tab>

  <Tab title="发色">
    | 值                | 描述   |
    | :--------------- | :--- |
    | `blonde`         | 金发   |
    | `platinumBlonde` | 白金金发 |
    | `brown`          | 棕发   |
    | `lightBrown`     | 浅棕发  |
    | `blue`           | 蓝发   |
    | `lightBlue`      | 浅蓝发  |
    | `purple`         | 紫发   |
    | `lightPurple`    | 浅紫发  |
    | `pink`           | 粉发   |
    | `black`          | 黑发   |
    | `white`          | 白发   |
    | `grey`           | 灰发   |
    | `silver`         | 银发   |
    | `red`            | 红发   |
    | `orange`         | 橙发   |
    | `green`          | 绿发   |
    | `gradient`       | 渐变发  |
    | `multicolored`   | 彩色发  |
    | `darkBlue`       | 深蓝发  |
    | `burgundy`       | 酒红发  |
    | `darkGreen`      | 深绿发  |
  </Tab>
</Tabs>

## 响应

<Warning>
  **响应字段处理流程**

  1. **处理公共响应字段**
     解析并验证公共响应字段，检查状态码或响应消息以确保请求成功且无错误。

  2. **处理业务响应字段**
     如果公共响应字段有效且无错误，则继续处理业务响应字段中的业务逻辑。
</Warning>

### 公共响应字段

[查看公共响应字段和错误代码](/essentials/response-description)

### 业务响应字段

| 字段          | 类型       | 选项      | 描述                                                                 |
| :---------- | :------- | :------ | :----------------------------------------------------------------- |
| `task_type` | `string` | `async` | 任务类型。 `async`: 异步任务。                                               |
| `task_id`   | `string` | -       | 异步任务ID。调用[查询异步任务结果](/api-reference/async-task-results) API 时使用此字段。 |

### 响应示例

```json theme={null}
{
  "request_id": "",
  "log_id": "",
  "error_code": 0,
  "error_msg": "",
  "error_detail": {
    "status_code": 200,
    "code": "",
    "code_message": "",
    "message": ""
  },
  "task_type": "",
  "task_id": ""
}
```


## OpenAPI

````yaml POST /portrait/effects/hairstyle-editor-pro
openapi: 3.0.0
info:
  title: AI发型设计 API
  description: AI发型设计 提供简单灵活的 API 端点，满足您的 AI 需求
  version: 1.0.0
  contact:
    name: AI发型设计 Support
servers:
  - url: https://api.aihairstyle.cn
    description: Production server
security: []
paths:
  /portrait/effects/hairstyle-editor-pro:
    post:
      tags:
        - AI Portrait
      summary: Hairstyle Editor Pro
      description: 基于稳定扩散模型的发型编辑API，支持多种发型和颜色选择
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/HairstyleEditorProForm'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HairstyleEditorProResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
      security:
        - apiKeyAuth: []
components:
  schemas:
    HairstyleEditorProForm:
      type: object
      required:
        - image
        - hair_style
        - color
        - image_size
        - task_type
      properties:
        image:
          type: string
          format: binary
          description: >-
            Image file for hairstyle editing (PNG/JPG/JPEG). ≤3MB,
            200x200~1999x1999.
        hair_style:
          type: string
          description: Hairstyle code
          enum:
            - TinfoilPerm
            - Chestnut
            - ChoppyBangs
            - SlickBack
            - BuzzCut
            - CurlyShag
            - UnderCut
            - WavyShag
            - LowFade
            - ManGreased
            - FauxHawk
            - HighTightFade
            - Comma_Hair
            - Korean_Wavy_Crop
            - Smooth_Crop
            - Natural_Middle_Part
            - Side-Part_Crop
            - FreshSide-Parted
            - FluffyMiddlePart
            - Natural_Side-Part
            - Wolf_Crop
            - Wind-Tousled_Crop
            - Side-Parted_Textured
            - WavyMiddlePart
            - ShortCurlyPixie
            - JapaneseShort
            - MediumLongLayered
            - ShortNeatBob
            - DoubleBun
            - PixieCut
            - LongHimeCut
            - BobCut
            - CurlyBob
            - LongCurly
            - LongWavy
            - FishtailBraid
            - ShortPixieWithShavedSides
            - Updo
            - BluntBowlCut
            - Chignon
            - SlickedBack
            - StackedCurlsInShortBob
            - WavyFrenchBobVibesfrom1920
            - ShortTwintails
            - LongStraight
            - TwinBraids
            - Ponytail
            - LongTwintails
            - BoxBraids
            - FrenchBangs
            - ShoulderLengthHair
            - Side-Parted_Waves
            - Magic_Perm
            - Vintage_Curls
            - Mushroom_Curl
            - Textured_Crop
            - Side_Flip_Perm
            - Layered_Waves
        color:
          type: string
          description: Color (optional).
          enum:
            - blonde
            - platinumBlonde
            - brown
            - lightBrown
            - blue
            - lightBlue
            - purple
            - lightPurple
            - pink
            - black
            - white
            - grey
            - silver
            - red
            - orange
            - green
            - gradient
            - multicolored
            - darkBlue
            - burgundy
            - darkGreen
        image_size:
          type: integer
          nullable: true
          enum:
            - 1
            - 2
            - 3
            - 4
          description: Returns the number of images. Default 1.
        task_type:
          type: string
          enum:
            - async
          description: 'Task Type. async: Asynchronous task.'
          default: async
    HairstyleEditorProResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessResponse'
        - type: object
          properties:
            task_id:
              type: string
              description: Task ID for async processing
            result:
              type: array
              items:
                type: string
                description: Result image URL
              description: Array of result image URLs
    SuccessResponse:
      type: object
      properties:
        request_id:
          type: string
          description: Request ID
        log_id:
          type: string
          description: Log ID
        error_code:
          type: integer
          description: Status code (0 for success)
        error_msg:
          type: string
          description: Error message
        error_detail:
          type: object
          properties:
            status_code:
              type: integer
              description: HTTP status code
            code:
              type: string
              description: Error code
            code_message:
              type: string
              description: Error code description
            message:
              type: string
              description: Detailed error message
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: ailabapi-api-key
      description: API Key for authentication

````