예: Computer Vision API를 호출하는 방법Example: How to call the Computer Vision API

이 가이드에서는 REST를 사용하여 Computer Vision API를 호출하는 방법을 보여 줍니다.This guide demonstrates how to call Computer Vision API using REST. 샘플은 Computer Vision API 클라이언트 라이브러리를 사용하여 C#으로 작성되고 HTTP POST/GET 호출로 작성됩니다.The samples are written both in C# using the Computer Vision API client library, and as HTTP POST/GET calls. 다음을 집중적으로 살펴보겠습니다.We will focus on:

  • “태그”, “설명” 및 “범주”를 가져오는 방법How to get "Tags", "Description" and "Categories".
  • “도메인별” 정보(유명인)를 가져오는 방법How to get "Domain-specific" information (celebrities).

필수 구성 요소Prerequisites

로컬에 저장된 이미지의 이미지 URL 또는 경로.Image URL or path to locally stored image.

  • 지원되는 입력 방법: application/octet stream 또는 이미지 URL 형식의 원시 이미지 이진Supported input methods: Raw image binary in the form of an application/octet stream or image URL
  • 지원되는 이미지 형식: JPEG, PNG, GIF, BMPSupported image formats: JPEG, PNG, GIF, BMP
  • 이미지 파일 크기: 4MB 미만Image file size: Less than 4MB
  • 이미지 크기: 50 x 50픽셀 초과Image dimension: Greater than 50 x 50 pixels

아래 예제에서는 다음 기능을 보여 줍니다.In the examples below, the following features are demonstrated:

  1. 이미지를 분석하고 반환된 태그 및 설명의 배열 가져오기.Analyzing an image and getting an array of tags and a description returned.
  2. 도메인별 모델(특히 “유명인” 모델)을 사용하여 이미지를 분석하고 반환된 해당 결과를 JSON으로 가져오기.Analyzing an image with a domain-specific model (specifically, "celebrities" model) and getting the corresponding result in JSON retune.

기능은 다음을 기준으로 분류됩니다.Features are broken down on:

  • 옵션 1: 범위 분석 - 제공된 모델만 분석Option One: Scoped Analysis - Analyze only a given model
  • 옵션 2: 고급 분석 - 86개 범주 분류를 통해 추가 정보를 제공하도록 분석Option Two: Enhanced Analysis - Analyze to provide additional details with 86-categories taxonomy

1단계: API 호출 권한 부여Step 1: Authorize the API call

Computer Vision API를 호출할 때마다 구독 키가 필요합니다.Every call to the Computer Vision API requires a subscription key. 이 키는 쿼리 문자열 매개 변수를 통해 전달되거나 요청 헤더에서 지정되어야 합니다.This key needs to be either passed through a query string parameter or specified in the request header.

구독 키를 얻으려면 구독 키를 얻는 방법을 참조하세요.To obtain a subscription key, see How to Obtain Subscription Keys.

1. 쿼리 문자열을 통한 구독 키 전달은 아래 Computer Vision API 예제를 확인합니다.1. Passing the subscription key through a query string, see below as a Computer Vision API example:

https://westus.api.cognitive.microsoft.com/vision/v2.0/analyze?visualFeatures=Description,Tags&subscription-key=<Your subscription key>

2. 구독 키 전달은 HTTP 요청 헤더에서 지정될 수도 있습니다.2. Passing the subscription key can also be specified in the HTTP request header:

ocp-apim-subscription-key: <Your subscription key>

3. 클라이언트 라이브러리를 사용하는 경우 구독 키는 VisionServiceClient의 생성자를 통해 전달됩니다.3. When using the client library, the subscription key is passed in through the constructor of VisionServiceClient:

var visionClient = new VisionServiceClient(“Your subscriptionKey”);

2단계: Computer Vision API 서비스에 이미지를 업로드하고 태그, 설명 및 유명인 다시 가져오기Step 2: Upload an image to the Computer Vision API service and get back tags, descriptions and celebrities

Computer Vision API 호출을 수행하는 기본적인 방법은 직접 이미지를 업로드하는 것입니다.The basic way to perform the Computer Vision API call is by uploading an image directly. 이미지에서 데이터 판독과 함께 응용 프로그램/옥텟 스트림 콘텐츠 형식으로 “POST” 요청을 보내 수행합니다.This is done by sending a "POST" request with application/octet-stream content type together with the data read from the image. “태그” 및 “설명”의 경우 이 업로드 메서드는 모든 Computer Vision API 호출에 동일합니다.For "Tags" and "Description", this upload method will be the same for all the Computer Vision API calls. 유일한 차이점은 사용자가 지정하는 쿼리 매개 변수입니다.The only difference will be the query parameters the user specifies.

제공된 이미지의 “태그” 및 “설명”을 가져오는 방법은 다음과 같습니다.Here’s how to get "Tags" and "Description" for a given image:

옵션 1: “태그” 및 1개 “설명”의 목록 가져오기Option One: Get list of "Tags" and one "Description"

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

AnalysisResult analysisResult;
var features = new VisualFeature[] { VisualFeature.Tags, VisualFeature.Description };

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

옵션 2: “태그” 목록만 또는 “설명” 목록만 가져오기:Option Two Get list of "Tags" only, or list of "Description" only:

태그만:Tags-only:
POST https://westus.api.cognitive.microsoft.com/vision/v2.0/tag&subscription-key=<Your subscription key>
var analysisResult = await visionClient.GetTagsAsync("http://contoso.com/example.jpg");
설명만:Description-only:
POST https://westus.api.cognitive.microsoft.com/vision/v2.0/describe&subscription-key=<Your subscription key>
using (var fs = new FileStream(@"C:\Vision\Sample.jpg", FileMode.Open))
{
  analysisResult = await visionClient.DescribeAsync(fs);
}

도메인별 분석(이 경우 유명인)을 가져오는 방법은 다음과 같습니다.Here is how to get domain-specific analysis (in our case, for celebrities).

옵션 1: 범위 분석 - 제공된 모델만 분석Option One: Scoped Analysis - Analyze only a given model

POST https://westus.api.cognitive.microsoft.com/vision/v2.0/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.0/models 
var models = await visionClient.ListModelsAsync();

옵션 2: 고급 분석 - 86개 범주 분류를 통해 추가 정보를 제공하도록 분석Option Two: Enhanced Analysis - Analyze to provide additional details with 86-categories taxonomy

하나 이상 도메인별 모델의 세부 정보 외에 일반 이미지 분석을 가져오려는 응용 프로그램의 경우 모델 쿼리 매개 변수를 사용하여 v1 API를 확장합니다.For applications where you want to get generic image analysis in addition to details from one or more domain-specific models, we extend the v1 API with the models query parameter.

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

이 메서드를 호출하는 경우 86개 범주 분류자를 먼저 호출합니다.When this method is invoked, we will call the 86-category classifier first. 범주 중 하나라도 알려진/일치 모델의 범주와 일치할 경우 분류자 호출의 두 번째 전달이 발생합니다.If any of the categories match that of a known/matching model, a second pass of classifier invocations will occur. 예를 들어 “details=all” 또는 “details”에 ‘celebrities’가 포함된 경우 86개 범주 분류자가 호출된 후 유명인 모델을 호출하고 결과에는 범주 사용자가 포함됩니다.For example, if "details=all", or "details" include ‘celebrities’, we will call the celebrities model after the 86-category classifier is called and the result includes the category person. 이렇게 하면 유명인에 관심 있는 사용자의 대기 시간이 옵션 1에 비해 증가합니다.This will increase latency for users interested in celebrities, compared to Option One.

이 경우 모든 v1 쿼리 매개 변수는 동일하게 동작합니다.All v1 query parameters will behave the same in this case. visualFeatures=categories가 지정되지 않으면 암시적으로 사용하도록 설정됩니다.If visualFeatures=categories is not specified, it will be implicitly enabled.

3단계: analyze&visualFeatures=Tags, Description에 대한 JSON 출력 검색 및 이해Step 3: Retrieving and understanding the JSON output for analyze&visualFeatures=Tags, Description

예를 들면 다음과 같습니다.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 ContentContent
태그들Tags objectobject 태그 배열의 최상위 개체Top-level object for array of tags
tags[].Nametags[].Name stringstring 태그 분류자의 키워드Keyword from tags classifier
tags[].Scoretags[].Score numbernumber 신뢰도 점수, 0~1.Confidence score, between 0 and 1.
descriptiondescription objectobject 설명의 최상위 개체.Top-level object for a description.
description.tags[]description.tags[] stringstring 태그 목록.List of tags. 캡션을 생성하는 기능에 신뢰도가 부족한 경우 태그는 호출자에게 제공되는 유일한 정보일 수 있습니다.If there insufficient confidence in the ability to produce a caption, the tags maybe the only information available to the caller.
description.captions[].textdescription.captions[].text stringstring 이미지를 설명하는 구.A phrase describing the image.
description.captions[].confidencedescription.captions[].confidence numbernumber 구의 신뢰도.Confidence for the phrase.

4단계: 도메인별 모델의 JSON 출력 검색 및 이해Step 4: Retrieving and understanding the JSON output of domain-specific models

옵션 1: 범위 분석 - 제공된 모델만 분석Option One: Scoped Analysis - Analyze only a given model

출력은 태그 배열이고, 예제는 다음과 같습니다.The output will be an array of tags, an example will be like this example:

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

옵션 2: 고급 분석 - 86개 범주 분류를 통해 추가 정보를 제공하도록 분석Option Two: Enhanced Analysis - Analyze to provide additional details with 86-categories taxonomy

옵션 2(고급 분석)를 사용한 도메인별 모델의 경우 범주 반환 형식이 확장됩니다.For domain-specific models using Option Two (Enhanced Analysis), the categories return type is extended. 예제는 다음과 같습니다.An example follows:

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

범주 필드는 원래 분류의 86개 범주 중 하나 이상이 포함된 목록입니다.The categories field is a list of one or more of the 86-categories in the original taxonomy. 밑줄로 끝나는 범주는 해당 범주 및 자식과 일치합니다(예: 유명인 모델의 경우 people_ 및 people_group).Note also that categories ending in an underscore will match that category and its children (for example, people_ as well as people_group, for celebrities model).

필드Field typeType ContentContent
범주categories objectobject 최상위 개체Top-level object
categories[].namecategories[].name stringstring 86개 범주 분류의 이름Name from 86-category taxonomy
categories[].scorecategories[].score numbernumber 신뢰도 점수, 0~1Confidence score, between 0 and 1
categories[].detailcategories[].detail object?object? 선택적 세부 정보 개체Optional detail object

여러 범주가 일치하는 경우(예: model=celebrities일 경우 86개 범주 분류자가 people_ 및 people_young의 점수를 둘 다 반환하는 경우) 세부 정보는 가장 일반적인 수준 일치(이 예제에서는 people_)에 연결됩니다.Note that if multiple categories match (for example, 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.)

오류 응답Errors Responses

이는 옵션 1 및 옵션 2 시나리오에서 둘 다 반환될 수 있는, NotSupportedModel 오류(HTTP 400)의 추가 오류가 포함된 vision.analyze와 동일합니다.These are identical to vision.analyze, with the additional error of NotSupportedModel error (HTTP 400), which may be returned in both Option One and Option Two scenarios. 옵션 2(고급 분석)의 경우 세부 정보에 지정된 모델이 인식되지 않으면 API는 모델 중 하나 이상이 유효하더라도 NotSupportedModel을 반환합니다.For Option Two (Enhanced Analysis), if any of the models specified in details are not recognized, the API will return a NotSupportedModel, even if one or more of them are valid. 사용자는 listModels를 호출하여 지원되는 모델을 찾을 수 있습니다.Users can call listModels to find out what models are supported.

요약Summary

이는 Computer Vision API의 기본 기능으로, 이미지를 업로드하고 반환으로 중요한 메타데이터를 검색하는 방법입니다.These are the basic functionalities of the Computer Vision API: how you can upload images and retrieve valuable metadata in return.

REST API를 사용하려면 Computer Vision API 참조로 이동합니다.To use the REST API, go to Computer Vision API Reference.