NAV Navbar
shell php python Java C#
  • API Web Service
  • API Overview
  • Migrating to API v2
  • Multipredict
  • Solution: Room Type
  • Solution: Exterior Home Style
  • Solution: Home Features (v3)
  • Solution: Home Appliances
  • Solution: Logos / Watermarks
  • Solution: Photo Compliance
  • Solution: Kitchen Finishes
  • Errors
  • Legacy Solutions
  • API Web Service

    Restb.ai provides its computer vision service via a RESTful API web service. The API is built upon a simple premise: you send image URLs to the service and it returns AI computed predictions. The type of prediction returned is based on the model specified for processing the image.

    Solutions

    In total, we have seven solutions that are available to customers, as defined in the following table:

    Solution Type Model
    Room Type Prediction real_estate_global_v2
    Exterior Home Style Prediction re_styles
    Home Features (v3) Detections re_features_v3
    Home Appliances Detections re_appliances
    Logos / Watermarks Detections re_logo
    Photo Compliance Detections re_compliance
    Kitchen Finishes Detections re_kitchen_finishes

    Each solution is described in greater detail in the below sections.

    Solution Type

    There are two types of AI solutions that are currently supported: Prediction and Detections. A model represents a specific application of an AI solution and will consist of one of these two types of solutions.

    Prediction Type Solutions

    The Prediction type solutions will predict a general category of a provided image. There are currently two Prediction type models:

    Detections Type Solutions

    The Detections type solutions make predictions about the relevant objects or features detected in an image, and consists of five different models:

    API Overview

    API Endpoint URL

    In Restb.ai's API service there are two main API endpoints. Each endpoint corresponds to a specific region that we provide our API service from. The URL component of each API endpoint is outlined in the table below:

    Region API Endpoint URL
    US https://api-us.restb.ai/
    EU https://api-eu.restb.ai/

    Note that for optimal performance you should make requests to the appropriate region's endpoint based on the geographical location of your stored images. For example if your image server is hosted in the US, you should use our US API endpoint. For clients outside of both the US and EU, you should use the region which you can access with the lowest latency (this often differs from geographical proximity). The legacy endpoint https://api.restb.ai still works as before and simply points to the EU region; however, it does not support the newer API contexts.

    API Context

    The new contexts support a requests-per-second model of rate limiting (as opposed to the older, less flexible concurrent threads model of rate limiting). Before, existing clients that had e.g. 10 concurrency could spawn 10 threads sending requests in parallel. However, this has several performance limitations, particularly pertaining to iowait, which is mitigated when utilizing a requests-per-second (rps) based approach. We have created some sample code in GitHub and a tutorial to help facilitate transitioning to the requests-per-second model of rate limiting.

    In addition to the existing /vision/v1 context, there is now a new /vision/v2 context that corresponds to our new API version number 2. Please see the APIv2 section for details about our new API enhancements.

    API Usage

    The API is RESTful and can be accessed over HTTPS via one of the above endpoint URLs. You will need a unique client_key in order to use our API endpoints.

    The different endpoints share the same parameter options: model_id, client_key, and either image_url or image_base64:

    Parameter Method Parameter Location Description
    client_key GET | POST query Unique client authentication key provided by Restb.ai
    model_id GET | POST query | body Specifies the model to use with the endpoint
    image_url GET | POST query | body Internet accessible URL to an input image
    image_base64 POST body URL and filename -safe base64(url) encoded image

    Every request must contain either an image_url or image_base64 parameter, but not both. If using the image_url parameter, the specified URL needs to be publicly accessible. Also, note that the performance of the image hosting server can impact the response times of our API.

    Note: Testing the API outside the boundaries of realistic use cases will return unfavorable results (e.g. trying to recognize the dining area from a computer generated or heavily altered image).

    Working with images

    In general, smaller images of approximately 800x600 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. Also, we recommend the use of bicubic interpolation / resampling when resizing images for the best results. The shortest edge of an image should ideally be no less than about 600 pixels. Note that due to computational limitations, we cannot process images that are more than 229 pixels, although anything higher than 800x600 is unnecessary.

    We support standard image formats, including but not exclusively limited to JPEG, GIF, TIFF, and/or PNG. Non-standard formats are not supported by the platform and may result in 001 errors being returned.

    While both URL and base64 are supported (although only one at a time), it is advisable to send image URLs to the platform, as it will yield more optimal performance on a per-request basis (image contents do not have to be fully transferred before the request is validated), as well as having more robustness via retry attempts if your image cannot be reached on the first attempt. Also, while using the image_url parameter please remember to properly escape / url-encode the URL; they can often contain reserved characters that must be escaped to be properly passed in as a parameter (especially ?, &, /, and = characters).

    Finally, note that base64 encoded images must be provided as base64url strings. The base64url format is a variant of base64 which is URL and file name safe (by replacing + and / symbols with - and _, respectively).

    Performance

    Going forward we will only be supporting the requests-per-second concurrency model, which means requests need to be rate-limited. There are many libraries available that provide control mechanisms for throttling your request rate. In addition, we have provided examples in our SDK tutorial as well. As a best practice, we recommend utilizing an exponential back-off retry strategy for dealing with errors, as well as explicitly setting a timeout (e.g. 60 seconds) to ensure that I/O errors do not cause your processes to stall indefinitely.

    API Limitations

    Free tier API keys

    If you require higher request volume capacity, the ability to process concurrent requests, and/or premium features like returning the center_point, 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 trial's 5,000 free requests).

    Authentication

    All requests to the API need to be authorized via the client_key query parameter, which should be set to your provided, unique client key. Note that client_key should always be passed in as a query parameter, even when sending HTTP POST requests.

    # On the command-line, you can just pass the client key with each request
    curl "https://api-us.restb.ai/vision/v2/predict?client_key=YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api-us.restb.ai/vision/v2/predict";
    
    $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-us.restb.ai/vision/v2/predict'
    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-us.restb.ai/vision/v2/predict";
    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-us.restb.ai/vision/v2/predict");
    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.

    Migrating to API v2

    The main reason for version 2 of our API was to improve the API based on user feedback, including both simplifying sending of requests as well as making it easier to parse and process responses. The newer response format also facilitates the addition of new features such as i18n without having to change how the response is processed. The changes are specified in more detail below.

    Requests for APIv2

    In order to access APIv2, the new /vision/v2 context must be used. Similarly to the /vision/v1 context, all requests will utilize the requests-per-second rate limiting model (as opposed to the older “number of concurrent requests” model). But going forward, instead of having to specify between classify and segmentation, the endpoint is now simply always predict. This means the end-point will always be one of the following (depending on your region):

    Region Full Endpoint URL
    US https://api-us.restb.ai/vision/v2/predict
    EU https://api-eu.restb.ai/vision/v2/predict

    We hope this helps simplify the API request process for all of our clients!

    JSON Response in APIv2

    Example Response - Room Type

    {
     "error": "false",
     "correlation_id": "14b096b0-e738-4380-a86a-8f88860ee1aa",
     "version": "2",
     "time": "2018-09-10T13:19:06.100680",
     "response": {
       "solutions": {
         "real_estate_global_v2": {
           "predictions": [
             {
               "confidence": 0.984749436378479,
               "label": "patio_terrace"
             },
             {
               "confidence": 0.010592819191515446,
               "label": "mountain_view"
             },
             {
               "confidence": 0.000911033945158124,
               "label": "outdoor_building"
             },
             {
               "confidence": 0.0005386354168877006,
               "label": "community_amenities"
             },
             {
               "confidence": 0.00041301248711533844,
               "label": "bedroom"
             }
           ],
           "top_prediction": {
             "confidence": 0.984749436378479,
             "label": "patio_terrace"
           }
         }
       }
     }
    }
    

    Example Response - Home Features

    {
       "error": "false",
       "correlation_id": "21711413-991f-47df-85eb-4a8f94cd8abe",
       "version": "2",
       "time": "2018-09-10T13:19:11.414744",
       "response": {
           "solutions": {
               "re_features_v3": {
                   "detections": [
                       {
                           "label": "deck"
                       },
                       {
                           "label": "hot_tub"
                       },
                       {
                           "label": "mountain_view"
                       }
                   ]
               }
           }
       }
    }
    

    While the changes for the requesting process have been made simpler, the changes in the JSON response structure are a little bit more complex. However, the response is now a lot simpler to integrate with, as there will no longer be mixed datatypes in arrays. In addition, the response structure contains a lot more metadata, including things such as time and correlation_id, which we hope will be useful for clients to better track the requests they are making to our API service. We have also minimized the usage of arrays, which we also hope will make it simpler to parse the new JSON response structures.

    The response wrapper is mostly unchanged, and still contains an error attribute, as well as a response attribute when there are no errors. However, we have added the aforementioned time and correlation_id attributes, as well as a version identifier for specifying how to parse the response.

    Response Wrapper

    Attribute Type Purpose
    error string whether or not the request was successfully processed or not
    response dict contains the response data if the request was successful
    time string server time of request (ISO format)
    correlation_id string unique identifier for specific request
    version string identifier of response format version

    Response Attributes

    Attribute Type Purpose
    solutions dict solutions wrapper
    solutions|<model_id> dict wrapper for a specific model_id
    solutions|<model_id>|predictions array array of label, confidence pairs of top 5 predictions
    solutions|<model_id>|top_prediction dict contains label, confidence pair of top prediction
    solutions|<model_id>|detections array array of detected object labels

    Internationalization (i18n)

    Example Response - Room Type w/i18n

    {
      "error": "false",
      "correlation_id": "14b096b0-e738-4380-a86a-8f88860ee1aa",
      "version": "2",
      "time": "2018-09-10T13:19:06.100680",
      "response": {
        "i18n": {
          "en_US": {
            "lang": "en",
            "locale": "US",
            "locale_encoding": "ISO3166-1",
            "lang_encoding": "ISO639-1"
          },
          "zh_CN": {
            "lang": "zh",
            "locale": "CN",
            "locale_encoding": "ISO3166-1",
            "lang_encoding": "ISO639-1"
          }
        },
        "solutions": {
          "real_estate_global_v2": {
            "predictions": [
              {
                "confidence": 0.984749436378479,
                "label": "patio_terrace"
              },
              {
                "confidence": 0.010592819191515446,
                "label": "mountain_view"
              },
              {
                "confidence": 0.000911033945158124,
                "label": "outdoor_building"
              },
              {
                "confidence": 0.0005386354168877006,
                "label": "community_amenities"
              },
              {
                "confidence": 0.00041301248711533844,
                "label": "bedroom"
              }
            ],
            "top_prediction": {
              "i18n": {
                "en_US": {
                  "lang": "en",
                  "locale": "US",
                  "translated_label": "Patio / Terrace"
                },
                "zh_CN": {
                  "lang": "zh",
                  "locale": "CN",
                  "translated_label": "露台"
                }
              },
              "confidence": 0.984749436378479,
              "label": "patio_terrace"
            }
          }
        }
      }
    }
    

    Example Response - Home Features w/i18n

    {
        "error": "false",
        "correlation_id": "21711413-991f-47df-85eb-4a8f94cd8abe",
        "version": "2",
        "time": "2018-09-10T13:19:11.414744",
        "response": {
            "i18n": {
                "en_US": {
                    "lang": "en",
                    "locale": "US",
                    "locale_encoding": "ISO3166-1",
                    "lang_encoding": "ISO639-1"
                },
                "zh_CN": {
                    "lang": "zh",
                    "locale": "CN",
                    "locale_encoding": "ISO3166-1",
                    "lang_encoding": "ISO639-1"
                }
            },
            "solutions": {
                "re_features_v3": {
                    "detections": [
                        {
                            "i18n": {
                                "en_US": {
                                    "lang": "en",
                                    "locale": "US",
                                    "translated_label": "Deck"
                                },
                                "zh_CN": {
                                    "lang": "zh",
                                    "locale": "CN",
                                    "translated_label": "木质平台"
                                }
                            },
                            "label": "deck"
                        },
                        {
                            "i18n": {
                                "en_US": {
                                    "lang": "en",
                                    "locale": "US",
                                    "translated_label": "Hot Tub"
                                },
                                "zh_CN": {
                                    "lang": "zh",
                                    "locale": "CN",
                                    "translated_label": "热水浴缸"
                                }
                            },
                            "label": "hot_tub"
                        },
                        {
                            "i18n": {
                                "en_US": {
                                    "lang": "en",
                                    "locale": "US",
                                    "translated_label": "Mountain View"
                                },
                                "zh_CN": {
                                    "lang": "zh",
                                    "locale": "CN",
                                    "translated_label": "山景"
                                }
                            },
                            "label": "mountain_view"
                        }
                    ]
                }
            }
        }
    }
    

    With the new JSON response structure, it is now also easier to add in additional metadata; one such added feature was internationalization (i18n) support. You can pass in i18n as a parameter to your request and we will return supported language/locale combinations. For now, only en_US and zh_CN are supported, but there will be additional languages added soon!

    Center Point

     Example Response - Home Features with center_point

    {
        "error": "false",
        "correlation_id": "4e97bcbb-53af-4528-a22f-d46f2ce23db6",
        "version": "2",
        "time": "2018-10-02T13:09:40.448881",
        "response": {
            "solutions": {
                "re_features_v3": {
                    "detections": [
                        {
                            "center_point": {
                                "y": 0.47466216216216217,
                                "x": 0.6316085489313836
                            },
                            "label": "natural_light"
                        },
                        {
                            "center_point": {
                                "y": 0.6030405405405406,
                                "x": 0.29471316085489313
                            },
                            "label": "fireplace"
                        },
                        {
                            "center_point": {
                                "y": 0.8209459459459459,
                                "x": 0.4932508436445444
                            },
                            "label": "hardwood_floor"
                        },
                        {
                            "center_point": {
                                "y": 0.8842905405405406,
                                "x": 0.35208098987626546
                            },
                            "label": "hardwood_floor"
                        },
                        {
                            "center_point": {
                                "y": 0.18412162162162163,
                                "x": 0.5067491563554556
                            },
                            "label": "coffered_ceiling"
                        },
                        {
                            "center_point": {
                                "y": 0.18158783783783783,
                                "x": 0.5573678290213724
                            },
                            "label": "beamed_ceiling"
                        }
                    ]
                }
            }
        }
    }
    

    One new feature that was capable due to the new APIv2 JSON response structure is the ability for us to dynamically add center point to “detections” style solutions (such as re_features_v3, re_appliances, re_logo, etc). In each detection, there will be a new center_point block that contains relative coordinates for the center point for each detected object.

    Transitioning to the newer API Contexts

    So for example, if a sample request URL looked like this before:

    https://api-us.restb.ai/classify?client_key=YOUR_CLIENT_KEY_HERE&model_id=real_estate_global_v2&image_url=https://demo.restb.ai/images/demo/demo-1.jpg

    it would need to be modified to:

    https://api-us.restb.ai/vision/v2/predict?client_key=YOUR_CLIENT_KEY_HERE&model_id=real_estate_global_v2&image_url=https://demo.restb.ai/images/demo/demo-1.jpg

    or to vision/v1/classify if the older response type is desired. Also, because of the new requests-per-second rate-limited model, requests that go over the rate threshold will receive status code 429 "Too Many Requests" HTTP errors as a response, which needs to be handled accordingly (e.g. retries need to be implemented in the client). Finally, if a client key is missing or erroneously specified, the API will now return status code 403 "Forbidden" HTTP errors.

    Finally, for compatibility reasons with sending base64 requests to this new context, client_key should always be sent as a query parameter, even if the other parameters are sent in the request body (as form fields).

    Multipredict

    The roll-out of the updated version 2 of our API facilitated our newest platform capability: multipredict. Going forward, clients can now issue multipredict type requests to our platform, which allows running multiple solutions on a single image. This prevents the need for having to submit multiple requests (one per solution) on the same image. With the new multipredict capability, responses for each individual solution are now returned in the single, combined response, thereby making it easier to use our API on a "per-image" basis.

    API Changes: Sending Updated Requests

    URL="https://api-us.restb.ai/vision/v2/multipredict"
    URL+="?model_id=real_estate_global_v2,re_features_v3,re_appliances"
    URL+="&image_url=https://demo.restb.ai/images/demo/demo-1.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use the HTTP POST method:
    curl "https://api-us.restb.ai/vision/v2/multipredict" \
    -d model_id="real_estate_global_v2,re_features_v3,re_appliances" \
    -d image_url="https://demo.restb.ai/images/demo/demo-1.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api-us.restb.ai/vision/v2/multipredict";
    $payload = array(
        "model_id"   => "real_estate_global_v2,re_features_v3,re_appliances",
        "image_url"  => "https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/multipredict'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 'real_estate_global_v2,re_features_v3,re_appliances',
        # Add the image URL you want to classify
        'image_url': 'https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/multipredict";
    String query = "model_id=real_estate_global_v2,re_features_v3,re_appliances"
        + "&image_url=https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/multipredict");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// handle parameters
    query["client_key"] = "YOUR_CLIENT_KEY";
    query["model_id"] = "real_estate_global_v2,re_features_v3,re_appliances";
    query["image_url"] = "https://demo.restb.ai/images/demo/demo-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 API is more or less the same as with API version 2, with only a few specific changes in how the request is submitted. First, instead of utiliizing the /vision/v2/predict endpoint, developers should utilize the /vision/v2/multipredict endpoint. To specify multiple solutions, there are two ways to facilitate this:

    1. multiple model_id parameters: the easiest way to specify multiple solutions is to simply specify multiple model_id parameters. For example, instead of simply passing in &model_id=real_estate_global_v2, developers can now pass in &model_id=real_estate_global_v2&model_id=re_features_v3&model_id=re_appliances. As many model_id parameters can be provided as desired, although note that duplicates will not be processed.

    2. comma-separated list: the other supported way to specify multiple model_id parameters is to speciy all desired solutions via a comma-separated list as the parameter value. For example: model_id=real_estate_global_v2,re_features_v3,re_appliances. This is useful when utilizing a library or programming language that doesn't support passing in multiple HTTP parameters (GET or POST) with the same name. Note that there should be no whitespace in the parameter value.

    API Changes: Parsing the Updated Response

    Example Response - multipredict with Room Type, Home Features, and Home Appliances

    {
        "response": {
            "solutions": {
                "re_features_v3": {
                    "detections": [
                        {
                            "label": "natural_light"
                        },
                        {
                            "label": "hardwood_floor"
                        },
                        {
                            "label": "fireplace"
                        },
                        {
                            "label": "coffered_ceiling"
                        }
                    ]
                },
                "real_estate_global_v2": {
                    "predictions": [
                        {
                            "confidence": 0.9999727010726929,
                            "label": "living_room"
                        },
                        {
                            "confidence": 0.0000034364468319836305,
                            "label": "office"
                        },
                        {
                            "confidence": 0.0000029434274892992107,
                            "label": "misc_room"
                        },
                        {
                            "confidence": 0.0000021963514882372692,
                            "label": "cinema_room"
                        },
                        {
                            "confidence": 0.0000021153089164727135,
                            "label": "patio_terrace"
                        }
                    ],
                    "top_prediction": {
                        "confidence": 0.9999727010726929,
                        "label": "living_room"
                    }
                },
                "re_appliances": {
                    "detections": [
                        {
                            "label": "tv"
                        }
                    ]
                }
            }
        },
        "correlation_id": "e56667bd-2617-4513-9e5e-ae25903e20b2",
        "version": "2",
        "error": "false",
        "time": "2019-01-16T22:14:35.643815"
    }
    

    Given that a multipredict request will have only a single response, the corresponding response details for each solution will be in the solutions wrapper, which uses each solution's model_id as the key of the solution-specific sub-dictionary. In this example, a multipredict request is sent with model_id=real_estate_global_v2,re_features_v3,re_appliances. When sending standard predict requests, there would only be one model_id in the solutions wrapper, but in this multipredict example there are three model_id's in the solutions wrapper, one for each specified model_id parameter.

    Heuristic Business Logic

    Example Response - multipredict with Kitchen Finishes and Room Type

    {
        "response": {
            "solutions": {
                "real_estate_global_v2": {
                    "predictions": [
                        {
                            "confidence": 0.99993896484375,
                            "label": "kitchen"
                        },
                        {
                            "confidence": 0.00000560039552510716,
                            "label": "bathroom"
                        },
                        {
                            "confidence": 0.000005518387752090348,
                            "label": "non_related"
                        },
                        {
                            "confidence": 0.000005008054358768277,
                            "label": "front_house"
                        },
                        {
                            "confidence": 0.000003982167072535958,
                            "label": "misc_room"
                        }
                    ],
                    "top_prediction": {
                        "confidence": 0.99993896484375,
                        "label": "kitchen"
                    }
                },
                "re_kitchen_finishes": {
                    "detections": [
                        {
                            "label": "light_floor"
                        },
                        {
                            "label": "pendant_lighting"
                        },
                        {
                            "label": "brown_cabinets"
                        },
                        {
                            "label": "stone_countertops"
                        },
                        {
                            "label": "light_countertops"
                        }
                    ]
                }
            }
        },
        "correlation_id": "c8d93f74-8a41-410c-a3e9-0303abdff105",
        "version": "2",
        "time": "2019-03-27T14:31:41.944279",
        "error": "false"
    }
    

    Our platform will now also intelligently filter results when certain combinations of solutions are used, as shown in the following table:

    Base Solution Model ID Filter Solution Model ID Business Logic
    re_styles real_estate_global_v2 The exterior home style will only be returned if the image's room type is classified as front_house; otherwise the result for the exterior home style solution will be not_front_house
    re_kitchen_finishes real_estate_global_v2 The kitchen finishes solution will only return detections if the image's room type is classified as kitchen

    For example, when using multipredict with model_id=re_kitchen_finishes,real_estate_global_v2 on an image that isn't a kitchen (as determined by the real_estate_global_v2 solution), no results will be returned for the re_kitchen_finishes solution.

    Caveats

    This is an extension of the predict feature and as such requires using version 2 of our API in conjunction with the multipredict endpoint. Prior versions of our API do not support multipredict and will return results for one solution in the response as before. Likewise, passing multiple solutions to predict will also return only one solution in the response.

    Error Handling

    Due to the all-or-nothing nature of multipredict requests (especially when factoring in the heuristic business logic), if any individual solution encounters an error, then the entire request will be flagged as an error.

    Request Counting

    Note that from a billing perspective, every solution used in a multipredict request will count as a single request. For example, a multipredict request using Room Type, Home Features, and Home Appliances will count as 3 requests.

    Concurrency

    Since every individual solution within a multipredict request counts as a separate request, this needs to be factored in when handling concurrency control. For example, if your account is configured for 6 rps and you wish to use 3 solutions in every multipredict request, you can only issue up to 2 multipredict requests per second.

    Solution: Room Type

    The "Room Type" solution 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 (people, animals, non-related, etc).

    API: Room Type

    URL="https://api-us.restb.ai/vision/v2/predict"
    URL+="?model_id=real_estate_global_v2"
    URL+="&image_url=https://demo.restb.ai/images/demo/demo-1.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use the HTTP POST method:
    curl "https://api-us.restb.ai/vision/v2/predict" \
    -d model_id="real_estate_global_v2" \
    -d image_url="https://demo.restb.ai/images/demo/demo-1.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api-us.restb.ai/vision/v2/predict";
    $payload = array(
        "model_id"   => "real_estate_global_v2",
        "image_url"  => "https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/predict'
    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': 'https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/predict";
    String query = "model_id=real_estate_global_v2"
        + "&image_url=https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/predict");
    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"] = "https://demo.restb.ai/images/demo/demo-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 Room Type solution is a Prediction type solution which uses the real_estate_global_v2 model. It will return the room types with the highest predicted confidence based on the image of the room.

    Room Type List

    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.

    Room Type Examples

    The above command returns a JSON response structured like the following:

    {
        "error": "false",
        "correlation_id": "602c19cb-cd28-418c-8613-ec1434542c85",
        "version": "2",
        "time": "2018-10-31T15:09:32.095830",
        "response": {
            "solutions": {
                "real_estate_global_v2": {
                    "predictions": [
                        {
                            "confidence": 0.9999698400497437,
                            "label": "living_room"
                        },
                        {
                            "confidence": 0.000003354518412379548,
                            "label": "office"
                        },
                        {
                            "confidence": 0.0000031579993446939625,
                            "label": "misc_room"
                        },
                        {
                            "confidence": 0.000002683668299141573,
                            "label": "patio_terrace"
                        },
                        {
                            "confidence": 0.0000024902528821257874,
                            "label": "cinema_room"
                        }
                    ],
                    "top_prediction": {
                        "confidence": 0.9999698400497437,
                        "label": "living_room"
                    }
                }
            }
        }
    }
    
    

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

    Solution: Exterior Home Style

    The "Exterior Home Style" solution is designed to recognize and differentiate between 16 different categories of the most common architectural styles of a house.

    exterior house style example 1exterior house style example 2

    API: Exterior Home Style

    URL="https://api-us.restb.ai/vision/v2/predict"
    URL+="?model_id=re_styles"
    URL+="&image_url=https://demo.restb.ai/images/demo/demo-styles.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use the HTTP POST method:
    curl "https://api-us.restb.ai/vision/v2/predict" \
    -d model_id="re_styles" \
    -d image_url="https://demo.restb.ai/images/demo/demo-styles.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api-us.restb.ai/vision/v2/predict";
    $payload = array(
        "model_id"   => "re_styles",
        "image_url"  => "https://demo.restb.ai/images/demo/demo-styles.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-us.restb.ai/vision/v2/predict'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 're_styles',
        # Add the image URL you want to classify
        'image_url': 'https://demo.restb.ai/images/demo/demo-styles.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-us.restb.ai/vision/v2/predict";
    String query = "model_id=re_styles"
        + "&image_url=https://demo.restb.ai/images/demo/demo-styles.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-us.restb.ai/vision/v2/predict");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// handle parameters
    query["client_key"] = "YOUR_CLIENT_KEY";
    query["model_id"] = "re_styles";
    query["image_url"] = "https://demo.restb.ai/images/demo/demo-styles.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 Exterior Home Style solution is a Prediction type solution which uses the re_styles model. It will return the home styles with the highest predicted confidence based on the image of the front of the house.

    Note: The exterior home styles solution requires the supplied image to have a "front house" perspective (specifically, as predicted by our "Room Type" solution). If the picture does not have that perspective, the results will be non-deterministic. Because of this, we recommend either first classifying your images using our 'Room Type' solution and then sending the images tagged as front_house to this solution, or alternatively, if you include both the 'Room Type' solution (real_estate_global_v2) and the 'Exterior Home Style' solution (re_styles) in a multipredict request, heuristic business logic will be automatically applied and the top result will be not_front_house if the perspective is not front_house. Please see the samples below for recommended example perspectives.

    Exterior Home Style List

    art_deco, cape_cod, colonial, contemporary, craftsman, farmhouse, italianate, log, mediterranean__spanish, neoclassical__greek_revival, oriental, prairie, pueblo_revival, ranch, tudor, victorian

    Exterior Home Style Examples

    The above command returns a JSON response structured like the following:

    {
        "error": "false",
        "correlation_id": "0b41ffe6-4906-4bf4-b6ea-0d44f05dfeae",
        "version": "2",
        "time": "2018-10-31T11:00:11.149719",
        "response": {
            "solutions": {
                "re_styles": {
                    "predictions": [
                        {
                            "confidence": 0.999518096446991,
                            "label": "victorian"
                        },
                        {
                            "confidence": 0.00025303856818936765,
                            "label": "craftsman"
                        },
                        {
                            "confidence": 0.0001277134579140693,
                            "label": "tudor"
                        },
                        {
                            "confidence": 0.00003627101250458509,
                            "label": "italianate"
                        },
                        {
                            "confidence": 0.000016591864550719038,
                            "label": "farmhouse"
                        }
                    ],
                    "top_prediction": {
                        "confidence": 0.999518096446991,
                        "label": "victorian"
                    }
                }
            }
        }
    }
    

    exterior home style example set 1 exterior home style example set 2

    Solution: Home Features (v3)

    The "Home Features (v3)" solution is used to identify 29 distinct indoor or outdoor home features present in an image of a property (e.g. fireplace, high ceiling, or pool). This solution returns all of the detected features within an image.

    API: Home Features

    URL="https://api-us.restb.ai/vision/v2/predict"
    URL+="?model_id=re_features_v3"
    URL+="&image_url=https://demo.restb.ai/images/demo/demo-1.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use POST:
    curl "https://api-us.restb.ai/vision/v2/predict" \
    -d model_id="re_features_v3" \
    -d image_url="https://demo.restb.ai/images/demo/demo-1.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api-us.restb.ai/vision/v2/predict";
    $payload = array(
        "model_id"   => "re_features_v3",
        "image_url"  => "https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/predict'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 're_features_v3',
        # Add the image URL you want to process
        'image_url': 'https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/predict";
    String query = "model_id=re_features_v3"
        + "&image_url=https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/predict");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// handle parameters
    query["client_key"] = "YOUR_CLIENT_KEY";
    query["model_id"] = "re_features_v3";
    query["image_url"] = "https://demo.restb.ai/images/demo/demo-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 Home Features (v3) solution is a Detections type solution which uses the re_features_v3 model. It will return all detected home features as detected in an image as a list.

    List of Home Features

    Please note that the tags in Home Features v3 have been standardized to use only lower case letters.

    Indoor

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

    Outdoor

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

    Examples: Home Features

    The above command returns standard JSON structured like this:

    {
        "error": "false",
        "correlation_id": "82048092-e12f-4733-a6e7-713b1edfdeaa",
        "version": "2",
        "time": "2018-10-31T15:59:13.734775",
        "response": {
            "solutions": {
                "re_features_v3": {
                    "detections": [
                        {
                            "label": "natural_light"
                        },
                        {
                            "label": "fireplace"
                        },
                        {
                            "label": "hardwood_floor"
                        },
                        {
                            "label": "coffered_ceiling"
                        },
                        {
                            "label": "beamed_ceiling"
                        }
                    ]
                }
            }
        }
    }
    

    Indoor Example

    Home Features (v3) indoor example

    Outdoor Example

    Home Features (v3) outdoor example

    Solution: Home Appliances

    The "Home Appliances" solution is used to identify multiple appliances present in an image of a property (e.g. microwave or oven, etc).

    API: Home Appliances

    URL="https://api-us.restb.ai/vision/v2/predict"
    URL+="?model_id=re_appliances"
    URL+="&image_url=https://demo.restb.ai/images/demo/demo-2.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use POST:
    curl "https://api-us.restb.ai/vision/v2/predict" \
    -d model_id="re_appliances" \
    -d image_url="https://demo.restb.ai/images/demo/demo-2.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api-us.restb.ai/vision/v2/predict";
    $payload = array(
        "model_id"   => "re_appliances",
        "image_url"  => "https://demo.restb.ai/images/demo/demo-2.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-us.restb.ai/vision/v2/predict'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 're_appliances',
        # Add the image URL you want to process
        'image_url': 'https://demo.restb.ai/images/demo/demo-2.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-us.restb.ai/vision/v2/predict";
    String query = "model_id=re_appliances"
        + "&image_url=https://demo.restb.ai/images/demo/demo-2.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-us.restb.ai/vision/v2/predict");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// handle parameters
    query["client_key"] = "YOUR_CLIENT_KEY";
    query["model_id"] = "re_appliances";
    query["image_url"] = "https://demo.restb.ai/images/demo/demo-2.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 Home Appliances solution is a Detections type solution which uses the re_appliances model. It will return all detected appliances as detected in an image as a list.

    List of Home Appliances

    dishwasher, elevator, microwave, oven, radiator, refrigerator, tv, wall_mounted_ac, washer__dryer, water_heater

    Example: Home Appliances

    The above command returns standard JSON structured like this:

    {
        "time": "2018-10-31T17:08:52.398578",
        "correlation_id": "e058d067-cf52-41bb-a60b-f0fd5d807eae",
        "version": "2",
        "error": "false",
        "response": {
            "solutions": {
                "re_appliances": {
                    "detections": [
                        {
                            "label": "microwave"
                        },
                        {
                            "label": "oven"
                        }
                    ]
                }
            }
        }
    }
    

    Home Appliances Example - kitchen

    Solution: Logos / Watermarks

    The "Logos / Watermarks" solution is used to detect logos, watermarks, and text in images. An example use case for this API would be use the data to automatically find and filter / flag images that contained logos, watermarks, or text in them.

    API: Logos / Watermarks

    URL="https://api-us.restb.ai/vision/v2/predict"
    URL+="?model_id=re_logo"
    URL+="&image_url=https://demo.restb.ai/images/demo/demo-1.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use POST:
    curl "https://api-us.restb.ai/vision/v2/predict" \
    -d model_id="re_logo" \
    -d image_url="https://demo.restb.ai/images/demo/demo-1.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api-us.restb.ai/vision/v2/predict";
    $payload = array(
        "model_id"   => "re_logo",
        "image_url"  => "https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/predict'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 're_logo',
        # Add the image URL you want to process
        'image_url': 'https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/predict";
    String query = "model_id=re_logo"
        + "&image_url=https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v2/predict");
    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"] = "https://demo.restb.ai/images/demo/demo-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 Logos / Watermarks solution is a Detections type solution which uses the re_logo model. It will return all detected logos, watermarks, and text as detected in an image as a list.

    Example: Logos / Watermarks

    The above command returns JSON structured like this:

    {
        "error": "false",
        "correlation_id": "26adaf72-63cf-44c1-932c-91da3b839157",
        "version": "2",
        "time": "2018-10-31T16:02:30.107742",
        "response": {
            "solutions": {
                "re_logo": {
                    "detections": [
                        {
                            "label": "watermark"
                        }
                    ]
                }
            }
        }
    }
    

    logos/watermarks example with centerpoint

    Solution: Photo Compliance

    The "Photo Compliance" solution allows platforms to automatically detect if the images uploaded by real estate agentscontain any content that might violate compliance rules, such as having identifying (contact) information or a person's face in an image.

    Note: the original Privacy Compliance solution (model ID re_privacy) was merged into the new Photo Compliance solution (model ID re_compliance).

    API: Photo Compliance

    URL="https://api-us.restb.ai/vision/v2/predict"
    URL+="?model_id=re_compliance"
    URL+="&image_url=https://demo.restb.ai/images/demo/demo-4.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use POST:
    curl "https://api-us.restb.ai/vision/v2/predict" \
    -d model_id="re_compliance" \
    -d image_url="https://demo.restb.ai/images/demo/demo-4.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api-us.restb.ai/vision/v2/predict";
    $payload = array(
        "model_id"   => "re_compliance",
        "image_url"  => "https://demo.restb.ai/images/demo/demo-4.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-us.restb.ai/vision/v2/predict'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 're_compliance',
        # Add the image URL you want to process
        'image_url': 'https://demo.restb.ai/images/demo/demo-4.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-us.restb.ai/vision/v2/predict";
    String query = "model_id=re_compliance"
        + "&image_url=https://demo.restb.ai/images/demo/demo-4.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-us.restb.ai/vision/v2/predict");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// handle parameters
    query["client_key"] = "YOUR_CLIENT_KEY";
    query["model_id"] = "re_compliance";
    query["image_url"] = "https://demo.restb.ai/images/demo/demo-4.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 Photo Compliance solution is a Detections type solution which uses the re_compliance model. It will return all detected faces, license plates, phone numbers, email addresses, and sign posts as detected in an image as a list.

    List of Photo Compliance Detections

    email, face_person, license_plate, phone_number, sign_post

    Example: Photo Compliance

    The above command returns standard JSON structured like this:

    {
        "error": "false",
        "correlation_id": "74d50977-1a6d-4ab0-8a9b-034e80a19601",
        "version": "2",
        "time": "2018-10-31T16:40:07.860307",
        "response": {
            "solutions": {
                "re_compliance": {
                    "detections": [
                        {
                            "label": "face_person"
                        },
                        {
                            "label": "license_plate"
                        },
                        {
                            "label": "phone_number"
                        },
                        {
                            "label": "sign_post"
                        }
                    ]
                }
            }
        }
    }
    

    photo compliance example with face, license plate, phone number, and sign detections

    Solution: Kitchen Finishes

    The "Kitchen Finishes" solution is used to identify specific finishes of a kitchen (e.g. the color of cabinets). This solution returns all of the detected features within an image. When multiple colors of cabinets or floor are detected then it returns the predominant color.

    API: Kitchen Finishes

    URL="https://api-us.restb.ai/vision/v2/predict"
    URL+="?model_id=re_kitchen_finishes"
    URL+="&image_url=https://demo.restb.ai/images/demo/demo-2.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use POST:
    curl "https://api-us.restb.ai/vision/v2/predict" \
    -d model_id="re_kitchen_finishes" \
    -d image_url="https://demo.restb.ai/images/demo/demo-2.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api-us.restb.ai/vision/v2/predict";
    $payload = array(
        "model_id"   => "re_kitchen_finishes",
        "image_url"  => "https://demo.restb.ai/images/demo/demo-2.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-us.restb.ai/vision/v2/predict'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 're_kitchen_finishes',
        # Add the image URL you want to process
        'image_url': 'https://demo.restb.ai/images/demo/demo-2.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-us.restb.ai/vision/v2/predict";
    String query = "model_id=re_kitchen_finishes"
        + "&image_url=https://demo.restb.ai/images/demo/demo-2.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-us.restb.ai/vision/v2/predict");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// handle parameters
    query["client_key"] = "YOUR_CLIENT_KEY";
    query["model_id"] = "re_kitchen_finishes";
    query["image_url"] = "https://demo.restb.ai/images/demo/demo-2.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 Kitchen Finishes solution is a Detections type solution which uses the re_kitchen_finishes model. It will return all detected finishes for countertops, cabinets, and floors, as well as pendant lighting and kitchen island sinks as detected in an image as a list.

    List of Kitchen Finishes Detections

    stone_countertops, dark_countertops, light_countertops, dark_floor, light_floor, dark_brown_cabinets, brown_cabinets, light_brown_cabinets, white_cabinets, kitchen_island_sink, pendant_lighting

    Example: Kitchen Finishes

    The above command returns standard JSON structured like this:

    {
      "response": {
        "solutions": {
          "re_kitchen_finishes": {
            "detections": [
              {
                "label": "pendant_lighting"
              },
              {
                "label": "white_cabinets"
              },
              {
                "label": "stone_countertops"
              },
              {
                "label": "light_countertops"
              },
              {
                "label": "dark_floor"
              }
            ]
          }
        }
      },
      "correlation_id": "220e65b4-f976-4f67-9ca5-1cd79e290e7e",
      "version": "2",
      "error": "false",
      "time": "2019-03-27T14:18:55.300521"
    }
    

    Kitchen Finishes example with light/stone countertops, white cabinets, dark floors, and pendant lighting detections

    Errors

    Example of a JSON error response:

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

    The Restb.ai API uses the following error codes:

    Code Message Meaning
    001 Invalid or unreachable image, please try another Image is not reachable or the URL is invalid.
    002 Unknown client Invalid client_key specified in request.
    003 Invalid model id Invalid model_id specified in request.
    004 Request Limit Reached The specified client_key is out of free requests.
    005 Too Many Concurrent Requests More requests are being sent in parallel than are allotted for the specified client_key.
    006 Account Limited The specified account has been disabled.
    007 Error processing image An unspecified error has occurred during request processing.
    008 Invalid URL specified At least one required parameter is missing.

    Note that despite receiving an error code, the HTTP status code will still be 200 "OK".

    Legacy Solutions

    This page lists all deprecated or retired solutions and is maintained for historical reference purposes.

    Deprecated: 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-us.restb.ai/vision/v1/segmentation"
    URL+="?model_id=re_features_v2"
    URL+="&image_url=https://demo.restb.ai/images/demo/demo-1.jpg"
    URL+="&client_key=YOUR_CLIENT_KEY"
    
    curl $URL
    
    # You can also use POST:
    curl "https://api-us.restb.ai/vision/v1/segmentation" \
    -d model_id="re_features_v2" \
    -d image_url="https://demo.restb.ai/images/demo/demo-1.jpg" \
    -d client_key="YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api-us.restb.ai/vision/v1/segmentation";
    $payload = array(
        "model_id"   => "re_features_v2",
        "image_url"  => "https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v1/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': 'https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v1/segmentation";
    String query = "model_id=re_features_v2"
        + "&image_url=https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v1/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"] = "https://demo.restb.ai/images/demo/demo-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-us.restb.ai/vision/v1/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.

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

    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