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 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 either image_url or image_base64:

    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 Internet accessible URL to an input image
    image_base64 POST A base64 encoded representation of the 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"
    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 to directly send a base64 image:
    curl "https://api.restb.ai/classify" \
    -d model_id="real_estate_global" \
    -d image_base64="%2F9j%2F4AAQSkZJRgABAQAASA..." \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api.restb.ai/classify";
    $payload = array(
        "model_id"   => "real_estate_global",
        "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);
    
    // Alternatively use the HTTP POST method
    
    $image_url = "http://demo.restb.ai/img/gallery/realestate/home-scenes/real_estate_global-1.jpg";
    $image_content = file_get_contents($image_url);
    $image_base64 = base64_encode($image_content);
    
    $base_url = "https://api.restb.ai/classify";
    $payload = array(
        "model_id"      => "real_estate_global",
        "image_base64"  => $image_base64,
        "client_key"    => "YOUR_CLIENT_KEY"
    );
    
    $options = array(
        // Use the key 'http' even if you are using HTTPS
        'http' => array(
            'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
            'method'  => 'POST',
            'content' => http_build_query($payload)
        )
    );
    $context = stream_context_create($options);
    
    // Make the request
    $response = file_get_contents($base_url, false, $context);
    $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',
        # 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()
    
    # You can also use POST to send a base64 image:
    
    import base64
    import requests
    
    url = 'https://api.restb.ai/classify'
    
    # Change the image URL you want to classify
    image_url = 'http://demo.restb.ai/img/gallery/realestate/home-scenes/real_estate_global-1.jpg'
    image_content = requests.get(image_url).content
    
    # base64 encode the image content
    image_base64 = base64.b64encode(image_content)
    
    # # The code below gets a base64 image from a file rather than from a URL
    # # Change the filename with your desired image file
    # filename = 'bedroom.jpg'
    # with open(filename, 'rb') as image_file: 
    #      image_base64 = base64.b64encode(image_file.read())  
    
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 'real_estate_global',
        'image_base64': image_base64
    }
    
    # Make the classify request
    response = requests.post(url, data=payload)
    
    # The response is in JSON format
    json_response = response.json()
    
    String url = "https://api.restb.ai/classify";
    String query = "model_id=real_estate_global"
        + "&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";
    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": [
                [
                    ["kitchen", 0.9999998807907104],
                    ["bathroom", 3.353897426450203e-08],
                    ["living/dining_room", 2.1737655231390818e-08],
                    ["walk_in_closet", 2.0118338994734586e-08],
                    ["room/bedroom", 9.74578728829556e-09],
                    ["terrace", 5.494501742475677e-09],
                    ["swimming_pool", 3.866567510613095e-09],
                    ["gym", 2.6767055238963167e-09],
                    ["non_related", 1.3646255236920979e-09],
                    ["parking", 1.122763770844415e-09]
                ]
            ]
        },
        "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 model to classify home spaces
    image_url GET The URL to the image to be classified
    image_base64 POST Alternatively, the base64 encoded image

    List of currently identifiable home spaces

    kitchen, living_room, misc_room, bedroom, garden, walk_in_closet/pantry, plan, gym, cinema_room, non_related, laundry_room, dining_area, garage, foyer_entrance, office, empty_room, sports_court, water_view, mountain_view, details, wine_room, bathroom, stairs, other_room, corridor, patio/terrace, outdoor_house, animals, outdoor_building, community_amenities, pool

    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.

    Watermark and Logo Detection

    URL="https://api.restb.ai/segmentation"
    URL+="?model_id=re_logo"
    URL+="&image_url=http://i.imgur.com/i2L35ZS.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use POST to send a base64 image:
    curl "https://api.restb.ai/segmentation" \
    -d model_id="re_logo" \
    -d image_base64="%2F9j%2F4AAQSkZJRgABAQAASA..." \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api.restb.ai/segmentation";
    $payload = array(
        "model_id"   => "re_logo",
        "image_url"  => "http://i.imgur.com/i2L35ZS.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);
    
    // You can also use POST:
    
    $image_url = "http://i.imgur.com/i2L35ZS.jpg";
    $image_content = file_get_contents($image_url);
    $image_base64 = base64_encode($image_content);
    
    $base_url = "https://api.restb.ai/segmentation";
    $payload = array(
        "model_id"      => "re_logo",
        "image_base64"  => $image_base64,
        "client_key"    => "YOUR_CLIENT_KEY"
    );
    
    $options = array(
        // Use the key 'http' even if you are using HTTPS
        'http' => array(
            'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
            'method'  => 'POST',
            'content' => http_build_query($payload)
        )
    );
    $context = stream_context_create($options);
    
    // Make the request
    $response = file_get_contents($base_url, false, $context);
    $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 segmentate
        'image_url': 'http://i.imgur.com/i2L35ZS.jpg'
    }
    
    # Make the segmentation request
    response = requests.get(url, params=payload)
    
    # The response is formatted in JSON
    json_response = response.json()
    
    # You can also use POST to send a base64 image:
    
    import base64
    import requests
    
    url = 'https://api.restb.ai/segmentation'
    
    # Change the image URL you want to segmentate
    image_url = 'http://i.imgur.com/i2L35ZS.jpg'
    image_content = requests.get(image_url).content
    
    # Encode the image content with Base64
    image_base64 = base64.b64encode(image_content)
    
    # # The code below gets a base64 image from a file rather than from a URL
    # # Change the filename with your desired image file
    # filename = 'bedroom.jpg'
    # with open(filename, 'rb') as image_file: 
    #      image_base64 = base64.b64encode(image_file.read())  
    
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 're_logo',
        'image_base64': image_base64
    }
    
    # Make the segmentation request
    response = requests.post(url, data=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://i.imgur.com/i2L35ZS.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://i.imgur.com/i2L35ZS.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": [
                ["logo", 421, 1, 517, 54],
                ["watermark", 92, 124, 424, 246],
                ["watermark", 328, 338, 499, 379]
            ]
        },
        "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 The URL to the image to be processed
    image_base64 POST Alternatively, the base64 encoded image

    Example: Watermark and Logo Detection

    Watermark and logo detection example

    Home Features Detection

    URL="https://api.restb.ai/segmentation"
    URL+="?model_id=re_features"
    URL+="&image_url=http://www.casarurallasmarzas.com/public/images/sites/314-12129.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use POST to send a base64 image:
    curl "https://api.restb.ai/segmentation" \
    -d model_id="re_features" \
    -d image_base64="%2F9j%2F4AAQSkZJRgABAQAASA..." \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api.restb.ai/segmentation";
    $payload = array(
        "model_id"   => "re_features",
        "image_url"  => "http://www.casarurallasmarzas.com/public/images/sites/314-12129.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);
    
    // You can also use POST:
    
    $image_url = "http://www.casarurallasmarzas.com/public/images/sites/314-12129.jpg";
    $image_content = file_get_contents($image_url);
    $image_base64 = base64_encode($image_content);
    
    $base_url = "https://api.restb.ai/segmentation";
    $payload = array(
        "model_id"      => "re_features",
        "image_base64"  => $image_base64,
        "client_key"    => "YOUR_CLIENT_KEY"
    );
    
    $options = array(
        // Use the key 'http' even if you are using HTTPS
        'http' => array(
            'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
            'method'  => 'POST',
            'content' => http_build_query($payload)
        )
    );
    $context = stream_context_create($options);
    
    // Make the request
    $response = file_get_contents($base_url, false, $context);
    $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',
        # Add the image URL you want to segmentate
        'image_url': 'http://www.casarurallasmarzas.com/public/images/sites/314-12129.jpg'
    }
    
    # Make the segmentation request
    response = requests.get(url, params=payload)
    
    # The response is formatted in JSON
    json_response = response.json()
    
    # You can also use POST to send a base64 image:
    
    import base64
    import requests
    
    url = 'https://api.restb.ai/segmentation'
    
    # Change the image URL you want to segmentate
    image_url = 'http://www.casarurallasmarzas.com/public/images/sites/314-12129.jpg'
    image_content = requests.get(image_url).content
    
    # Encode the image content with Base64
    image_base64 = base64.b64encode(image_content)
    
    # # The code below gets a base64 image from a file rather than from a URL
    # # Change the filename with your desired image file
    # filename = 'bedroom.jpg'
    # with open(filename, 'rb') as image_file: 
    #      image_base64 = base64.b64encode(image_file.read())  
    
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 're_features',
        'image_base64': image_base64
    }
    
    # Make the segmentation request
    response = requests.post(url, data=payload)
    
    # The response is formatted in JSON
    json_response = response.json()
    
    String url = "https://api.restb.ai/segmentation";
    String query = "model_id=re_features"
        + "&image_url=http://www.casarurallasmarzas.com/public/images/sites/314-12129.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";
    query["image_url"] = "http://www.casarurallasmarzas.com/public/images/sites/314-12129.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": [
                ["notable_chandelier"],
                ["beamed_ceiling"],
                ["vaulted_ceiling"],
                ["notable_chandelier"],
                ["natural_light"],
                ["natural_light"],
                ["kitchen_island"],
                ["hardwood_floor"],
                ["stainless_steel"]
            ]
        },
        "error": "false"
    }
    

    The re_features model of the segmentation API endpoint is used to identify multiple home features present in an image of a property (e.g. fireplace, hardward floor, or stainless steel appliances). 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 model to detect multiple home features
    image_url GET The URL to the image to be processed
    image_base64 POST Alternatively, the base64 encoded image

    List of currently identifiable features

    stainless_steel, kitchen_bar, kitchen_island, double_sinks, luxury_bathtub, 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.

    Example: Home Features

    Home features 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.