Effettua una richiesta API Vision

L'API Cloud Vision è un'API REST che utilizza operazioni POST HTTP per eseguire l'analisi dei dati sulle immagini inviate nella richiesta. L'API usa JSON sia per le richieste che per le risposte.

Riepilogo

Endpoint

L'API Vision è composta da un singolo endpoint (https://vision.googleapis.com/v1/images) che supporta un metodo di richiesta HTTP (annotate):

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

Autenticazione

La richiesta POST deve essere autenticata trasmettendo una chiave API o un token OAuth. Per maggiori dettagli, vedi la pagina Autentica.

Formato della richiesta JSON

Il corpo della tua richiesta POST contiene un oggetto JSON, contenente un singolo elenco requests, che a sua volta contiene uno o più oggetti di tipo AnnotateImageRequest:

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

Ogni richiesta:

  • Deve contenere un elenco requests.

Nell'elenco requests:

  • image specifica il file immagine. Può essere inviato come stringa con codifica Base64, il percorso di un file Cloud Storage o come URL accessibile pubblicamente. Per ulteriori dettagli, consulta la sezione Fornire l'immagine.

  • features elenca i tipi di annotazione da eseguire sull'immagine. Puoi specificare uno o più tipi, nonché il maxResults da restituire per ciascuno.

  • imageContext (non mostrato nell'esempio sopra) specifica suggerimenti al servizio per agevolare l'annotazione: riquadri di delimitazione, lingue e proporzioni dei suggerimenti di ritaglio.

Fornire l'immagine

Puoi fornire l'immagine nella tua richiesta in uno dei tre seguenti modi:

  • Come stringa immagine con codifica Base64. Se l'immagine viene archiviata in locale, puoi convertirla in una stringa e trasmetterla come valore di image.content:

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

    Consulta la pagina relativa alla codifica Base64 per istruzioni sulla codifica su varie piattaforme.

  • Come URI di Cloud Storage. Passa l'URI completo come valore di image.source.imageUri:

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

    Il file in Cloud Storage deve essere accessibile per il metodo di autenticazione in uso. Se utilizzi una chiave API, il file deve essere accessibile pubblicamente. Se utilizzi un account di servizio, il file deve essere accessibile all'utente che ha creato l'account di servizio.

  • Come URL HTTP o HTTPS accessibile pubblicamente. Trasmetti l'URL come valore di 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
        }
      ]
    }
  ]
}

    Durante il recupero delle immagini dagli URL HTTP/HTTPS, Google non può garantire che la richiesta venga completata. La tua richiesta potrebbe non riuscire se l'host specificato la rifiuta (ad es. a causa di limitazioni della richiesta o di prevenzione DoS) oppure se Google limita le richieste al sito per prevenire gli abusi. Come best practice, non dipendere da immagini ospitate esternamente per le applicazioni di produzione.

Formato della risposta JSON

La richiesta annotate riceve una risposta JSON di tipo AnnotateImageResponse. Sebbene le richieste siano simili per ogni tipo di funzionalità, le risposte per ogni tipo di funzionalità possono essere molto diverse. Per informazioni complete, consulta la pagina di riferimento sull'API Vision.

Il codice seguente mostra un esempio di risposta di rilevamento etichette per la foto mostrata di seguito:

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

Librerie client

Google fornisce librerie client in una serie di linguaggi di programmazione per semplificare il processo di creazione e invio delle richieste e di ricezione e analisi delle risposte.

Per le istruzioni sull'installazione e sull'utilizzo, consulta Librerie client.