Skip to main content
POST
/
portrait
/
effects
/
hairstyle-editor-premium
Hairstyle Editor Premium
curl --request POST \
  --url https://api.aihairstyle.cn/portrait/effects/hairstyle-editor-premium \
  --header 'Content-Type: multipart/form-data' \
  --header 'ailabapi-api-key: <api-key>' \
  --form image='@example-file' \
  --form hair_style=BuzzCut \
  --form image_template='@example-file' \
  --form color=reference
{
  "request_id": "<string>",
  "log_id": "<string>",
  "error_code": 123,
  "error_msg": "<string>",
  "error_detail": {
    "status_code": 123,
    "code": "<string>",
    "code_message": "<string>",
    "message": "<string>"
  },
  "task_id": "<string>"
}

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.

​
请求

  • URL: /portrait/effects/hairstyle-editor-premium
  • 方法: POST
  • Content-Type: multipart/form-data
专业版是异步接口。提交任务后请保存响应中的 task_id，再调用异步任务查询 API 获取最终图片结果。

​
图片要求

  • 图片格式: 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

​
请求体参数

字段必填类型默认描述
image是file-主图片。用于生成发型效果的人像图片。
hair_style否string-内置发型模板。hair_style 和 image_template 至少传一个。
image_template否file-发型参考图。用于参考图发型迁移。
color否stringreference发色。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锡纸烫

​
发色

值描述
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，传入 task_id。
  4. 当 task_status=2 时，从 result 中读取生成图片 URL。

​
计费

  • 单次费用: ￥0.15/次
  • 计费方式: 异步任务按成功提交次数计费。
  • 查询任务: 查询异步任务结果不重复计费。

​
响应

响应字段处理流程
  1. 处理公共响应字段 解析并验证公共响应字段，检查状态码或响应消息以确保请求成功且无错误。
  2. 处理业务响应字段 如果公共响应字段有效且无错误，则继续处理业务响应字段中的 task_id。

​
公共响应字段

查看公共响应字段和错误代码

​
业务响应字段

字段类型描述
task_idstring异步任务 ID。调用异步任务查询 API 时使用此字段。

​
响应示例

{
  "request_id": "",
  "log_id": "",
  "error_code": 0,
  "error_msg": "",
  "error_detail": {
    "status_code": 200,
    "code": "",
    "code_message": "",
    "message": ""
  },
  "task_id": ""
}

​
相关链接

Authorizations

​
ailabapi-api-key
string
header
required

API Key for authentication

Body

multipart/form-data

Provide hair_style or image_template. If both are provided, hair_style takes precedence.

​
image
file
required

Source image (PNG/JPG/JPEG). ≤5MB, 200x200~4090x4090. Face proportion must be at least 10%.

​
hair_style
enum<string>

Built-in hairstyle preset. Provide this field or image_template. If both are provided, hair_style takes precedence.

Available options:
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
file

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
enum<string>
default:reference

Hair color preset. reference uses the hair color from image_template.

Available options:
reference,
blonde,
platinumBlonde,
brown,
lightBrown,
blue,
lightBlue,
purple,
lightPurple,
pink,
black,
white,
grey,
silver,
red,
orange,
green,
gradient,
multicolored,
darkBlue,
burgundy,
darkGreen

Response

Success

​
request_id
string

Request ID

​
log_id
string

Log ID

​
error_code
integer

Status code (0 for success)

​
error_msg
string

Error message

​
error_detail
object
​
task_id
string

Task ID for querying async task results