Effettua una richiesta di API Vision

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

Riepilogo

  • Le richieste sono richieste POST a https://vision.googleapis.com/v1/images:annotate.
  • Devi authenticate le tue richieste.
  • Il corpo della richiesta è simile a questo. Le risposte sono simili a questa, ma i campi variano a seconda del tipo di annotazione che stai facendo.
  • Ecco come inviare una richiesta con cURL.
  • Esistono anche librerie client.
  • Cerchi una demo rapida? Soltanto trascina.

Endpoint

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

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

Autenticazione

La richiesta POST deve autenticarsi passando una chiave API o un Token OAuth. Per maggiori dettagli, consulta la pagina Esegui l'autenticazione.

Formato di richiesta JSON

Il corpo della richiesta POST contiene un oggetto JSON contenente un singolo elencorequests, che a sua volta contiene uno o più oggetti di tipoAnnotateImageRequest:

{
  "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, come posizione del file Cloud Storage o come URL accessibile pubblicamente. Consulta: Fornisci l'immagine per maggiori dettagli.

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

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

Fornire l'immagine

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

  • Come stringa di immagine con codifica base64. Se l'immagine è archiviata localmente, puoi convertirla in una stringa e passarla come valore di image.content:

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

    Consulta la sezione Codifica Base64 per le istruzioni sulla codifica attivata su varie piattaforme.

  • Come URI 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 al metodo di autenticazione in uso. Se utilizzi una chiave API, il file deve essere pubblico accessibili. Se utilizzi un account di servizio, il file deve essere accessibile all'utente che lo ha creato.

  • Come URL HTTP o HTTPS accessibile pubblicamente. Passa 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
            }
          ]
        }
      ]
    }
    

    Quando recupera le immagini da URL HTTP/HTTPS, Google non può garantire che la richiesta verrà completata. La richiesta potrebbe non andare a buon fine se l'host specificato rifiuta la richiesta (ad es. a causa del throttling delle richieste o della prevenzione dei DoS) o se Google limita le richieste al sito per la prevenzione di abusi. Come migliore non dipendere da immagini ospitate esternamente per la produzione diverse applicazioni.

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 ciascun tipo di funzionalità possono essere molto diverse. Consulta il Riferimento API Vision per informazioni esaustive.

Il codice seguente mostra una risposta di rilevamento delle etichette di esempio per la foto riportata 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 diversi linguaggi di programmazione per semplificare la procedura di creazione e invio delle richieste, nonché di ricezione e analisi delle risposte.

Consulta le librerie client per le istruzioni di installazione e utilizzo.