Computer Vision API を呼び出すCall the Computer Vision API

この記事では、REST API を使用して Computer Vision API を呼び出す方法を紹介します。This article demonstrates how to call the Computer Vision API by using the REST API. サンプルは、Computer Vision API クライアント ライブラリを使用する C# と HTTP POST (または GET) 呼び出しの両方で記述されています。The samples are written both in C# by using the Computer Vision API client library and as HTTP POST or GET calls. この記事では、次の内容を重点的に取り上げます。The article focuses on:

  • タグ、説明、カテゴリを取得するGetting tags, a description, and categories
  • ドメイン固有情報 ("有名人") を取得するGetting domain-specific information, or "celebrities"

この記事の例では、次の機能のデモンストレーションを行います。The examples in this article demonstrate the following features:

  • 画像を分析して、タグの配列と説明を取得するAnalyzing an image to return an array of tags and a description
  • ドメイン固有モデル (具体的には "有名人" モデル) を使用して画像を分析し、対応する結果を JSON で取得するAnalyzing an image with a domain-specific model (specifically, the "celebrities" model) to return the corresponding result in JSON

これらの機能には、次のオプションがあります。The features offer the following options:

  • オプション 1:スコープされた分析 - 特定のモデルのみを分析するOption 1: Scoped Analysis - Analyze only a specified model
  • オプション 2:高度な分析 - 追加情報を提供するために、86 カテゴリ分類を使用して分析するOption 2: Enhanced Analysis - Analyze to provide additional details by using 86-categories taxonomy

前提条件Prerequisites

  • Azure サブスクリプション - 無料アカウントを作成しますAn Azure subscription - Create one for free
  • Azure サブスクリプションを入手したら、Azure portal で Computer Vision リソースを作成し、キーとエンドポイントを取得します。Once you have your Azure subscription, create a Computer Vision resource in the Azure portal to get your key and endpoint. デプロイされたら、 [リソースに移動] をクリックします。After it deploys, click Go to resource.
    • 対象のアプリケーションを Computer Vision サービスに接続するには、作成したリソースのキーとエンドポイントが必要です。You will need the key and endpoint from the resource you create to connect your application to the Computer Vision service. このクイックスタートで後に示すコードに、自分のキーとエンドポイントを貼り付けます。You'll paste your key and endpoint into the code below later in the quickstart.
    • Free 価格レベル (F0) を使用してサービスを試用し、後から運用環境用の有料レベルにアップグレードすることができます。You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.
  • ローカルに保存された画像の URL またはパスAn image URL or a path to a locally stored image
  • サポートされている入力方法: application/octet-stream 形式または画像 URL 形式の未加工画像バイナリSupported input methods: a raw image binary in the form of an application/octet-stream, or an image URL
  • サポートされる画像形式: JPEG、PNG、GIF、BMPSupported image file formats: JPEG, PNG, GIF, and BMP
  • 画像ファイルのサイズ:4 MB 以下Image file size: 4 MB or less
  • 画像サイズ: 50 × 50 ピクセル以上Image dimensions: 50 × 50 pixels or greater

API 呼び出しを承認するAuthorize the API call

Computer Vision API への呼び出しでは、毎回サブスクリプション キーが必要です。Every call to the Computer Vision API requires a subscription key. このキーは、クエリ文字列パラメーターを通じて渡すか、または要求ヘッダーで指定する必要があります。This key must be either passed through a query string parameter or specified in the request header.

サブスクリプション キーは、次のいずれかの方法で渡すことができます。You can pass the subscription key by doing any of the following:

  • 次の Computer Vision API の例のように、クエリ文字列で渡します。Pass it through a query string, as in this Computer Vision API example:

    https://westus.api.cognitive.microsoft.com/vision/v2.1/analyze?visualFeatures=Description,Tags&subscription-key=<Your subscription key>
    
  • HTTP 要求ヘッダーで指定します。Specify it in the HTTP request header:

    ocp-apim-subscription-key: <Your subscription key>
    
  • クライアント ライブラリを使用する場合、ComputerVisionClient のコンストラクターでキーを渡し、クライアントのプロパティでリージョンを指定します。When you use the client library, pass the key through the constructor of ComputerVisionClient, and specify the region in a property of the client:

    var visionClient = new ComputerVisionClient(new ApiKeyServiceClientCredentials("Your subscriptionKey"))
    {
        Endpoint = "https://westus.api.cognitive.microsoft.com"
    }
    

Computer Vision API サービスに画像をアップロードするUpload an image to the Computer Vision API service

Computer Vision API の呼び出しを実行する基本的な方法は、画像を直接アップロードして、タグ、説明、有名人を取得することです。The basic way to perform the Computer Vision API call is by uploading an image directly to return tags, a description, and celebrities. これを行うには、バイナリ画像を HTTP 本文に追加して、画像から読み取るデータと共に "POST" 要求を送信します。You do this by sending a "POST" request with the binary image in the HTTP body together with the data read from the image. アップロード方法は、すべての Computer Vision API 呼び出しで共通です。The upload method is the same for all Computer Vision API calls. 唯一の違いは、指定するクエリ パラメーターです。The only difference is the query parameters that you specify.

特定の画像について、次のいずれかのオプションを使用してタグと説明を取得します。For a specified image, get tags and a description by using either of the following options:

オプション 1: タグの一覧と説明を取得するOption 1: Get a list of tags and a description

POST https://westus.api.cognitive.microsoft.com/vision/v2.1/analyze?visualFeatures=Description,Tags&subscription-key=<Your subscription key>
using System.IO;
using Microsoft.Azure.CognitiveServices.Vision.ComputerVision;
using Microsoft.Azure.CognitiveServices.Vision.ComputerVision.Models;

ImageAnalysis imageAnalysis;
var features = new VisualFeatureTypes[] { VisualFeatureTypes.Tags, VisualFeatureTypes.Description };

using (var fs = new FileStream(@"C:\Vision\Sample.jpg", FileMode.Open))
{
  imageAnalysis = await visionClient.AnalyzeImageInStreamAsync(fs, features);
}

オプション 2:タグの一覧のみまたは説明のみを取得するOption 2: Get a list of tags only or a description only

タグのみの場合は、次を実行します。For tags only, run:

POST https://westus.api.cognitive.microsoft.com/vision/v2.1/tag?subscription-key=<Your subscription key>
var tagResults = await visionClient.TagImageAsync("http://contoso.com/example.jpg");

説明のみの場合は、次を実行します。For a description only, run:

POST https://westus.api.cognitive.microsoft.com/vision/v2.1/describe?subscription-key=<Your subscription key>
using (var fs = new FileStream(@"C:\Vision\Sample.jpg", FileMode.Open))
{
  imageDescription = await visionClient.DescribeImageInStreamAsync(fs);
}

ドメイン固有の分析 (有名人) を取得するGet domain-specific analysis (celebrities)

オプション 1: スコープされた分析 - 特定のモデルのみを分析するOption 1: Scoped analysis - Analyze only a specified model

POST https://westus.api.cognitive.microsoft.com/vision/v2.1/models/celebrities/analyze
var celebritiesResult = await visionClient.AnalyzeImageInDomainAsync(url, "celebrities");

このオプションでは、他のすべてのクエリ パラメーター {visualFeatures, details} は有効ではありません。For this option, all other query parameters {visualFeatures, details} are not valid. サポートされているすべてのモデルを表示する場合は、次のコマンドを使用します。If you want to see all supported models, use:

GET https://westus.api.cognitive.microsoft.com/vision/v2.1/models 
var models = await visionClient.ListModelsAsync();

オプション 2:高度な分析 - 追加情報を提供するために、86 カテゴリ分類を使用して分析するOption 2: Enhanced analysis - Analyze to provide additional details by using 86-categories taxonomy

1 つ以上のドメイン固有モデルからの詳細に加え、汎用的な画像分析を取得するアプリケーションでは、モデルのクエリ パラメーターを使用して v1 API を拡張します。For applications where you want to get a generic image analysis in addition to details from one or more domain-specific models, extend the v1 API by using the models query parameter.

POST https://westus.api.cognitive.microsoft.com/vision/v2.1/analyze?details=celebrities

このメソッドを呼び出すときは、まず 86 カテゴリ分類子を呼び出します。When you invoke this method, you first call the 86-category classifier. いずれかのカテゴリが既知の (対応する) モデルのカテゴリと一致した場合、分類子呼び出しの 2 番目のパスが発生します。If any of the categories matches that of a known or matching model, a second pass of classifier invocations occurs. たとえば、"details=all" の場合、または "details" に "celebrities" が含まれている場合、86 カテゴリ分類子を呼び出した後に有名人モデルを呼び出します。For example, if "details=all" or "details" includes "celebrities," you call the celebrities model after you call the 86-category classifier. 結果には、そのカテゴリに属する人物が含まれます。The result includes the category person. 有名人に関心があるユーザーにとって、この方法は、オプション 1 に比べて待ち時間が長くなります。In contrast with Option 1, this method increases latency for users who are interested in celebrities.

このケースでは、v1 のすべてのクエリ パラメーターが同じように動作します。In this case, all v1 query parameters behave in the same way. visualFeatures=categories を指定しなかった場合は、これが暗黙的に有効になります。If you don't specify visualFeatures=categories, it's implicitly enabled.

分析の JSON 出力を取得して解釈するRetrieve and understand the JSON output for analysis

次に例を示します。Here's an example:

{  
  "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
      }
    ]
  }
}
フィールドField TypeType コンテンツContent
TagsTags object タグの配列の最上位オブジェクト。The top-level object for an array of tags.
tags[].Nametags[].Name string タグ分類子からのキーワード。The keyword from the tags classifier.
tags[].Scoretags[].Score number 信頼度スコア (0 と 1 の間)。The confidence score, between 0 and 1.
descriptiondescription object description の最上位オブジェクト。The top-level object for a description.
description.tags[]description.tags[] string タグの一覧。The list of tags. キャプションを生成する機能で信頼度が不足している場合、おそらく呼び出し元が入手できる情報はタグのみになります。If there is insufficient confidence in the ability to produce a caption, the tags might be the only information available to the caller.
description.captions[].textdescription.captions[].text string 画像を説明する語句。A phrase describing the image.
description.captions[].confidencedescription.captions[].confidence number 語句の信頼度スコア。The confidence score for the phrase.

ドメイン固有モデルの JSON 出力を取得して解釈するRetrieve and understand the JSON output of domain-specific models

オプション 1: スコープされた分析 - 特定のモデルのみを分析するOption 1: Scoped analysis - Analyze only a specified model

次の例に示すように、出力はタグの配列になります。The output is an array of tags, as shown in the following example:

{  
  "result":[  
    {  
      "name":"golden retriever",
      "score":0.98
    },
    {  
      "name":"Labrador retriever",
      "score":0.78
    }
  ]
}

オプション 2:高度な分析 - 追加情報を提供するために、"86 カテゴリ" 分類を使用して分析するOption 2: Enhanced analysis - Analyze to provide additional details by using the "86-categories" taxonomy

オプション 2 (高度な分析) を使用するドメイン固有モデルでは、次の例に示したように、カテゴリの戻り値の型が拡張されます。For domain-specific models using Option 2 (enhanced analysis), the categories return type is extended, as shown in the following example:

{  
  "requestId":"87e44580-925a-49c8-b661-d1c54d1b83b5",
  "metadata":{  
    "width":640,
    "height":430,
    "format":"Jpeg"
  },
  "result":{  
    "celebrities":[  
      {  
        "name":"Richard Nixon",
        "faceRectangle":{  
          "left":107,
          "top":98,
          "width":165,
          "height":165
        },
        "confidence":0.9999827
      }
    ]
  }
}

categories フィールドは、元の分類内の86 カテゴリの 1 つまたは複数の一覧です。The categories field is a list of one or more of the 86 categories in the original taxonomy. アンダースコアで終わるカテゴリは、そのカテゴリとその子 (たとえば、有名人モデルでは "people_" と "people_group") に一致します。Categories that end in an underscore match that category and its children (for example, "people_" or "people_group," for the celebrities model).

フィールドField TypeType コンテンツContent
categoriescategories object 最上位レベルのオブジェクト。The top-level object.
categories[].namecategories[].name string 86 カテゴリ分類リストからの名前。The name from the 86-category taxonomy list.
categories[].scorecategories[].score number 信頼度スコア (0 と 1 の間)。The confidence score, between 0 and 1.
categories[].detailcategories[].detail object? (省略可能) 詳細オブジェクト。(Optional) The detail object.

複数のカテゴリと一致する場合 (たとえば、model=celebrities のときに 86 カテゴリ分類子が "people_" と "people_young" を返す場合)、詳細は、最も汎用性が高いレベルの一致 (この例では "people_") に添付されます。If multiple categories match (for example, the 86-category classifier returns a score for both "people_" and "people_young," when model=celebrities), the details are attached to the most general level match ("people_," in that example).

エラー応答Error responses

これらのエラーは vision.analyze のエラーと同一ですが、NotSupportedModel エラー (HTTP 400) が追加されています。これは、オプション 1 とオプション 2 のどちらのシナリオでも返される可能性があります。These errors are identical to those in vision.analyze, with the additional NotSupportedModel error (HTTP 400), which might be returned in both the Option 1 and Option 2 scenarios. オプション 2 (高度な分析) では、詳細に指定されたモデルのいずれかが認識されない場合は、有効なモデルが 1 つ以上ある場合でも、API は NotSupportedModel を返します。For Option 2 (enhanced analysis), if any of the models that are specified in the details isn't recognized, the API returns a NotSupportedModel, even if one or more of them are valid. サポートされているモデルは、listModels を呼び出すことで確認できます。To find out what models are supported, you can call listModels.

次のステップNext steps

REST API を使用するには、Computer Vision API リファレンスを参照してください。To use the REST API, go to Computer Vision API Reference.