diff --git a/specification/cognitiveservices/data-plane/VisualSearch/v1.0/VisualSearch.json b/specification/cognitiveservices/data-plane/VisualSearch/v1.0/VisualSearch.json index ccea0e8ec0fd..12cd6485dc9b 100644 --- a/specification/cognitiveservices/data-plane/VisualSearch/v1.0/VisualSearch.json +++ b/specification/cognitiveservices/data-plane/VisualSearch/v1.0/VisualSearch.json @@ -2,13 +2,13 @@ "swagger": "2.0", "info": { "title": "Visual Search API", - "description": "The Image Visual Search API lets you send an image to Bing and get back a list of relevant tags. Each tag contains potential actions a user might be interested in. This section provides technical details about the request format and headers that you use to request actions and the JSON response objects that contain them. For examples that show how to make requests, see [Searching the Web for Images](https://docs.microsoft.com/azure/cognitive-services/bing-image-search/search-the-web).", + "description": "Visual Search API lets you discover insights about an image such as visually similar images, shopping sources, and related searches. The API can also perform text recognition, identify entities (people, places, things), return other topical content for the user to explore, and more. For more information, see [Visual Search Overview](https://docs.microsoft.com/azure/cognitive-services/bing-visual-search/overview).", "version": "1.0" }, "parameters": { "x-bingapis-sdk": { "name": "X-BingApis-SDK", - "description": "Activate swagger compliance", + "description": "Activate swagger compliance.", "x-ms-parameter-location": "method", "required": true, "type": "string", @@ -45,7 +45,7 @@ "paths": { "/images/visualsearch": { "post": { - "summary": "The Image Visual Search API lets you send an image to Bing and get back a list of relevant tags. Each tag contains potential actions a user might be interested in. This section provides technical details about the request format and headers that you use to request actions and the JSON response objects that contain them. For examples that show how to make requests, see [Searching the Web for Images](https://docs.microsoft.com/azure/cognitive-services/bing-image-search/search-the-web).", + "summary": "Visual Search API lets you discover insights about an image such as visually similar images, shopping sources, and related searches. The API can also perform text recognition, identify entities (people, places, things), return other topical content for the user to explore, and more. For more information, see [Visual Search Overview](https://docs.microsoft.com/azure/cognitive-services/bing-visual-search/overview).", "operationId": "Images_VisualSearch", "tags": [ "ImageVisualSearch" @@ -73,7 +73,7 @@ "name": "Accept-Language", "x-ms-client-name": "AcceptLanguage", "in": "header", - "description": "A comma-delimited list of one or more languages to use for user interface strings. The list is in decreasing order of preference. For additional information, including expected format, see [RFC2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html). This header and the [setLang](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-images-api-v7-reference#setlang) query parameter are mutually exclusive; do not specify both. If you set this header, you must also specify the [cc](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-images-api-v7-reference#cc) query parameter. To determine the market to return results for, Bing uses the first supported language it finds from the list and combines it with the cc parameter value. If the list does not include a supported language, Bing finds the closest language and market that supports the request or it uses an aggregated or default market for the results. To determine the market that Bing used, see the BingAPIs-Market header. Use this header and the cc query parameter only if you specify multiple languages. Otherwise, use the [mkt](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-images-api-v7-reference#mkt) and [setLang](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-images-api-v7-reference#setlang) query parameters. A user interface string is a string that's used as a label in a user interface. There are few user interface strings in the JSON response objects. Any links to Bing.com properties in the response objects apply the specified language.", + "description": "A comma-delimited list of one or more languages to use for user interface strings. The list is in decreasing order of preference. For additional information, including expected format, see [RFC2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html). This header and the [setLang](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-visual-search-api-v7-reference#setlang) query parameter are mutually exclusive; do not specify both. If you set this header, you must also specify the [cc](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-visual-search-api-v7-reference#cc) query parameter. To determine the market to return results for, Bing uses the first supported language it finds from the list and combines it with the cc parameter value. If the list does not include a supported language, Bing finds the closest language and market that supports the request or it uses an aggregated or default market for the results. To determine the market that Bing used, see the BingAPIs-Market header. Use this header and the cc query parameter only if you specify multiple languages. Otherwise, use the [mkt](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-visual-search-api-v7-reference#mkt) and [setLang](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-visual-search-api-v7-reference#setlang) query parameters. A user interface string is a string that's used as a label in a user interface. There are few user interface strings in the JSON response objects. Any links to Bing.com properties in the response objects apply the specified language.", "required": false, "type": "string" }, @@ -81,7 +81,7 @@ "name": "Content-Type", "x-ms-client-name": "ContentType", "in": "header", - "description": "Optional request header. If you set the [modules](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-images-api-v7-reference#modulesrequested) query parameter to RecognizedEntities, you may specify the binary of an image in the body of a POST request. If you specify the image in the body of a POST request, you must specify this header and set its value to multipart/form-data. The maximum image size is 1 MB.", + "description": "Must be set to multipart/form-data and include a boundary parameter (for example, multipart/form-data; boundary=). For more details, see [Content form types]( https://docs.microsoft.com/en-us/azure/cognitive-services/bing-visual-search/overview#content-form-types).", "required": false, "type": "string" }, @@ -89,7 +89,7 @@ "name": "User-Agent", "x-ms-client-name": "UserAgent", "in": "header", - "description": "The user agent originating the request. Bing uses the user agent to provide mobile users with an optimized experience. Although optional, you are encouraged to always specify this header. The user-agent should be the same string that any commonly used browser sends. For information about user agents, see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html). The following are examples of user-agent strings. Windows Phone: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822). Android: Mozilla / 5.0 (Linux; U; Android 2.3.5; en - us; SCH - I500 Build / GINGERBREAD) AppleWebKit / 533.1 (KHTML; like Gecko) Version / 4.0 Mobile Safari / 533.1. iPhone: Mozilla / 5.0 (iPhone; CPU iPhone OS 6_1 like Mac OS X) AppleWebKit / 536.26 (KHTML; like Gecko) Mobile / 10B142 iPhone4; 1 BingWeb / 3.03.1428.20120423. PC: Mozilla / 5.0 (Windows NT 6.3; WOW64; Trident / 7.0; Touch; rv:11.0) like Gecko. iPad: Mozilla / 5.0 (iPad; CPU OS 7_0 like Mac OS X) AppleWebKit / 537.51.1 (KHTML, like Gecko) Version / 7.0 Mobile / 11A465 Safari / 9537.53", + "description": "The user agent originating the request. Bing uses the user agent to provide mobile users with an optimized experience. Although optional, you are encouraged to always specify this header. The user-agent should be the same string that any commonly used browser sends. For information about user agents, see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html). The following are examples of user-agent strings. Windows Phone: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822). Android: Mozilla / 5.0 (Linux; U; Android 2.3.5; en - us; SCH - I500 Build / GINGERBREAD) AppleWebKit / 533.1 (KHTML; like Gecko) Version / 4.0 Mobile Safari / 533.1. iPhone: Mozilla / 5.0 (iPhone; CPU iPhone OS 6_1 like Mac OS X) AppleWebKit / 536.26 (KHTML; like Gecko) Mobile / 10B142 iPhone4; 1 BingWeb / 3.03.1428.20120423. PC: Mozilla / 5.0 (Windows NT 6.3; WOW64; Trident / 7.0; Touch; rv:11.0) like Gecko. iPad: Mozilla / 5.0 (iPad; CPU OS 7_0 like Mac OS X) AppleWebKit / 537.51.1 (KHTML, like Gecko) Version / 7.0 Mobile / 11A465 Safari / 9537.53.", "required": false, "type": "string" }, @@ -97,7 +97,7 @@ "name": "X-MSEdge-ClientID", "x-ms-client-name": "ClientId", "in": "header", - "description": "Bing uses this header to provide users with consistent behavior across Bing API calls. Bing often flights new features and improvements, and it uses the client ID as a key for assigning traffic on different flights. If you do not use the same client ID for a user across multiple requests, then Bing may assign the user to multiple conflicting flights. Being assigned to multiple conflicting flights can lead to an inconsistent user experience. For example, if the second request has a different flight assignment than the first, the experience may be unexpected. Also, Bing can use the client ID to tailor web results to that client ID’s search history, providing a richer experience for the user. Bing also uses this header to help improve result rankings by analyzing the activity generated by a client ID. The relevance improvements help with better quality of results delivered by Bing APIs and in turn enables higher click-through rates for the API consumer. IMPORTANT: Although optional, you should consider this header required. Persisting the client ID across multiple requests for the same end user and device combination enables 1) the API consumer to receive a consistent user experience, and 2) higher click-through rates via better quality of results from the Bing APIs. Each user that uses your application on the device must have a unique, Bing generated client ID. If you do not include this header in the request, Bing generates an ID and returns it in the X-MSEdge-ClientID response header. The only time that you should NOT include this header in a request is the first time the user uses your app on that device. Use the client ID for each Bing API request that your app makes for this user on the device. Persist the client ID. To persist the ID in a browser app, use a persistent HTTP cookie to ensure the ID is used across all sessions. Do not use a session cookie. For other apps such as mobile apps, use the device's persistent storage to persist the ID. The next time the user uses your app on that device, get the client ID that you persisted. Bing responses may or may not include this header. If the response includes this header, capture the client ID and use it for all subsequent Bing requests for the user on that device. If you include the X-MSEdge-ClientID, you must not include cookies in the request.", + "description": "Bing uses this header to provide users with consistent behavior across Bing API calls. Bing often flights new features and improvements, and it uses the client ID as a key for assigning traffic on different flights. If you do not use the same client ID for a user across multiple requests, then Bing may assign the user to multiple conflicting flights. Being assigned to multiple conflicting flights can lead to an inconsistent user experience. For example, if the second request has a different flight assignment than the first, the experience may be unexpected. Also, Bing can use the client ID to tailor web results to that client ID’s search history, providing a richer experience for the user. Bing also uses this header to help improve result rankings by analyzing the activity generated by a client ID. The relevance improvements help with better quality of results delivered by Bing APIs and in turn enables higher click-through rates for the API consumer. IMPORTANT: Although optional, you should consider this header required. Persisting the client ID across multiple requests for the same end user and device combination enables 1) the API consumer to receive a consistent user experience, and 2) higher click-through rates via better quality of results from the Bing APIs. Each user that uses your application on the device must have a unique, Bing generated client ID. If you do not include this header in the request, Bing generates an ID and returns it in the X-MSEdge-ClientID response header. The only time that you should NOT include this header in a request is the first time the user uses your app on that device. Use the client ID for each Bing API request that your app makes for this user on the device. Persist the client ID. To persist the ID in a browser app, use a persistent HTTP cookie to ensure the ID is used across all sessions. Do not use a session cookie. For other apps such as mobile apps, use the device's persistent storage to persist the ID. The next time the user uses your app on that device, get the client ID that you persisted. Bing responses may or may not include this header. If the response includes this header, capture the client ID and use it for all subsequent Bing requests for the user on that device. ATTENTION: You must ensure that this Client ID is not linkable to any authenticatable user account information. If you include the X-MSEdge-ClientID, you must not include cookies in the request.", "required": false, "type": "string" }, @@ -121,7 +121,7 @@ "name": "knowledgeRequest", "x-ms-client-name": "KnowledgeRequest", "in": "formData", - "description": "A JSON object containing information about the image. The image and imageInsightsToken fields are mutually exclusive – the body of the request must include only one of them.", + "description": "The form data is a JSON object that identifies the image using an insights token or URL to the image. The object may also include an optional crop area that identifies an area of interest in the image. The insights token and URL are mutually exclusive – do not specify both. You may specify knowledgeRequest form data and image form data in the same request only if knowledgeRequest form data specifies the cropArea field only (it must not include an insights token or URL).", "required": false, "type": "string" }, @@ -129,7 +129,7 @@ "name": "image", "x-ms-client-name": "Image", "in": "formData", - "description": "The uploaded image file. The size of the image is limited to 1 MB and the file name must be \"image\". The image and imageInsightsToken fields are mutually exclusive – the body of the request must include only one of them.", + "description": "The form data is an image binary. The Content-Disposition header's filename parameter must be set to \"image\". You must specify an image binary if you do not use knowledgeRequest form data to specify the image; you may not use both forms to specify an image. You may specify knowledgeRequest form data and image form data in the same request only if knowledgeRequest form data specifies the cropArea field only (it must not include an insights token or URL).", "required": false, "type": "file" } @@ -149,7 +149,7 @@ } }, "x-ms-examples": { - "Successful image visual search": { + "Successful visual search": { "$ref": "./examples/SuccessfulVisualSearchRequest.json" } } @@ -166,7 +166,7 @@ "type": "object", "properties": { "tags": { - "description": "Includes a list of image knowledge tags", + "description": "A list of visual search tags.", "readOnly": true, "type": "array", "items": { @@ -181,7 +181,7 @@ } }, "Response": { - "description": "Defines a response. All schemas that could be returned at the root of a response should inherit from this", + "description": "Defines a response. All schemas that return at the root of the response must inherit from this object.", "allOf": [ { "$ref": "#/definitions/Identifiable" @@ -190,12 +190,12 @@ "type": "object", "properties": { "readLink": { - "description": "The URL that returns this resource.", + "description": "The URL that returns this resource. To use the URL, append query parameters as appropriate and include the Ocp-Apim-Subscription-Key header.", "readOnly": true, "type": "string" }, "webSearchUrl": { - "description": "The URL To Bing's search result for this item.", + "description": "The URL to Bing's search result for this item.", "readOnly": true, "type": "string" } @@ -210,17 +210,17 @@ "type": "object", "properties": { "displayName": { - "description": "Display name for this tag, for default tag, there is no display name", + "description": "Display name for this tag. For the default tag, the display name is empty.", "readOnly": true, "type": "string" }, "boundingBox": { - "description": "The bounding box for this tag, for default tag, there is no bounding box", + "description": "The bounding box for this tag. For the default tag, there is no bounding box.", "$ref": "#/definitions/ImageTagRegion", "readOnly": true }, "actions": { - "description": "Actions within this tag. The order of the items denotes the default ranking order of these actions.", + "description": "Actions within this tag. The order of the items denotes the default ranking order of these actions, with the first action being the most likely user intent.", "readOnly": true, "type": "array", "items": { @@ -230,7 +230,7 @@ } }, "ImageObject": { - "description": "Defines an image", + "description": "Defines an image.", "allOf": [ { "$ref": "#/definitions/MediaObject" @@ -239,22 +239,22 @@ "type": "object", "properties": { "thumbnail": { - "description": "The URL to a thumbnail of the image", + "description": "The URL to a thumbnail of the image.", "$ref": "#/definitions/ImageObject", "readOnly": true }, "imageInsightsToken": { - "description": "The token that you use in a subsequent call to the Image Search API to get additional information about the image. For information about using this token, see the insightsToken query parameter.", + "description": "The token that you use in a subsequent call to Visual Search API to get additional information about the image. For information about using this token, see the imageInsightsToken field inside the knowledgeRequest request parameter.", "readOnly": true, "type": "string" }, "insightsMetadata": { - "description": "A count of the number of websites where you can shop or perform other actions related to the image. For example, if the image is of an apple pie, this object includes a count of the number of websites where you can buy an apple pie. To indicate the number of offers in your UX, include badging such as a shopping cart icon that contains the count. When the user clicks on the icon, use imageInisghtsToken to get the list of websites.", + "description": "A count of the number of websites where you can shop or perform other actions related to the image. For example, if the image is of an apple pie, this object includes a count of the number of websites where you can buy an apple pie. To indicate the number of offers in your UX, include badging such as a shopping cart icon that contains the count. When the user clicks on the icon, use imageInisghtsToken in a subsequent Visual Search API call to get the list of shopping websites.", "$ref": "#/definitions/ImagesImageMetadata", "readOnly": true }, "imageId": { - "description": "Unique Id for the image", + "description": "Unique Id for the image.", "readOnly": true, "type": "string" }, @@ -264,7 +264,7 @@ "type": "string" }, "visualWords": { - "description": "Visual representation of the image. Used for getting more sizes", + "description": "For interal use only.", "readOnly": true, "type": "string" } @@ -337,7 +337,7 @@ "type": "string" }, "alternateName": { - "description": "An alias for the item", + "description": "An alias for the item.", "readOnly": true, "type": "string" }, @@ -357,7 +357,7 @@ "type": "object", "properties": { "result": { - "description": "The result produced in the action", + "description": "The result produced in the action.", "readOnly": true, "type": "array", "items": { @@ -365,17 +365,17 @@ } }, "displayName": { - "description": "A display name for the action", + "description": "A display name for the action.", "readOnly": true, "type": "string" }, "isTopAction": { - "description": "A boolean representing whether this result is the top action", + "description": "A Boolean representing whether this result is the top action.", "readOnly": true, "type": "boolean" }, "serviceUrl": { - "description": "Url inside Thing_x gets you a url to fulfill action directly,however ServiceUrl Gives you more data to determine how to take action.e.g. ServiceUrl might return json and an image url in it.", + "description": "Use this URL to get additional data to determine how to take the appropriate action. For example, the serviceUrl might return JSON along with an image URL.", "readOnly": true, "type": "string" } @@ -407,7 +407,7 @@ "type": "object", "properties": { "actionType": { - "description": "A string representing the type of action", + "description": "A string representing the type of action.", "readOnly": true, "type": "string" } @@ -423,7 +423,7 @@ "type": "object", "properties": { "contentUrl": { - "description": "Original URL to retrieve the source (file) for the media object (e.g the source URL for the image).", + "description": "Original URL to retrieve the source (file) for the media object (e.g., the source URL for the image).", "readOnly": true, "type": "string" }, @@ -433,12 +433,12 @@ "type": "string" }, "contentSize": { - "description": "Size of the media object content (use format \"value unit\" e.g \"1024 B\").", + "description": "Size of the media object content. Use format \"value unit\" (e.g., \"1024 B\").", "readOnly": true, "type": "string" }, "encodingFormat": { - "description": "Encoding format (e.g mp3, mp4, jpeg, etc).", + "description": "Encoding format (e.g., mp3, mp4, jpeg, etc).", "readOnly": true, "type": "string" }, @@ -467,7 +467,7 @@ "type": "object", "properties": { "shoppingSourcesCount": { - "description": "The number of websites that offer goods of the products seen in the image.", + "description": "The number of websites that sell the products seen in the image.", "readOnly": true, "type": "integer", "format": "int32" @@ -486,7 +486,7 @@ } }, "ResponseBase": { - "description": "Response base", + "description": "Response base.", "discriminator": "_type", "type": "object", "properties": { @@ -591,7 +591,7 @@ "type": "string" }, "text": { - "description": "Text content of this creative work", + "description": "Text content of this creative work.", "readOnly": true, "type": "string" } @@ -607,7 +607,7 @@ "type": "object", "properties": { "seller": { - "description": "Seller for this offer", + "description": "Seller for this offer.", "$ref": "#/definitions/Organization", "readOnly": true }, @@ -791,7 +791,7 @@ } }, "availability": { - "description": "The item's availability. The following are the possible values: Discontinued, InStock, InStoreOnly, LimitedAvailability, OnlineOnly, OutOfStock, PreOrder, SoldOut", + "description": "The item's availability. The following are the possible values: Discontinued, InStock, InStoreOnly, LimitedAvailability, OnlineOnly, OutOfStock, PreOrder, SoldOut.", "readOnly": true, "type": "string", "enum": [ @@ -862,7 +862,7 @@ "type": "object" }, "NormalizedQuadrilateral": { - "description": "Defines a region of an image. The region is a convex quadrilateral defined by coordinates of its top left, top right, bottom left and bottom right points. The coordinates are fractional values of the original image's width and height in the range 0.0 through 1.0.", + "description": "Defines a region of an image. The region is a convex quadrilateral defined by coordinates of its top left, top right, bottom left, and bottom right points. The coordinates are fractional values of the original image's width and height in the range 0.0 through 1.0.", "allOf": [ { "$ref": "#/definitions/StructuredValue" @@ -881,15 +881,15 @@ "$ref": "#/definitions/Point2D" }, "topRight": { - "description": "The top right corner coordinate", + "description": "The top right corner coordinate.", "$ref": "#/definitions/Point2D" }, "bottomRight": { - "description": "The bottom right corner coordinate", + "description": "The bottom right corner coordinate.", "$ref": "#/definitions/Point2D" }, "bottomLeft": { - "description": "The bottom left corner coordinate", + "description": "The bottom left corner coordinate.", "$ref": "#/definitions/Point2D" } } @@ -903,7 +903,7 @@ "type": "object", "properties": { "data": { - "description": "Information about the entity", + "description": "Information about the entity.", "$ref": "#/definitions/Thing", "readOnly": true } @@ -918,7 +918,7 @@ "type": "object", "properties": { "data": { - "description": "A list of images", + "description": "A list of images.", "$ref": "#/definitions/ImagesModule", "readOnly": true } @@ -933,7 +933,7 @@ "type": "object", "properties": { "data": { - "description": "A list of recipes related to the image", + "description": "A list of recipes related to the image.", "$ref": "#/definitions/RecipesModule", "readOnly": true } @@ -948,7 +948,7 @@ "type": "object", "properties": { "data": { - "description": "A list of queries related to the image", + "description": "A list of queries related to the image.", "$ref": "#/definitions/RelatedSearchesModule", "readOnly": true } @@ -963,7 +963,7 @@ "type": "object", "properties": { "data": { - "description": "A list of merchants that offer items related to the image", + "description": "A list of merchants that offer items related to the image.", "$ref": "#/definitions/AggregateOffer", "readOnly": true } @@ -1000,12 +1000,12 @@ "type": "string" }, "displayText": { - "description": "The display version of the query term. This version of the query term may contain special characters that highlight the search term found in the query string. The string contains the highlighting characters only if the query enabled hit highlighting", + "description": "The display version of the query term.", "readOnly": true, "type": "string" }, "webSearchUrl": { - "description": "The URL that takes the user to the Bing search results page for the query.Only related search results include this field.", + "description": "The URL that takes the user to the Bing search results page for the query.", "readOnly": true, "type": "string" }, @@ -1104,12 +1104,12 @@ ], "properties": { "x": { - "description": "The x-coordinate of the point", + "description": "The x-coordinate of the point.", "type": "number", "format": "float" }, "y": { - "description": "The y-coordinate of the point", + "description": "The y-coordinate of the point.", "type": "number", "format": "float" } @@ -1183,32 +1183,37 @@ } }, "KnowledgeRequest": { - "description": "A JSON object containing information about the image. The image and imageInsightsToken fields are mutually exclusive – the body of the request must include only one of them.", + "description": "A JSON object that contains information about the image to get insights of. Specify this object only in a knowledgeRequest form data.", "type": "object", "properties": { "imageInfo": { - "description": "A JSON object containing information about the image. The image and imageInsightsToken fields are mutually exclusive – the body of the request must include only one of them.", + "description": "A JSON object that identities the image to get insights of.", "$ref": "#/definitions/ImageInfo", "readOnly": true + }, + "filters": { + "description": "A key-value object consisting of filters that may be specified to limit the results returned by the API.", + "$ref": "#/definitions/Filters", + "readOnly": true } } }, "ImageInfo": { - "description": "A JSON object containing information about the image. The image and imageInsightsToken fields are mutually exclusive – the body of the request must include only one of them.", + "description": "A JSON object that identities the image to get insights of . It also includes the optional crop area that you use to identify the region of interest in the image.", "type": "object", "properties": { "imageInsightsToken": { - "description": "An image insights token. To get the insights token, call one of the Image Search APIs (for example, /images/search). In the search results, the [Image](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-images-api-v7-reference#image) object's [imageInsightsToken](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-images-api-v7-reference#image-imageinsightstoken) field contains the token. The image and imageInsightsToken fields are mutually exclusive – do not specify both.", + "description": "An image insights token. To get the insights token, call one of the Image Search APIs (for example, /images/search). In the search results, the [Image](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-images-api-v7-reference#image) object's [imageInsightsToken](https://docs.microsoft.com/en-us/rest/api/cognitiveservices/bing-images-api-v7-reference#image-imageinsightstoken) field contains the token. The imageInsightsToken and url fields mutually exclusive; do not specify both. Do not specify an insights token if the request includes the image form data.", "readOnly": true, "type": "string" }, "url": { - "description": "The URL of the input image. The URL should match the image specified by the imageInsightsToken fields if both are present. The image and URL fields are mutually exclusive – do not specify both.", + "description": "The URL of the input image. The imageInsightsToken and url fields are mutually exclusive; do not specify both. Do not specify the URL if the request includes the image form data.", "readOnly": true, "type": "string" }, "cropArea": { - "description": "A JSON object consisting of coordinates specifying the four corners of a cropped rectangle within the input image.", + "description": "A JSON object consisting of coordinates specifying the four corners of a cropped rectangle within the input image. Use the crop area to identify the region of interest in the image. You can apply the crop area to the images specified using the imageInsightsToken or url fields, or an image binary specified in an image form data.", "$ref": "#/definitions/CropArea", "readOnly": true } @@ -1225,26 +1230,37 @@ ], "properties": { "top": { - "description": "The top coordinate of the region to be cropped. The coordinate is a fractional value of the original image's height and is measured from the top, left corner of the image. Specify the coordinate as a value from 0.0 through 1.0.", + "description": "The top coordinate of the region to be cropped. The coordinate is a fractional value of the original image's height and is measured from the top edge of the image. Specify the coordinate as a value from 0.0 through 1.0.", "type": "number", "format": "float" }, "bottom": { - "description": "The bottom coordinate of the region to be cropped. The coordinate is a fractional value of the original image's height and is measured from the top, left corner of the image. Specify the coordinate as a value from 0.0 through 1.0.", + "description": "The bottom coordinate of the region to be cropped. The coordinate is a fractional value of the original image's height and is measured from the top edge of the image. Specify the coordinate as a value from 0.0 through 1.0.", "type": "number", "format": "float" }, "left": { - "description": "The left coordinate of the region to be cropped. The coordinate is a fractional value of the original image's height and is measured from the top, left corner of the image. Specify the coordinate as a value from 0.0 through 1.0.", + "description": "The left coordinate of the region to be cropped. The coordinate is a fractional value of the original image's width and is measured from the left edge of the image. Specify the coordinate as a value from 0.0 through 1.0.", "type": "number", "format": "float" }, "right": { - "description": "The right coordinate of the region to be cropped. The coordinate is a fractional value of the original image's height and is measured from the top, left corner of the image. Specify the coordinate as a value from 0.0 through 1.0.", + "description": "The right coordinate of the region to be cropped. The coordinate is a fractional value of the original image's width and is measured from the left edge of the image. Specify the coordinate as a value from 0.0 through 1.0.", "type": "number", "format": "float" } } + }, + "Filters": { + "description": "A key-value object consisting of filters that may be specified to limit the results returned by the API. Current available filters: site.", + "type": "object", + "properties": { + "site": { + "description": "The URL of the site to return similar images and similar products from. (e.g., \"www.bing.com\", \"bing.com\").", + "readOnly": true, + "type": "string" + } + } } } } \ No newline at end of file