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"

필수 조건Prerequisites

  • 로컬에 저장된 이미지의 이미지 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
  • 이미지 파일 크기: 4MB 이하Image file size: 4 MB or less
  • 이미지 크기: 50 × 50 픽셀 이상Image dimensions: 50 × 50 pixels or greater

이 문서의 예제에서는 다음 기능을 보여줍니다.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

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.

평가판 키를 가져오려면 다음 중 하나를 수행합니다.To get a free trial key, do either of the following:

다음 방법 중 하나로 구독 키를 전달할 수 있습니다.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. upload 메서드는 모든 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

하나 이상의 도메인별 모델 세부 정보 외에 일반 이미지 분석을 가져오려는 애플리케이션의 경우 모델 쿼리 매개 변수를 사용하여 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-category 분류자를 호출합니다.When you invoke this method, you first call the 86-category classifier. 범주 중 하나라도 알려진 모델 또는 일치 모델의 범주와 일치하는 경우 분류자 호출이 두 번째로 전달됩니다.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-category 분류자를 호출한 후 유명인 모델을 호출합니다.For example, if "details=all" or "details" includes "celebrities," you call the celebrities model after you call the 86-category classifier. 그 결과에는 person 범주가 포함됩니다.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 ContentContent
태그들Tags 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 설명의 최상위 개체입니다.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
      }
    ]
  }
}

범주 필드는 원래 분류의 86개 범주 중 하나 이상이 포함된 목록입니다.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 ContentContent
범주categories 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

이러한 오류는 옵션 1 및 옵션 2 시나리오에서 반환될 수 있는 추가 NotSupportedModel 오류(HTTP 400)가 포함된 vision.analyze의 오류와 동일합니다.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(고급 분석)의 경우 세부 정보에 지정된 모델이 인식되지 않으면 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.