Method: files.asyncBatchAnnotate

Run asynchronous image detection and annotation for a list of generic files, such as PDF files, which may contain multiple pages and multiple images per page. Progress and results can be retrieved through the google.longrunning.Operations interface. Operation.metadata contains OperationMetadata (metadata). Operation.response contains AsyncBatchAnnotateFilesResponse (results).

HTTP request

POST https://vision.googleapis.com/v1p2beta1/files:asyncBatchAnnotate

The URL uses Google API HTTP annotation syntax.

Request body

The request body contains data with the following structure:

JSON representation
{
  "requests": [
    {
      object(AsyncAnnotateFileRequest)
    }
  ]
}
Fields
requests[]

object(AsyncAnnotateFileRequest)

Individual async file annotation requests for this batch.

Response body

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

This resource represents a long-running operation that is the result of a network API call.

JSON representation
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object(Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
Fields
name

string

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the name should have the format of operations/some/unique/name.

metadata

object

Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata. Any method that returns a long-running operation should document the metadata type, if any.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

done

boolean

If the value is false, it means the operation is still in progress. If true, the operation is completed, and either error or response is available.

Union field result. The operation result, which can be either an error or a valid response. If done == false, neither error nor response is set. If done == true, exactly one of error or response is set. result can be only one of the following:
error

object(Status)

The error result of the operation in case of failure or cancellation.

response

object

The normal response of the operation in case of success. If the original method returns no data on success, such as Delete, the response is google.protobuf.Empty. If the original method is standard Get/Create/Update, the response should be the resource. For other methods, the response should have the type XxxResponse, where Xxx is the original method name. For example, if the original method name is TakeSnapshot(), the inferred response type is TakeSnapshotResponse.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

Authorization Scopes

Requires one of the following OAuth scopes:

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

For more information, see the Auth Guide.

AsyncAnnotateFileRequest

An offline file annotation request.

JSON representation
{
  "inputConfig": {
    object(InputConfig)
  },
  "features": [
    {
      object(Feature)
    }
  ],
  "imageContext": {
    object(ImageContext)
  },
  "outputConfig": {
    object(OutputConfig)
  }
}
Fields
inputConfig

object(InputConfig)

Required. Information about the input file.

features[]

object(Feature)

Required. Requested features.

imageContext

object(ImageContext)

Additional context that may accompany the image(s) in the file.

outputConfig

object(OutputConfig)

Required. The desired output location and metadata (e.g. format).

InputConfig

The desired input location and metadata.

JSON representation
{
  "gcsSource": {
    object(GcsSource)
  },
  "mimeType": string
}
Fields
gcsSource

object(GcsSource)

The Google Cloud Storage location to read the input from.

mimeType

string

The type of the file. Currently only "application/pdf" and "image/tiff" are supported. Wildcards are not supported.

GcsSource

The Google Cloud Storage location where the input will be read from.

JSON representation
{
  "uri": string
}
Fields
uri

string

Google Cloud Storage URI for the input file. This must only be a Google Cloud Storage object. Wildcards are not currently supported.

OutputConfig

The desired output location and metadata.

JSON representation
{
  "gcsDestination": {
    object(GcsDestination)
  },
  "batchSize": number
}
Fields
gcsDestination

object(GcsDestination)

The Google Cloud Storage location to write the output(s) to.

batchSize

number

The max number of response protos to put into each output JSON file on Google Cloud Storage. The valid range is [1, 100]. If not specified, the default value is 20.

For example, for one pdf file with 100 pages, 100 response protos will be generated. If batchSize = 20, then 5 json files each containing 20 response protos will be written under the prefix gcsDestination.uri.

Currently, batchSize only applies to GcsDestination, with potential future support for other output configurations.

GcsDestination

The Google Cloud Storage location where the output will be written to.

JSON representation
{
  "uri": string
}
Fields
uri

string

Google Cloud Storage URI where the results will be stored. Results will be in JSON format and preceded by its corresponding input URI. This field can either represent a single file, or a prefix for multiple outputs. Prefixes must end in a /.

Examples:

If multiple outputs, each response is still AnnotateFileResponse, each of which contains some subset of the full list of AnnotateImageResponse. Multiple outputs can happen if, for example, the output JSON is too large and overflows into multiple sharded files.

Try it!