Quickstart: Using the command line

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

Cloud 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. Select or create a GCP project.

   Note: If you don't plan to keep the resources you create in this procedure, create a new project instead of selecting an existing project. After you finish following these steps, you can delete the project, removing all resources associated with the project.

   Go to the Project selector page

3. Make sure that billing is enabled for your Google Cloud Platform project.

   Learn how to enable billing

4. Enable the Vision API.

   Enable the API

5. Set up authentication:

   1. In the GCP 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.

      Note: The Role field authorizes your service account to access resources. You can view and change this field later by using the GCP Console. If you are developing a production app, specify more granular permissions than Project > Owner. For more information, see granting roles to service accounts.
   5. Click Create. A JSON file that contains your key downloads to your computer.

6. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the file 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.

   Example: Linux or macOS

   Replace [PATH] with the file path of the JSON file that contains your service account key.

   export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   Replace [PATH] with the file path of the JSON file that contains your service account key, and [FILE_NAME] with the filename.

   With PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\[FILE_NAME].json"

   With command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=[PATH]

7. Install and initialize the Cloud SDK.

Make an image annotation request

After completing the Before you begin steps you can use 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:

Google Cloud Storage URI:

gs://cloud-samples-data/vision/using_curl/shanghai.jpeg

HTTPS URL:

https://console.cloud.google.com/storage/browser/cloud-samples-data/vision/using_curl/shanghai.jpeg

Image credit: Steve Long, 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:

request.json

{
  'requests': [
    {
      'image': {
        'source': {
          'gcsImageUri': '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'
        },
      ]
    }
  ]
}

Field value details

• image.source.gcsImageUri - Indicates the image stored in a Google Cloud Storage bucket. You change this request to image.source.imageUri for a publicly available URI, or image.content to pass a base64 encoded string representation of an image.
• features - An object representing a specific feature type. You can request multiple feature types for a single image.
• type - The enum value specifying a feature.
• maxResults (optional) - A limiting value on the results returned.
• model (optional) - If applicable you can specify either builtin/stable (the default if unset) or builtin/latest to choose your model. Refer to the Release notes topic for a list of recently updated models.

Send the request

You use curl and the body content from request.json to send the request to the Cloud 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

• The sample curl command uses the gcloud auth application-default print-access-token command to get an authentication token.
• Note that to pass a filename to curl you use the -d option (for "data") and precede the filename with an @ sign. This file should be in the same directory in which you execute the curl command.

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:

• three labelAnnotations results
• one textAnnotations result (shortened for clarity)
• one localizedObjectAnnotations result

Response

Note: Zero coordinate values omitted. When the API detects a coordinate ("x" or "y") value of 0, that coordinate is omitted in the JSON response. Thus, a response with a bounding poly around the entire image would be
[{},{"x": 100},{"x": 100,"y": 100},{"y": 100}] for an image that is 100px by 100px. For more information, see the API Reference documentation.

{
  "responses": [
    {
      "labelAnnotations": [
        {
          "mid": "/m/09g5pq",
          "description": "People",
          "score": 0.9504782,
          "topicality": 0.9504782
        },
        {
          "mid": "/m/01c8br",
          "description": "Street",
          "score": 0.8911568,
          "topicality": 0.8911568
        },
        {
          "mid": "/m/079bkr",
          "description": "Mode of transport",
          "score": 0.89089024,
          "topicality": 0.89089024
        }
      ],
      "textAnnotations": [
        {
          "locale": "zh",
          "description": "牛牛面馆\n",
          "boundingPoly": {
            "vertices": [
              {
                "x": 159,
                "y": 212
              },
              {
                "x": 947,
                "y": 212
              },
              {
                "x": 947,
                "y": 354
              },
              {
                "x": 159,
                "y": 354
              }
            ]
          }
        },
        ...
      ],
      "fullTextAnnotation": {
        "pages": [
          {
            ...
                "paragraphs": [
                  {
                    ...
                    "words": [
                      {
                        ...
                        "symbols": [
                          {
                            ...
                ],
                "blockType": "TEXT"
              }
            ]
          }
        ],
        "text": "牛牛面馆\n"
      },
      "localizedObjectAnnotations": [
        {
          "mid": "/m/01g317",
          "name": "Person",
          "score": 0.94413143,
          "boundingPoly": {
            "normalizedVertices": [
              {
                "x": 0.26063988,
                "y": 0.46869153
              },
              {
                "x": 0.40736017,
                "y": 0.46869153
              },
              {
                "x": 0.40736017,
                "y": 0.8957791
              },
              {
                "x": 0.26063988,
                "y": 0.8957791
              }
            ]
          }
        }
      ]
    }
  ]
}

Label detection results

1. description: "People", score: 0.950
2. description: "Street", score: 0.891
3. description: "Mode of transport", score: 0.890

Text detection results

• text: 牛牛面馆\n
• vertices: (x: 159, y: 212), (x: 947, y: 212), (x: 947, y: 354), (x: 159, y: 354 )

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)

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

What's next

• See a list of all feature types and their uses.
• Get started with the Vision API in your language of choice by using a Vision API Client Library.
• Use the How-to guides to learn more about specific features, see example annotations, and get annotations for an individual file or image.
• Learn about batch image and file (PDF/TIFF/GIF) annotation.
• Work through the sample applications.
• Browse more specific use cases on the community tutorials page.