---
title: "POST /v1/{+parent}/images:annotate"
method: POST
path: "/v1/{+parent}/images:annotate"
tags: ["projects"]
---

# POST /v1/{+parent}/images:annotate

`POST /v1/{+parent}/images:annotate`

Run image detection and annotation for a batch of images.

## Path parameters

- `parent` string, required

## Request body

- BatchAnnotateImagesRequest — Multiple image annotation requests are batched into a single service call.
  - `parent` string — Optional. Target project and location to make a call. Format: `projects/{project-id}/locations/{location-id}`. If no parent is specified, a region will be chosen automatically. Supported location-ids: `us`: USA country only, `asia`: East asia areas, like Japan, Taiwan, `eu`: The European Union. Example: `projects/project-A/locations/eu`.
  - `labels` object — Optional. The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints), can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.
  - `requests` AnnotateImageRequest[] — Required. Individual image annotation requests for this batch.
    - `features` Feature[] — Requested features.
      - `type` 'TYPE_UNSPECIFIED' | 'FACE_DETECTION' | 'LANDMARK_DETECTION' | 'LOGO_DETECTION' | 'LABEL_DETECTION' | 'TEXT_DETECTION' | 'DOCUMENT_TEXT_DETECTION' | 'SAFE_SEARCH_DETECTION' | 'IMAGE_PROPERTIES' | 'CROP_HINTS' | 'WEB_DETECTION' | 'PRODUCT_SEARCH' | 'OBJECT_LOCALIZATION' — The feature type.
      - `model` string — Model to use for the feature. Supported values: "builtin/stable" (the default if unset) and "builtin/latest". `DOCUMENT_TEXT_DETECTION` and `TEXT_DETECTION` also support "builtin/rc" for the latest release candidate.
      - `maxResults` integer — Maximum number of results of this type. Does not apply to `TEXT_DETECTION`, `DOCUMENT_TEXT_DETECTION`, or `CROP_HINTS`.
    - `image` Image — Client image to perform Google Cloud Vision API tasks over.
      - `source` ImageSource — External image source (Google Cloud Storage or web URL image location).
        - `gcsImageUri` string — **Use `image_uri` instead.** The Google Cloud Storage URI of the form `gs://bucket_name/object_name`. Object versioning is not supported. See [Google Cloud Storage Request URIs](https://cloud.google.com/storage/docs/reference-uris) for more info.
        - `imageUri` string — The URI of the source image. Can be either: 1. A Google Cloud Storage URI of the form `gs://bucket_name/object_name`. Object versioning is not supported. See [Google Cloud Storage Request URIs](https://cloud.google.com/storage/docs/reference-uris) for more info. 2. A publicly-accessible image HTTP/HTTPS URL. When fetching images from HTTP/HTTPS URLs, Google cannot guarantee that the request will be completed. Your request may fail if the specified host denies the request (e.g. due to request throttling or DOS prevention), or if Google throttles requests to the site for abuse prevention. You should not depend on externally-hosted images for production applications. When both `gcs_image_uri` and `image_uri` are specified, `image_uri` takes precedence.
      - `content` string, byte — Image content, represented as a stream of bytes. Note: As with all `bytes` fields, protobuffers use a pure binary representation, whereas JSON representations use base64. Currently, this field only works for BatchAnnotateImages requests. It does not work for AsyncBatchAnnotateImages requests.
    - `imageContext` ImageContext — Image context and/or feature-specific parameters.
      - `latLongRect` LatLongRect — Rectangle determined by min and max `LatLng` pairs.
        - `minLatLng` LatLng — An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard. Values must be within normalized ranges.
          - `latitude` number, double — The latitude in degrees. It must be in the range [-90.0, +90.0].
          - `longitude` number, double — The longitude in degrees. It must be in the range [-180.0, +180.0].
        - `maxLatLng` LatLng — An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard. Values must be within normalized ranges.
          - `latitude` number, double — The latitude in degrees. It must be in the range [-90.0, +90.0].
          - `longitude` number, double — The longitude in degrees. It must be in the range [-180.0, +180.0].
      - `cropHintsParams` CropHintsParams — Parameters for crop hints annotation request.
        - `aspectRatios` number[] — Aspect ratios in floats, representing the ratio of the width to the height of the image. For example, if the desired aspect ratio is 4/3, the corresponding float value should be 1.33333. If not specified, the best possible crop is returned. The number of provided aspect ratios is limited to a maximum of 16; any aspect ratios provided after the 16th are ignored.
      - `languageHints` string[] — List of languages to use for TEXT_DETECTION. In most cases, an empty value yields the best results since it enables automatic language detection. For languages based on the Latin alphabet, setting `language_hints` is not needed. In rare cases, when the language of the text in the image is known, setting a hint will help get better results (although it will be a significant hindrance if the hint is wrong). Text detection returns an error if one or more of the specified languages is not one of the [supported languages](https://cloud.google.com/vision/docs/languages).
      - `textDetectionParams` TextDetectionParams — Parameters for text detections. This is used to control TEXT_DETECTION and DOCUMENT_TEXT_DETECTION features.
        - `enableTextDetectionConfidenceScore` boolean — By default, Cloud Vision API only includes confidence score for DOCUMENT_TEXT_DETECTION result. Set the flag to true to include confidence score for TEXT_DETECTION as well.
        - `advancedOcrOptions` string[] — A list of advanced OCR options to further fine-tune OCR behavior. Current valid values are: - `legacy_layout`: a heuristics layout detection algorithm, which serves as an alternative to the current ML-based layout detection algorithm. Customers can choose the best suitable layout algorithm based on their situation.
      - `productSearchParams` ProductSearchParams — Parameters for a product search request.
        - `boundingPoly` BoundingPoly — A bounding polygon for the detected image annotation.
          - `normalizedVertices` NormalizedVertex[] — The bounding polygon normalized vertices.
            - `x` number, float — X coordinate.
            - `y` number, float — Y coordinate.
          - `vertices` Vertex[] — The bounding polygon vertices.
            - `x` integer — X coordinate.
            - `y` integer — Y coordinate.
        - `filter` string — The filtering expression. This can be used to restrict search results based on Product labels. We currently support an AND of OR of key-value expressions, where each expression within an OR must have the same key. An '=' should be used to connect the key and value. For example, "(color = red OR color = blue) AND brand = Google" is acceptable, but "(color = red OR brand = Google)" is not acceptable. "color: red" is not acceptable because it uses a ':' instead of an '='.
        - `productSet` string — The resource name of a ProductSet to be searched for similar images. Format is: `projects/PROJECT_ID/locations/LOC_ID/productSets/PRODUCT_SET_ID`.
        - `productCategories` string[] — The list of product categories to search in. Currently, we only consider the first category, and either "homegoods-v2", "apparel-v2", "toys-v2", "packagedgoods-v1", or "general-v1" should be specified. The legacy categories "homegoods", "apparel", and "toys" are still supported but will be deprecated. For new products, please use "homegoods-v2", "apparel-v2", or "toys-v2" for better product search accuracy. It is recommended to migrate existing products to these categories as well.
      - `webDetectionParams` WebDetectionParams — Parameters for web detection request.
        - `includeGeoResults` boolean — This field has no effect on results.

## Response `200`

Successful response

---

[API](https://skmtc.net/google/apis/vision.md) · [All operations](https://skmtc.net/google/apis/vision/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/vision/versions/d5becca397b9/schema)