Name: LightX v2 – Virtual Hairstyle Try-On | Free · $53/mo | API.market
Brand: lightxeditor
SKU: api-lightxeditor-hairstyle
Availability: InStock
Author: API Market

# ✨ AI Hairstyle API (LightX V2)

## Overview

The **LightX AI Hairstyle API (V2)** lets you generate realistic virtual hairstyle transformations with AI. Send a user-uploaded image and a text prompt; the API returns natural-looking hairstyles that fit the person's face shape and hair structure and blend seamlessly with the photo.

The API uses a **secure two-step image flow**: you can upload images via the Image Upload API or use a supported image URL. Processing is **asynchronous**: you get an order ID, poll for status, and receive the final image URL when status is `active`.

---

## Features

- **Text-driven hairstyles** — Describe the look (e.g. "curly blonde bob") and get a realistic result
- **Face-aware** — Output adapts to face shape and existing hair
- **Secure image handling** — Pre-signed upload URLs; no external image URLs
- **Async processing** — Submit job, poll by order ID, retrieve output when ready
- **JPEG output** — Each generation returns one JPEG image
- **Async result** — Poll by order ID to get the output image URL

---

## Use Cases

- **Virtual makeovers** — Let users try hairstyles before a salon visit
- **Salon & beauty apps** — Integrate try-on into booking or consultation tools
- **Fashion and styling platforms** — Combine outfit and hairstyle suggestions
- **E-commerce** — Show product or look with different hair styles
- **Personalization** — Custom avatars, profile photos, or social content

---

## Visual Examples

<table>
  <thead>
    <tr>
      <th>Input</th>
      <th>Hairstyle</th>
      <th>Output</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><img src="https://blog.api.market/wp-content/uploads/2026/02/MESSI.jpg" alt="Input: Messi portrait" width="200" /></td>
      <td>textured quiff hairstyle and a low taper fade on the sides</td>
      <td><img src="https://blog.api.market/wp-content/uploads/2026/02/messi-new.png" alt="Output: quiff and taper" width="200" /></td>
    </tr>
    <tr>
      <td><img src="https://blog.api.market/wp-content/uploads/2025/12/professional-headshot-api-market.webp" alt="Input: professional headshot" width="200" /></td>
      <td>long curly hairs</td>
      <td><img src="https://blog.api.market/wp-content/uploads/2026/02/74f915c60927445dad0be60366cdc33b_1024x1024.jpg" alt="Output: long curly" width="200" /></td>
    </tr>
    <tr>
      <td><img src="https://blog.api.market/wp-content/uploads/2026/02/adam-api-market.jpeg" alt="Input: Adam" width="200" /></td>
      <td>classic pompadour</td>
      <td><img src="https://blog.api.market/wp-content/uploads/2026/02/adam-output-api-market.png" alt="Output: pompadour" width="200" /></td>
    </tr>
    <tr>
      <td><img src="https://blog.api.market/wp-content/uploads/2026/02/priyanka.png" alt="Input: Priyanka" width="200" /></td>
      <td>the bob</td>
      <td><img src="https://blog.api.market/wp-content/uploads/2026/02/priyanka-bob-api-market.png" alt="Output: bob" width="200" /></td>
    </tr>
  </tbody>
</table>

Try more in the [API Playground](https://api.market/store/lightxeditor/hairstyle#api-playground) on the product page.

---

## API Documentation

### Base URL

**`https://prod.api.market/api/v1/lightxeditor/hairstyle`**

Append the path for each endpoint: `/hairstyle/` (generate), `/order-status/` (check status).

### Authentication

The API uses API Key-based authentication. Include your key in the header. Get the key from your [API.market account](https://api.market) after subscribing to the product.

```http
x-api-market-key: YOUR_API_KEY
```

### Examples

**Generate AI Hairstyle** — POST `/hairstyle/`

```bash
curl -X 'POST' \
  'https://prod.api.market/api/v1/lightxeditor/hairstyle/hairstyle/' \
  -H 'accept: */*' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "imageUrl": "https://example.com/image.jpg",
  "textPrompt": "your input prompt"
}'
```

**Response:**

```json
{
  "statusCode": 2000,
  "message": "SUCCESS",
  "body": {
    "orderId": "74f915c60927445dad0be60366cdc33b",
    "maxRetriesAllowed": 5,
    "avgResponseTimeInSec": 15,
    "status": "init"
  }
}
```

Use `orderId` in the order-status request. Poll until `body.status` is `active` or `failed`.

---

**Check Order Status** — POST `/order-status/`

```bash
curl -X 'POST' \
  'https://prod.api.market/api/v1/lightxeditor/hairstyle/order-status/' \
  -H 'accept: */*' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "orderId": "74f915c60927445dad0be60366cdc33b"
}'
```

**Response (status = active):**

```json
{
  "statusCode": 2000,
  "message": "SUCCESS",
  "body": {
    "orderId": "74f915c60927445dad0be60366cdc33b",
    "status": "active",
    "output": "https://blog.api.market/wp-content/uploads/2026/02/74f915c60927445dad0be60366cdc33b_1024x1024.jpg"
  }
}
```

While still processing, `body.status` is `init`. When complete, `body.status` is `active` and `body.output` is the result image URL. On failure, `body.status` is `failed`.

---

## Error Codes

| **HTTP Status** | **Error Code** | **Message** |
|-----------------|----------------|-------------|
| 200 | SUCCESS | Request successful; check the response body for result or status. |
| 400 | INVALID_INPUT | Missing or invalid input fields (e.g. imageUrl, textPrompt, orderId). |
| 401 | UNAUTHORIZED | Invalid or missing API Key (x-api-market-key). |
| 403 | FORBIDDEN | Valid key but insufficient permissions or subscription. |
| 404 | NOT_FOUND | Invalid path or order ID. |
| 429 | RATE_LIMITED | Rate limit exceeded; retry after the indicated delay. |
| 500 | SERVER_ERROR | An unexpected error occurred. Try again later or contact support. |
| 503 | SERVICE_UNAVAILABLE | Service temporarily unavailable; retry later. |

---

## Rate Limits

- Poll the order-status endpoint about **every 3 seconds**. Up to **5** status checks are typically allowed per order (`maxRetriesAllowed`). Avoid polling more frequently to prevent rate limits.

---

## Error Handling

- Use the **status** field in the response body to detect `init`, `active`, or `failed`.
- On **failed**, check the response body for error details.
- For HTTP errors (4xx/5xx), implement retries with exponential backoff for 5xx and 429.

**Example error response (generic shape):**

```json
{
  "statusCode": 4000,
  "message": "ERROR",
  "body": {
    "error": "Invalid or missing parameter",
    "details": "imageUrl is required"
  }
}
```

---

## FAQ

**Can I use an image URL for the hairstyle request?**  
Yes. You can use a public image URL (e.g. from the API Playground examples) or the `imageUrl` from the Image Upload API after uploading via the `uploadImage` PUT.

**How long does generation take?**  
Typically around 15 seconds. Poll the order-status endpoint every 3 seconds until `status` is `active` or `failed`.

**What if status is "failed"?**  
Check the response body for error details and retry with valid inputs if needed.

**Where do I get my API key?**  
Subscribe to the product on [API.market](https://api.market/store/lightxeditor/hairstyle) and use the API key from your account as the `x-api-market-key` header value.

---

## Support

For questions or issues, please contact **hello@api.market** or use the embedded chat on the bottom right corner of the product page.


Generate realistic virtual hairstyles on any photo via text. Face-aware results. Free 10 calls/mo, from $53/mo. Try it free on API.market.

LightX v2 – Virtual Hairstyle Try-On | Free · $53/mo | API.market

Free