API Documentation

We offer a comprehensive API for developers and businesses to integrate AI hairstyles and augmented reality into their applications. Start with the Basic API to get started, or dive into the Enterprise API for full business integration.

Are you a SaaS provider or platform looking to integrate AIHairstyles into your platform? Check out the Partner 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.

CodeDescription
200 - OKEverything worked as expected
400 - Bad RequestThe request was unacceptable, often due to missing parameters
401 - UnauthorizedNo valid API key provided
402 - Payment RequiredThe account has insufficient credits
403 - ForbiddenThe API key doesn't have permissions
404 - Not FoundThe requested resource doesn't exist
500 - Server ErrorSomething went wrong on our end

Basic API

The Basic API provides direct access to AIHairstyles' core functionality for individual users and simple integrations.

Authentication: Basic API endpoints require a personal API key. You can generate and manage your API keys above if you're logged in.

Who should use the Basic API?

  • Individual developers building personal projects or simple apps
  • Small businesses who want direct API access without enterprise features
  • Prototype builders testing hairstyle generation functionality
  • Content creators generating hairstyles for social media or marketing

Typical Workflow:

1. Get available styles with GET /styles
2. Get hair colors with GET /colors
3. Generate hairstyles with POST /generation/hairstyle
4. Check results with GET /generation/{id}

Get Styles

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

Get Colours

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

Generate Hairstyles

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": "IMG-123123.jpg", // Must reference an image in your AIhairstyles account, or use 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

Check 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

Enterprise API

The Enterprise API is designed for businesses (salons, barbers, hair clinics) to manage their own data, clients, and settings within the AIHairstyles platform.

Authentication: Enterprise API endpoints require your business's API key. You can manage your API keys from your enterprise dashboard.

Who should use the Enterprise API?

  • Salon owners who want to integrate client data into their existing booking/management systems
  • Barber shops looking to build custom client consultation workflows
  • Hair clinics needing to manage patient consultations and treatment tracking
  • Developers building custom applications for hair businesses

List Clients

GET/api/v1/enterprise/{enterprise_name}/clients

Retrieve a list of all clients associated with your enterprise, including their consultation history and generated images.

Headers

x-api-key: your_enterprise_api_key

Parameters

  • enterprise_name: Your enterprise's URL slug (found in your dashboard URL)
  • page (optional): Page number for pagination (default: 1)
  • limit (optional): Number of clients to return (default: 10)
  • search (optional): Search by email address

Response

Success (200)

{
  "clients": [
    {
      "id": "client_123",
      "email": "client@example.com",
      "name": "Jane Smith",
      "phone_number": "+1234567890",
      "user_id": "user_456",
      "metadata": {
        "source": "ai_studio",
        "created_by": "user_789"
      },
      "enterprise_clients_media": [
        {
          "id": "media_101",
          "file_url": "https://...",
          "file_name": "img-abc123",
          "created_at": "2024-01-20T14:15:00Z",
          "metadata": {
            "source": "upload"
          }
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15
  }
}

Create Client

POST/api/v1/enterprise/{enterprise_name}/clients

Add a new client to your enterprise. You must provide either an email address or phone number (or both) to create a client.

Headers

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

Request Body

{
  "email": "client@example.com", // optional but either email or phone_number is required
  "name": "Jane Smith", // optional
  "phone_number": "+1234567890", // optional but either email or phone_number is required
  "source": "client_page" // optional, can be used to track where the client was added from
}

Response

Success (200)

{
  "success": true,
  "client": {
    "id": "client_123",
    "email": "client@example.com",
    "name": "Jane Smith",
    "phone_number": "+1234567890",
    "enterprise_id": "ent_456",
    "user_id": null,
    "metadata": {
      "source": "ai_studio",
      "created_by": "user_789"
    },
    "created_at": "2024-01-15T10:30:00Z"
  },
  "message": "Client created successfully"
}

Validation Rules

  • Either email or phone_number must be provided (or both)
  • If email is provided, it must be a valid email format
  • name is optional but if provided must be at least 1 character

Common Errors

  • 400 Bad Request: Invalid email format, missing contact information (neither email nor phone provided), or other validation errors
  • 401 Unauthorized: Invalid or missing API key
  • 409 Conflict: Client with this email or phone number already exists for this enterprise

Get Client Details

GET/api/v1/enterprise/{enterprise_name}/clients/{client_id}

Get detailed information about a specific client, including their complete media history.

Headers

x-api-key: your_enterprise_api_key

Parameters

  • enterprise_name: Your enterprise's URL slug
  • client_id: The unique identifier of the client

Response

Success (200)

{
  "id": "client_123",
  "email": "client@example.com",
  "name": "Jane Smith",
  "phone_number": "+1234567890",
  "user_id": "user_456",
  "metadata": {
    "source": "ai_studio",
    "created_by": "user_789"
  },
  "enterprise_clients_media": [
    {
      "id": "media_101",
      "file_url": "https://...",
      "file_name": "img-abc123",
      "created_at": "2024-01-20T14:15:00Z",
      "metadata": {
        "source": "upload"
      }
    }
  ],
  "media_count": 25,
  "media_loaded": 5
}

Get Client Generation History

GET/api/v1/enterprise/{enterprise_name}/clients/{client_id}/generations

Retrieve all hairstyle generations for a specific client, including images and metadata.

Headers

x-api-key: your_enterprise_api_key

Parameters

  • enterprise_name: Your enterprise's URL slug
  • client_id: The unique identifier of the client
  • page (optional): Page number for pagination (default: 1)
  • limit (optional): Number of generations to return (default: 10)

Response

Success (200)

{
  "generations": [
    {
      "id": "gen_456",
      "created_at": "2024-01-20T14:15:00Z",
      "status": "completed",
      "data": {
        "styles": ["Long Bob", "Pixie Cut"],
        "gender": "feminine",
        "hairColours": ["brown"],
        "options": {
          "force_new_hairline": false
        }
      },
      "images": [
        "https://ik.imagekit.io/aihairstyles/...",
        "https://ik.imagekit.io/aihairstyles/..."
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 8,
    "totalPages": 1
  }
}

List API Keys

GET/api/v1/enterprise/{enterprise_name}/api-keys

View all API keys for your enterprise (values are masked for security).

Headers

x-api-key: your_enterprise_api_key

Response

Success (200)

{
  "data": [
    {
      "id": "key_789",
      "name": "Mobile App Integration",
      "created_at": "2024-01-15T10:30:00Z",
      "last_used": "2024-01-20T09:15:00Z",
      "status": "active",
      "api_key": "ak_**********************cdef"
    }
  ],
  "message": "API keys retrieved successfully"
}

Create API Key

POST/api/v1/enterprise/{enterprise_name}/api-keys

Generate a new API key for your enterprise. Useful for creating separate keys for different applications or team members.

Headers

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

Request Body

{
  "name": "Mobile App Integration",
  "expires_at": "2025-01-15T00:00:00Z" // optional
}

Response

Success (200)

{
  "success": true,
  "data": {
    "id": "key_789",
    "name": "Mobile App Integration", 
    "api_key": "ak_1234567890abcdef...",
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2025-01-15T00:00:00Z",
    "status": "active"
  },
  "message": "API key created successfully"
}
Important: The API key value is only shown once. Store it securely immediately after creation.

Delete API Key

DELETE/api/v1/enterprise/{enterprise_name}/api-keys/{key_id}

Permanently disable an API key. This action cannot be undone.

Headers

x-api-key: your_enterprise_api_key

Parameters

  • enterprise_name: Your enterprise's URL slug
  • key_id: The unique identifier of the API key to delete

Response

Success (200)

{
  "success": true,
  "message": "API key deleted successfully"
}

Common Errors

  • 404 Not Found: API key not found or doesn't belong to this enterprise
  • 400 Bad Request: Cannot delete the last remaining API key

Partner API

The Partner API is designed for trusted platform partners who need to programmatically create and manage multiple business accounts within the AIHairstyles ecosystem.

Partner Access Only: This API requires special admin API keys that are only issued to approved partners. Contact our team to become a partner.

Who should use the Partner API?

  • SaaS providers offering salon management software with AI consultation features
  • White-label solution providers building custom hairstyling applications for clients
  • Franchise systems deploying consistent AI consultation tools across multiple locations
  • E-commerce platforms integrating virtual try-on experiences for hair product retailers

Becoming a Partner

Ready to integrate AIHairstyles into your platform? Contact our partnerships team to discuss your use case and get access to admin API keys.

Contact Partnerships Team

Create Enterprise

POST/api/v1/admin/enterprise

Create a new enterprise account programmatically using an admin API key. This endpoint is designed for trusted partners who need to create businesses within the AIHairstyles ecosystem.

Partner Access Only: This endpoint requires an admin API key that can only be issued to approved partners. Contact our team to become a partner.

Headers

Content-Type: application/json
x-partner-api-key: your_partner_api_key_here

Request Body

{
  "businessName": "Hair Salon & Spa",
  "businessType": "salon",
  "ownerEmail": "owner@hairsalon.com"
}

Parameters

  • businessName: Required The name of the business (minimum 4 characters)
  • businessType: Required The type of business. Must be one of: "salon", "barber", "hair-clinic"
  • ownerEmail: Required - Email address of the business owner who will have admin access to the enterprise

Response

Success (201)

{
  "data": {
    "enterprise_id": "550e8400-e29b-41d4-a716-446655440000",
    "enterprise_name": "hair-salon-spa-1234",
    "enterprise_brand_name": "Hair Salon & Spa",
    "widget_id": 12345,
    "api_key": "ak_abcdef123456789...",
    "owner_email": "owner@hairsalon.com",
    "links": {
      "enterprise_overview": "https://aihairstyles.com/org/hair-salon-spa-1234",
      "widget_management": "https://aihairstyles.com/org/hair-salon-spa-1234/widgets/12345",
      "widget_embed": "https://aihairstyles.com/studio-widget?widget_id=12345"
    }
  },
  "message": "Enterprise created successfully",
  "status": "success"
}

Error (4xx/5xx)

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

Response Fields

  • enterprise_id: Unique UUID for the created enterprise
  • enterprise_name: URL-safe slug name for the enterprise (used in URLs)
  • enterprise_brand_name: Original business name as provided in the request
  • widget_id: ID of the default widget created for the enterprise
  • api_key: Default API key for the enterprise (store securely)
  • owner_email: Email address of the enterprise owner
  • links.enterprise_overview: Direct URL to the enterprise dashboard
  • links.widget_management: Direct URL to configure the widget settings
  • links.widget_embed: Direct URL for embedding the AI consultation widget

What Gets Created

When you create an enterprise via this endpoint, the following items are automatically created in a single atomic transaction:

  • Enterprise Account: A new business account with active subscription status
  • Owner User Account: If the email doesn't exist, a new user account is created; otherwise, the existing user is assigned as owner
  • User Permissions: The owner is granted full access with business_owner role and admin privileges
  • Default Widget: An enabled widget for AI hair consultations
  • Default API Key: A standard API key for the enterprise to use

Common Errors

  • 400 Bad Request: Invalid request body, validation errors, or missing required fields like ownerEmail
  • 401 Unauthorized: Missing or invalid admin API key
  • 409 Conflict: Unable to generate unique enterprise name
  • 500 Server Error: Unexpected server error during creation

Integration Notes

  • Store the returned enterprise_id and api_key in your database
  • The owner_email links to the user who will manage the enterprise
  • The widget_id can be used to embed the AI consultation widget
  • The enterprise_name is used for URL routing and API endpoints
  • The owner can immediately log in and access their enterprise dashboard
  • All created resources are immediately active and ready for use