Vision API リクエストを作成する

Cloud Vision API は、HTTP POST オペレーションを使用して、リクエストで送信した画像のデータ解析を行う REST API です。この API では、リクエストとレスポンスの両方で JSON を使用します。

概要

リクエストは、https://vision.googleapis.com/v1/images:annotate に対する POST リクエストです。
リクエストの認証が必要です。
リクエスト本文はこのようなものです。レスポンスはこのようになりますが、フィールドは、実行するアノテーションのタイプに応じて異なります。
cURL でリクエストを送信する方法は、次のとおりです。
クライアントライブラリもあります。
簡単なデモを用意しましたのでお試しください。ドラッグ＆ドロップするだけです。

エンドポイント

Vision API を構成するエンドポイントは 1 つ（https://vision.googleapis.com/v1/images）で、1 つの HTTP リクエストメソッド（annotate）をサポートしています。

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

認証

POST リクエストは、API キーまたは OAuth トークンのいずれかを渡して認証することが必要です。詳しくは、認証のページをご覧ください。

JSON リクエストの形式

POST リクエストの本文には、requests リストを 1 つ含む JSON オブジェクトが入ります。リストには AnnotateImageRequest タイプのオブジェクトを 1 つ以上含めることができます。

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

リクエスト作成時の注意:

requests リストを含める必要があります。

requests リストで:

image は、画像ファイルを指定します。base64 エンコード文字列、Cloud Storage ファイルの場所、または公開 URL を送信できます。詳しくは、画像の指定をご覧ください。
features では、画像に対して行うアノテーションのタイプをリストします。タイプは 1 つ以上指定でき、返される maxResults もタイプごとに指定できます。
imageContext（上の例には示されていません）では、境界ボックス、言語、クロップヒント、アスペクト比といった、アノテーションを補足するヒントをサービスリクエストに指定します。

画像の指定

リクエストで画像を指定するには次の 3 つの方法があります。

base64 エンコードの画像文字列として。画像がローカルに格納されている場合、文字列に変換し、image.content の値として渡すことができます。
```
{
  "requests":[
    {
      "image":{
        "content":"/9j/7QBEUGhvdG9zaG9...image contents...fXNWzvDEeYxxxzj/Coa6Bax//Z"
      },
      "features":[
        {
          "type":"FACE_DETECTION",
          "maxResults":10
        }
      ]
    }
  ]
}
```
さまざまなプラットフォームでのエンコードについては、base64 エンコードをご覧ください。
Cloud Storage URI として。完全な URI を image.source.imageUri の値として渡します。
```
{
  "requests":[
    {
      "image":{
        "source":{
          "imageUri":
            "gs://bucket_name/path_to_image_object"
        }
      },
      "features":[
        {
          "type":"LABEL_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}
```
Cloud Storage 内のファイルには、使用する認証方式によりアクセス可能でなければなりません。API キーを使用している場合、ファイルは公開され、アクセス可能でなければなりません。サービスアカウントを使用している場合、そのサービスアカウントを作成したユーザーからファイルにアクセス可能でなければなりません。
HTTP または HTTPS でアクセス可能な公開 URL として。URL を 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
        }
      ]
    }
  ]
}
```
HTTP / HTTPS URL から画像を取得する場合、リクエストが完了するとは限りません。リクエストの調整や DoS 防止などのため、指定したホストがリクエストを拒否することがあります。また、不正利用を防止するため、Google がサイトに対するリクエストを調整することもあります。このような状況ではリクエストが失敗します。ベストプラクティスとして、本番環境のアプリケーションでは、外部ホストの画像を頼りにしないでください。

JSON レスポンスの形式

annotate リクエストは、AnnotateImageResponse タイプの JSON レスポンスを受け取ります。リクエストはどの機能タイプでも類似していますが、レスポンスは機能タイプごとに大きく異なる場合があります。詳しくは、Vision API リファレンスをご覧ください。

以下のコードは、下の写真に対するラベル検出のレスポンスの例です。

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

クライアントライブラリ

Google では、リクエストの作成と送信、またレスポンスの受信と解析の処理を簡素化するため、複数のプログラミング言語でクライアントライブラリを用意しています。

インストール方法と使用方法については、クライアントライブラリをご覧ください。