Faire une requête dans l'API Vision

L'API Cloud Vision est une API REST qui utilise des opérations HTTP POST pour analyser les données des images que vous envoyez dans vos requêtes. L'API utilise JSON à la fois pour les requêtes et les réponses.

Résumé

  • Les requêtes POST sont à envoyer à https://vision.googleapis.com/v1/images:annotate.
  • Vous devez authentifier vos requêtes.
  • Le corps des requêtes ressemble à ceci. Les réponses ressemblent à ceci, mais les champs inclus dans la réponse varient en fonction du type d'annotation que vous faites.
  • Voici comment envoyer une requête avec cURL.
  • Il existe également des bibliothèques clientes.
  • Vous avez besoin d'une démonstration rapide ? Il vous suffit d'effectuer un glisser-déposer d'une image !

Endpoint

L'API Cloud Vision consiste en un seul point de terminaison (https://vision.googleapis.com/v1/images) compatible avec une méthode de requête HTTP (annotate) :

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

Authentification

Vos requêtes POST doivent s'authentifier en transmettant une clé API ou un jeton OAuth. Pour plus de détails, reportez-vous à la page S'authentifier.

Format de requête JSON

Le corps de la requête POST contient un objet JSON, composé lui-même d'une seule liste requests qui contient à son tour un ou plusieurs objets de type AnnotateImageRequest :

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

Chaque requête :

  • doit contenir une liste requests.

Dans la liste requests :

  • image spécifie le fichier image. Il peut prendre la forme d'une chaîne codée en base64, d'un emplacement de fichier Cloud Storage ou d'une URL accessible au public. Reportez-vous à la section Fournir l'image pour plus de détails.

  • features répertorie les types d'annotations à effectuer sur l'image. Vous pouvez spécifier un ou plusieurs types, ainsi que le maxResults à renvoyer pour chacun d'eux.

  • imageContext (non illustré dans l'exemple ci-dessus) donne des indications au service pour l'aider à annoter : cadres de délimitation, langues et formats pour les suggestions de cadrage.

Fournir l'image

Vous pouvez fournir l'image associée à votre requête de l'une des trois manières suivantes :

  • En tant que chaîne d'image encodée en base64. Si l'image est stockée localement, vous pouvez la convertir en chaîne et la transmettre en tant que valeur de image.content :

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

    Consultez la page Encodage en base64 pour obtenir des instructions sur l'encodage sur différentes plates-formes.

  • En tant qu'URI Cloud Storage. Transmettez l'URI complet en tant que valeur de image.source.imageUri :

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

    Le fichier Cloud Storage doit être accessible via la méthode d'authentification que vous utilisez. Si vous utilisez une clé API, le fichier doit être accessible au public. Si vous utilisez un compte de service, le fichier doit être accessible à l'utilisateur qui a créé le compte de service.

  • En tant qu'URL HTTP ou HTTPS accessible au public. Transmettez l'URL en tant que valeur 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
        }
      ]
    }
  ]
}

    Lorsque les images sont récupérées par le biais d'URL HTTP/HTTPS, Google ne peut pas garantir que la requête sera traitée. La requête peut échouer si l'hébergeur la rejette (par exemple, en raison de mesures de limitation du trafic ou de protection contre les attaques DoS) ou si Google limite l'accès au site afin d'empêcher tout abus. Vos applications de production ne doivent pas dépendre d'images hébergées en externe.

Format de réponse JSON

La requête annotate reçoit une réponse JSON de type AnnotateImageResponse. Bien que les différents types de requêtes soient similaires entre eux, leurs réponses peuvent être très différentes selon les fonctionnalités utilisées. Consultez la documentation de référence sur l'API Cloud Vision pour des informations détaillées.

Le code ci-dessous illustre un exemple de réponse de détection de thèmes pour la photo ci-dessous :

{
  "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
        }
      ]
    }
  ]
}

Bibliothèques clientes

Google fournit des bibliothèques clientes dans plusieurs langages de programmation afin de simplifier le processus de création et d’envoi de requêtes, ainsi que la réception et l’analyse des réponses.

Consultez la page Bibliothèques clientes pour obtenir des instructions sur leur installation et leur utilisation.