다음을 통해 공유


이미지 분석 3.2 API 호출

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

이 가이드에서는 이미 Vision 리소스 를 만들고 키와 엔드포인트 URL을 얻었다고 가정합니다. 클라이언트 SDK를 사용하는 경우 클라이언트 개체도 인증해야 합니다. 이러한 단계에 대한 자세한 내용은 이미지 분석 빠른 시작을 참조 하세요.

서비스에 데이터 제출

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

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

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

데이터 처리 방법 결정

시각적 기능 선택

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

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

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

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

<endpoint>/vision/v3.2/analyze?visualFeatures=Tags

언어 지정

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

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

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

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

<endpoint>/vision/v3.2/analyze?visualFeatures=Tags&language=en

서비스에서 결과 가져오기

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

참고 항목

범위가 지정된 API 호출

이미지 분석의 일부 기능은 직접 또는 분석 API 호출을 통해 호출할 수 있습니다. 예를 들어, <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

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