Create Generalization

How to create a generalization

There are no direct API methods to send a request to in order to create a generalization table, this feature is only available if the method supports it. For this example we will be use NSFW Classification as it supports generalization and it's easy to understand. This procedure is the same for any other method that supports generalization with the exception that the labels are different which are specified in the documentation for the method.
Parameter NameDefault ValueRequiredDescription
generalize0TrueIf set to 1, you are telling the API that you want to generalize the results
generalization_sizeNULLTrueThe size of the generalization table, cannot be 0 or less or greater than what your subscription supports. The mininum for a subscription is 5 and the maximum is 20
When you want to generalize the results for a method that supports generalization, you would generally pass on those two parameters to generalize the results and you will retrieve a Generalization ID which will allow you to continue the generalization in the next request by providing the Generalization ID as a generalization_id parameter instead, below is a few examples of what the request should look like in cURL

Example cURL request

curl --location --request POST 'https://api.intellivoid.net/coffeehouse/v1/image/nsfw_classification' \
--form 'access_key="<YOUR ACCESS KEY>"' \
--form '[email protected]"nothing_important.jpg"' \
--form 'generalize="1"' \
--form 'generalization_size="20"'

Example Response

{
  "success": true,
  "response_code": 200,
  "results": {
    "nsfw_classification": {
      "content_hash": "2d5e8a3a8588cc66baad2d606d0b595827c19b26da8fe91fd4cbfbb38df28e35",
      "content_type": "jpg",
      "safe_prediction": 99.9262,
      "unsafe_prediction": 0.073795,
      "is_nsfw": false
    },
    "generalization": {
      "id": "da61676a13ebf77c3825dbad62d4cccbc14e96eb6e83f9f117eb1b41a1e53fcc",
      "size": 20,
      "top_label": "safe",
      "top_probability": 99.9262,
      "probabilities": [
        {
          "label": "safe",
          "calculated_probability": 99.9262,
          "current_pointer": 0,
          "probabilities": [
            99.9262
          ]
        },
        {
          "label": "unsafe",
          "calculated_probability": 0.073795,
          "current_pointer": 0,
          "probabilities": [
            0.073795
          ]
        }
      ]
    }
  }
}

Generalization Object Structure

NameTypeDescription
idstringThe Generalization ID, this is used to update this table with new predictions
sizeintThe maximum size of the generalization table
top_labelstringThe top label from the generalization table
top_probabilityfloatThe top probability that is related to the top label from the generalization table
probabilitiesProbability[]Array of probabilities, each dedicated for each label.

Probability Object Structure

NameTypeDescription
labelstringThe label of the probability set
calculated_probabilityfloatThe calculation of the set of probabilities as a whole
current_pointerintThe current pointer of the probability set
probabilitiesfloat[]Array of probabilities in the generalization table that are being used to calculate calculated_probability

Generalization Size Exceeded response

This response is returned when the parameter generalization_size is greater than what the subscription allows.
{
  "success": false,
  "response_code": 400,
  "error": {
    "error_code": 16,
    "type": "CLIENT",
    "message": "You cannot exceed a generalization size of '20' (Subscription restriction)"
  }
}

Generalization Size Invalid response

This response is returned when the parameter generalization_size contains an invalid value
{
  "success": false,
  "response_code": 400,
  "error": {
    "error_code": 15,
    "type": "CLIENT",
    "message": "The 'generalization_size' parameter cannot contain a value of 0 or negative"
  }
}