Llamada a la API Image Analysis 3.2

Este artículo muestra cómo llamar a la API Image Analysis 3.2 para devolver información sobre las características visuales de una imagen. También muestra cómo analizar la información devuelta mediante los SDK del cliente o la API de REST.

En esta guía se da por supuesto que ya ha creado un recurso de Visión y ha obtenido una clave y una dirección URL del punto de conexión. Si usa un SDK de cliente, también tendrá que autenticar un objeto cliente. Si no ha realizado estos pasos, siga el inicio rápido para comenzar.

Envío de datos al servicio

El código de esta guía usa imágenes remotas referenciadas por URL. Es posible que desee probar diferentes imágenes por su cuenta para ver toda la capacidad de las funciones de análisis de imágenes.

Al analizar una imagen remota, se especifica la URL de la imagen formateando el cuerpo de la petición de la siguiente manera: {"url":"http://example.com/images/test.jpg"}.

Para analizar una imagen local, se ponen los datos binarios de la imagen en el cuerpo de la petición HTTP.

Determinación de cómo se procesan los datos

Selección de características visuales

Analyze API proporciona acceso a todas las características de análisis de imágenes del servicio. Elija qué operaciones realizar en función de su propio caso de uso. Consulte la información general para obtener una descripción de cada característica. Los ejemplos siguientes incluyen todas las funciones visuales disponibles, pero para el uso práctico es probable que solo necesite una o dos.

Puede especificar qué funciones quiere usar mediante la configuración de los parámetros de consulta de la URL de la API de análisis. Un parámetro puede tener varios valores, que se separan por comas. Cada característica que especifique requerirá más tiempo de cálculo, así que especifique solo lo que necesite.

Parámetro URL Value Descripción
features Read Lee el texto visible en la imagen y lo genera como datos JSON estructurados.
features Description Describe el contenido de la imagen con una oración completa en los idiomas que se admiten.
features SmartCrops Busca las coordenadas del rectángulo que recortarán la imagen con la relación de aspecto deseada mientras conserva el área de interés.
features Objects Detecta varios objetos en una imagen, incluida la ubicación aproximada. El argumento Objects solo está disponible en inglés.
features Tags Etiqueta la imagen con una lista detallada de palabras relacionadas con el contenido de la imagen.

Una URL rellenada tiene el siguiente aspecto:

<endpoint>/vision/v3.2/analyze?visualFeatures=Tags

Especificación de idiomas

También puede especificar el idioma de los datos devueltos.

El siguiente parámetro de consulta de la dirección URL especifica el idioma. El valor predeterminado es en.

Parámetro URL Value Descripción
language en Inglés
language es Español
language ja Japonés
language pt Portugués
language zh Chino simplificado

Una URL rellenada tiene el siguiente aspecto:

<endpoint>/vision/v3.2/analyze?visualFeatures=Tags&language=en

Obtención de resultados a partir del servicio

Esta sección muestra cómo analizar los resultados de la llamada a la API. Se incluye la propia llamada a la API.

Nota

Llamadas API con ámbito

A algunas de las características de Image Analysis se les puede llamar directamente, así como a través de una llamada a Analyze API. Por ejemplo, puede hacer un análisis de alcance de solo las etiquetas de imagen al hacer una solicitud a <endpoint>/vision/v3.2/tag (o al método correspondiente en el SDK). Consulte la documentación de referencia para ver otras características a las que se puede llamar por separado.

El servicio devuelve una respuesta HTTP 200y el cuerpo contiene los datos devueltos en forma de cadena JSON. El texto siguiente es un ejemplo de una respuesta JSON.

{
    "metadata":
    {
        "width": 300,
        "height": 200
    },
    "tagsResult":
    {
        "values":
        [
            {
                "name": "grass",
                "confidence": 0.9960499405860901
            },
            {
                "name": "outdoor",
                "confidence": 0.9956876635551453
            },
            {
                "name": "building",
                "confidence": 0.9893627166748047
            },
            {
                "name": "property",
                "confidence": 0.9853052496910095
            },
            {
                "name": "plant",
                "confidence": 0.9791355729103088
            }
        ]
    }
}

Códigos de error

Consulte la siguiente lista de posibles errores y sus causas:

  • 400
    • InvalidImageUrl - La dirección URL de la imagen tiene un formato que no se admite o no es accesible.
    • InvalidImageFormat - Los datos de entrada no son una imagen válida.
    • InvalidImageSize - La imagen de entrada es demasiado grande.
    • NotSupportedVisualFeature - El tipo de característica especificado no es válido.
    • NotSupportedImage - La imagen no se admite como, por ejemplo, pornografía infantil.
    • InvalidDetails - Valor de parámetro detail no admitido.
    • NotSupportedLanguage - La operación solicitada no es compatible con el lenguaje especificado.
    • BadArgument - En el mensaje de error se proporcionan más detalles.
  • 415: error de tipo de medio no compatible. El Content-Type no está en los tipos permitidos:
    • Para una dirección URL de imagen, Content-Type debe ser application/json
    • En el caso de los datos de imagen binarios, Content-Type debe ser application/octet-stream o multipart/form-data
  • 500
    • FailedToProcess
    • Timeout - Se ha agotado el tiempo de espera del procesamiento de imágenes.
    • InternalServerError

Sugerencia

Al trabajar con Visión de Azure AI, puede encontrar errores transitorios producidos por límites de frecuencia aplicados por el servicio u otros problemas transitorios, como interrupciones de red. Para información sobre cómo controlar estos tipos de errores, consulte la sección sobre el patrón Retry en la guía de patrones de diseño en la nube y el patrón Circuit Breaker relacionado.

Pasos siguientes