search_users_by_image async ¶

async def search_users_by_image(
    self,
    collection_id: "capo_rekognition.types.collection_id.CollectionId",
    image: "capo_rekognition.types.image.Image",
    *,
    config_overrides: Optional[AsyncRekognitionClientConfig] = None,
    user_match_threshold: Optional["capo_rekognition.types.percent.Percent"] = None,
    max_users: Optional[
        "capo_rekognition.types.max_user_results.MaxUserResults"
    ] = None,
    quality_filter: Optional[
        "capo_rekognition.types.quality_filter.QualityFilter"
    ] = None,
) -> "capo_rekognition.types.search_users_by_image_response.SearchUsersByImageResponse":
    """<p>Searches for UserIDs using a supplied image. It first detects the largest face in the image, and then searches a specified collection for matching UserIDs. </p> <p>The operation returns an array of UserIDs that match the face in the supplied image, ordered by similarity score with the highest similarity first. It also returns a bounding box for the face found in the input image. </p> <p>Information about faces detected in the supplied image, but not used for the search, is returned in an array of <code>UnsearchedFace</code> objects. If no valid face is detected in the image, the response will contain an empty <code>UserMatches</code> list and no <code>SearchedFace</code> object. </p>

    Args:
        collection_id: <p>The ID of an existing collection containing the UserID.</p>
        user_match_threshold: <p>Specifies the minimum confidence in the UserID match to return. Default value is 80.</p>
        max_users: <p>Maximum number of UserIDs to return.</p>
        quality_filter: <p>A filter that specifies a quality bar for how much filtering is done to identify faces. Filtered faces aren't searched for in the collection. The default value is NONE.</p>

    Raises:
        capo_rekognition.errors.access_denied_exception.AccessDeniedException: <p>You are not authorized to perform the action.</p>
        capo_rekognition.errors.image_too_large_exception.ImageTooLargeException: <p>The input image size exceeds the allowed limit. If you are calling DetectProtectiveEquipment, the image size or resolution exceeds the allowed limit. For more information, see Guidelines and quotas in Amazon Rekognition in the Amazon Rekognition Developer Guide. </p>
        capo_rekognition.errors.internal_server_error.InternalServerError: <p>Amazon Rekognition experienced a service issue. Try your call again.</p>
        capo_rekognition.errors.invalid_image_format_exception.InvalidImageFormatException: <p>The provided image format is not supported. </p>
        capo_rekognition.errors.invalid_parameter_exception.InvalidParameterException: <p>Input parameter violated a constraint. Validate your parameter before calling the API operation again.</p>
        capo_rekognition.errors.invalid_s3_object_exception.InvalidS3ObjectException: <p>Amazon Rekognition is unable to access the S3 object specified in the request.</p>
        capo_rekognition.errors.provisioned_throughput_exceeded_exception.ProvisionedThroughputExceededException: <p>The number of requests exceeded your throughput limit. If you want to increase this limit, contact Amazon Rekognition.</p>
        capo_rekognition.errors.resource_not_found_exception.ResourceNotFoundException: <p>The resource specified in the request cannot be found.</p>
        capo_rekognition.errors.throttling_exception.ThrottlingException: <p>Amazon Rekognition is temporarily unable to process the request. Try your call again.</p>
        capo_rekognition.errors.UnknownServiceError: The service returned an error code this client does not model.

    Examples:
        SearchUsersByImage
        Searches for UserIDs using a supplied image.

        >>> await client.search_users_by_image(collection_id='MyCollection', image={'S3Object': {'Bucket': 'bucket', 'Name': 'input.jpg'}}, max_users=2, user_match_threshold=70, quality_filter='MEDIUM')
    """

    async def _handler(
        req: "AsyncOperationRequest[capo_rekognition.types.search_users_by_image_request.SearchUsersByImageRequest]",
    ) -> AsyncOperationResponse[
        "capo_rekognition.types.search_users_by_image_response.SearchUsersByImageResponse"
    ]:
        import capo_rekognition._operations.rekognition_service.search_users_by_image

        (
            output,
            http_response,
        ) = await capo_rekognition._operations.rekognition_service.search_users_by_image.async_search_users_by_image(
            req.options, req.input
        )
        return AsyncOperationResponse(output=output, response=http_response)

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("SearchUsersByImage")
    )
    input_: capo_rekognition.types.search_users_by_image_request.SearchUsersByImageRequest = {
        "collection_id": collection_id,
        "image": image,
    }
    if user_match_threshold is not None:
        input_["user_match_threshold"] = user_match_threshold
    if max_users is not None:
        input_["max_users"] = max_users
    if quality_filter is not None:
        input_["quality_filter"] = quality_filter

    response = await aexecute_pipeline(
        AsyncOperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    await response.response.aclose()
    return response.output