NAV Navbar
shell php python Java C#
  • Introduction
  • Authentication
  • API Endpoint: Classify
  • API Endpoint: Segmentation
  • Errors
  • Introduction

    Quick Start

    You can visit our demo site to use the Restb.ai API without a client key. To obtain a client key, please contact us at restb.ai/contact.

    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.

    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

    The classify endpoint 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:

    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).

    Free API key limitations

    The free API key gives you access to a total of 10,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 10,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.

    API Endpoint: Classify

    Home Space Classification

    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"
    }
    

    This API endpoint is designed to recognize and differentiate between 31 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).

    HTTP Request URL

    The classify API endpoint uses the following URL base https://api.restb.ai/classify and supports either GET or POST HTTP methods.

    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 currently identifiable home spaces

    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

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

    API Endpoint: Segmentation

    The segmentation API endpoint uses the following URL base https://api.restb.ai/segmentation and supports either GET or POST HTTP methods. The general purpose for this API endpoint is to detect multiple features or objects within a specific image. There are two models supported by this endpoint re_logo and re_features_v2 which are described below.

    Home Features v2 - Indoor and Outdoor

    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"
    }
    

    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.

    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 currently identifiable features

    Indoor

    stainless_steel, kitchen_bar, kitchen_islan, 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

    Example: Indoor Home Features

    Home features v2 example - indoor

    Example: Outdoor Home Features

    Home features v2 example - outdoor

    Watermark and Logo Detection

    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"
    }
    

    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.

    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: Watermark and Logo Detection

    Watermark and logo 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.