NAV Navbar
shell php python Java C#
  • Introduction
  • Authentication
  • Solution: Room Types
  • Solution: Home Features v2
  • Solution: Logos / Watermarks
  • Errors
  • Introduction

    Quick Start

    You can visit our demo site to use the Restb.ai API without a client key. A trial client key can be obtained at our website.

    API Overview

    The API is built around a simple concept: you send inputs (images) to the service and it returns AI computed predictions. The type of prediction returned is based on the combination of the API endpoint used and the model specified for processing the input. Each combination of endpoint and model pertains to one "solution" that Restb.ai provides.

    Endpoint & Model Overview

    In Restb.ai's API, there are two API endpoints that are currently supported: classify and segmentation. An API endpoint is responsible for a certain type of computation, as dictated by a specified model. Each API endpoint supports one or more models, depending on the endpoint. A model represents the type of AI computation being computed for the endpoint.

    Classify Endpoint

    For the "Room Types" solution, we use the classify endpoint which predicts the category of the image (e.g. kitchen or bathroom). This endpoint supports the use of the real_estate_global_v2 model.

    Segmentation Endpoint

    The segmentation endpoint makes predictions about the relevant features detected in the image, and supports two different model options:

    Solutions

    In total, we have three solutions, defined by the three models across two endpoints that are available to customers. They are outlined in the table below:

    Solution Model Endpoint
    Room Types real_estate_global_v2 classify
    Home Features re_features_v2 segmentation
    Logos / Watermarks re_logo segmentation

    API Usage

    The API is RESTful and can be accessed over HTTP or HTTPS at the api.restb.ai domain. You will need a unique client_key in order to use our API endpoints.

    The two different endpoints classify and segmentation share the same parameter options: model_id, client_key, and image_url:

    Parameter Method Description
    model_id GET | POST Specifies the model to use with the endpoint
    client_key GET | POST Unique client authentication key provided by Restb.ai
    image_url GET | POST Internet accessible URL to an input image

    Note: Testing the API outside the boundaries of realistic use cases will return unfavorable results (e.g. trying to recognize the dining area from the gingerbread house in Hansel and Gretel).

    Working with images

    In general, smaller images of approximately 640x480 resolution work the most optimally on the platform. Unnecessarily large images should be resized for optimal platform performance before being sent to Restb.ai's API service. Not resizing images doesn't necessarily yield better results, and also takes longer to download and process. When resizing the image, note that using lossy compression formats (such as JPEG) can drop the quality of the image, so be sure to take care to preserve quality during the resize operation.

    Free API key limitations

    The free API key gives you access to a total of 5,000 API requests for 30 days, which includes both classify and segmentation endpoints.

    Only one image can be processed at a time when using a free key.

    The response time when using a free tier API key is higher (slower) than with a commercial tier key.

    If you require higher request volume capacity and/or the ability to process concurrent requests, please contact us.

    Note: Making an API request to one model_id and then another request for the same image to another model_id is considered as 2 separate requests (out of the 5,000 per month).

    Authentication

    All requests to the API need to be authorized via the client_key parameter, which should be set to your provided, unique client key.

    # On the command-line, you can just pass the client key with each request
    curl "https://api.restb.ai/API_ENDPOINT?client_key=YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api.restb.ai/API_ENDPOINT";
    
    $payload = array(
        // Add the client key to the parameters array
        "client_key" => "YOUR_CLIENT_KEY"
    
        // Other parameters...
    );
    $url = sprintf("%s?%s", $base_url, http_build_query($payload));
    
    import requests
    
    url = 'https://api.restb.ai/API_ENDPOINT'
    payload = {
        # Add the client key to the parameters dictionary
        "client_key" => "YOUR_CLIENT_KEY"
    
        # Other parameters...
    }
    
    response = requests.get(url, params=payload)
    
    String url = "https://api.restb.ai/API_ENDPOINT";
    String query = "client_key=YOUR_CLIENT_KEY";
    
    // Other parameters...
    // query += "&" + "param_key=param_value";
    
    try {
        InputStream response = new URL(url + "?" + query).openStream();
    } catch (Exception e) {
        e.printStackTrace();
    }
    
    var builder = new UriBuilder("https://api.restb.ai/API_ENDPOINT");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// set client_key parameter
    query["client_key"] = "YOUR_CLIENT_KEY";
    /// Other parameters...
    
    builder.Query = query.ToString();
    string url = builder.ToString();
    string content = string.Empty;
    
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
    

    If using our examples, please make sure to replace YOUR_CLIENT_KEY with your API key, and API_ENDPOINT with one of our previously mentioned API endpoints.

    Solution: Room Types

    This API endpoint is designed to recognize and differentiate between 33 different categories of specific house/apartment spaces shown in an image. It also detects whether the image pertains to real estate or not (spam, people, etc).

    API: Room Types

    URL="https://api.restb.ai/classify"
    URL+="?model_id=real_estate_global_v2"
    URL+="&image_url=http://demo.restb.ai/img/gallery/realestate/home-scenes/real_estate_global-1.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use the HTTP POST method:
    curl "https://api.restb.ai/classify" \
    -d model_id="real_estate_global_v2" \
    -d image_url="http://demo.restb.ai/img/gallery/realestate/home-scenes/real_estate_global-1.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api.restb.ai/classify";
    $payload = array(
        "model_id"   => "real_estate_global_v2",
        "image_url"  => "http://demo.restb.ai/img/gallery/realestate/home-scenes/real_estate_global-1.jpg",
        "client_key" => "YOUR_CLIENT_KEY"
    );
    $url = sprintf("%s?%s", $base_url, http_build_query($payload));
    
    // Make the request
    $response = file_get_contents($url);
    $json_response = json_decode($response);
    
    # Make sure you have installed the required packages:
    # $ pip install requests
    
    import requests
    
    url = 'https://api.restb.ai/classify'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 'real_estate_global_v2',
        # Add the image URL you want to classify
        'image_url': 'http://demo.restb.ai/img/gallery/realestate/home-scenes/real_estate_global-1.jpg'
    }
    
    # Make the classify request
    response = requests.get(url, params=payload)
    
    # The response is formatted in JSON
    json_response = response.json()
    
    String url = "https://api.restb.ai/classify";
    String query = "model_id=real_estate_global_v2"
        + "&image_url=http://demo.restb.ai/img/gallery/realestate/home-scenes/real_estate_global-1.jpg"
        + "&client_key=YOUR_CLIENT_KEY";
    
    InputStream response = new URL(url + "?" + query).openStream();
    
    try {
        Scanner scanner = new Scanner(response);
        String responseBody = scanner.useDelimiter("\\A").next();
        System.out.println(responseBody);
    } catch (Exception e) {
        e.printStackTrace();
    }
    
    /// build URI from endpoint base
    var builder = new UriBuilder("https://api.restb.ai/classify");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// handle parameters
    query["client_key"] = "YOUR_CLIENT_KEY";
    query["model_id"] = "real_estate_global_v2";
    query["image_url"] = "http://demo.restb.ai/img/gallery/realestate/home-scenes/real_estate_global-1.jpg";
    
    builder.Query = query.ToString();
    string url = builder.ToString();
    string content = string.Empty;
    
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
    request.AutomaticDecompression = DecompressionMethods.GZip;
    
    using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
    using (Stream stream = response.GetResponseStream())
    using (StreamReader reader = new StreamReader(stream))
    {
        content = reader.ReadToEnd();
    }
    
    Console.WriteLine(content);
    

    The above command returns JSON structured like the following:

    {
        "response": {
            "probabilities": [
                [
                    ["bathroom", 0.9999727010726929],
                    ["bedroom", 0.000004378894573164871],
                    ["laundry_room", 0.000002750007752183592],
                    ["office", 6.252743673940131e-7],
                    ["dining_area", 3.638390353444265e-7],
                    ["living_room", 3.2475622901984025e-7],
                    ["cinema_room", 2.653695787557808e-7],
                    ["kitchen", 2.2092224583047937e-7],
                    ["outdoor_building", 1.9765960246331815e-7],
                    ["wine_room", 1.457932228277059e-7]
                ]
            ]
        },
        "error": "false"
    }
    

    HTTP Request URL

    The room types solution utilizes the classify API endpoint, which has the following URL base https://api.restb.ai/classify and supports either GET or POST HTTP methods. Room types uses the real_estate_global_v2 model with parameters as described below.

    Parameters

    Parameter HTTP Method Description
    model_id GET | POST Use the real_estate_global_v2 model to classify home spaces
    image_url GET | POST The URL to the image to be classified

    Note: The image_url needs to be publicly accessible. Our AI isn’t trained to hack private networks... yet. ;)

    Note: The performance of the image hosting server can impact the response times of our API. #Fiber

    List of Room Types

    Animals, backyard, bathroom, bedroom, cinema_room, community_amenities, corridor, details, dining_area, empty_room, foyer_entrance, front_house, garage, gym, kitchen, laundry_room, living_room, map_location, misc_room, mountain_view, non_related, office, outdoor_building, patio_terrace, plan, pool, sauna, sport_court, stairs, utility_room, walk_in_closet_pantry, water_view, wine_room.

    Examples: Room Types

    Home spaces example set 1 Home spaces example set 2 Home spaces example set 3.

    Solution: Home Features v2

    The re_features_v2 model of the segmentation API endpoint is used to identify multiple indoor or outdoor home features present in an image of a property (e.g. fireplace, high ceiling, or pool). The API endpoint returns all of the detected features within an image.

    API: Home Features

    URL="https://api.restb.ai/segmentation"
    URL+="?model_id=re_features_v2"
    URL+="&image_url=http://demo.restb.ai/img/gallery/realestate/home-features/re_features-1.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use POST:
    curl "https://api.restb.ai/segmentation" \
    -d model_id="re_features_v2" \
    -d image_url="http://demo.restb.ai/img/gallery/realestate/home-features/re_features-1.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api.restb.ai/segmentation";
    $payload = array(
        "model_id"   => "re_features_v2",
        "image_url"  => "http://demo.restb.ai/img/gallery/realestate/home-features/re_features-1.jpg",
        "client_key" => "YOUR_CLIENT_KEY"
    );
    $url = sprintf("%s?%s", $base_url, http_build_query($payload));
    
    // Make the request
    $response = file_get_contents($url);
    $json_response = json_decode($response);
    
    # Make sure you have the required packages:
    # $ pip install requests
    
    import requests
    
    url = 'https://api.restb.ai/segmentation'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 're_features_v2',
        # Add the image URL you want to process
        'image_url': 'http://demo.restb.ai/img/gallery/realestate/home-features/re_features-1.jpg'
    }
    
    # Make the segmentation request
    response = requests.get(url, params=payload)
    
    # The response is formatted in JSON
    json_response = response.json()
    
    String url = "https://api.restb.ai/segmentation";
    String query = "model_id=re_features_v2"
        + "&image_url=http://demo.restb.ai/img/gallery/realestate/home-features/re_features-1.jpg"
        + "&client_key=YOUR_CLIENT_KEY";
    
    InputStream response = new URL(url + "?" + query).openStream();
    
    try (Scanner scanner = new Scanner(response)) {
        String responseBody = scanner.useDelimiter("\\A").next();
        System.out.println(responseBody);
    }
    
    /// build URI from endpoint base
    var builder = new UriBuilder("https://api.restb.ai/segmentation");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// handle parameters
    query["client_key"] = "YOUR_CLIENT_KEY";
    query["model_id"] = "re_features_v2";
    query["image_url"] = "http://demo.restb.ai/img/gallery/realestate/home-features/re_features-1.jpg";
    
    builder.Query = query.ToString();
    string url = builder.ToString();
    string content = string.Empty;
    
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
    request.AutomaticDecompression = DecompressionMethods.GZip;
    
    using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
    using (Stream stream = response.GetResponseStream())
    using (StreamReader reader = new StreamReader(stream))
    {
        content = reader.ReadToEnd();
    }
    
    Console.WriteLine(content);
    

    The above command returns JSON structured like this:

    {
        "response": {
            "objects": [
                "coffered_ceiling",
                "hardwood_floor",
                "fireplace",
                "natural_light"
            ]
        },
        "error": "false"
    }
    

    HTTP Request URL

    The home features solution utilizes the segmentation API endpoint, which has the following URL base https://api.restb.ai/segmentation and supports either GET or POST HTTP methods. Home features uses the re_features_v2 model with parameters as described below.

    Parameters

    Parameter HTTP Method Description
    model_id GET | POST Use the re_features_v2 model to detect indoor/outdoor home features
    image_url GET | POST The URL to the image to be processed

    Note: The image_url needs to be publicly accessible. Our AI isn’t trained to hack private networks... yet. ;)

    Note: The performance of the image hosting server can impact the response times of our API. #Fiber

    List of Home Features

    Indoor

    stainless_steel, kitchen_bar, kitchen_island, tile_floor, hardwood_floor, carpet, skylight, vaulted_ceiling, beamed_ceiling, coffered_ceiling, natural_light, notable_chandelier, exposed_bricks, high_ceiling, ceiling_fan, french_doors, fireplace.

    Outdoor

    deck, lawn, outdoor_kitchen, outdoor_living_space, pool, central_AC, fire_pit, hot_tub, fireplace, ceiling_fan, french_doors, dock, water_view, mountain_view

    Examples: Home Features

    Indoor Home Features

    Home features v2 example - indoor

    Outdoor Home Features

    Home features v2 example - outdoor

    Solution: Logos / Watermarks

    The re_logo model of the segmentation API endpoint is used to detect watermarks, logos, and text in images. An example use case for this API would be use the data to automatically filter out or crop images that contain watermarks, logos, and text. The API endpoint returns a collection of detected objects and the positions of the objects in the image via two x-y coordinates that correspond to the top left and bottom right corners of the bounding box.

    API: Logos / Watermarks

    URL="https://api.restb.ai/segmentation"
    URL+="?model_id=re_logo"
    URL+="&image_url=http://demo.restb.ai/img/gallery/realestate/logos-watermarks/re_logo-1.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use POST:
    curl "https://api.restb.ai/segmentation" \
    -d model_id="re_logo" \
    -d image_url="http://demo.restb.ai/img/gallery/realestate/logos-watermarks/re_logo-1.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api.restb.ai/segmentation";
    $payload = array(
        "model_id"   => "re_logo",
        "image_url"  => "http://demo.restb.ai/img/gallery/realestate/logos-watermarks/re_logo-1.jpg",
        "client_key" => "YOUR_CLIENT_KEY"
    );
    $url = sprintf("%s?%s", $base_url, http_build_query($payload));
    
    // Make the request
    $response = file_get_contents($url);
    $json_response = json_decode($response);
    
    # Make sure you have the required packages:
    # $ pip install requests
    
    import requests
    
    url = 'https://api.restb.ai/segmentation'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 're_logo',
        # Add the image URL you want to process
        'image_url': 'http://demo.restb.ai/img/gallery/realestate/logos-watermarks/re_logo-1.jpg'
    }
    
    # Make the segmentation request
    response = requests.get(url, params=payload)
    
    # The response is formatted in JSON
    json_response = response.json()
    
    String url = "https://api.restb.ai/segmentation";
    String query = "model_id=re_logo"
        + "&image_url=http://demo.restb.ai/img/gallery/realestate/logos-watermarks/re_logo-1.jpg"
        + "&client_key=YOUR_CLIENT_KEY";
    
    InputStream response = new URL(url + "?" + query).openStream();
    
    try (Scanner scanner = new Scanner(response)) {
        String responseBody = scanner.useDelimiter("\\A").next();
        System.out.println(responseBody);
    }
    
    /// build URI from endpoint base
    var builder = new UriBuilder("https://api.restb.ai/segmentation");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// handle parameters
    query["client_key"] = "YOUR_CLIENT_KEY";
    query["model_id"] = "re_logo";
    query["image_url"] = "http://demo.restb.ai/img/gallery/realestate/logos-watermarks/re_logo-1.jpg";
    
    builder.Query = query.ToString();
    string url = builder.ToString();
    string content = string.Empty;
    
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
    request.AutomaticDecompression = DecompressionMethods.GZip;
    
    using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
    using (Stream stream = response.GetResponseStream())
    using (StreamReader reader = new StreamReader(stream))
    {
        content = reader.ReadToEnd();
    }
    
    Console.WriteLine(content);
    

    The above command returns JSON structured like this:

    {
        "response": {
            "objects": [
                ["watermark", 551, 856, 1080, 1209],
                ["logo", 1097, 909, 1781, 1161]
            ]
        },
        "error": "false"
    }
    

    HTTP Request URL

    The logos / watermarks solution utilizes the segmentation API endpoint, which has the following URL base https://api.restb.ai/segmentation and supports either GET or POST HTTP methods. Logos / watermarks uses the re_logo model with parameters as described below.

    Parameters

    Parameter HTTP Method Description
    model_id GET | POST Use the re_logo model to detect watermarks and logos
    image_url GET | POST The URL to the image to be processed

    Note: The image_url needs to be publicly accessible. Our AI isn’t trained to hack private networks... yet. ;)

    Note: The performance of the image hosting server can impact the response times of our API. #Fiber

    Example: Logos / Watermarks

    Logo and watermark detection example

    Errors

    Example of a JSON error response:

    {
        "message": "Unkown client",
        "error_id": "002",
        "error": "true"
    }
    

    The Restb.ai API uses the following error codes:

    Error Code Meaning
    001 Invalid or unreachable image.
    002 Unkown client key.
    003 Invalid model id.
    004 Request limit reached.
    005 Too many concurrent requests.
    006 Account limited.
    007 Error processing image.