Skip to main content
POST
/
api
/
portrait
/
effects
/
hairstyle-editor-pro
Hairstyle Changer Pro
curl --request POST \
  --url https://www.ailabapi.com/api/portrait/effects/hairstyle-editor-pro \
  --header 'Content-Type: multipart/form-data' \
  --header 'ailabapi-api-key: <api-key>' \
  --form version=V3 \
  --form image='@example-file' \
  --form hair_style=BuzzCut \
  --form color=blonde
{
  "request_id": "",
  "log_id": "",
  "error_detail": {
    "code": "",
    "code_message": "",
    "message": ""
  },
  "task_id": ""
}

Documentation Index

Fetch the complete documentation index at: https://ailabtools.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Photo Validation GuideTo ensure user-uploaded photos meet the Hairstyle Processing API requirements, we recommend splitting the workflow into two stages: Face Analysis and Hairstyle Processing. This approach minimizes error wait times by validating images on the frontend, ensuring they meet API standards before proceeding to hairstyle processing. This enhances overall user experience.For detailed information, refer to the Photo Validation Guide.

​
Query Task

This is an asynchronous task API. The submission request returns only task_id.Use task_id to call Querying Async Task Results and retrieve the final result. Async task results remain available for 24 hours. Query every 5 seconds.
FieldTypeDescription
dataobjectFinal result data.
+imagesarrayResult image URLs.
++images[]stringResult image URL.
{
  "data": {
    "images": []
  }
}
images are temporary and remain valid for 24 hours. If you need long-term storage, download the files to your own storage within that period.

​
Submit Task

​
Input Image Examples

Use a clear portrait with a complete, unobstructed face at an appropriate size. The examples below show valid inputs and common invalid cases.

​
hair_style

The following enum values are supported for hair_style.

​
color

The following enum values are supported for color.

Authorizations

​
ailabapi-api-key
string
header
required

API Key for authentication

Body

multipart/form-data
​
version
enum<string>
required

Version. Note: Only V3 uses the latest logic. All requests will be forced to V3 in the future. Response fields remain backward compatible.

Available options:
V3
​
image
file
required

Source image.

  • Image format: JPEG JPG PNG
  • Image size: No more than 5 MB.
  • Image resolution: Larger than 200x200px, smaller than 4090x4090px.
  • Minimum Face Proportion: To ensure effectiveness, the proportion of the face in the image cannot be less than 10%.
  • Facial Integrity: To ensure effectiveness, the face in the image should ideally not be obscured.
  • Facial Angle: To ensure effectiveness, the face in the image should ideally be front-facing, with no more than a 30-degree rotation to the left or right.
​
hair_style
enum<string>
required

Hairstyle. See Supported hair_style values.

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
Example:

"BuzzCut"

​
color
enum<string>
default:blonde

Hair color preset. See Supported color values.

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

Response

200 - application/json

Success

​
request_id
string
required

Request ID for debugging.

​
log_id
string
required

Log ID for debugging.

​
error_detail
object
required
​
task_id
string
required

Task ID for querying Querying Async Task Results.