# Welcome! We're an innovative AI solutions startup focused on building custom AI algorithms that excel in skin recognition, analysis & matching with inclusive data sets for over 100 skin shades and undertones. ## Introduction to roboAPIs Our APIs allow you to access the power of our AI-powered platform and incorporate its capabilities into your systems and processes. With our APIs, you can foster inclusivity and efficiency, enabling personalized experiences in your applications, processes, and systems. We can empower your business, or company to offer personalized product recommendations to your customers based on their unique skin shade and undertones. Our APIs are designed to be easy to use and integrate, with detailed documentation and code samples provided to help you get started. Whether you are a developer working on a custom integration or a business owner looking to enhance your customer experience, our APIs have something to offer. In this documentation, you will find detailed information on each of our APIs, including descriptions of their functionality, parameters, and responses. You will also find examples of how to use the APIs, along with tips and a troubleshooting guide to help you get the most out of them. If you have any questions or need help integrating our APIs, don't hesitate to contact our developer support team. We are here to help you succeed and bring the benefits of personalized product recommendations to your customers. ## Want to jump right in? Feeling like an eager beaver? Jump into the quick start docs and get making your first request: {% content-ref url="/pages/Fi45JKDjNFQGgp3cZlx0" %} [Quick Start](/quick-start) {% endcontent-ref %} ## Want to deep dive? Dive a little deeper and start exploring our API reference to get an idea of everything possible with the API: {% content-ref url="/pages/SeDj06pBgp3pPAxX9uW4" %} [API Reference](/reference/api-reference) {% endcontent-ref %} # Quick Start Don't worry. We get it! It's always more fun to jump right in and then read the documentation if something breaks. We got you covered. {% hint style="info" %} **Good to know:** Our current API is the Skin Shade Detection API. The Beauty & Fashion Product Recommendation API is also coming soon! {% endhint %} ## Get your API Key Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error. The best way to interact with our APIs is to use standard HTTP verbs as our APIs are organized around REST. Before you start using the `skinshade` or `lips` endpoint, you need to generate an API key. This can be done by making a **GET** request to the `generatekey` endpoint. This endpoint is rate-limited to 1 request per month for the free tier. Here is an example of how to make a request to the `generatekey` endpoint using curl: ```sh curl --location 'https://api.robomua.com/api/generatekey' ``` The response will be a JSON object containing your API key: ```json { "roboKey": "your-api-key" } ``` {% hint style="info" %} **Good to know:** To authenticate your API request, you will need to include the API key in the request header as follows: `x-api-key`: \ Be sure to replace \ with your actual API key. {% endhint %} *** ## Make your first request Send an authenticated request to our endpoints to make your first request. This `skinshade` endpoint will fetch the exact skin shade of the person from the image file based on the user's skin tone and undertones, which is nice. The `lips` endpoint will return the processed image with the lipstick color applied to the lips. The `hairswap` endpoint returns a processed image with the newly selected hairstyle. Once you have your API key, you can start using the endpoints. All endpoints accept **POST** requests with an image file in the request body. The `lips` endpoint also requires the name of a color and the `hairswap` endpoint also requires a number corresponding to the preferred hairstyle. The image file should be png, jpg, jpeg, or heic. Here is an example of how to make a request to the `skinshade` endpoint using curl: {% code overflow="wrap" %} ```shell curl --location 'https://api.robomua.com/api/skinshade' \ --header 'x-api-key: your-api-key' \ --form 'file=@"/path/to/your/image.jpeg"' ``` {% endcode %} The response will be a JSON object containing the detected skin shade and tone range: ```json { "skinShade": "#hex-color", "toneRange": "tone-range" } ``` Take a look at how you can use the `lips` endpoint via curl: ```sh curl --location 'https://api.robomua.com/api/lips' \ --header 'x-api-key: your-api-key' \ --form 'file=@"/path/to/your/image.jpeg"' \ --form 'color="color-name"' ``` The response will be a JSON object containing a base64 string of the binary data of the image with the lipstick color applied: ```json { "lipsImage": "base64-encoded-string" } ``` Here is how you can send a request to the `hairswap` endpoint via curl: ```sh curl --location 'api.robomua.com/api/hairswap' \ --header 'x-api-key: your-api-key' \ --form 'file=@"/path/to/your/image.jpeg""' \ --form 'hair="integer-for-style"' ``` You will get a JSON object response containing a base64 string of the binary data of the image with the new hairstyle: ```json { "hairstyleImage": "base64-encoded-string" } ``` # API Reference Our complete list of APIs to help supercharge your applications with AI that excels in finding the right shade of people based on their skin tone and undertones as well as virtual try-ons. Dive into the specifics of each API endpoint by checking out our complete documentation. ## Skin Shade Detection API Everything related to skin shade analysis, recognition, and matching: {% content-ref url="/pages/5iYzIaHZKD5Xk71jxOMY" %} [Skin Shade Detection API](/reference/api-reference/skin-shade-detection-api) {% endcontent-ref %} ## Lips Application API Everything related to virtual try-ons and application of lip products: {% content-ref url="/pages/dsHfQZleDpMI4H5nTZgy" %} [Lips Application API](/reference/api-reference/lips-application-api) {% endcontent-ref %} ## Hairstyle Try-On API Everything related to virtual try-ons for different ways to style one's hair: {% content-ref url="/pages/sVnKfL1TDouan6EG3Bq2" %} [Hairstyle Try-On API](/reference/api-reference/hairstyle-try-on-api) {% endcontent-ref %} {% hint style="info" %} **Good to know:** We have another API coming soon which will be the Beauty & Fashion Products Recommendation API! {% endhint %} # Skin Shade Detection API This API employs advanced algorithms to factor in undertones, providing a more accurate and nuanced understanding of skin color to create more personalized and inclusive user experiences. {% hint style="info" %} **Good to know:** We only offer cloud APIs and our methods are kept up to date automatically with changes to the API. {% endhint %} ## Endpoints ### GET /api/generatekey Generates a new API key. This endpoint is rate-limited to 1 request per month for the free tier. #### Response A JSON object containing the generated API key. ```json { "roboKey": "your-api-key" } ``` ### POST /api/skinshade Detects the skin shade from an image based on the tone and undertones. {% tabs %} {% tab title="Parameters" %} ``` x-api-key (header): Your API key. ``` {% code overflow="wrap" %} ``` file (form-data): The image file. Should be of type png, jpg, jpeg, or heic. ``` {% endcode %} {% endtab %} {% tab title="Response" %} A JSON object containing the detected skin shade and tone range. ```json { "skinShade": "#hex-color", "toneRange": "tone-range" } ``` {% endtab %} {% endtabs %} ### GET /api/skinshade-health Check the application's health, the AI model, and the database. #### Response A JSON object containing the following fields: {% code overflow="wrap" %} ```json - `status`: A string that indicates the overall health of the API. It can be either "healthy" or "unhealthy". - `details`: A dictionary containing each component's status. The keys are the names of the components ("app", "model", "database"), and the values are strings describing the status of the component. ``` {% endcode %} #### Status Codes ```json - `200 OK`: The API is healthy. - `503 Service Unavailable`: The API is unhealthy. ``` #### Example Response ```json { "status": "healthy", "details": { "app": "App is running", "model": "AI model is loaded", "database": "Database is connected" } } ``` {% hint style="info" %} **Good to know:** The health check endpoint is useful for monitoring the health of the API and quickly identifying any issues with the application, the AI model, or the database. {% endhint %} *** ## Error Codes * **403**: Missing or invalid API key. * **429**: API key exceeded request limit. * **400**: No file part, selected file, or invalid file type. ## Authentication To authenticate your requests, include your API key in the `x-api-key` header. ## Request Limit The `generatekey` endpoint is rate-limited to 1 request per month for the free tier. The `skinshade` endpoint is rate-limited to 100 requests per month per API key for the free tier. ## Acceptable Image Files The `skinshade` endpoint accepts image files of type png, jpg, jpeg, and heic. The maximum file size is 5MB. # Lips Application API This API employs precise facial landmarks to accurately and naturally apply lipstick to the lips in an image. {% hint style="info" %} **Good to know:** We only offer cloud APIs and our methods are kept up to date automatically with changes to the API. {% endhint %} ## Endpoints ### GET /api/generatekey Generates a new API key. This endpoint is rate-limited to 1 request per month for the free tier. #### Response A JSON object containing the generated API key. ```json { "roboKey": "your-api-key" } ``` ### POST /api/lips Applies lipstick color to the lips in the image. {% tabs %} {% tab title="Parameters" %} ``` x-api-key (header): Your API key. ``` {% code overflow="wrap" %} ``` file (form-data): The image file. Should be of type png, jpg, jpeg, or heic. ``` {% endcode %} ``` color (form-data): The name of the color of the lipstick. ``` {% endtab %} {% tab title="Response" %} A JSON object containing the base64 string of the binary data of the processed image. ```json { "lipsImage": "base64-encoded-string" } ``` {% endtab %} {% endtabs %} ### GET /api/lips-health Check the application's health, the AI model, and the database. #### Response A JSON object containing the following fields: {% code overflow="wrap" %} ```json - `status`: A string that indicates the overall health of the API. It can be either "healthy" or "unhealthy". - `details`: A dictionary containing each component's status. The keys are the names of the components ("app", "model", "database"), and the values are strings describing the status of the component. ``` {% endcode %} #### Status Codes ```json - `200 OK`: The API is healthy. - `503 Service Unavailable`: The API is unhealthy. ``` #### Example Response ```json { "status": "healthy", "details": { "app": "App is running", "model": "AI model is loaded", "database": "Database is connected" } } ``` {% hint style="info" %} **Good to know:** The health check endpoint is useful for monitoring the health of the API and quickly identifying any issues with the application, the AI model, or the database. {% endhint %} *** ## Error Codes * **403**: Missing or invalid API key. * **429**: API key exceeded request limit. * **400**: No file part, selected file, or invalid file type. * **415**: Unsupported encoded image file. ## Authentication To authenticate your requests, include your API key in the `x-api-key` header. ## Request Limit The `generatekey` endpoint is rate-limited to 1 request per month for the free tier. The `lips` endpoint is rate-limited to 100 requests per month per API key for the free tier. ## Acceptable Image Files The `lips` endpoint accepts image files of type png, jpg, jpeg, and heic. The maximum file size is 5MB. # Hairstyle Try-On API This API employs precise facial landmarks to accurately and naturally try different hairstyles on an image. {% hint style="info" %} **Good to know:** We only offer cloud APIs and our methods are kept up to date automatically with changes to the API. {% endhint %} ## Endpoints ### GET /api/generatekey Generates a new API key. This endpoint is rate-limited to 1 request per month for the free tier. #### Response A JSON object containing the generated API key. ```json { "roboKey": "your-api-key" } ``` ### POST /api/hairswap Applies the selected hairstyle to the image. {% tabs %} {% tab title="Parameters" %} ``` x-api-key (header): Your API key. ``` {% code overflow="wrap" %} ``` file (form-data): The image file. Should be of type png, jpg, jpeg, or heic. ``` {% endcode %} ``` hair (form-data): The integer corresponding to the hairstyle. ``` {% endtab %} {% tab title="Response" %} A JSON object containing the base64 string of the binary data of the processed image. ```json { "hairstyleImage": "base64-encoded-string" } ``` {% endtab %} {% endtabs %} ### GET /api/hairswap-health Checks the health of the application, the AI model, and the database. #### Response A JSON object containing the following fields: {% code overflow="wrap" %} ```json - `status`: A string that indicates the overall health of the API. It can be either "healthy" or "unhealthy". - `details`: A dictionary that contains the status of each component. The keys are the names of the components ("app", "model", "database"), and the values are strings describing the status of the component. ``` {% endcode %} #### Status Codes ```json - `200 OK`: The API is healthy. - `503 Service Unavailable`: The API is unhealthy. ``` #### Example Response ```json { "status": "healthy", "details": { "app": "App is running", "model": "AI model is loaded", "database": "Database is connected" } } ``` {% hint style="info" %} **Good to know:** The health check endpoint is useful for monitoring the health of the API and quickly identifying any issues with the application, the AI model, or the database. {% endhint %} *** ## Error Codes * **403**: Missing or invalid API key. * **429**: API key exceeded request limit. * **400**: No file part, selected file, or invalid file type. * **415**: Unsupported encoded image file. ## Authentication To authenticate your requests, include your API key in the `x-api-key` header. ## Request Limit The `generatekey` endpoint is rate-limited to 1 request per month for the free tier. The `hairswap` endpoint is rate-limited to 100 requests per month per API key for the free tier. ## Acceptable Image Files The `hairswap` endpoint accepts image files of type png, jpg, jpeg, and heic. The maximum file size is 5MB. # Terms of Use It's important to understand our Terms of Use. These terms govern the use of our APIs and by using them, you are agreeing to these terms. Please read, understand, and agree to these terms before use. {% hint style="info" %} The Terms of Use cover key areas such as API key security, rate limiting, acceptable use, data usage, changes to terms, termination, warranties, and liability. Your understanding and compliance help us maintain a secure and efficient API environment for all users. {% endhint %} * **Acceptance of Terms**: By utilizing these APIs, you are expressing your agreement to abide by these terms of use. If you find these terms unacceptable, you are advised not to use these APIs. * **API Keys**: The security of your API keys is your responsibility. Sharing your API keys with others is strongly discouraged. * **Rate Limiting**: These APIs have rate limits. If you exceed these limits, your API keys may be temporarily or permanently suspended. * **Acceptable Use**: You are agreeing not to use the APIs for any illegal activities or in any manner that could potentially harm, disable, overburden, or impair the APIs. * **Data Usage**: You are agreeing to provide accurate data to the APIs and affirm that you possess the necessary rights to provide such data. * **Changes to Terms**: We hold the right to alter these terms at any given time. Regular review of these terms for any changes is recommended. * **Termination**: We hold the right to revoke your access to the APIs at any time and for any reason. * **Disclaimer of Warranties**: These APIs are provided without any warranties, either express or implied, and are to be used “as is”. * **Limitation of Liability**: We shall not be held liable for any direct, indirect, incidental, special, consequential, or exemplary damages resulting from your use of the APIs. ***By using these APIs, you are acknowledging that you have read, understood, and agreed to these terms of use.***