Method: projects.predict

Performs prediction on the data in the request.

HTTP request

POST https://ml.googleapis.com/v1/{name=projects/**}:predict

The URL uses Google API HTTP annotation syntax.

Path parameters

Parameters
name

string

Required. The resource name of a model or a version. If a model is specified without a version, the default version is used.

Authorization: requires Viewer role on the parent project.

Request body

The request body contains data with the following structure:

JSON representation
{
  "instances": {[
    object
  ]},
}
Fields
instances[]

object

Required. The list of instances to get predictions for.

The structure of each element of the instances list is determined by your model's input definition. Instances can include named inputs or can contain only unlabeled values.

Not all data includes named inputs. Some instances will be simple JSON values (boolean, number, or string). However, instances are often lists of simple values, or complex nested lists. Here are some examples of request bodies:

CSV data with each row encoded as a string value:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

Plain text:

{"instances": ["the quick brown fox", "la bruja le dio"]}

Sentences encoded as lists of words (vectors of strings):

{
  "instances": [
    ["the","quick","brown"],
    ["la","bruja","le"],
    ...
  ]
}

Floating point scalar values:

{"instances": [0.0, 1.1, 2.2]}

Vectors of integers:

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

Tensors (in this case, two-dimensional tensors):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

Images can be represented different ways. In this encoding scheme the first two dimensions represent the rows and columns of the image, and the third contains lists (vectors) of the R, G, and B values for each pixel:

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

Data encoding

JSON strings must be encoded as UTF-8. To send binary data, you must base64-encode the data and mark it as binary. To mark a JSON string as binary, replace it with a JSON object with a single attribute named `b64`:

{"b64": "..."} 

The following two examples show instances that require base64 encoding.

Two Serialized tf.Examples (fake data, for illustrative purposes only):

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

Two JPEG image byte strings (fake data, for illustrative purposes only):

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

Named references

If your data includes named references, format each instance as a JSON object with the named references as the keys:

JSON input data to be preprocessed:

{
  "instances": [
    {
      "a": 1.0,
      "b": true,
      "c": "x"
    },
    {
      "a": -2.0,
      "b": false,
      "c": "y"
    }
  ]
}

Multiple input tensors

Some models have an underlying TensorFlow graph that accepts multiple input tensors. In this case, you should use the names of JSON name/value pairs to identify the input tensors, as shown in the following exmaples:

For a graph with input tensor aliases "tag" (string) and "image" (base64-encoded string):

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

For a graph with input tensor aliases "tag" (string) and "image" (3-dimensional array of 8-bit ints):

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

Response body

If successful, the response body contains data with the following structure:

Response message for the projects.predict method.

JSON representation
{
  "predictions": [
    {
      object
    }
  ]
}

or

{
  "error": 
      string
}
Fields
predictions[]

object

The list of predictions, one per instance in the request.

error

string

On error, a message describing the problem. Returned instead of a prediction list if an error occurred while processing any instance.

Responses are very similar to requests.

If the call is successful, the response body will contain one prediction entry per instance in the request body, given in the same order. If prediction fails for any instance, the response body will contain no predictions and will contian a single error entry instead.

Even though there is one prediction per instance, the format of a prediction is not directly related to the format of an instance. Predictions take whatever format is specified in the outputs collection defined in the model. The collection of predictions is returned in a JSON list. Each member of the list can be a simple value, a list, or a JSON object of any complexity. If your model has more than one output tensor, each prediction will be a JSON object containing a name/value pair for each output. The names identify the output aliases in the graph.

The following examples show some possible responses:

A simple set of predictions for three input instances, where each prediction is an integer value:

{"predictions": [5, 4, 3]}

A more complex set of predictions, each containing two named values that correspond to output tensors, named label and scores respectively. The value of label is the predicted category ("car" or "beach") and scores contains a list of probabilities for that instance across the possible categories.

{
  "predictions": [
    {
      "label": "beach",
      "scores": [0.1, 0.9]
    },
    {
      "label": "car",
      "scores": [0.75, 0.25]
    }
  ]
}

A response when there is an error processing an input instance:

{"error": "Divide by zero"}

Authorization

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Auth Guide.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Machine Learning Engine (Cloud ML Engine)