AILabTools API - Hairstyle Changer Pro - API:V1.0.0(DEPRECATED)

---

draft: true

Important Announcement: API Version Update Notice

Dear Developers,

We are thrilled to announce that our API is receiving a major update! The new version will introduce a host of improvements and feature enhancements to enhance your development experience and meet your needs.

However, along with the rollout of the new version, we must also inform you that the old version of the API will no longer receive maintenance and support. This means that we will no longer release new features, fix known issues, or provide technical support for the old version of the API.

We strongly encourage you to upgrade to the latest version of the API as soon as possible to ensure that your applications continue to operate smoothly and to take advantage of the latest features and optimizations.

If you have any questions or need assistance regarding this change, please feel free to contact our support team ([email protected]). We are committed to assisting you and ensuring a smooth transition.

Once again, thank you for your support and trust in our API.

Best Regards,

AILabTools Support Team

Request

• URL: https://www.ailabapi.com/api/portrait/effects/hairstyle-editor-pro
• Method: POST
• Content-Type: multipart/form-data

Image requirements

• Image format: PNG JPG JPEG
• Image size: No more than 3 MB.
• Image resolution: Larger than 200x200px, smaller than 2000x2000px.
• Minimum Face Proportion: To ensure effectiveness, the proportion of the face in the image cannot be less than 20%.
• 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 45-degree rotation to the left or right.

Image Validity		Reason for Invalidity
✅
❌		No face
		Incomplete face
		Face obscured
		Face proportion too small
		The face is too large to edit the hairstyle

Header

Field	Required	Type	Description
ailabapi-api-key	YES	string	Application API KEY. Get API KEY

Body

Fixed Fields

Field	Required	Type	Scope	Default	Description
task_type	YES	string	async		Task Type. async: Asynchronous tasks.
image	YES	file			Main image.
hair_style	YES	string	Scope		Hairstyle. More Details
color	NO	string	Scope		Color. More Details
image_size	NO	integer	1 2 3 4	1	Returns the number of images.
mask	NO	file			Masked Image. If left blank, a masked image will be generated automatically. The white portion of the masked image is the editable area, while the black portion remains unchanged. For example, by using the white area of the mask to cover a person's face, the face will remain unaltered, and other parts will be generated automatically.
bangs	NO	integer	0 1	1	Whether to add bangs to the resulting image. This parameter is ineffective when the hairstyle has no bangs or when bangs are mandatory. Parameter Validity Explanation 0: No. 1: Yes. Parameter Effect Comparison
mode	NO	integer	1 2	1	Generation mode. Please enable this parameter based on the original hairstyle. 1: Head-only mode. More suitable for short hair. 2: Full-image generation mode. More suitable for long hair; use this mode when the original image features shoulder-length or longer hair. Parameter Effect Comparison
reference	NO	integer	0 1	0	Reference Original Hairstyle. Enabling this parameter will make changes to the hairstyle based on the original hairstyle, resulting in minor alterations. Please do not enable this parameter if changing from short hair to long hair or from long hair to short hair. 0: No. 1: Yes. Parameter Effect Comparison

hair_style

Category: Gender	Category: Length	hair_style	Description	Validity of the 'bangs' Field
Male	Short	BuzzCut	Buzz Cut hair	Ineffective
		UnderCut	UnderCut hair	Ineffective
		Pompadour	Pompadour hair	Ineffective
		SlickBack	Slick Back hair	Ineffective
		CurlyShag	Curly Shag hair	Effective
		WavyShag	Wavy Shag hair	Effective
		FauxHawk	Faux Hawk hair	Ineffective
		Spiky	Spiky hair	Ineffective
		CombOver	Comb-over hair	Effective
		HighTightFade	High and Tight Fade hair	Ineffective
		ManBun	Man Bun hair	Ineffective
		Afro	Afro hair	Effective
		LowFade	Low Fade hair	Effective
		UndercutLongHair	Undercut With Long Hair	Ineffective
		TwoBlockHaircut	Two Block Haircut	Effective
		TexturedFringe	Textured Fringe Hair	Effective
		BluntBowlCut	Blunt Bowl Cut	Ineffective
	Middle	LongWavyCurtainBangs	Long Wavy Curtain Bangs Hair	Effective
		MessyTousled	Messy Tousled hair	Effective
		MediumLengthWavy	Medium Length Wavy hair	Effective
	Long	CornrowBraids	Cornrow Braids hair	Ineffective
		LongHairTiedUp	Long Hair Tied Up Hair	Ineffective
Female	Short	ShortPixieWithShavedSides	Short Pixie With Shaved Sides	Effective
		ShortNeatBob	short neat bob hair	Effective
		DoubleBun	double bun hair	Effective
		Updo	Updo hair	Effective
		Spiked	spiked hair	Effective
		bowlCut	bowl cut hair	Effective
		Chignon	Chignon hair	Ineffective
		PixieCut	Pixie Cut hair	Effective
		SlickedBack	slicked back hair	Ineffective
	Middle	LongCurly	Long curly hair	Effective
		CurlyBob	Curly bob hair	Effective
		StackedCurlsInShortBob	Stacked Curls in Short Bob hair	Effective
		SidePartCombOverHairstyleWithHighFade	Side Part Comb-Over Hairstyle With High Fade hair	Ineffective
		WavyFrenchBobVibesfrom1920	Wavy French Bob Vibes from 1920	Effective
		BobCut	bob Haircut hair	Ineffective
		ShortTwintails	Short Twintails hair	Effective
		ShortCurlyPixie	Short Curly Pixie	Effective
	Long	LongStraight	Long straight hair	Effective
		LongWavy	Long wavy hair	Effective
		FishtailBraid	Fishtail braid hair	Effective
		TwinBraids	Twin Braids hair	Ineffective
		Ponytail	Ponytail hair	Effective
		Dreadlocks	dreadlocks hair	Ineffective
		Cornrows	Cornrows hair	Ineffective
		ShoulderLengthHair	Shoulder Length Straight Hair	Effective
		LooseCurlyAfro	Loose Curly Afro hair	Effective
		LongTwintails	Long Twintails hair	Ineffective

color

color	Description
blonde	blonde hair
platinumBlonde	platinum blonde hair
brown	brown hair
lightBrown	light brown hair
blue	blue hair
lightBlue	light blue hair
purple	purple hair
lightPurple	light purple hair
pink	pink hair
black	black hair
white	white hair
grey	grey hair
silver	silver hair
red	red hair
orange	orange hair
green	green hair
gradient	gradient hair
multicolored	multicolored hair
darkBlue	dark blue hair
burgundy	burgundy hair
darkGreen	dark green hair

bangs: Parameter Effect Comparison

When the 'bangs' field is valid

Hairstyle	bangs	Original	Result
Short Pixie With Shaved Sides	0
Short Pixie With Shaved Sides	1

When the 'bangs' Field Is Invalid

Hairstyle	bangs	Original	Result
slicked back hair	0
slicked back hair	1

mode: Parameter Effect Comparison

Hairstyle	mode	Original	Result
double bun hair	1
double bun hair	2

reference: Parameter Effect Comparison

Hairstyle	reference	Original	Result
Medium Length Wavy hair	0
Medium Length Wavy hair	1

Response

Processing Flow

1. Handle Public Parameters:

   First, parse and validate the Public Parameters, checking the status code or response message to ensure the request is successful and no errors are present.

2. Handle Business Parameters:

   If the public parameters are valid and no exceptions are found, proceed to process the business logic in the Business Parameters.

Public Parameters

Viewing Public Parameters and Error Codes

Business Parameters

Field	Type	Scope	Description
task_type	string	async	Task Type. async: Asynchronous tasks.
task_id	string		Asynchronous task ID. Please use this field when calling the Querying Async Task Results API.

Example

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

tip

This API is asynchronous, please keep task_id and call Querying Async Task Results to get the final results.

Asynchronous task results are valid for 24 hours. It is recommended that asynchronous task results be queried every 5 seconds.

Querying Async Task Results Response

Processing Flow

1. Handle Public Parameters:

   First, parse and validate the Public Parameters, checking the status code or response message to ensure the request is successful and no errors are present.

2. Handle Business Parameters:

   If the public parameters are valid and no exceptions are found, proceed to process the business logic in the Business Parameters.

Public Parameters

Viewing Public Parameters and Error Codes

Business Parameters

Field	Type	Scope	Description
task_status	integer	0 1 2	Asynchronous task status. 0: The task is queued. 1: Asynchronous processing. 2: Processing was successful.
data	object		The content of the result data returned.
+images	array		Array of resultant image addresses.

tip

The URL address is a temporary address, valid for 24 hours, and will not be accessible after it expires. If you need to save the file for a long time or permanently, please visit the URL address within 24 hours and download the file to your own storage space.

Example

{
  "error_code":     0,
  "error_code_str": "",
  "error_msg":      "",
  "error_detail":   {
    "status_code":  200,
    "code":         "",
    "code_message": "",
    "message":      ""
  },
  "task_status":    0,
  "data":           {
    "images": [
      "Image URL",
      "Image URL"
    ]
  }
}

Code example

👉 Online Experience 👈

If you'd like to see the actual effects, please visit the experience page for a trial.

• Introduction
• Code example