API Documentation

Complete technical reference for the AIHairstyles API

Authentication

The AIHairstyles API uses API keys for authentication. You can obtain your API key from your dashboard.

API Key Header

x-api-key: your_api_key_here

Errors

The AIHairstyles API uses conventional HTTP response codes to indicate the success or failure of an API request.

Code	Description
200 - OK	Everything worked as expected
400 - Bad Request	The request was unacceptable, often due to missing parameters
401 - Unauthorized	No valid API key provided
402 - Payment Required	The account has insufficient credits
403 - Forbidden	The API key doesn't have permissions
404 - Not Found	The requested resource doesn't exist
500 - Server Error	Something went wrong on our end

List Available Hairstyles

GET/api/v1/styles

Retrieve a list of all available hairstyles and their details.

Response

Success (200)

{
  "data": [
    {
      "description": "Bob - disheveled",
      "sex": "feminine",
      "id": 817941,
      "tags": "disheveled, bob"
    }
    // ... more styles
  ],
  "message": "",
  "error": false
}

Default Fields

description: Name/description of the hairstyle
sex: Gender category of the hairstyle
id: Unique identifier
tags: Associated tags/keywords

List Available Hair Colors

GET/api/v1/colors

Retrieve a list of all available hair colors and their details.

Response

Success (200)

{
  "data": [
    {
      "id": "color_123",
      "name": "Brown",
      "description": "Natural brown hair color",
      "preview_images": {
        "thumbnail": "https://...",
        "full": "https://..."
      }
    }
    // ... more colors
  ],
  "message": "",
  "error": false
}

Default Fields

id: Unique identifier for the hair color
name: Display name of the hair color
description: Detailed description of the hair color
preview_images: Object containing preview image URLs

Hairstyle Generation

POST/api/v1/generation/hairstyle

Generate a new hairstyle based on the provided image and parameters.

Headers

Content-Type: application/json
x-api-key: your_api_key_here

Request Body

{
  "mode": "live", // or "test"
  "gender": "person", // or "male", "female", "man", "woman"
  "styles": ["817941"], // Array of hairstyle ids
  "hair_colour": "brown",
  "image_name": "example.jpg", // Required if not using image_url
  "image_url": "https://example.com/image.jpg", // Required if not using image_name
  "force_new_hairline": false, // Optional
  "callback_url": "https://your-domain.com/webhook" // Optional
}

Response

Success (200)

{
  "data": {
    "id": "job_123",
    "mode": "live",
    "image": {
      "name": "example.jpg",
      "url": "https://..."
    }
  },
  "message": "Job created successfully",
  "status": "success"
}

Error (4xx/5xx)

{
  "data": null,
  "message": "Error message explaining what went wrong",
  "status": "error"
}

Common Errors

400 Bad Request: Invalid request body format or validation errors in the parameters
401 Unauthorized: Missing or invalid API key
402 Payment Required: Insufficient credits for the operation
404 Not Found: Image not found or inaccessible

Get Generation Status

GET/api/v1/generation/{id}

Retrieve the status and results of a specific generation job.

Headers

x-api-key: your_api_key_here

Parameters

id: The ID of the generation job (received from the generation endpoint)

Response

Success (200)

{
  "data": {
    "images": [
      "https://ik.imagekit.io/...",
      // ... more image URLs
    ],
    "status": "completed"
  },
  "message": "Success",
  "status": "success"
}

Error (4xx/5xx)

{
  "data": null,
  "message": "Error message explaining what went wrong",
  "status": "error"
}

Common Errors

401 Unauthorized: No API key provided
403 Forbidden: Invalid API key
404 Not Found: Generation job not found
500 Server Error: Unexpected server error