Envío de consultas de búsqueda a Bing Visual Search APISending search queries to the Bing Visual Search API

En este artículo se describen los parámetros y atributos de las solicitudes enviadas a Bing Visual Search API, así como el objeto de respuesta.This article describes the parameters and attributes of requests sent to the Bing Visual Search API, as well as the response object.

Puede obtener información acerca de una imagen de tres maneras:You can get insights about an image in three ways:

  • Mediante un token de conclusión que obtiene de una imagen en una llamada anterior a uno de los puntos de conexión de Bing Image Search API.Using an insights token that you get from an image in a previous call to one of the Bing Image Search API endpoints.
  • Enviando la dirección URL de una imagen.Sending the URL of an image.
  • Carga de una imagen (en formato binario).Uploading an image (in binary format).

Solicitudes de Bing Visual SearchBing Visual Search requests

Si envía a Visual Search una dirección URL o un token de imagen, el fragmento de código siguiente muestra el objeto JSON que hay que incluir en el cuerpo de POST:If you send Visual Search an image token or URL, the following snippet shows the JSON object that you must include in the body of the POST:

{
    "imageInfo" : {
        "url" : "",
        "imageInsightsToken" : "",
        "cropArea" : {
            "top" : 0.1,
            "left" : 0.5,
            "right" : 0.9,
            "bottom" : 0.9
        }
    },
    "knowledgeRequest" : {
      "filters" : {
        "site" : ""
      }
    }
}

El objeto imageInfo debe incluir el campo url o imageInsightsToken, pero no ambos.The imageInfo object must include either the url or imageInsightsToken field but not both. Defina el campo url con la dirección URL de una imagen que sea accesible a través de Internet.Set the url field to the URL of an Internet-accessible image. El tamaño máximo de imagen admitido es 1 MB.The maximum supported image size is 1 MB.

imageInsightsToken debe establecerse en un token de conclusión.The imageInsightsToken must be set to an insights token. Para obtener un token de conclusión, llame a Bing Image API.To get an insights token, call the Bing Image API. La respuesta contiene una lista de objetos Image.The response contains a list of Image objects. Cada objeto Image contiene un campo imageInsightsToken, que contiene el token.Each Image object contains an imageInsightsToken field, which contains the token.

El campo cropArea es opcional.The cropArea field is optional. El área de recorte especifica las esquinas superior izquierda e inferior derecha de una región de interés.The crop area specifies the top-left corner and bottom-right corner of a region of interest. Especifique los valores en el intervalo de 0.0 a 1.0.Specify the values in the range 0.0 through 1.0. Los valores son un porcentaje del ancho o alto total.The values are a percentage of the overall width or height. Por ejemplo, en el ejemplo anterior, se marca la mitad derecha de la imagen como región de interés.For example, the above example marks the right half of the image as the region of interest. Inclúyala si quiere limitar la solicitud de conclusión a la región de interés.Include it if you want to limit the insights request to the region of interest.

El objeto filters contiene un filtro de sitio (vea el campo site) que puede utilizar para restringir los resultados de imágenes y productos similares a un dominio específico.The filters object contains a site filter (see the site field) that you can use to restrict the similar images and similar products results to a specific domain. Por ejemplo, si la imagen es de un Surface Book, puede establecer site en www.microsoft.com.For example, if the image is of a Surface Book, you can set site to www.microsoft.com.

Si quiere obtener conclusiones acerca de una copia local de una imagen, cargue la imagen como datos binarios.If you want to get insights about a local copy of an image, upload the image as binary data.

Para obtener más información sobre cómo incluir estas opciones en el cuerpo de POST, vea Tipos de formulario de contenido.For details about including these options in the body of the POST, see Content form types.

Punto de conexión de búsquedaSearch endpoint

El punto de conexión de Visual Search es: https://api.cognitive.microsoft.com/bing/v7.0/images/visualsearch.The Visual Search endpoint is: https://api.cognitive.microsoft.com/bing/v7.0/images/visualsearch.

Las solicitudes solo se deben enviar como solicitudes HTTP POST.Requests must be sent as HTTP POST requests only.

Parámetros de consultaQuery parameters

Estos son los parámetros de consulta que debe especificar la solicitud.The following are the query parameters your request should specify. Como mínimo, debe incluir el parámetro de consulta mkt.At a minimum, you should include the mkt query parameter:

NOMBREName ValorValue typeType ObligatorioRequired
cccc Código de país de dos caracteres que representa de dónde provienen los resultados.A two-character country code that represents where the results come from.

Si establece este parámetro, debe especificar también el encabezado Accept-Language.If you set this parameter, you must also specify the Accept-Language header. Bing usa el primer idioma compatible que encuentra en la lista de idiomas y combina el idioma con el código de país que especifique para determinar el mercado del que debe devolver resultados.Bing uses the first supported language it finds from the list of languages, and combines the language with the country code that you specify to determine the market to return results from. Si la lista de idiomas no incluye ningún idioma compatible, Bing busca el idioma y el mercado más cercanos que admiten la solicitud.If the languages list does not include a supported language, Bing finds the closest language and market that supports the request. También puede usar un mercado agregado o predeterminado para los resultados, en lugar del especificado.Or it may use an aggregated or default market for the results instead of the specified one.

Debe utilizar este parámetro de consulta y el parámetro de consulta Accept-Language solo si especifica varios idiomas. En caso contrario, debe utilizar los parámetros de consulta mkt y setLang.You should use this query parameter and the Accept-Language query parameter only if you specify multiple languages; otherwise, you should use the mkt and setLang query parameters.

Este parámetro y el parámetro de consulta mkt son mutuamente excluyentes: no especifique los dos.This parameter and the mkt query parameter are mutually exclusive—do not specify both.
CadenaString SinNo
mktmkt Mercado de dónde proceden los resultados.The market where the results come from.

NOTA: Si se conoce, se recomienda especificar siempre el mercado.NOTE: You should always specify the market, if known. Especificar el mercado ayuda a Bing a enrutar la solicitud y devolver una respuesta adecuada y óptima.Specifying the market helps Bing route the request and return an appropriate and optimal response.

Este parámetro y el parámetro de consulta cc son mutuamente excluyentes: no especifique los dos.This parameter and the cc query parameter are mutually exclusive—do not specify both.
CadenaString Yes
safeSearchsafeSearch Filtro de contenido para adultos.A filter for adult content. Estos son los posibles valores posibles de filtro (no distingue entre mayúsculas y minúsculas).The following are the possible case-insensitive filter values.
  • Desactivado: devuelve páginas web con texto o imágenes para adultos.Off—Return webpages with adult text or images.

  • Moderado: devuelve páginas web con texto para adultos, pero no imágenes para adultos.Moderate—Return webpages with adult text, but not adult images.

  • Estricto: no devuelve páginas web con texto o imágenes para adultos.Strict—Do not return webpages with adult text or images.

El valor predeterminado es Moderado.The default is Moderate.

NOTA: Si la solicitud proviene de un mercado para el que la directiva para adultos de Bing requiere que safeSearch se defina como Estricto, Bing ignora el valor safeSearch y usa Estricto.NOTE: If the request comes from a market that Bing's adult policy requires that safeSearch be set to Strict, Bing ignores the safeSearch value and uses Strict.

NOTA: Si usa el operador de consulta site:, existe la posibilidad de que la respuesta contenga contenido para adultos, independientemente del valor asignado al parámetro de consulta safeSearch.NOTE: If you use the site: query operator, there is a chance that the response may contain adult content regardless of what the safeSearch query parameter is set to. Use site: solo si es consciente del contenido del sitio y el escenario admite la posibilidad de contenido para adultos.Use site: only if you are aware of the content on the site and your scenario supports the possibility of adult content.
CadenaString SinNo
setLangsetLang Idioma que se usará para las cadenas de la interfaz de usuario.The language to use for user interface strings. Especifique el idioma con el código ISO 639-1 de dos letras.Specify the language using the ISO 639-1 two-letter language code. Por ejemplo, el código de idioma de inglés es EN.For example, the language code for English is EN. El valor predeterminado es EN (inglés).The default is EN (English).

Aunque sea opcional, siempre debe especificar el idioma.Although optional, you should always specify the language. Normalmente, se establece setLang como el mismo idioma especificado por mkt, salvo que el usuario quiera que las cadenas de la interfaz de usuario se muestren en otro idioma.Typically, you set setLang to the same language specified by mkt unless the user wants the user interface strings displayed in a different language.

Este parámetro y el encabezado Accept-Language son mutuamente excluyentes: no especifique los dos.This parameter and the Accept-Language header are mutually exclusive—do not specify both.

Una cadena de interfaz de usuario es aquella que se usa como etiqueta en una interfaz de usuario.A user interface string is a string that's used as a label in a user interface. Hay pocas cadenas de interfaz de usuario en los objetos de respuesta JSON.There are few user interface strings in the JSON response objects. Además, los vínculos a las propiedades de Bing.com de los objetos de respuesta aplican el idioma especificado.Also, any links to Bing.com properties in the response objects apply the specified language.
CadenaString SinNo

encabezadosHeaders

Estos son los encabezados que debe especificar la solicitud.The following are the headers that your request should specify. Los encabezados Content-Type y Ocp-Apim-Subscription-Key son los únicos necesarios, pero también debe incluir User-Agent, X-MSEdge-ClientID, X-MSEdge-ClientIP y X-Search-Location.The Content-Type and Ocp-Apim-Subscription-Key headers are the only required headers, but you should also include User-Agent, X-MSEdge-ClientID, X-MSEdge-ClientIP, and X-Search-Location.

EncabezadoHeader DESCRIPCIÓNDescription
Accept-LanguageAccept-Language Encabezado de solicitud opcional.Optional request header.

Lista delimitada por comas de los idiomas que se usarán en las cadenas de la interfaz de usuario.A comma-delimited list of languages to use for user interface strings. La lista se muestra en orden de preferencia decreciente.The list is in decreasing order of preference. Para más información, incluido el formato esperado, consulte RFC2616.For more information, including expected format, see RFC2616.

Este encabezado y el parámetro de consulta setLang son mutuamente excluyentes, no especifique ambos.This header and the setLang query parameter are mutually exclusive—do not specify both.

Si establece este encabezado, debe especificar también el parámetro de consulta cc.If you set this header, you must also specify the cc query parameter. Para determinar el mercado para el que hay que devolver resultados, Bing usa el primer idioma compatible que encuentra en la lista y lo combina con el valor del parámetro cc.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. Si la lista no incluye ningún idioma compatible, Bing busca el idioma y el mercado más cercanos que admiten la solicitud, o bien usa un mercado agregado o predeterminado para los resultados.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. Para determinar el mercado que usó Bing, consulte el encabezado BingAPIs-Market.To determine the market that Bing used, see the BingAPIs-Market header.

Use este encabezado y el parámetro de consulta cc solo si especifica varios idiomas.Use this header and the cc query parameter only if you specify multiple languages. En caso contrario, use los parámetros de consulta mkt y setLang.Otherwise, use the mkt and setLang query parameters.

Una cadena de interfaz de usuario es aquella que se usa como etiqueta en una interfaz de usuario.A user interface string is a string that's used as a label in a user interface. Hay pocas cadenas de interfaz de usuario en los objetos de respuesta JSON.There are few user interface strings in the JSON response objects. Cualquier vínculo a las propiedades de Bing.com de los objetos de respuesta aplica el idioma especificado.Any links to Bing.com properties in the response objects apply the specified language.
Content-TypeContent-Type
BingAPIs-MarketBingAPIs-Market Encabezado de respuesta.Response header.

Mercado que usa la solicitud.The market used by the request. El formato es <CódigoIdioma>-<CódigoPaís>.The form is <languageCode>-<countryCode>. Por ejemplo, en-US.For example, en-US.
BingAPIs-TraceIdBingAPIs-TraceId Encabezado de respuesta.Response header.

Identificador de la entrada de registro que contiene los detalles de la solicitud.The ID of the log entry that contains the details of the request. Si se produce un error, capture este identificador.When an error occurs, capture this ID. Si no puede determinar y resolver el problema, incluya este identificador junto con el resto de información que proporcione al equipo de soporte técnico.If you are not able to determine and resolve the issue, include this ID along with the other information that you provide the Support team.
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key Encabezado de solicitud obligatorio.Required request header.

Clave de suscripción que recibió al suscribirse a este servicio en Cognitive Services.The subscription key that you received when you signed up for this service in Cognitive Services.
PragmaPragma
User-AgentUser-Agent Encabezado de solicitud opcional.Optional request header.

El agente de usuario que origina la solicitud.The user agent originating the request. Bing usa el agente de usuario para proporcionar a los usuarios de dispositivos móviles una experiencia optimizada.Bing uses the user agent to provide mobile users with an optimized experience. Aunque es opcional, se recomienda especificar siempre este encabezado.Although optional, you are encouraged to always specify this header.

El agente de usuario debe ser la misma cadena que envían los exploradores que más se usan.The user-agent should be the same string that any commonly used browser sends. Para obtener información sobre los agentes de usuario, consulte RFC 2616.For information about user-agents, see RFC 2616.

A continuación encontrará varios ejemplos de cadenas user-agent.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)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.1Android—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.20120423iPhone—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 GeckoPC—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.53iPad—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
X-MSEdge-ClientIDX-MSEdge-ClientID Encabezado de solicitud y respuesta opcional.Optional request and response header.

Bing usa este encabezado para proporcionar a los usuarios un comportamiento coherente en las llamadas API de Bing.Bing uses this header to provide users with consistent behavior across Bing API calls. Bing incorpora a menudo mejoras y características piloto nuevas, y usa el identificador de cliente como clave para asignar el tráfico en distintos paquetes piloto.Bing often flights new features and improvements, and it uses the client ID as a key for assigning traffic on different flights. Si no usa el mismo identificador de cliente para un usuario en varias solicitudes, Bing puede asignar el usuario a varios paquetes piloto en conflicto.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. La asignación a varios paquetes piloto en conflicto puede generar una experiencia de usuario incoherente.Being assigned to multiple conflicting flights can lead to an inconsistent user experience. Por ejemplo, si la segunda solicitud tiene una asignación de paquete piloto distinta de la primera, puede que se produzca una experiencia inesperada.For example, if the second request has a different flight assignment than the first, the experience may be unexpected. Además, Bing puede usar el identificador de cliente para personalizar los resultados web en el historial de búsqueda del identificador de cliente, lo que proporciona una experiencia enriquecida para el usuario.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 también utiliza este encabezado para ayudar a mejorar las clasificaciones de resultados mediante el análisis de la actividad que genera un identificador de cliente.Bing also uses this header to help improve result rankings by analyzing the activity generated by a client ID. Las mejoras de relevancia ayudan con una mayor calidad de los resultados que devuelven las API de Bing y, a su vez, permiten un mayor porcentaje de clics para el consumidor de la API.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.

IMPORTANTE: Aunque es opcional, considere este encabezado como obligatorio.IMPORTANT: Although optional, you should consider this header required. Conservar el identificador de cliente en varias solicitudes para la misma combinación de usuario final y dispositivo permite 1) que el consumidor de API reciba una experiencia de usuario coherente y 2) un mayor porcentaje de clics a través de una mejor calidad de los resultados de las API de Bing.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.

Estas son las reglas de uso básico que se aplican a este encabezado.The following are the basic usage rules that apply to this header.
  • Cada usuario que utiliza la aplicación en el dispositivo debe tener un identificador de cliente único generado por Bing.Each user that uses your application on the device must have a unique, Bing generated client ID.

    Si no incluye este encabezado en la solicitud, Bing genera un identificador y lo devuelve en el encabezado de respuesta X-MSEdge-ClientID.If you do not include this header in the request, Bing generates an ID and returns it in the X-MSEdge-ClientID response header. La única ocasión en que NO debe incluir este encabezado en una solicitud es la primera vez que el usuario usa la aplicación en el dispositivo.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.

  • ATENCIÓN: Debe asegurarse de que este identificador de cliente no se pueda vincular a la información de cualquier cuenta de usuario autenticada.ATTENTION: You must ensure that this Client ID is not linkable to any authenticated user account information.
  • Use el identificador de cliente para cada solicitud de API de Bing que haga la aplicación para este usuario en el dispositivo.Use the client ID for each Bing API request that your app makes for this user on the device.

  • Conserve el identificador de cliente.Persist the client ID. Para conservar el identificador en una aplicación de explorador, use una cookie HTTP persistente para asegurarse de que se use ese identificador en todas las sesiones.To persist the ID in a browser app, use a persistent HTTP cookie to ensure the ID is used across all sessions. No use una cookie de sesión.Do not use a session cookie. Para otras aplicaciones, como aplicaciones móviles, use el almacenamiento persistente del dispositivo para conservar el identificador.For other apps such as mobile apps, use the device's persistent storage to persist the ID.

    La próxima vez que el usuario use la aplicación en ese dispositivo, obtenga el identificador de cliente que conservó.The next time the user uses your app on that device, get the client ID that you persisted.

NOTA: Las respuestas de Bing pueden incluir este encabezado o no incluirlo.NOTE: Bing responses may or may not include this header. Si la respuesta incluye este encabezado, capture el identificador de cliente y úselo para todas las solicitudes posteriores de Bing del usuario en dicho dispositivo.If the response includes this header, capture the client ID and use it for all subsequent Bing requests for the user on that device.

NOTA: Si incluye X-MSEdge-ClientID, no debe incluir cookies en la solicitud.NOTE: If you include the X-MSEdge-ClientID, you must not include cookies in the request.
X-MSEdge-ClientIPX-MSEdge-ClientIP Encabezado de solicitud opcional.Optional request header.

Dirección IPv4 o IPv6 del dispositivo cliente.The IPv4 or IPv6 address of the client device. La dirección IP se usa para detectar la ubicación del usuario.The IP address is used to discover the user's location. Bing usa la información de ubicación para determinar el comportamiento de la búsqueda segura.Bing uses the location information to determine safe search behavior.

NOTA: Aunque es opcional, se recomienda especificar siempre tanto este encabezado como el encabezado X-Search-Location.NOTE: Although optional, you are encouraged to always specify this header and the X-Search-Location header.

No ofusque la dirección (por ejemplo, cambiando el último octeto a 0).Do not obfuscate the address (for example, by changing the last octet to 0). Al ofuscar los resultados de dirección, la ubicación no se encuentra cerca de la ubicación real, lo que puede provocar que Bing devuelva resultados erróneos.Obfuscating the address results in the location not being anywhere near the device's actual location, which may result in Bing serving erroneous results.
X-Search-LocationX-Search-Location Encabezado de solicitud opcional.Optional request header.

Una lista delimitada por punto y coma de pares clave-valor que describen la ubicación geográfica del cliente.A semicolon-delimited list of key/value pairs that describe the client's geographical location. Bing usa la información de ubicación para determinar el comportamiento de la búsqueda segura y devolver contenido local apropiado.Bing uses the location information to determine safe search behavior and to return relevant local content. Especifique el par clave-valor como <clave>:<valor>.Specify the key/value pair as <key>:<value>. A continuación se incluyen las claves que se usan para especificar la ubicación del usuario.The following are the keys that you use to specify the user's location.

  • lat: obligatoria.lat—Required. La latitud de la ubicación del cliente, en grados.The latitude of the client's location, in degrees. La latitud debe ser mayor o igual que -90.0, y menor o igual que +90.0.The latitude must be greater than or equal to -90.0 and less than or equal to +90.0. Los valores negativos indican latitudes del sur, mientras que los valores positivos indican latitudes del norte.Negative values indicate southern latitudes and positive values indicate northern latitudes.

  • long: obligatoria.long—Required. La longitud de la ubicación del cliente, en grados.The longitude of the client's location, in degrees. La longitud debe ser mayor o igual que -180.0, y menor o igual que +180.0.The longitude must be greater than or equal to -180.0 and less than or equal to +180.0. Los valores negativos indican longitudes occidentales, mientras que los valores positivos indican longitudes orientales.Negative values indicate western longitudes and positive values indicate eastern longitudes.

  • re: obligatorio.re—Required. El radio, en metros, que especifica la precisión horizontal de las coordenadas.The radius, in meters, which specifies the horizontal accuracy of the coordinates. Pase el valor que devuelve el servicio de ubicación del dispositivo.Pass the value returned by the device's location service. Los valores típicos pueden ser 22 m para GPS/Wi-Fi, 380 m para la triangulación de antenas repetidoras de telefonía móvil y 18 000 m para la búsqueda inversa de IP.Typical values might be 22 m for GPS/Wi-Fi, 380 m for cell tower triangulation, and 18,000 m for reverse IP lookup.

  • ts: opcional.ts—Optional. La marca de tiempo UTC UNIX del momento en que el cliente estaba en la ubicación.The UTC UNIX timestamp of when the client was at the location. (La marca de tiempo UNIX es el número de segundos transcurridos desde el 1 de enero de 1970).(The UNIX timestamp is the number of seconds since January 1, 1970.)

  • head: opcional.head—Optional. El encabezado relativo del cliente o la dirección de desplazamiento.The client's relative heading or direction of travel. Especifique la dirección de desplazamiento como grados de 0 a 360, en la dirección de las agujas del reloj con respecto al norte verdadero.Specify the direction of travel as degrees from 0 through 360, counting clockwise relative to true north. Especifique esta clave solo si la clave sp es distinta de cero.Specify this key only if the sp key is nonzero.

  • sp: opcional.sp—Optional. La velocidad horizontal, en metros por segundo, a la que se desplaza el dispositivo de cliente.The horizontal velocity (speed), in meters per second, that the client device is traveling.

  • alt: opcional.alt—Optional. La altitud del dispositivo de cliente, en metros.The altitude of the client device, in meters.

  • are: opcional.are—Optional. El radio, en metros, que especifica la precisión vertical de las coordenadas.The radius, in meters, that specifies the vertical accuracy of the coordinates. Especifique esta clave solo si especificó la clave alt.Specify this key only if you specify the alt key.

NOTA: Aunque muchas de las claves son opcionales, cuanta más información proporcione, más precisos serán los resultados de ubicación.NOTE: Although many of the keys are optional, the more information that you provide, the more accurate the location results are.

NOTA: Aunque es opcional, se recomienda especificar siempre la ubicación geográfica del usuario.NOTE: Although optional, you are encouraged to always specify the user's geographical location. Proporcionar la ubicación es especialmente importante si la dirección IP del cliente no refleja con precisión la ubicación física del usuario (por ejemplo, si el cliente utiliza VPN).Providing the location is especially important if the client's IP address does not accurately reflect the user's physical location (for example, if the client uses VPN). Para obtener resultados óptimos, debería incluir tanto este encabezado como X-MSEdge-ClientIP pero, como mínimo, debe incluir este.For optimal results, you should include this header and the X-MSEdge-ClientIP header, but at a minimum, you should include this header.

Nota

Recuerde que los Requisitos de uso y visualización de Bing Search API exigen el cumplimiento de todas las leyes aplicables, incluido el uso de estos encabezados.Remember that the Bing Search API use and display requirements require compliance with all applicable laws, including regarding use of these headers. Por ejemplo, en determinados lugares, como Europa, existen requisitos para obtener el consentimiento del usuario antes de colocar determinados dispositivos de seguimiento en los dispositivos de usuario.For example, in certain jurisdictions, such as Europe, there are requirements to obtain user consent before placing certain tracking devices on user devices.

Tipos de formulario de contenidoContent form types

La solicitud debe incluir el encabezado Content-Type.Each request must include the Content-Type header. El encabezado debe establecerse en: multipart/form-data; boundary=\<boundary string\>, donde <cadena delimitadora> es una cadena opaca única que identifica el límite de los datos del formulario.The header must be set to: multipart/form-data; boundary=\<boundary string\>, where <boundary string> is a unique, opaque string that identifies the boundary of the form data. Por ejemplo, boundary=boundary_1234-abcd.For example, boundary=boundary_1234-abcd.

Si envía a Visual Search una dirección URL o un token de imagen, el fragmento de código siguiente muestra los datos de formulario que hay que incluir en el cuerpo de POST.If you send Visual Search an image token or URL, the following snippet shows the form data you must include in the body of the POST. Los datos de formulario deben incluir el encabezado Content-Disposition y su parámetro name se debe establecer en to "knowledgeRequest".The form data must include the Content-Disposition header and you must set its name parameter to "knowledgeRequest". Para obtener información detallada del objeto imageInfo, consulte la sección dedicada a la solicitud.For details about the imageInfo object, see the request.

--boundary_1234-abcd
Content-Disposition: form-data; name="knowledgeRequest"

{
    "imageInfo" : {
        "url" : "https://contoso.com/2018/05/fashion/red.jpg"
    }
}

--boundary_1234-abcd--

Si carga una imagen local, el fragmento de código siguiente muestra los datos de formulario que hay que incluir en el cuerpo de POST.If you upload a local image, the following snippet shows the form data you must include in the body of the POST. Los datos de formulario deben incluir el encabezado Content-Disposition.The form data must include the Content-Disposition header. Asimismo, el parámetro name se debe establecer en "imagen" y el parámetro filename se puede establecer en cualquier cadena.Its name parameter must be set to "image" and the filename parameter may be set to any string. El encabezado Content-Type se puede establecer en cualquier tipo MIME de imagen común.The Content-Type header may be set to any commonly used image mime type. El contenido del formulario corresponde a los datos binario de la imagen.The contents of the form is the binary data of the image. Recuerde que el tamaño de imagen máximo que puede cargar es de 1 MB.The maximum image size you may upload is 1 MB. El valor mayor del ancho o alto debe ser como máximo 1500 píxeles.The largest of the width or height should be 1,500 pixels or less.

--boundary_1234-abcd
Content-Disposition: form-data; name="image"; filename="myimagefile.jpg"
Content-Type: image/jpeg

ÿØÿà JFIF ÖÆ68g-¤CWŸþ29ÌÄøÖ‘º«™æ±èuZiÀ)"óÓß°Î= ØJ9á+*G¦...

--boundary_1234-abcd--

El fragmento de código siguiente muestra cómo especificar la región de interés de una imagen cargada.The following snippet shows how to specify the region of interest of an uploaded image:

--boundary_1234-abcd
Content-Disposition: form-data; name="knowledgeRequest"

{
    "imageInfo" : {
        "cropArea" : {
            "top" : 0.2,
            "left" : 0.3,
            "bottom" : 0.7,
            "right" : 0.6
        }
    }
}

--boundary_1234-abcd
Content-Disposition: form-data; name="image"; filename="image"
Content-Type: image/jpeg


ÿØÿà JFIF ÖÆ68g-¤CWŸþ29ÌÄøÖ‘º«™æ±èuZiÀ)"óÓß°Î= ØJ9á+*G¦...

--boundary_1234-abcd--

Solicitud de ejemploExample request

El fragmento de código siguiente muestra una solicitud de conclusión de imagen completa que pasa un token de imagen y una región de interés.The following snippet shows a complete image insights request that passes an image token and region of interest. El token de conclusión se obtiene de una llamada anterior a /images/search:You get the insights token from a previous call to /images/search:

POST https://api.cognitive.microsoft.com/bing/v7.0/images/visualsearch?mkt=en-us HTTP/1.1  
Content-Type: multipart/form-data; boundary=boundary_1234-abcd
Ocp-Apim-Subscription-Key: 123456789ABCDE  
X-MSEdge-ClientIP: 999.999.999.999  
X-Search-Location: lat:47.60357;long:-122.3295;re:100  
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>  
Host: api.cognitive.microsoft.com 

--boundary_1234-abcd
Content-Disposition: form-data; name="knowledgeRequest"

{
    "imageInfo" : {
        "imageInsightsToken" : "mid_D6426898706EC7..."
        "cropArea" : {
            "top" : 0.1,
            "left" : 0.2,
            "bottom" : 0.7,
            "right" : 0.5
        }
    }
}

--boundary_1234-abcd--

Respuestas de Bing Visual SearchBing Visual Search responses

Nota

Como los formatos y los parámetros de dirección URL están sujetos a cambios sin previo aviso, use todas las direcciones URL tal y como están.Because URL formats and parameters are subject to change without notice, use all URLs as-is. No debe tomar dependencias en el formato o los parámetros de dirección URL excepto donde se indique.You should not take dependencies on the URL format or parameters except where noted.

Si hay conclusiones disponibles para la imagen, la respuesta contiene uno o varios valores tags que contienen las conclusiones.If there are insights available for the image, the response contains one or more tags that contain the insights. El campo image contiene el token de conclusión de la imagen de entrada:The image field contains the insights token for the input image:

{
  "_type" : "ImageKnowledge",
  "tags" : [
    {...},
    {...},
    {...},
    {...},
    {...}
  ],
  "image" : {
    "imageInsightsToken" : "bcid_AF8C9CA409421B..."
  }
}

El campo tags contiene un nombre para mostrar y una lista de acciones (conclusiones).The tags field contains a display name and list of actions (insights). Una de las etiquetas contiene un campo displayName que se establece en una cadena vacía.One of the tags contains a displayName field that is set to an empty string. Esta etiqueta contiene las conclusiones predeterminadas, como las páginas web que incluyen la imagen, imágenes visualmente similares y orígenes de compra para los productos de la imagen.This tag contains the default insights such as webpages that include the image, visually similar images, and shopping sources for items found in the image. Dado que toda la imagen es de interés, la etiqueta de conclusión predeterminada no incluye rectángulos de selección para las áreas de interés:Because the entire image is of interest, the default insights tag doesn't include bounding boxes for the regions of interest:

{
  "_type" : "ImageKnowledge",
  "tags" : [
    {
      "displayName" : "",
      "actions" : [
        {...},
        {...},
        {...},
        {...}
      ]
    },
    {...},
    {...},
    {...},
    {...}
  ],
  "image" : {
    "imageInsightsToken" : "bcid_AF8C9CA409421B..."
  }
}

Para obtener una lista de conclusiones predeterminadas, consulte Conclusiones predeterminadas.For a list of the default insights, see Default insights tag.

Las etiquetas restantes contienen otras conclusiones que pueden ser de interés para el usuario.The remaining tags contain other insights that may be of interest to the user. Por ejemplo, si la imagen contiene texto, una de las etiquetas puede incluir una conclusión TextResults, que contiene el texto reconocido.For example, if the image contains text, one of the tags may include a TextResults insight, which contains the recognized text. O bien, si Bing reconoce una entidad (es decir, una persona, un lugar o una cosa conocidos) en la imagen, una de las etiquetas puede identificar la entidad.Or, if Bing recognizes an entity (that is, a culturally well-known/popular person, place, or thing) in the image, one of the tags may identify the entity. Visual Search también devuelve un conjunto de términos variados (etiquetas) derivados de la imagen de entrada.Visual Search also returns a diverse set of terms (tags) derived from the input image. Estas etiquetas permiten a los usuarios explorar los conceptos que se encuentran en la imagen.These tags enable users to explore concepts found in the image. Por ejemplo, si la imagen de entrada es de un atleta famoso, una de las etiquetas podría ser deportes, que contiene vínculos a imágenes de deportes.For example, if the input image is of a famous athlete, one of the tags might be Sports, which contains links to images of sports.

Cada etiqueta incluye un nombre para mostrar que puede usar para clasificar las conclusiones, el rectángulo de selección que identifica la región de interés a que se aplica la conclusión, las propias conclusiones y una miniatura de la imagen.Each tag includes a display name that you can use to categorize the insight, bounding box that identifies the region of interest that the insight applies to, the insights themselves, and a thumbnail of the image. Por ejemplo, si la imagen es de una persona con un jersey de deportes, una de las etiquetas podría incluir un rectángulo de selección que delimite el jersey e incluya conclusiones de VisualSearch y ProductVisualSearch.For example, if the image is of a person wearing a sports jersey, one of the tags might include a bounding box that bounds the jersey and includes VisualSearch and ProductVisualSearch insights. Por otra parte, otra etiqueta podría incluir una conclusión de ImageResults que contenga una URL para una solicitud de API /images/search para obtener imágenes cuyos temas estén relacionados o una dirección URL de búsqueda de Bing.com que lleve al usuario a los resultados de búsqueda de imágenes de Bing.com.And another tag might include an ImageResults insight that contains a URL for an /images/search API request to get images that are topically related or a Bing.com search URL that takes the user to the Bing.com image search results.

El resto de etiquetas, distintas a la etiqueta de conclusión predeterminada, incluyen rectángulos de selección que identifican las regiones de interés de la imagen.All tags other than the default insights tag include bounding boxes that identify regions of interest in the image. Por ejemplo, si la imagen incluye varias personas conocidas, las etiquetas podrían incluir rectángulos de selección para cada una de ellas. O bien, si la imagen contiene prendas de vestir conocidas, las etiquetas podrían incluir rectángulos de selección para cada prenda reconocida.For example, if the image includes multiple recognized people, tags could include bounding boxes for each of the people, or if the image contains recognized clothing items, tags could include bounding boxes for each recognized clothing item. Puede usar los rectángulos de selección para crear zonas activas en la imagen que, cuando se haga clic sobre ellas, proporcionen detalles sobre el contenido de dicha región de la imagen.You can use the bounding boxes to create hot spots over the image that when clicked, provide details about the contents in that region of the image. No debe incluir zonas activas en una imagen para rectángulos de selección que identifiquen toda la imagen.You should not include hot spots in an image for bounding boxes that identify the entire image.

Reconocimiento de textoText recognition

Si la imagen contiene texto que reconoce el servicio, una de las etiquetas contendrá una conclusión (acción) de TextResults.If the image contains text that the service recognizes, one of the tags will contain a TextResults insight (action). El elemento displayName de la conclusión contiene el texto reconocido:The insight's displayName contains the recognized text:

    {
        "image" : {
            "thumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?q=%23%23Text..."
        },
        "displayName" : "##TextRecognition",
        "boundingBox" : {
            "queryRectangle" : {
                "topLeft" : {"x" : 0, "y" : 0},
                "topRight" : {"x" : 1, "y" : 0},
                "bottomRight" : {"x" : 1, "y" : 1},
                "bottomLeft" : {"x" : 0, "y" : 1}
            },
            "displayRectangle" : {
                "topLeft" : {"x" : 0, "y" : 0},
                "topRight" : {"x" : 1, "y" : 0},
                "bottomRight" : {"x" : 1, "y" : 1},
                "bottomLeft" : {"x" : 0, "y" : 1}
            }
        },
        "actions" : [{
            "displayName" : "WALK BIKE ACROSS BRIDGE",
            "actionType" : "TextResults"
        }],
        "sources" : ["OCR"]
    }

Dado que el campo displayName de la etiqueta contiene ##TextRecognition, no lo use como título de categoría en la experiencia de usuario.Because the tag's displayName field contains ##TextRecognition, do not use it as a category title in the UX. Esto se aplica a cualquier nombre para mostrar que empiece por ##.That goes for any display name that starts with ##. En su lugar, use el nombre para mostrar de la acción.Instead, use the action's display name.

El reconocimiento de texto también puede reconocer la información de contacto en tarjetas de presentación, como números de teléfono y direcciones de correo electrónico.Text recognition can also recognize the contact information on business cards, such as phone numbers and email addresses. El rectángulo delimitador identifica la ubicación de la información de contacto en la tarjeta.The bounding box identifies the location of the contact information on the card.

    {
      "image" : {
        "thumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?q=%23%23TextRecognition..."
      },
      "displayName" : "##TextRecognition",
      "boundingBox" : {
        "queryRectangle" : {
          "topLeft" : {"x" : 0.635, "y" : 0},
          "topRight" : {"x" : 0.77, "y" : 0},
          "bottomRight" : {"x" : 0.77, "y" : 0.4873333},
          "bottomLeft" : {"x" : 0.635, "y" : 0.4873333}
        },
        "displayRectangle" : {
          "topLeft" : {"x" : 0.635, "y" : 0},
          "topRight" : {"x" : 0.77, "y" : 0},
          "bottomRight" : {"x" : 0.77, "y" : 0.4873333},
          "bottomLeft" : {"x" : 0.635, "y" : 0.4873333}
        }
      },
      "actions" : [
        {
          "url" : "tel:888%20555%201212",
          "actionType" : "Uri"
        }
      ],
      "sources" : ["OCR"]
    },
    {
      "image" : {
        "thumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?q=%23%23TextRecognition..."
      },
      "displayName" : "##TextRecognition",
      "boundingBox" : {
        "queryRectangle" : {
          "topLeft" : {"x" : 0.63, "y" : 0},
          "topRight" : {"x" : 0.866, "y" : 0},
          "bottomRight" : {"x" : 0.866, "y" : 0.5553334},
          "bottomLeft" : {"x" : 0.63, "y" : 0.5553334}
        },
        "displayRectangle" : {
          "topLeft" : {"x" : 0.63, "y" : 0},
          "topRight" : {"x" : 0.866, "y" : 0},
          "bottomRight" : {"x" : 0.866, "y" : 0.5553334},
          "bottomLeft" : {"x" : 0.63, "y" : 0.5553334}
        }
      },
      "actions" : [
        {
          "url" : "mailto:someone@outlook.com",
          "actionType" : "Uri"
        }
      ],
      "sources" : ["OCR"]
    },
    {
      "image" : {
        "thumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?q=%23%23TextRecognition..."
      },
      "displayName" : "##TextRecognition",
      "boundingBox" : {
        "queryRectangle" : {
          "topLeft" : {"x" : 0, "y" : 0},
          "topRight" : {"x" : 1, "y" : 0},
          "bottomRight" : {"x" : 1, "y" : 1},
          "bottomLeft" : {"x" : 0, "y" : 1}
        },
        "displayRectangle" : {
          "topLeft" : {"x" : 0, "y" : 0},
          "topRight" : {"x" : 1, "y" : 0},
          "bottomRight" : {"x" : 1, "y" : 1},
          "bottomLeft" : {"x" : 0, "y" : 1}
        }
      },
      "actions" : [
        {
          "displayName" : "CHARLENE WHITNEY Graphic Designer 888 555 1212 someone@outlook.com www.contoso.com",
          "actionType" : "TextResults"
        }
      ],
      "sources" : ["OCR"]
    }

Si la imagen contiene una entidad reconocida, como una persona, lugar o cosa conocidos, una de las etiquetas puede incluir una conclusión de entidad.If the image contains a recognized entity such as a culturally well-known/popular person, place, or thing, one of the tags may include an Entity insight.

    {
      "image" : {
        "thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?q=Statue+of+Liberty..."
      },
      "displayName" : "Statue of Liberty",
      "boundingBox" : {
        "queryRectangle" : {
          "topLeft" : {"x" : 0.40625, "y" : 0.1757813},
          "topRight" : {"x" : 0.6171875, "y" : 0.1757813},
          "bottomRight" : {"x" : 0.6171875, "y" : 0.3867188},
          "bottomLeft" : {"x" : 0.40625, "y" : 0.3867188}
        },
        "displayRectangle" : {
          "topLeft" : {"x" : 0.40625, "y" : 0.1757813},
          "topRight" : {"x" : 0.6171875, "y" : 0.1757813},
          "bottomRight" : {"x" : 0.6171875, "y" : 0.3867188},
          "bottomLeft" : {"x" : 0.40625, "y" : 0.3867188}
        }
      },
      "actions" : [
        {
          "_type" : "ImageEntityAction",
          "webSearchUrl" : "https:\/\/www.bing.com\/search?q=Statue+of+Liberty",
          "displayName" : "Statue of Liberty",
          "actionType" : "Entity",
        }
      ]
    }

Otras referenciasSee also