Quickstart: Using the command line

This page shows you how to send three feature detection and annotation requests to the Vision API using the REST interface and the curl command.

Vision API enables easy integration of Google vision recognition technologies into developer applications. You can send image data and desired feature types to the Vision API, which then returns a corresponding response based on the image attributes you are interested in. For more information about the feature types offered, see the List of all Vision API features.

Before you begin

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to the project selector page

  3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  4. Enable the Vision API.

    Enable the API

  5. Set up authentication:
    1. In the Cloud Console, go to the Create service account key page.

      Go to the Create Service Account Key page
    2. From the Service account list, select New service account.
    3. In the Service account name field, enter a name.
    4. From the Role list, select Project > Owner.

    5. Click Create. A JSON file that contains your key downloads to your computer.
  6. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your service account key. This variable only applies to your current shell session, so if you open a new session, set the variable again.

  7. Install and initialize the Cloud SDK.

Make an image annotation request

After completing the Before you begin steps you can use the Vision API to annotate an image file.

In this example you use curl to send a request to the Vision API using the following image:

Cloud Storage URI:




Shanghai street image
Image credit: Steve Long on Unsplash.

Create the request JSON

The following request.json file demonstrates how to request three images:annotate features and limit the results in the response.

Create the JSON request file with the following text, and save it as a request.json plain text file in your working directory:


  "requests": [
      "image": {
        "source": {
          "imageUri": "gs://cloud-samples-data/vision/using_curl/shanghai.jpeg"
      "features": [
          "type": "LABEL_DETECTION",
          "maxResults": 3
          "type": "OBJECT_LOCALIZATION",
          "maxResults": 1
          "type": "TEXT_DETECTION",
          "maxResults": 1,
          "model": "builtin/latest"

Send the request

You use curl and the body content from request.json to send the request to the Vision API. Enter the following on your command line:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
https://vision.googleapis.com/v1/images:annotate -d @request.json

Interpret the response

You should see a JSON response similar to the one below.

The request JSON body specified maxResults for each annotation type. Consequently, you will see the following in the response JSON:

Label detection results

  1. description: "People", score: 0.950
  2. description: "Street", score: 0.891
  3. description: "Mode of transport", score: 0.890
Shanghai street image
Image credit: Steve Long on Unsplash (annotations added).

Text detection results

  • text: 牛牛面馆\n
  • vertices: (x: 159, y: 212), (x: 947, y: 212), (x: 947, y: 354), (x: 159, y: 354 )
Shanghai street image
Image credit: Steve Long on Unsplash (annotations added).

Object detection results

  • name: "Person", score: 0.944
  • normalized vertices: (x: 0.260, y: 0.468), (x: 0.407, y: 0.468), (x: 0.407, y: 0.895), (x: 0.260, y: 0.895)
Shanghai street image
Image credit: Steve Long on Unsplash (annotations added).

Congratulations! You've sent your first request to the Vision API.

What's next