> ## 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-premium
* **方法**: `POST`
* **Content-Type**: `multipart/form-data`
专业版是异步接口。提交任务后请保存响应中的 `task_id`，再调用[异步任务查询 API](/api-reference/async-task-results) 获取最终图片结果。
### 图片要求
* **图片格式**: `PNG` `JPG` `JPEG`
* **图片大小**: 不超过 5MB。
* **图片分辨率**: 大于 200x200px，小于 4090x4090px。
* **最小面部比例**: 为确保效果，图像中面部的比例不能小于 10%。
* **面部完整性**: 建议使用面部无遮挡、五官清晰的照片。
* **面部角度**: 建议使用正面或接近正面的照片。
当同时传入 `hair_style` 和 `image_template` 时，系统优先使用 `hair_style`，并忽略 `image_template`。如果需要参考图发型迁移，请不要传 `hair_style`。
### 请求头
| 字段 | 必填 | 类型 | 描述 |
| :----------------- | :- | :------- | :----------------------------------------------- |
| `ailabapi-api-key` | 是 | `string` | 应用 API KEY。 [获取 API KEY](/common/authentication) |
### 请求体参数
| 字段 | 必填 | 类型 | 默认 | 描述 |
| :--------------- | :- | :------- | :---------- | :-------------------------------------------- |
| `image` | 是 | `file` | - | 主图片。用于生成发型效果的人像图片。 |
| `hair_style` | 否 | `string` | - | 内置发型模板。`hair_style` 和 `image_template` 至少传一个。 |
| `image_template` | 否 | `file` | - | 发型参考图。用于参考图发型迁移。 |
| `color` | 否 | `string` | `reference` | 发色。`reference` 表示使用参考图发色，也可以传入预设发色。 |
### 发型来源
| 模式 | 参数组合 | 说明 |
| --------- | ---------------------------------------------- | ---------------- |
| 预设发型 | `image` + `hair_style` | 使用内置发型模板生成结果。 |
| 参考图发型 | `image` + `image_template` | 将参考图中的发型迁移到主图人物。 |
| 参考图发型和发色 | `image` + `image_template` + `color=reference` | 同时参考发型和发色。 |
| 预设发型和预设发色 | `image` + `hair_style` + 预设 `color` | 使用指定发型和指定发色。 |
## 参数选项
### 发型选项
专业版支持传统发型值和编号发型值。OpenAPI 的 Try It 面板中已包含完整枚举。
| 值 | 描述 |
| :-------------------- | :----- |
| `BuzzCut` | 寸头 |
| `UnderCut` | 削边 |
| `Pompadour` | 蓬巴杜 |
| `SlickBack` | 背头 |
| `CurlyShag` | 凌乱卷发 |
| `WavyShag` | 波浪卷发 |
| `FauxHawk` | 伪莫霍克发型 |
| `HighTightFade` | 高渐变发型 |
| `LowFade` | 低渐变 |
| `ManBun` | 男士发髻 |
| `Afro` | 非洲卷 |
| `TwoBlockHaircut` | 韩式两层剪 |
| `TexturedFringe` | 纹理刘海 |
| `Comma_Hair` | 逗号刘海 |
| `Korean_Wavy_Crop` | 韩式波浪短发 |
| `Natural_Middle_Part` | 自然中分 |
| `Side-Part_Crop` | 商务侧分 |
| `FluffyMiddlePart` | 蓬松中分 |
| `Wolf_Crop` | 狼尾短发 |
| `TinfoilPerm` | 锡纸烫 |
| 值 | 描述 |
| :-------------------------- | :---- |
| `ShortPixieWithShavedSides` | 短精灵剃边 |
| `ShortNeatBob` | 干练短波波 |
| `DoubleBun` | 双丸子头 |
| `Updo` | 盘发 |
| `Chignon` | 发髻 |
| `PixieCut` | 精灵短发 |
| `LongCurly` | 长卷发 |
| `CurlyBob` | 卷发波波头 |
| `BobCut` | 波波头 |
| `ShortTwintails` | 短双马尾 |
| `LongStraight` | 长直发 |
| `LongWavy` | 长波浪卷 |
| `FishtailBraid` | 鱼尾辫 |
| `Ponytail` | 马尾 |
| `ShoulderLengthHair` | 齐肩发 |
| `LongHimeCut` | 长公主切 |
| `Layered_Waves` | 层次波浪 |
| `FrenchBangs` | 法式刘海 |
| `JapaneseShort` | 日系短发 |
| `MediumLongLayered` | 中长层次发 |
| 值 | 描述 |
| :------------------------------------------------ | :----- |
| `male_hairstyle_0001` - `male_hairstyle_0062` | 男士编号发型 |
| `female_hairstyle_0001` - `female_hairstyle_0073` | 女士编号发型 |
### 发色
| 值 | 描述 |
| :--------------- | :------ |
| `reference` | 使用参考图发色 |
| `blonde` | 金发 |
| `platinumBlonde` | 白金金发 |
| `brown` | 棕发 |
| `lightBrown` | 浅棕发 |
| `blue` | 蓝发 |
| `lightBlue` | 浅蓝发 |
| `purple` | 紫发 |
| `lightPurple` | 浅紫发 |
| `pink` | 粉发 |
| `black` | 黑发 |
| `white` | 白发 |
| `grey` | 灰发 |
| `silver` | 银发 |
| `red` | 红发 |
| `orange` | 橙发 |
| `green` | 绿发 |
| `gradient` | 渐变发 |
| `multicolored` | 彩色发 |
| `darkBlue` | 深蓝发 |
| `burgundy` | 酒红发 |
| `darkGreen` | 深绿发 |
## 异步处理流程
1. 调用本接口提交任务。
2. 从响应中读取 `task_id`。
3. 调用[异步任务查询 API](/api-reference/async-task-results)，传入 `task_id`。
4. 当 `task_status=2` 时，从 `result` 中读取生成图片 URL。
## 计费
* **单次费用**: `￥0.15/次`
* **计费方式**: 异步任务按成功提交次数计费。
* **查询任务**: 查询异步任务结果不重复计费。
## 响应
**响应字段处理流程**
1. **处理公共响应字段**
解析并验证公共响应字段，检查状态码或响应消息以确保请求成功且无错误。
2. **处理业务响应字段**
如果公共响应字段有效且无错误，则继续处理业务响应字段中的 `task_id`。
### 公共响应字段
[查看公共响应字段和错误代码](/essentials/response-description)
### 业务响应字段
| 字段 | 类型 | 描述 |
| :-------- | :------- | :---------------------------------------------------------------- |
| `task_id` | `string` | 异步任务 ID。调用[异步任务查询 API](/api-reference/async-task-results) 时使用此字段。 |
### 响应示例
```json theme={null}
{
"request_id": "",
"log_id": "",
"error_code": 0,
"error_msg": "",
"error_detail": {
"status_code": 200,
"code": "",
"code_message": "",
"message": ""
},
"task_id": ""
}
```
## 相关链接
* [发型设计专业版介绍](/hairstyle-editor-premium/introduction)
* [异步任务查询 API](/api-reference/async-task-results)
* [图片验证指南](/essentials/photo-validation-guide)
* [错误处理](/essentials/error-handling)
## OpenAPI
````yaml POST /portrait/effects/hairstyle-editor-premium
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-premium:
post:
tags:
- AI Portrait
summary: Hairstyle Editor Premium
description: 支持预设发型和参考图发型迁移的发型设计专业版 API
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/HairstyleEditorPremiumForm'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/HairstyleEditorPremiumResponse'
'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:
HairstyleEditorPremiumForm:
type: object
required:
- image
description: >-
Provide hair_style or image_template. If both are provided, hair_style
takes precedence.
properties:
image:
type: string
format: binary
description: >-
Source image (PNG/JPG/JPEG). ≤5MB, 200x200~4090x4090. Face
proportion must be at least 10%.
hair_style:
type: string
description: >-
Built-in hairstyle preset. Provide this field or image_template. If
both are provided, hair_style takes precedence.
enum:
- BuzzCut
- UnderCut
- Pompadour
- SlickBack
- CurlyShag
- WavyShag
- FauxHawk
- Spiky
- CombOver
- HighTightFade
- ManBun
- Afro
- LowFade
- UndercutLongHair
- TwoBlockHaircut
- TexturedFringe
- BluntBowlCut
- LongWavyCurtainBangs
- MessyTousled
- CornrowBraids
- LongHairTiedUp
- Middle-parted
- ManGreased
- WavyMiddlePart
- Natural_Side-Part
- Wolf_Crop
- Wind-Tousled_Crop
- Side-Parted_Textured
- FluffyMiddlePart
- FreshSide-Parted
- Smooth_Crop
- Korean_Wavy_Crop
- Comma_Hair
- Side-Part_Crop
- Natural_Middle_Part
- ShortPixieWithShavedSides
- ShortNeatBob
- DoubleBun
- Updo
- Spiked
- bowlCut
- Chignon
- PixieCut
- SlickedBack
- LongCurly
- CurlyBob
- StackedCurlsInShortBob
- SidePartCombOverHairstyleWithHighFade
- WavyFrenchBobVibesfrom1920
- BobCut
- ShortTwintails
- ShortCurlyPixie
- LongStraight
- LongWavy
- FishtailBraid
- TwinBraids
- Ponytail
- Dreadlocks
- Cornrows
- ShoulderLengthHair
- LooseCurlyAfro
- LongTwintails
- LongHimeCut
- BoxBraids
- Layered_Waves
- Side_Flip_Perm
- Textured_Crop
- Mushroom_Curl
- Vintage_Curls
- Magic_Perm
- Side-Parted_Waves
- Fluffy_Short
- Smooth_Inward_Bob
- Neat_Short
- Natural_Short
- Chic_Tapered_Bob
- Edgy_Textured_Pixie
- Elegant_Wavy_Crop
- Chic_Wavy_Pixie
- Elegant_Side_Wave
- Soft_Layered_Curl
- Executive_Pixie
- Curved_Chic_Bob
- Airy_Short_Curls
- Playful_Curly_Bob
- Playful_Wavy_Bob
- Elegant_Soft_Curl
- Elegant_Smooth_Bob
- Retro_Airy_Curl
- Soft_Wavy_Bob
- Light_Inward_Bob
- Neat_Curly_Crop_Cut
- Elegant_Volumized_Bob
- Modern_Curls_Chic
- Mocha_Volume_Pixie
- Elegant_Side_Flow
- Chestnut
- ChoppyBangs
- StructuredWavyShag
- TinfoilPerm
- ClassicWavyBob
- Fluffy_Pixie_Cut
- FrenchBangs
- JapaneseShort
- MediumLongLayered
- male_hairstyle_0001
- male_hairstyle_0002
- male_hairstyle_0003
- male_hairstyle_0004
- male_hairstyle_0005
- male_hairstyle_0006
- male_hairstyle_0007
- male_hairstyle_0008
- male_hairstyle_0009
- male_hairstyle_0010
- male_hairstyle_0011
- male_hairstyle_0012
- male_hairstyle_0013
- male_hairstyle_0014
- male_hairstyle_0015
- male_hairstyle_0016
- male_hairstyle_0017
- male_hairstyle_0018
- male_hairstyle_0019
- male_hairstyle_0020
- male_hairstyle_0021
- male_hairstyle_0022
- male_hairstyle_0023
- male_hairstyle_0024
- male_hairstyle_0025
- male_hairstyle_0026
- male_hairstyle_0027
- male_hairstyle_0028
- male_hairstyle_0029
- male_hairstyle_0030
- male_hairstyle_0031
- male_hairstyle_0032
- male_hairstyle_0033
- male_hairstyle_0034
- male_hairstyle_0035
- male_hairstyle_0036
- male_hairstyle_0037
- male_hairstyle_0038
- male_hairstyle_0039
- male_hairstyle_0040
- male_hairstyle_0041
- male_hairstyle_0042
- male_hairstyle_0043
- male_hairstyle_0044
- male_hairstyle_0045
- male_hairstyle_0046
- male_hairstyle_0047
- male_hairstyle_0048
- male_hairstyle_0049
- male_hairstyle_0050
- male_hairstyle_0051
- male_hairstyle_0052
- male_hairstyle_0053
- male_hairstyle_0054
- male_hairstyle_0055
- male_hairstyle_0056
- male_hairstyle_0057
- male_hairstyle_0058
- male_hairstyle_0059
- male_hairstyle_0060
- male_hairstyle_0061
- male_hairstyle_0062
- female_hairstyle_0001
- female_hairstyle_0002
- female_hairstyle_0003
- female_hairstyle_0004
- female_hairstyle_0005
- female_hairstyle_0006
- female_hairstyle_0007
- female_hairstyle_0008
- female_hairstyle_0009
- female_hairstyle_0010
- female_hairstyle_0011
- female_hairstyle_0012
- female_hairstyle_0013
- female_hairstyle_0014
- female_hairstyle_0015
- female_hairstyle_0016
- female_hairstyle_0017
- female_hairstyle_0018
- female_hairstyle_0019
- female_hairstyle_0020
- female_hairstyle_0021
- female_hairstyle_0022
- female_hairstyle_0023
- female_hairstyle_0024
- female_hairstyle_0025
- female_hairstyle_0026
- female_hairstyle_0027
- female_hairstyle_0028
- female_hairstyle_0029
- female_hairstyle_0030
- female_hairstyle_0031
- female_hairstyle_0032
- female_hairstyle_0033
- female_hairstyle_0034
- female_hairstyle_0035
- female_hairstyle_0036
- female_hairstyle_0037
- female_hairstyle_0038
- female_hairstyle_0039
- female_hairstyle_0040
- female_hairstyle_0041
- female_hairstyle_0042
- female_hairstyle_0043
- female_hairstyle_0044
- female_hairstyle_0045
- female_hairstyle_0046
- female_hairstyle_0047
- female_hairstyle_0048
- female_hairstyle_0049
- female_hairstyle_0050
- female_hairstyle_0051
- female_hairstyle_0052
- female_hairstyle_0053
- female_hairstyle_0054
- female_hairstyle_0055
- female_hairstyle_0056
- female_hairstyle_0057
- female_hairstyle_0058
- female_hairstyle_0059
- female_hairstyle_0060
- female_hairstyle_0061
- female_hairstyle_0062
- female_hairstyle_0063
- female_hairstyle_0064
- female_hairstyle_0065
- female_hairstyle_0066
- female_hairstyle_0067
- female_hairstyle_0068
- female_hairstyle_0069
- female_hairstyle_0070
- female_hairstyle_0071
- female_hairstyle_0072
- female_hairstyle_0073
image_template:
type: string
format: binary
description: >-
Reference image for hairstyle transfer. Provide this field or
hair_style. If both are provided, image_template is ignored.
PNG/JPG/JPEG, ≤5MB, 200x200~4090x4090.
color:
type: string
description: >-
Hair color preset. reference uses the hair color from
image_template.
default: reference
enum:
- reference
- blonde
- platinumBlonde
- brown
- lightBrown
- blue
- lightBlue
- purple
- lightPurple
- pink
- black
- white
- grey
- silver
- red
- orange
- green
- gradient
- multicolored
- darkBlue
- burgundy
- darkGreen
HairstyleEditorPremiumResponse:
allOf:
- $ref: '#/components/schemas/SuccessResponse'
- type: object
properties:
task_id:
type: string
description: Task ID for querying async task results
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
````