NAV Navbar
shell php python Java C#
  • Restb.ai API Service
  • API Overview
  • Solution: Room Type
  • Solution: Exterior Home Style
  • Solution: Home Features v3
  • Solution: Logos / Watermarks
  • Solution: Privacy Compliance
  • Errors
  • Legacy Solutions
  • Restb.ai API Service

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

    Quick Start

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

    Solutions

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

    Solution Endpoint Model
    Room Type classify real_estate_global_v2
    Exterior Home Style classify re_styles
    Home Features (v3) segmentation re_features_v3
    Logos / Watermarks segmentation re_logo
    Privacy Compliance segmentation re_privacy

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

    Solution Endpoints

    A solution endpoint is responsible for a certain type of AI prediction; there are two that are currently supported: classify and segmentation. Each solution endpoint supports two or more models, depending on the endpoint. A model represents a specific application of an AI prediction.

    Classify Solution Endpoint

    The classify endpoint predicts the category of a provided image. This endpoint supports two different models:

    Segmentation Solution Endpoint

    The segmentation endpoint makes predictions about the relevant features detected in the image, and supports three different models:

    API Overview

    API Endpoint URL

    In Restb.ai's API there are two main API endpoints that correspond to each region from which we provide our API service. The URL component of the 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. The legacy endpoint https://api.restb.ai still works as before and simply points to the EU region; however, it does not support our new API context.

    API Context

    We are now transitioning towards 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 (which currently supports python, more languages to be added later) and a tutorial to help facilitate transitioning to this new model.

    To utilize the new requests-per-second model of rate-limiting, please contact us at support@restb.ai. You will also need to update your integration to utilize the new, versioned context path. For now there is only v1, but in the future there will be more added versions:

    /vision/v1

    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/v1/classify?client_key=YOUR_CLIENT_KEY_HERE&model_id=real_estate_global_v2&image_url=https://demo.restb.ai/images/demo/demo-1.jpg

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

    API Usage

    The API is RESTful and can be accessed over HTTP or HTTPS at the api-us.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 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, but not both.

    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 when resizing images for the best results. The shortest edge of an image should ideally be no less than about 600 pixels.

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

    API Limitations

    Free tier API keys

    Areas of Interest

    If you require higher request volume capacity, the ability to process concurrent requests, and/or premium features like returning the areas of interest, 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 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-us.restb.ai/vision/v1/API_ENDPOINT?client_key=YOUR_CLIENT_KEY"
    
    <?php
    $base_url = "https://api-us.restb.ai/vision/v1/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-us.restb.ai/vision/v1/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-us.restb.ai/vision/v1/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-us.restb.ai/vision/v1/API_ENDPOINT");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// set client_key parameter
    query["client_key"] = "YOUR_CLIENT_KEY";
    /// Other parameters...
    
    builder.Query = query.ToString();
    string url = builder.ToString();
    string content = string.Empty;
    
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
    

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

    Solution: Room 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/v1/classify"
    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/v1/classify" \
    -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/v1/classify";
    $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/v1/classify'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 'real_estate_global_v2',
        # Add the image URL you want to classify
        'image_url': '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/v1/classify";
    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/v1/classify");
    builder.Port = -1;
    var query = HttpUtility.ParseQueryString(builder.Query);
    
    /// handle parameters
    query["client_key"] = "YOUR_CLIENT_KEY";
    query["model_id"] = "real_estate_global_v2";
    query["image_url"] = "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 the following:

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

    HTTP Request URL

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

    Parameters

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

    Note: The image_url needs to be publicly accessible.

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

    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

    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.

    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 top result will be not_front_house. Because of this, we recommend first classifying your images using our 'Room Type' solution and then sending the images tagged as front_house to this solution. Please see the samples below for recommended example perspectives.

    exterior house style example 1exterior house style example 2

    API: Exterior Home Style

    URL="https://api-us.restb.ai/vision/v1/classify"
    URL+="?model_id=re_styles"
    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/v1/classify" \
    -d model_id="re_styles" \
    -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/classify";
    $payload = array(
        "model_id"   => "re_styles",
        "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/v1/classify'
    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-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/v1/classify";
    String query = "model_id=re_styles"
        + "&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/v1/classify");
    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-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": [
                [
                    ["not_front_house", 0.9999921917915344],
                    ["contemporary", 6.025919052632389e-06],
                    ["craftsman", 1.6516591667681269e-06],
                    ["pueblo_revival", 1.2903758495053097e-07],
                    ["prairie", 3.813975849552287e-10],
                    ["mediterranean__spanish", 3.072797435336311e-10],
                    ["log", 2.0187637856956125e-10],
                    ["neoclassical__greek_revival", 1.5436624407113436e-10],
                    ["ranch", 9.238548988321771e-11],
                    ["italianate", 8.174796050589711e-11]
                ]
            ]
        },
        "error": "false"
    }
    

    HTTP Request URL

    The exterior home style solution utilizes the classify API endpoint, which has the following URL base https://api-us.restb.ai/vision/v1/classify and supports either GET or POST HTTP methods. This solution uses the re_styles model with parameters as described below.

    Parameters

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

    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.

    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

    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 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_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/v1/segmentation" \
    -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/v1/segmentation";
    $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/v1/segmentation'
    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/v1/segmentation";
    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/v1/segmentation");
    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 above command returns standard JSON structured like this:

    {
        "response": {
            "objects": [
                "fireplace",
                "pool"
            ]
        },
        "error": "false"
    }
    

    With the 'areas of interest' premium feature enabled, the returned JSON contains more information:

    {
        "response": {
            "objects": [
                ["fireplace", 12, 188, 354, 594],
                ["pool", 600, 274, 997, 485]
            ]
        },
        "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_v3 model with parameters as described below.

    Parameters

    Parameter HTTP Method Description
    model_id GET | POST Use the re_features_v3 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

    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

    Standard solution, indoor image

    Home features v3 standard example - indoor

    Standard solution, outdoor image

    Home features v3 standard example - outdoor

    Premium solution with areas of interest, indoor image

    Home features v3 premium example - indoor

    Premium solution with areas of interest, outdoor image

    Home features v3 premium example - outdoor

    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 images that contained logos, watermarks, or text in them. An additional use case might be to actually filter out or crop images that contain logos, watermarks, or text (this requires the 'areas of interest' premium feature). The API endpoint returns a collection of detected objects in the image, and optionally the positions of the objects in the image via two x-y coordinates that correspond to the top left and bottom right corners of the bounding box.

    API: Logos / Watermarks

    URL="https://api-us.restb.ai/vision/v1/segmentation"
    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/v1/segmentation" \
    -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/v1/segmentation";
    $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/v1/segmentation'
    payload = {
        # Add your client key
        'client_key': 'YOUR_CLIENT_KEY',
        'model_id': 're_logo',
        # Add the image URL you want to process
        'image_url': '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_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/v1/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"] = "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": [
                "watermark",
                "logo"
            ]
        },
        "error": "false"
    }
    

    With the 'areas of interest' premium feature enabled, the returned JSON contains more information:

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

    HTTP Request URL

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

    Parameters

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

    Note: The image_url needs to be publicly accessible.

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

    Examples: Logos / Watermarks

    Standard solution

    standard logo/watermark example

    Premium solution with areas of interest

    premium logo/watermark example with premium feature areas of interest

    Solution: Privacy Compliance

    The "Privacy Compliance" solution is used to identify content inside an image that might lead to privacy concerns (a person's face or a license plate number). The API endpoint returns all of the detected sensitive content within an image.

    API: Privacy Compliance

    URL="https://api-us.restb.ai/vision/v1/segmentation"
    URL+="?model_id=re_privacy"
    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_privacy" \
    -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_privacy",
        "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_privacy',
        # 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_privacy"
        + "&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_privacy";
    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 standard JSON structured like this:

    {
        "response": {
            "objects": [
                "face",
                "license_plate"
            ]
        },
        "error": "false"
    }
    

    With the 'areas of interest' premium feature enabled, the returned JSON contains more information:

    {
        "response": {
            "objects": [
                ["face", 1021, 107, 1269, 342],
                ["license_plate", 76, 687, 275, 757]
            ]
        },
        "error": "false"
    }
    

    HTTP Request URL

    The privacy compliance 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. This solution uses the re_privacy model with parameters as described below.

    Parameters

    Parameter HTTP Method Description
    model_id GET | POST Use the re_privacy model to detect privacy compliance concerns
    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.

    Examples: Privacy Compliance

    Standard solution

    standard privacy solution example

    Premium solution with areas of interest

    privacy solution example with premium feature areas of interest

    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.

    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