On January 1, 2020 this library will no longer support Python 2 on the latest released version. Previously released library versions will continue to be available. For more information please visit Python 2 support on Google Cloud.

Client for Google Cloud Vision API

class google.cloud.vision_v1p2beta1.ImageAnnotatorClient(transport=None, channel=None, credentials=None, client_config=None, client_info=None, client_options=None)

Service that performs Google Cloud Vision API detection tasks over client images, such as face, landmark, logo, label, and text detection. The ImageAnnotator service returns detected entities from the images.

Constructor.

Parameters

• (Union[ImageAnnotatorGrpcTransport, (transport) – Callable[[~.Credentials, type], ~.ImageAnnotatorGrpcTransport]): A transport instance, responsible for actually making the API calls. The default transport uses the gRPC protocol. This argument may also be a callable which returns a transport instance. Callables will be sent the credentials as the first argument and the default transport class as the second argument.

• channel (grpc.Channel) – DEPRECATED. A Channel instance through which to make calls. This argument is mutually exclusive with credentials; providing both will raise an exception.

• credentials (google.auth.credentials.Credentials) – The authorization credentials to attach to requests. These credentials identify this application to the service. If none are specified, the client will attempt to ascertain the credentials from the environment. This argument is mutually exclusive with providing a transport instance to transport; doing so will raise an exception.

• client_config (dict) – DEPRECATED. A dictionary of call options for each method. If not specified, the default configuration is used.

• client_info (google.api_core.gapic_v1.client_info.ClientInfo) – The client info used to send a user-agent string along with API requests. If None, then default info will be used. Generally, you only need to set this if you’re developing your own client library.

• client_options (Union[dict, google.api_core.client_options.ClientOptions]) – Client options used to set user options on the client. API Endpoint should be set through client_options.

annotate_image(request, retry=None, timeout=None)

Run image detection and annotation for an image.

Example

>>> from google.cloud.vision_v1 import ImageAnnotatorClient
>>> client = ImageAnnotatorClient()
>>> request = {
...     'image': {
...         'source': {'image_uri': 'https://foo.com/image.jpg'},
...     },
... }
>>> response = client.annotate_image(request)

Parameters

• request (AnnotateImageRequest) –

• retry (Optional[google.api_core.retry.Retry]) – A retry object used to retry requests. If None is specified, requests will not be retried.

• timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

Returns

AnnotateImageResponse The API response.

async_batch_annotate_files(requests, retry=<object object>, timeout=<object object>, metadata=None)

Run async image detection and annotation for a list of generic files (e.g. PDF) 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).

Example

>>> from google.cloud import vision_v1p2beta1
>>>
>>> client = vision_v1p2beta1.ImageAnnotatorClient()
>>>
>>> # TODO: Initialize `requests`:
>>> requests = []
>>>
>>> response = client.async_batch_annotate_files(requests)
>>>
>>> def callback(operation_future):
...     # Handle result.
...     result = operation_future.result()
>>>
>>> response.add_done_callback(callback)
>>>
>>> # Handle metadata.
>>> metadata = response.metadata()

Parameters

• requests (list[Union[dict, AsyncAnnotateFileRequest]]) –

  Required. Individual async file annotation requests for this batch.

  If a dict is provided, it must be of the same form as the protobuf message AsyncAnnotateFileRequest

• retry (Optional[google.api_core.retry.Retry]) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

• timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

• metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.

Returns

A _OperationFuture instance.

Raises

• google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.

• google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.

• ValueError – If the parameters are invalid.

batch_annotate_images(requests, retry=<object object>, timeout=<object object>, metadata=None)

Run image detection and annotation for a batch of images.

Example

>>> from google.cloud import vision_v1p2beta1
>>>
>>> client = vision_v1p2beta1.ImageAnnotatorClient()
>>>
>>> # TODO: Initialize `requests`:
>>> requests = []
>>>
>>> response = client.batch_annotate_images(requests)

Parameters

• requests (list[Union[dict, AnnotateImageRequest]]) –

  Required. Individual image annotation requests for this batch.

  If a dict is provided, it must be of the same form as the protobuf message AnnotateImageRequest

• retry (Optional[google.api_core.retry.Retry]) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

• timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

• metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.

Returns

A BatchAnnotateImagesResponse instance.

Raises

• google.api_core.exceptions.GoogleAPICallError – If the request failed for any reason.

• google.api_core.exceptions.RetryError – If the request failed due to a retryable error and retry attempts failed.

• ValueError – If the parameters are invalid.

crop_hints(image, max_results=None, retry=None, timeout=None, **kwargs)

Return crop hints information.

Parameters

• image (Image) – The image to analyze.

• max_results (int) – Number of results to return, does not apply for TEXT_DETECTION, DOCUMENT_TEXT_DETECTION, or CROP_HINTS.

• retry (int) – Number of retries to do before giving up.

• timeout (int) – Number of seconds before timing out.

• kwargs (dict) – Additional properties to be set on the AnnotateImageRequest.

Returns

The API response.

Return type

AnnotateImageResponse

document_text_detection(image, max_results=None, retry=None, timeout=None, **kwargs)

Perform document text detection.

Parameters

• image (Image) – The image to analyze.

• max_results (int) – Number of results to return, does not apply for TEXT_DETECTION, DOCUMENT_TEXT_DETECTION, or CROP_HINTS.

• retry (int) – Number of retries to do before giving up.

• timeout (int) – Number of seconds before timing out.

• kwargs (dict) – Additional properties to be set on the AnnotateImageRequest.

Returns

The API response.

Return type

AnnotateImageResponse

enums = <module 'google.cloud.vision_v1p2beta1.gapic.enums' from '/tmpfs/src/github/python-vision/google/cloud/vision_v1p2beta1/gapic/enums.py'>

face_detection(image, max_results=None, retry=None, timeout=None, **kwargs)

Perform face detection.

Parameters

• image (Image) – The image to analyze.

• max_results (int) – Number of results to return, does not apply for TEXT_DETECTION, DOCUMENT_TEXT_DETECTION, or CROP_HINTS.

• retry (int) – Number of retries to do before giving up.

• timeout (int) – Number of seconds before timing out.

• kwargs (dict) – Additional properties to be set on the AnnotateImageRequest.

Returns

The API response.

Return type

AnnotateImageResponse

classmethod from_service_account_file(filename, *args, **kwargs)

Creates an instance of this client using the provided credentials file.

Parameters

• filename (str) – The path to the service account private key json file.

• args – Additional arguments to pass to the constructor.

• kwargs – Additional arguments to pass to the constructor.

Returns

The constructed client.

Return type

ImageAnnotatorClient

classmethod from_service_account_json(filename, *args, **kwargs)

Creates an instance of this client using the provided credentials file.

Parameters

• filename (str) – The path to the service account private key json file.

• args – Additional arguments to pass to the constructor.

• kwargs – Additional arguments to pass to the constructor.

Returns

The constructed client.

Return type

ImageAnnotatorClient

image_properties(image, max_results=None, retry=None, timeout=None, **kwargs)

Return image properties information.

Parameters

• image (Image) – The image to analyze.

• max_results (int) – Number of results to return, does not apply for TEXT_DETECTION, DOCUMENT_TEXT_DETECTION, or CROP_HINTS.

• retry (int) – Number of retries to do before giving up.

• timeout (int) – Number of seconds before timing out.

• kwargs (dict) – Additional properties to be set on the AnnotateImageRequest.

Returns

The API response.

Return type

AnnotateImageResponse

label_detection(image, max_results=None, retry=None, timeout=None, **kwargs)

Perform label detection.

Parameters

• image (Image) – The image to analyze.

• max_results (int) – Number of results to return, does not apply for TEXT_DETECTION, DOCUMENT_TEXT_DETECTION, or CROP_HINTS.

• retry (int) – Number of retries to do before giving up.

• timeout (int) – Number of seconds before timing out.

• kwargs (dict) – Additional properties to be set on the AnnotateImageRequest.

Returns

The API response.

Return type

AnnotateImageResponse

landmark_detection(image, max_results=None, retry=None, timeout=None, **kwargs)

Perform landmark detection.

Parameters

• image (Image) – The image to analyze.

• max_results (int) – Number of results to return, does not apply for TEXT_DETECTION, DOCUMENT_TEXT_DETECTION, or CROP_HINTS.

• retry (int) – Number of retries to do before giving up.

• timeout (int) – Number of seconds before timing out.

• kwargs (dict) – Additional properties to be set on the AnnotateImageRequest.

Returns

The API response.

Return type

AnnotateImageResponse

logo_detection(image, max_results=None, retry=None, timeout=None, **kwargs)

Perform logo detection.

Parameters

• image (Image) – The image to analyze.

• max_results (int) – Number of results to return, does not apply for TEXT_DETECTION, DOCUMENT_TEXT_DETECTION, or CROP_HINTS.

• retry (int) – Number of retries to do before giving up.

• timeout (int) – Number of seconds before timing out.

• kwargs (dict) – Additional properties to be set on the AnnotateImageRequest.

Returns

The API response.

Return type

AnnotateImageResponse

safe_search_detection(image, max_results=None, retry=None, timeout=None, **kwargs)

Perform safe search detection.

Parameters

• image (Image) – The image to analyze.

• max_results (int) – Number of results to return, does not apply for TEXT_DETECTION, DOCUMENT_TEXT_DETECTION, or CROP_HINTS.

• retry (int) – Number of retries to do before giving up.

• timeout (int) – Number of seconds before timing out.

• kwargs (dict) – Additional properties to be set on the AnnotateImageRequest.

Returns

The API response.

Return type

AnnotateImageResponse

text_detection(image, max_results=None, retry=None, timeout=None, **kwargs)

Perform text detection.

Parameters

• image (Image) – The image to analyze.

• max_results (int) – Number of results to return, does not apply for TEXT_DETECTION, DOCUMENT_TEXT_DETECTION, or CROP_HINTS.

• retry (int) – Number of retries to do before giving up.

• timeout (int) – Number of seconds before timing out.

• kwargs (dict) – Additional properties to be set on the AnnotateImageRequest.

Returns

The API response.

Return type

AnnotateImageResponse

web_detection(image, max_results=None, retry=None, timeout=None, **kwargs)

Perform web detection.

Parameters

• image (Image) – The image to analyze.

• max_results (int) – Number of results to return, does not apply for TEXT_DETECTION, DOCUMENT_TEXT_DETECTION, or CROP_HINTS.

• retry (int) – Number of retries to do before giving up.

• timeout (int) – Number of seconds before timing out.

• kwargs (dict) – Additional properties to be set on the AnnotateImageRequest.

Returns

The API response.

Return type

AnnotateImageResponse