이미지 분석 API 호출

이 문서에서는 이미지 분석 API를 호출하여 이미지의 시각적 기능에 대한 정보를 반환하는 방법을 보여 줍니다. 또한 클라이언트 SDK 또는 REST API를 사용하여 반환된 정보를 구문 분석하는 방법을 보여 줍니다.

이 가이드에서는 사용자가 이미 Computer Vision 리소스를 생성했으며 키와 엔드포인트 URL을 획득했다고 가정합니다. 클라이언트 SDK를 사용하는 경우 클라이언트 개체도 인증해야 합니다. 해당 단계를 수행하지 않은 경우에는 빠른 시작에 따라 시작합니다.

서비스에 데이터 제출

이 가이드의 코드는 URL에서 참조하는 원격 이미지를 사용합니다. 이미지 분석 기능의 전체 기능을 보기 위해 다양한 이미지를 직접 시도할 수 있습니다.

원격 이미지를 분석하는 경우 {"url":"http://example.com/images/test.jpg"} 같이 요청 본문의 형식을 지정하여 이미지 URL을 지정합니다.

로컬 이미지를 분석하려면 HTTP 요청 본문에 이진 이미지 데이터를 넣습니다.

데이터 처리 방법 결정

시각적 기능 선택

분석 API를 통해 모든 서비스의 이미지 분석 기능에 액세스할 수 있습니다. 자체 사용 사례에 따라 수행할 작업을 선택합니다. 각 기능의 설명은 개요를 참조하세요. 아래 예제에서는 사용 가능한 모든 시각적 기능을 추가하지만 실제 사용 시에는 하나 또는 두 개만 필요할 수 있습니다.

분석 API의 URL 쿼리 매개 변수를 설정하여 사용하려는 기능을 지정할 수 있습니다. 매개 변수는 쉼표로 구분된 여러 값을 가질 수 있습니다. 지정하는 기능마다 추가 계산 시간이 필요하므로 필요한 항목만 지정합니다.

URL 매개 변수 Description
features Read 는 이미지에서 표시되는 텍스트를 읽고 구조화된 JSON 데이터로 출력합니다.
features Description 지원되는 언어를 사용하여 완전한 문장으로 이미지 콘텐츠를 설명합니다.
features SmartCrops 는 관심 영역을 유지하면서 이미지를 원하는 가로 세로 비율로 자르는 사각형 좌표를 찾습니다.
features Objects 이미지 내에서 대략적인 위치를 포함한 다양한 개체를 감지합니다. Objects 인수는 영어로만 사용할 수 있습니다.
features Tags 이미지 콘텐츠와 관련된 단어의 자세한 목록으로 이미지에 태그를 지정합니다.

채워진 URL은 다음과 같이 표시됩니다.

https://{endpoint}/computervision/imageanalysis:analyze?api-version=2022-10-12-preview&features=Tags

언어 지정

반환되는 데이터의 언어를 지정할 수도 있습니다.

다음 URL 쿼리 매개 변수는 언어를 지정합니다. 기본값은 en입니다.

URL 매개 변수 Description
language en 영어
language es 스페인어
language ja 일본어
language pt 포르투갈어
language zh 중국어(간체)

채워진 URL은 다음과 같이 표시됩니다.

https://{endpoint}/computervision/imageanalysis:analyze?api-version=2022-10-12-preview&features=Tags&language=en

서비스에서 결과 가져오기

이 섹션에서는 API 호출의 결과를 구문 분석하는 방법을 보여 줍니다. 여기에는 API 호출 자체가 포함됩니다.

참고

범위가 지정된 API 호출

이미지 분석 기능 중 일부는 직접 호출하거나 분석 API 호출을 통해 호출할 수 있습니다. 예를 들어, https://{endpoint}/vision/v3.2/tag(또는 SDK의 해당 메서드)에 대한 요청을 실행하여 이미지 태그에 대해서만 범위가 지정된 분석을 수행할 수 있습니다. 별도로 호출할 수 있는 다른 기능은 참조 설명서를 확인하세요.

이 서비스는 200 HTTP 응답을 반환하며 본문에는 반환된 데이터가 JSON 문자열 형식으로 포함됩니다. 다음 텍스트는 JSON 응답의 예제입니다.

{
    "metadata":
    {
        "width": 300,
        "height": 200
    },
    "tagsResult":
    {
        "values":
        [
            {
                "name": "grass",
                "confidence": 0.9960499405860901
            },
            {
                "name": "outdoor",
                "confidence": 0.9956876635551453
            },
            {
                "name": "building",
                "confidence": 0.9893627166748047
            },
            {
                "name": "property",
                "confidence": 0.9853052496910095
            },
            {
                "name": "plant",
                "confidence": 0.9791355729103088
            }
        ]
    }
}

오류 코드

가능한 오류 및 오류의 원인에 대한 다음 목록을 참조하세요.

  • 400
    • InvalidImageUrl - 이미지 URL의 형식이 잘못되었거나 액세스할 수 없습니다.
    • InvalidImageFormat - 입력 데이터가 유효한 이미지가 아닙니다.
    • InvalidImageSize - 입력 이미지가 너무 큽니다.
    • NotSupportedVisualFeature - 지정한 기능 유형이 잘못되었습니다.
    • NotSupportedImage - 지원되지 않는 이미지(예: 아동 음란물)입니다.
    • InvalidDetails - 지원되지 않는 detail 매개 변수 값입니다.
    • NotSupportedLanguage - 요청된 작업이 지정된 언어로 지원되지 않습니다.
    • BadArgument - 자세한 내용이 오류 메시지에 제공됩니다.
  • 415 - 지원되지 않는 미디어 형식 오류입니다. Content-Type은 허용되는 형식이 아닙니다.
    • 이미지 URL의 경우 Content-Type이 application/json이어야 합니다.
    • 이진 이미지 데이터의 경우 Content-Type이 application/octet-stream 또는 multipart/form-data여야 합니다.
  • 500
    • FailedToProcess
    • Timeout - 이미지 처리 시간이 초과되었습니다.
    • InternalServerError

Computer Vision을 사용하는 동안 서비스에 적용된 요금 제한에 의한 일시적인 오류나 네트워크 중단과 같은 다른 일시적인 문제가 발생할 수 있습니다. 이러한 유형의 오류를 처리하는 방법에 대한 내용은 클라우드 디자인 패턴 가이드의 다시 시도 패턴 및 관련 회로 차단기 패턴을 참조하세요.

다음 단계

  • 각 기능을 자세히 알아보려면 개념 문서를 살펴보세요.
  • 제공되는 기능을 자세히 알아보려면 API 참조를 참조하세요.