Name: Flux Kontext – AI Hair Style Changer | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-flux-ai-hair-style-color-changer
Availability: InStock
Author: API Market

Shashank Agarwal

# 💇‍♂️ Instant AI Hair Style & Color Changer API (Flux Kontext)

## Overview
The Instant AI Hair Style & Color Changer API transforms any portrait by altering the hairstyle and hair color, giving you ultra-fast, realistic renderings. Whether you need virtual try-ons for e-commerce, creative edits for social media, or any other hair-focused transformations, this AI service delivers pro-quality outputs in seconds.

Powered by FLUX.1 Kontext, this model supports a wide range of hairstyles (e.g., pixie cut, braided ponytail, mohawk) and colors (e.g., blonde, brown, black, red, pink). Simply submit an image and desired style/color constraints, and the API will handle the rest, returning an edited image or a URL to download it.

## Features
- Quickly change hair color with realistic detail.
- Large hairstyle library: from standard cuts to unique braided styles.
- Maintains facial features and preserves image clarity.
- Ultra-fast, asynchronous processing with easy polling.
- Fine-grained aspect ratio control.
- Multiple output formats (JPEG or PNG).

## Use Cases
1. • E-Commerce Virtual Try-Ons: Let users preview new hairstyles or colors before purchasing hair products or wigs.  
2. • Salon Booking Apps: Showcase potential makeovers to clients by simulating color and style changes.  
3. • Fashion & Social Media Marketing: Run A/B tests on different hair style images without repeated photo shoots.  
4. • Entertainment Industry: Conceptualize character looks for movies, TV shows, and video games.  
5. • Personal Usage & Content Creation: Experiment with multiple hair variations for personal profiles, influencer content, or fun transformations.

## Visual Examples

Below is an example showcasing the input image and a corresponding generated output:

### Example Input Portrait
![Example input portrait image](https://blog.api.market/wp-content/uploads/2025/12/professional-headshot-api-market.webp)

• Description: This image shows a person’s portrait prior to any transformations.

### Example Output (Changed Hair Style/Color)
![Example output with new hairstyle/color](https://blog.api.market/wp-content/uploads/2026/01/purple-braid-api-market.png)

• Description: The result after applying a “Random” haircut and “Random” hair color. Notice the realistic style changes and color tones.

## Pricing
• 1 API unit = 1 image processed.  
• GET requests to check prediction status (GET /api/v1/magicapi/ai-hair-style-color-changer/predictions/{id}) are free and do not count toward usage.  
• Various pricing tiers are available to accommodate different user volumes and budgets.

## API Documentation

Below are the essential details for using the API.

### Base URL
All API requests should be made to:
```
https://prod.api.market/api/v1/magicapi/ai-hair-style-color-changer
```

### Authentication
Include your API key in the request header:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```
Replace "YOUR_API_MARKET_KEY" with the actual key provided in your API.market account.

### Asynchronous Processing
This API processes images asynchronously. Once you create a prediction, it returns a prediction ID. You must then poll the status endpoint until the prediction is either succeeded or failed.

Typical flow:
1. POST your request to /predictions.
2. Receive a prediction ID in the response.
3. Poll the GET /predictions/{id} endpoint until the status is "succeeded" or "failed".
4. Once "succeeded", retrieve the generated image from the "output" field.

We recommend:  
• Poll every 1 second.  
• Timeout after 600 seconds (10 minutes).  
• Handle errors and status changes appropriately.

### Endpoints

#### 1. Create a Prediction
POST /api/v1/magicapi/ai-hair-style-color-changer/predictions

• Description: Creates a new haircut transformation request.

Request Body (JSON):
```json
{
  "version": "48f03523665cabe9a2e832ea9cc2d7c30ad5079cb5f1c1f07890d40596fe1f87",
  "input": {
    "input_image": "https://your-image-url.jpg",
    "haircut": "Random",
    "hair_color": "Random",
    "aspect_ratio": "match_input_image",
    "gender": "none",
    "seed": 1,
    "output_format": "png",
    "safety_tolerance": 2
  }
}
```

• Response Examples:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "48f03523665cabe9a2e832ea9cc2d7c30ad5079cb5f1c1f07890d40596fe1f87",
  "status": "starting",
  "created_at": "2025-06-05T20:18:36.191Z"
}
```

##### cURL Example
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-hair-style-color-changer/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "48f03523665cabe9a2e832ea9cc2d7c30ad5079cb5f1c1f07890d40596fe1f87",
    "input": {
      "input_image": "https://your-image-url.jpg",
      "haircut": "Random",
      "hair_color": "Random",
      "aspect_ratio": "match_input_image",
      "gender": "none",
      "seed": 1,
      "output_format": "png",
      "safety_tolerance": 2
    }
  }'
```

#### 2. Get Prediction Status & Result
GET /api/v1/magicapi/ai-hair-style-color-changer/predictions/{id}

• Description: Retrieve the current status of a prediction. Once "status" is "succeeded," the "output" field contains a URL to the transformed image.

• Response Example (when status is succeeded):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://some-delivery-service.com/path-to-output-image.png",
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

##### cURL Example
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-hair-style-color-changer/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Status Codes
• 200 OK: Request successful  
• 201 Created: Resource successfully created (e.g., prediction created)  
• 400 Bad Request: Invalid input parameters or malformed request  
• 401 Unauthorized: Missing or invalid API key  
• 403 Forbidden: Valid API key but insufficient permissions  
• 404 Not Found: Resource not found  
• 429 Too Many Requests: Rate limit exceeded; slow down requests or increase your plan  
• 500 Internal Server Error: Server-side error; try again later  
• 503 Service Unavailable: Service may be temporarily unavailable or under maintenance

### Rate Limits
API.market enforces rate limits to maintain service stability. If you exceed the allowed requests per minute for your plan, you will receive a 429 (Too Many Requests) response. We recommend exponential backoff or a short retry interval in these scenarios.

## Error Handling
Errors are returned in JSON format. Example:
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'input_image' is required",
    "status": 400
  }
}
```
• Validate your request body before sending.  
• On 400 (Bad Request) or 422 (Unprocessable Entity), review the message to correct your parameters.  
• On 429 (Too Many Requests), implement a backoff strategy.  
• On 500 or 503, retry after a delay or contact support if the error persists.

## Implementation Guide

### Example Code

#### JavaScript (Node.js) Example with Polling
```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-hair-style-color-changer";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({
        version: "48f03523665cabe9a2e832ea9cc2d7c30ad5079cb5f1c1f07890d40596fe1f87",
        input: inputData
      })
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second between checks
  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-magicapi-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}
```

#### Python Example with Polling
```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-hair-style-color-changer"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    payload = {
        "version": "48f03523665cabe9a2e832ea9cc2d7c30ad5079cb5f1c1f07890d40596fe1f87",
        "input": input_data
    }
    response = requests.post(f"{BASE_URL}/predictions", headers=headers, json=payload)

    if response.status_code != 200 and response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    prediction = response.json()
    prediction_id = prediction["id"]

    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        response = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers={"x-magicapi-key": API_KEY}
        )
        
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")
        
        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")

        time.sleep(POLL_INTERVAL)

    raise Exception("Prediction timed out after 10 minutes")
```

#### cURL Example
```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-hair-style-color-changer/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "48f03523665cabe9a2e832ea9cc2d7c30ad5079cb5f1c1f07890d40596fe1f87",
    "input": {
      "input_image": "https://your-image-url.jpg",
      "haircut": "Random",
      "hair_color": "Random",
      "aspect_ratio": "match_input_image"
    }
  }'

# Example response:
# {
#   "id": "abcd1234",
#   "status": "starting"
# }

# Step 2: Poll the prediction status
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-hair-style-color-changer/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Cache your input images or pre-check them to reduce repeated submissions.  
- Limit requests to essential transformations to reduce costs.  
- For large volumes, consider higher-tier plans to lower per-image costs.

## FAQ
1. **How long does it take for a prediction to finish?**  
   Typically a few seconds, but can take up to a minute or more for complex transformations.

2. **What image formats are supported for input?**  
   JPEG, PNG, GIF, and WebP.

3. **Can I specify multiple hairstyles at once?**  
   Each request processes a single set of parameters. For multiple variations, submit separate requests.

4. **What if the output is not as expected?**  
   Consider adjusting the seed, or re-checking your input image and parameter values.

5. **Are overlays, such as hats or accessories, possible?**  
   Currently, the focus is on hair transformations. For additional modifications, watch for future feature updates.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello[at]api.market.

Change hair style and color in portraits with AI. Get ultra-fast, realistic renderings for virtual try-ons. From $0.05/call. Try it free on API.market.