L'API Cloud Vision è un'API REST che utilizza operazioni HTTP POST per eseguire l'analisi dei dati sulle immagini che invii nella richiesta. L'API utilizza JSON sia per le richieste che per le risposte.
Riepilogo
- Le richieste sono richieste POST a
https://vision.googleapis.com/v1/images:annotate
. - Devi autenticare le tue richieste.
- Il corpo della richiesta è simile a questo. Le risposte sono simili a queste, ma i campi variano a seconda del tipo di annotazione che stai eseguendo.
- Ecco come inviare una richiesta con cURL.
- Esistono anche librerie client.
- Vuoi una breve demo? Basta trascinare.
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 Autenticazione.
Formato della richiesta JSON
Il corpo della 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 di
requests
.
All'interno dell'elenco requests
:
image
specifica il file immagine. Può essere inviato come stringa con codifica Base64, come posizione 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é ilmaxResults
da restituire per ciascuno.imageContext
(non mostrato nell'esempio precedente) specifica i suggerimenti per il servizio per facilitare l'annotazione: riquadri di delimitazione, lingue e proporzioni dei suggerimenti di ritaglio.
Fornire l'immagine
Puoi fornire l'immagine nella richiesta in tre modi:
Come stringa 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 Codifica Base64 per istruzioni sulla codifica 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 che stai utilizzando. 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 il 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 } ] } ] }
Quando recupera 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 la rifiuta (ad es. a causa della limitazione delle richieste o della prevenzione di attacchi DoS) o se Google limita le richieste al sito per prevenire abusi. 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 dell'API Vision.
Il codice riportato di seguito mostra una risposta di esempio per il rilevamento delle 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 diversi linguaggi di programmazione per semplificare la procedura di creazione e invio delle richieste, nonché di ricezione e analisi delle risposte.
Consulta la sezione Librerie client per le istruzioni di installazione e utilizzo.