Hacer una solicitud a la API de Vision

La API Cloud Vision es una API REST que usa operaciones HTTP POST para analizar los datos de las imágenes que envías en la solicitud. La API usa JSON tanto para las solicitudes como para las respuestas.

Resumen

• Las solicitudes son solicitudes POST a https://vision.googleapis.com/v1/images:annotate.
• Debes autenticar tus solicitudes.
• El cuerpo de la solicitud tiene el siguiente aspecto. Las respuestas serán similares a esta, pero los campos variarán en función del tipo de anotación que estés haciendo.
• A continuación, se explica cómo enviar una solicitud con cURL.
• También hay bibliotecas de cliente.
• ¿Quieres ver una demostración rápida? Solo tienes que arrastrar y soltar.

Endpoint

La API Vision consta de un único endpoint (https://vision.googleapis.com/v1/images) que admite un método de solicitud HTTP (annotate):

POST https://vision.googleapis.com/v1/images:annotate

Autenticación

La solicitud POST debe autenticarse mediante una clave de API o un token de OAuth. Para obtener más información, consulta la página Autenticar.

Formato de solicitud JSON

El cuerpo de la solicitud POST contiene un objeto JSON que incluye una lista requests, que a su vez contiene uno o varios objetos de tipo AnnotateImageRequest:

{
  "requests":[
    {
      "image":{
        "content":"/9j/7QBEUGhvdG9...image contents...eYxxxzj/Coa6Bax//Z"
      },
      "features":[
        {
          "type":"LABEL_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}

Cada solicitud:

• Debe contener una lista requests.

En la lista requests:

• image especifica el archivo de imagen. Se puede enviar como una cadena codificada en Base64, como una ubicación de archivo de Cloud Storage o como una URL de acceso público. Para obtener más información, consulta la sección Proporcionar la imagen.

• features muestra los tipos de anotación que se pueden realizar en la imagen. Puedes especificar uno o varios tipos, así como el maxResults que se devolverá para cada uno.

• imageContext (no se muestra en el ejemplo anterior) especifica sugerencias para el servicio que ayudan con las anotaciones: cuadros delimitadores, idiomas y relaciones de aspecto de las sugerencias de recorte.

Proporcionar la imagen

Puedes proporcionar la imagen en tu solicitud de tres formas:

• Como una cadena de imagen codificada en Base64. Si la imagen se almacena de forma local, puede convertirla en una cadena y pasarla como valor de image.content:

  {
    "requests":[
      {
        "image":{
          "content":"/9j/7QBEUGhvdG9zaG9...image contents...fXNWzvDEeYxxxzj/Coa6Bax//Z"
        },
        "features":[
          {
            "type":"FACE_DETECTION",
            "maxResults":10
          }
        ]
      }
    ]
  }
  

  Consulta las instrucciones para codificar en Base64 en varias plataformas.

• Como URI de Cloud Storage. Transmita el URI completo como valor de image.source.imageUri:

  {
    "requests":[
      {
        "image":{
          "source":{
            "imageUri":
              "gs://bucket_name/path_to_image_object"
          }
        },
        "features":[
          {
            "type":"LABEL_DETECTION",
            "maxResults":1
          }
        ]
      }
    ]
  }
  

  El archivo de Cloud Storage debe ser accesible para el método de autenticación que estés usando. Si usas una clave de API, el archivo debe ser accesible públicamente. Si usas una cuenta de servicio, el usuario que la haya creado debe tener acceso al archivo.

• Como una URL HTTP o HTTPS de acceso público. Transfiere la URL como valor de image.source.imageUri:

  {
    "requests":[
      {
        "image":{
          "source":{
            "imageUri":
              "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png"
          }
        },
        "features":[
          {
            "type":"LOGO_DETECTION",
            "maxResults":1
          }
        ]
      }
    ]
  }
  

  Cuando se obtienen imágenes de URLs HTTP o HTTPS, Google no puede garantizar que la solicitud se complete. Es posible que tu solicitud falle si el host especificado la deniega (por ejemplo, debido a la limitación de solicitudes o a la prevención de ataques DoS) o si Google limita las solicitudes al sitio para evitar abusos. Como práctica recomendada, no dependas de imágenes alojadas externamente para las aplicaciones de producción.

Formato de respuesta JSON

La solicitud annotate recibe una respuesta JSON de tipo AnnotateImageResponse. Aunque las solicitudes son similares para cada tipo de función, las respuestas de cada tipo de función pueden ser muy diferentes. Consulta la referencia de la API Vision para obtener información completa.

El código que se muestra a continuación es un ejemplo de respuesta de detección de etiquetas de la foto que se muestra a continuación:

{
  "responses": [
    {
      "labelAnnotations": [
        {
          "mid": "/m/0bt9lr",
          "description": "dog",
          "score": 0.97346616
        },
        {
          "mid": "/m/09686",
          "description": "vertebrate",
          "score": 0.85700572
        },
        {
          "mid": "/m/01pm38",
          "description": "clumber spaniel",
          "score": 0.84881884
        },
        {
          "mid": "/m/04rky",
          "description": "mammal",
          "score": 0.847575
        },
        {
          "mid": "/m/02wbgd",
          "description": "english cocker spaniel",
          "score": 0.75829375
        }
      ]
    }
  ]
}

Bibliotecas de cliente

Google ofrece bibliotecas de cliente en varios lenguajes de programación para simplificar el proceso de crear y enviar solicitudes, así como de recibir y analizar respuestas.

Consulta las instrucciones de instalación y uso en el artículo Bibliotecas de cliente.