Chiamare l'API di analisi immagini

Questo articolo illustra come chiamare l'API Analisi immagini per restituire informazioni sulle funzionalità visive di un'immagine. Illustra anche come analizzare le informazioni restituite usando gli SDK client o l'API REST.

Questa guida presuppone che sia già stata creata una risorsa Visione artificiale e ottenuta una chiave di sottoscrizione e un URL dell'endpoint. Se si usa un SDK client, è anche necessario autenticare un oggetto client. Se questi passaggi non sono stati eseguiti, seguire la guida introduttiva per iniziare.

Inviare dati al servizio

Il codice in questa guida usa immagini remote a cui fa riferimento l'URL. È possibile provare immagini diverse autonomamente per visualizzare la funzionalità completa delle funzionalità di analisi delle immagini.

Quando si analizza un'immagine locale, si inseriscono i dati dell'immagine binaria nel corpo della richiesta HTTP. Per un'immagine remota, specificare l'URL dell'immagine formattando il corpo della richiesta come indicato di seguito: {"url":"http://example.com/images/test.jpg"}.

Determinare come elaborare i dati

Selezionare le funzionalità visive

L'API Analizza consente di accedere a tutte le funzionalità di analisi delle immagini del servizio. Scegliere le operazioni da eseguire in base al proprio caso d'uso. Per una descrizione di ogni funzionalità, vedere la panoramica . Gli esempi seguenti aggiungono tutte le funzionalità visive disponibili, ma per l'utilizzo pratico è probabile che sia necessario solo uno o due.

È possibile specificare le funzionalità da usare impostando i parametri di query URL dell'API Analizza. Un parametro può avere più valori, separati da virgole. Ogni funzionalità specificata richiederà più tempo di calcolo, quindi specificare solo gli elementi necessari.

Parametro dell'URL Valore Descrizione
visualFeatures Adult rileva se l'immagine è pornografica in natura (mostra nudità o un atto sessuale) o è gory (rappresenta la violenza estrema o il sangue). Viene rilevato anche contenuto sessualmente suggestivo ("contenuto racy").
visualFeatures Brands rileva vari marchi all'interno di un'immagine, inclusa la posizione approssimativa. L'argomento Brand è disponibile solo in inglese.
visualFeatures Categories classifica il contenuto dell'immagine in base a una tassonomia definita nella documentazione. Questo valore è il valore predefinito di visualFeatures.
visualFeatures Color determina il colore accentato, il colore dominante e se un'immagine è blackwhite&.
visualFeatures Description descrive il contenuto dell'immagine con una frase completa nelle lingue supportate.
visualFeatures Faces rileva se i visi sono presenti. Se presente, generare coordinate, sesso e età.
visualFeatures ImageType rileva se l'immagine è clip art o un disegno a linee.
visualFeatures Objects rileva vari oggetti all'interno di un'immagine, inclusa la posizione approssimativa. L'argomento Objects è disponibile solo in inglese.
visualFeatures Tags contrassegna l'immagine con un elenco dettagliato di parole correlate al contenuto dell'immagine.
details Celebrities identifica le celebrità se rilevate nell'immagine.
details Landmarks identifica i punti di riferimento se rilevati nell'immagine.

Un URL popolato potrebbe essere simile al seguente:

https://{endpoint}/vision/v2.1/analyze?visualFeatures=Description,Tags&details=Celebrities

Specificare le lingue

È anche possibile specificare la lingua dei dati restituiti.

Il parametro di query URL seguente specifica il linguaggio. Il valore predefinito è en.

Parametro dell'URL Valore Descrizione
language en Inglese
language es Spagnolo
language ja Giapponese
language pt Portoghese
language zh Cinese semplificato

Un URL popolato potrebbe essere simile al seguente:

https://{endpoint}/vision/v2.1/analyze?visualFeatures=Description,Tags&details=Celebrities&language=en

Ottenere risultati dal servizio

Questa sezione illustra come analizzare i risultati della chiamata API. Include la chiamata API stessa.

Nota

Chiamate API con ambito

Alcune delle funzionalità in Analisi immagini possono essere chiamate direttamente e tramite la chiamata api Analizza. Ad esempio, è possibile eseguire un'analisi con ambito solo dei tag di immagine eseguendo una richiesta a https://{endpoint}/vision/v3.2/tag (o al metodo corrispondente nell'SDK). Vedere la documentazione di riferimento per altre funzionalità che possono essere chiamate separatamente.

Il servizio restituisce una 200 risposta HTTP e il corpo contiene i dati restituiti sotto forma di stringa JSON. Il testo seguente è un esempio di risposta JSON.

{  
  "tags":[  
    {  
      "name":"outdoor",
      "score":0.976
    },
    {  
      "name":"bird",
      "score":0.95
    }
  ],
  "description":{  
    "tags":[  
      "outdoor",
      "bird"
    ],
    "captions":[  
      {  
        "text":"partridge in a pear tree",
        "confidence":0.96
      }
    ]
  }
}

Per le spiegazioni dei campi in questo esempio, vedere la tabella seguente:

Campo Type Contenuto
Tag object L'oggetto di primo livello per una matrice di tag.
tags[].Name string La parola chiave del classificatore di tag.
tags[].Score number Il punteggio di attendibilità, compreso tra 0 e 1.
description object Oggetto di primo livello per una descrizione dell'immagine.
description.tags[] string L'elenco di tag. Se l'attendibilità nella capacità di produrre una didascalia non è sufficiente, i tag potrebbero essere l'unica informazione disponibile per il chiamante.
description.captions[].text string Frase che descrive l'immagine.
description.captions[].confidence number Il punteggio di attendibilità per la frase.

Codici di errore

Vedere l'elenco seguente di possibili errori e delle relative cause:

  • 400
    • InvalidImageUrl - L'URL dell'immagine non è formattato o non è accessibile.
    • InvalidImageFormat - I dati di input non sono un'immagine valida.
    • InvalidImageSize - L'immagine di input è troppo grande.
    • NotSupportedVisualFeature - Il tipo di funzionalità specificato non è valido.
    • NotSupportedImage - Immagine non supportata, ad esempio pornografia infantile.
    • InvalidDetails - Valore del parametro non supportato detail .
    • NotSupportedLanguage - L'operazione richiesta non è supportata nella lingua specificata.
    • BadArgument - Vengono forniti altri dettagli nel messaggio di errore.
  • 415 - Errore del tipo di supporto non supportato. Il tipo di contenuto non è nei tipi consentiti:
    • Per un URL di immagine, Content-Type deve essere application/json
    • Per i dati di un'immagine binaria, Content-Type deve essere application/octet-stream o multipart/form-data
  • 500
    • FailedToProcess
    • Timeout - Timeout dell'elaborazione delle immagini.
    • InternalServerError

Suggerimento

Durante l'uso di Visione artificiale, è possibile che si verifichino errori temporanei causati dai limiti di velocità applicati dal servizio o da altri problemi temporanei, ad esempio interruzioni di rete. Per informazioni sulla gestione di questi tipi di errori, vedere Modello di ripetizione dei tentativi nella guida Modelli di progettazione cloud e l'articolo correlato Modello a interruttore.

Passaggi successivi

  • Esplorare gli articoli sui concetti per altre informazioni su ogni funzionalità.
  • Per altre informazioni sulla funzionalità dell'API, vedere le informazioni di riferimento sulle API.