Add support for visual_search Admin API

Author: const-cloudinary

cloudinary/api.py

@@ -155,6 +155,26 @@ def resources_by_context(key, value=None, **options):
     return call_api("get", uri, params, **options)
 
 
+def visual_search(image_url=None, image_asset_id=None, text=None, **options):
+    """
+    Find images based on their visual content.
+
+    :param image_url:       The URL of an image.
+    :type image_url:        str
+    :param image_asset_id:  The asset_id of an image in your account.
+    :type image_asset_id:   str
+    :param text:            A textual description, e.g., "cat"
+    :type text:             str
+    :param options:         Additional options
+    :type options:          dict, optional
+    :return:                Resources (assets) that were found
+    :rtype:                 Response
+    """
+    uri = ["resources", "visual_search"]
+    params = {"image_url": image_url, "image_asset_id": image_asset_id, "text": text}
+    return call_api("get", uri, params, **options)
+
+
 def resource(public_id, **options):
     resource_type = options.pop("resource_type", "image")
     upload_type = options.pop("type", "upload")

cloudinary/utils.py

@@ -106,6 +106,7 @@
     "categorization",
     "detection",
     "similarity_search",
+    "visual_search",
     "background_removal",
     "upload_preset",
     "phash",

test/test_api.py

@@ -10,9 +10,9 @@
 import cloudinary
 from cloudinary import api, uploader, utils
 from cloudinary.utils import fq_public_id
-from test.helper_test import SUFFIX, TEST_IMAGE, get_uri, get_headers, get_params, get_list_param, get_param, TEST_DOC, get_method, \
-    UNIQUE_TAG, api_response_mock, ignore_exception, cleanup_test_resources_by_tag, cleanup_test_transformation, \
-    cleanup_test_resources, UNIQUE_TEST_FOLDER, EVAL_STR, get_json_body
+from test.helper_test import SUFFIX, TEST_IMAGE, get_uri, get_headers, get_params, get_list_param, get_param, \
+    TEST_DOC, get_method, UNIQUE_TAG, api_response_mock, ignore_exception, cleanup_test_resources_by_tag, \
+    cleanup_test_transformation, cleanup_test_resources, UNIQUE_TEST_FOLDER, EVAL_STR, get_json_body, REMOTE_TEST_IMAGE
 from cloudinary.exceptions import BadRequest, NotFound
 
 MOCK_RESPONSE = api_response_mock()
@@ -284,6 +284,22 @@ def test06b_resources_direction(self, mocker):
         self.assertTrue(get_uri(args).endswith('/resources/image/tags/{}'.format(API_TEST_TAG)))
         self.assertEqual(get_params(args)['direction'], 'desc')
 
+    @patch('urllib3.request.RequestMethods.request')
+    @unittest.skipUnless(cloudinary.config().api_secret, "requires api_key/api_secret")
+    def test_visual_search(self, mocker):
+        """ should allow using visual search """
+        mocker.return_value = MOCK_RESPONSE
+
+        api.visual_search(REMOTE_TEST_IMAGE, API_TEST_ASSET_ID, "sample image")
+
+        args, kwargs = mocker.call_args
+        self.assertTrue(get_uri(args).endswith('/resources/visual_search'))
+
+        params = get_params(args)
+        self.assertEqual(REMOTE_TEST_IMAGE, params['image_url'])
+        self.assertEqual(API_TEST_ASSET_ID, params['image_asset_id'])
+        self.assertEqual("sample image", params['text'])
+
     @patch('urllib3.request.RequestMethods.request')
     @unittest.skipUnless(cloudinary.config().api_secret, "requires api_key/api_secret")
     def test_extra_headers(self, mocker):

test/test_uploader.py

@@ -953,7 +953,13 @@ def test_various_upload_parameters(self, request_mock):
         """Should support various parameters in upload and explicit"""
         request_mock.return_value = MOCK_RESPONSE
 
-        options = {'cinemagraph_analysis': True, 'accessibility_analysis':True, 'media_metadata':True}
+        options = {
+            'cinemagraph_analysis': True,
+            'accessibility_analysis': True,
+            'media_metadata': True,
+            'visual_search': True,
+        }
+
         uploader.upload(TEST_IMAGE, **options)
 
         params = get_params(request_mock.call_args[0])