Package vision provides a client for the Google Cloud Vision API.

Google Cloud Vision allows easy integration of vision detection features into developer applications, including image labeling, face and landmark detection, optical character recognition (OCR), and tagging of explicit content. For more information about Cloud Vision, read the Google Cloud Vision API Documentation at

Creating Images

The Cloud Vision API supports a variety of image file formats, including JPEG, PNG8, PNG24, Animated GIF (first frame only), and RAW. See for the complete list of formats. Be aware that Cloud Vision sets upper limits on file size as well as on the total combined size of all images in a request. Reducing your file size can significantly improve throughput; however, be careful not to reduce image quality in the process. See for current file size limits.

Creating an Image instance does not perform an API request.

Use NewImageFromReader to obtain an image from any io.Reader, such as an open file:

f, err := os.Open("path/to/image.jpg")
if err != nil { ... }
defer f.Close()
img, err := vision.NewImageFromReader(f)
if err != nil { ... }

Use NewImageFromGCS to refer to an image in Google Cloud Storage:

img := vision.NewImageFromGCS("gs://my-bucket/my-image.png")

Annotating Images

Client.Annotate is the most general method in the package. It can run multiple detections on multiple images with a single API call.

To describe the detections you want to perform on an image, create an AnnotateRequest and specify the maximum number of results to return for each detection of interest. The exceptions are safe search and image properties, where a boolean is used instead.

resultSlice, err := client.Annotate(ctx, &vision.AnnotateRequest{
    Image:      img,
    MaxLogos:   5,
    MaxTexts:   100,
    SafeSearch: true,
if err != nil { ... }

You can pass as many AnnotateRequests as desired to client.Annotate. The return value is a slice of an Annotations. Each Annotations value may contain an Error along with one or more successful results. The failed detections will have a nil annotation.

result := resultSlice[0]
if result.Error != nil { ... } // some detections failed
for _, logo := range result.Logos { ... }
for _, text := range result.Texts { ... }
if result.SafeSearch != nil { ... }

Other methods on Client run a single detection on a single image. For instance, Client.DetectFaces will run face detection on the provided Image. These methods return a single annotation of the appropriate type (for example, DetectFaces returns a FaceAnnotation). The error return value incorporates both API call errors and the detection errors stored in Annotations.Error, simplifying your logic.

faces, err := client.DetectFaces(ctx, 10) // maximum of 10 faces
if err != nil { ... }

Here faces is a slice of FaceAnnotations. The Face field of each FaceAnnotation provides easy access to the positions of facial features:


This package is experimental and subject to API changes.

Imported only in test by 2 package(s)


Imports 9 package(s)


Test imports 1 package(s)