Vision API-Anfrage stellen

Die Cloud Vision API ist eine REST API. Sie können damit unter Verwendung von HTTP POST-Operationen die von Ihnen in der Anfrage gesendeten Bilder analysieren. Die API verwendet für Anfragen und Antworten JSON.

Zusammenfassung

Anfragen sind POST-Anfragen an https://vision.googleapis.com/v1/images:annotate.
Sie müssen Ihre Anfragen authentifizieren.
Der Anfragetext sieht so aus. Antworten sehen etwa so aus. Die Felder variieren jedoch entsprechend dem verwendeten Anmerkungstyp.
So senden Sie eine Anfrage mit cURL.
Es gibt auch Clientbibliotheken.
Sie möchten ein kurzes Demo? Verwenden Sie einfach Drag-and-drop.

Endpunkt

Die Vision API besteht aus nur einem Endpunkt (https://vision.googleapis.com/v1/images), der wiederum nur eine HTTP-Anfragemethode (annotate) unterstützt:

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

Authentifizierung

Zur Authentifizierung der POST-Anfrage muss ein API-Schlüssel oder ein OAuth-Token übergeben werden. Weitere Informationen finden Sie auf der Seite zur Authentifizierung.

JSON-Anfrageformat

Der Text der POST-Anfrage enthält ein JSON-Objekt mit nur einer requests-Liste. Diese umfasst ein oder mehrere Objekte vom Typ AnnotateImageRequest:

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

Für alle Anfragen gilt:

Muss eine requests-Liste enthalten.

Innerhalb der requests-Liste:

gibt image die Bilddatei an. Sie kann als Base64-codierter String, als Cloud Storage-Dateispeicherort oder als öffentlich zugängliche URL gesendet werden. Details hierzu finden Sie unter Bild bereitstellen.
features listet die Typen der Anmerkungen auf, die im Bild vorgenommen werden sollen. Sie können einen oder mehrere Typen sowie die maxResults (maximale Anzahl der Ergebnisse) angeben, die zurückgegeben werden sollen.
imageContext(im obigen Beispiel nicht gezeigt) gibt dem Dienst Hinweise, die bei der Annotation helfen sollen: Begrenzungsrahmen, Sprachen und Seitenverhältnisse für Zuschneidehinweise.

Bild bereitstellen

Sie können das Bild in der Anfrage auf drei Arten bereitstellen:

Als Base64-codierten Bildstring. Wenn das Bild lokal gespeichert ist, können Sie es in einen String konvertieren und als Wert von image.content übergeben:

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

Eine Anleitung zur Codierung auf verschiedenen Plattformen finden Sie im Abschnitt zur Base64-Codierung.

Als Cloud Storage-URI. Übergeben Sie den vollständigen URI als Wert von image.source.imageUri:
```
{
  "requests":[
    {
      "image":{
        "source":{
          "imageUri":
            "gs://bucket_name/path_to_image_object"
        }
      },
      "features":[
        {
          "type":"LABEL_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}
```
Die Datei in Cloud Storage muss für die von Ihnen verwendete Authentifizierungsmethode zugänglich sein. Wenn Sie einen API-Schlüssel verwenden, muss die Datei öffentlich zugänglich sein. Wenn Sie ein Dienstkonto verwenden, muss die Datei für den Nutzer zugänglich sein, der das Dienstkonto erstellt hat.
Als öffentlich zugängliche HTTP- oder HTTPS-URL. Übergeben Sie die URL als Wert von 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
        }
      ]
    }
  ]
}
```
Beim Abrufen von Bildern von HTTP- oder HTTPS-URLs kann Google nicht garantieren, dass die Anfrage abgeschlossen wird. Ihre Anfrage kann fehlschlagen, wenn der angegebene Host die Anfrage ablehnt (z. B. aufgrund von Anfragendrosselung oder zur DoS-Prävention) oder wenn Google Anfragen an die Website drosselt, um Missbrauch vorzubeugen. Als Best Practice sollten Sie sich für Produktionsanwendungen nicht auf extern gehostete Bilder verlassen.

JSON-Antwortformat

Die annotate-Anfrage erhält eine JSON-Antwort vom Typ AnnotateImageResponse. Zwar sind die Anfragen für alle Elementtypen ähnlich, die Antworten können aber sehr unterschiedlich ausfallen. Ausführliche Informationen finden Sie in der Vision API-Referenz.

Der nachfolgende Code zeigt eine Beispielantwort für die Labelerkennung des unten dargestellten Fotos:

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

Clientbibliotheken

Google stellt Clientbibliotheken in verschiedenen Programmiersprachen bereit, um das Erstellen und Senden von Anfragen sowie den Empfang und die Analyse von Antworten zu vereinfachen.

Anleitungen zur Installation und Verwendung finden Sie unter Clientbibliotheken.