Invia una richiesta all'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

Endpoint

L'API Vision è costituita 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 passando una chiave API o un token OAuth. Per maggiori dettagli, consulta la pagina Esegui l'autenticazione.

Formato della 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. Per maggiori 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 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 richiesta in tre modi:

  • 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
        }
      ]
    }
  ]
}

    Per istruzioni sulla codifica su varie piattaforme, consulta Codifica Base64.

  • 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 di dominio pubblico. Se utilizzi un account di servizio, il file deve essere accessibile all'utente che lo ha creato.

  • Come URL HTTP o HTTPS accessibile al pubblico. 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 della limitazione delle richieste o della prevenzione dei DoS) o se Google limita le richieste al sito per prevenire comportamenti illeciti. Come best practice, non fare affidamento su 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 il riferimento all'API Vision.

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.