Vision API 요청 보내기

Cloud Vision API는 HTTP POST 작업을 사용하여 요청에서 전송한 이미지에 대해 데이터 분석을 수행하는 REST API입니다. 이 API는 요청과 응답에 JSON을 사용합니다.

요약

요청은 https://vision.googleapis.com/v1/images:annotate에 대한 POST 요청입니다.
요청을 인증해야 합니다.
요청 본문은 이러한 모양입니다. 응답은 이러한 모양과 비슷하지만 적용하는 주석 유형에 따라 필드가 달라집니다.
cURL로 요청을 보내는 방법을 참조하세요.
클라이언트 라이브러리도 제공됩니다.
간단한 데모를 원하시나요? 드래그 앤 드롭으로 가능합니다.

엔드포인트

Vision API는 HTTP 요청 메서드 하나(annotate)를 지원하는 단일 엔드포인트(https://vision.googleapis.com/v1/images)로 구성됩니다.

POST https://vision.googleapis.com/v1/images:annotate

인증

API 키 또는 OAuth 토큰을 전달하여 POST 요청을 인증해야 합니다. 자세한 내용은 인증 페이지를 참조하세요.

JSON 요청 형식

POST 요청의 본문은 JSON 객체를 포함하며, 이 객체에 포함된 단일 requests 목록은 AnnotateImageRequest 유형의 객체를 하나 이상 포함합니다.

{
  "requests":[
    {
      "image":{
        "content":"/9j/7QBEUGhvdG9...image contents...eYxxxzj/Coa6Bax//Z"
      },
      "features":[
        {
          "type":"LABEL_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}

각 요청에는 다음이 적용됩니다.

requests 목록을 포함해야 합니다.

requests 목록 내 각 항목은 다음과 같습니다.

image는 이미지 파일을 지정합니다. base64 인코딩 문자열, Google Cloud Storage 파일 위치 또는 공개적으로 액세스 가능한 URL로 전송할 수 있습니다. 자세한 내용은 이미지 제공을 참조하세요.
features는 이미지에 대해 수행할 주석의 유형을 나열합니다. 하나 이상의 유형과 각 유형에서 반환할 maxResults를 지정할 수 있습니다.
위 예시에 나오지 않은 imageContext는 주석 작업에 도움이 되는 경계 상자, 언어, 자르기 힌트의 가로세로 비율과 같은 힌트를 서비스에 지정합니다.

이미지 제공

요청에서 다음 세 가지 방법 중 하나로 이미지를 제공할 수 있습니다.

base64 인코딩 이미지 문자열. 이미지가 로컬에 저장된 경우 문자열로 변환하여 image.content의 값으로 전달할 수 있습니다.

{
  "requests":[
    {
      "image":{
        "content":"/9j/7QBEUGhvdG9zaG9...image contents...fXNWzvDEeYxxxzj/Coa6Bax//Z"
      },
      "features":[
        {
          "type":"FACE_DETECTION",
          "maxResults":10
        }
      ]
    }
  ]
}

다양한 플랫폼에서 인코딩하는 방법은 Base64 인코딩을 참조하세요.

Cloud Storage URI. 전체 URI를 image.source.imageUri의 값으로 전달합니다.

{
  "requests":[
    {
      "image":{
        "source":{
          "imageUri":
            "gs://bucket_name/path_to_image_object"
        }
      },
      "features":[
        {
          "type":"LABEL_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}

사용하는 인증 방식에서 Cloud Storage의 파일에 액세스할 수 있어야 합니다. API 키를 사용하는 경우 파일에 공개 액세스가 가능해야 합니다. 서비스 계정을 사용하는 경우 서비스 계정을 만든 사용자가 파일에 액세스할 수 있어야 합니다.

공개적으로 액세스가 가능한 HTTP 또는 HTTPS URL. URL을 image.source.imageUri의 값으로 전달합니다.
```
{
  "requests":[
    {
      "image":{
        "source":{
          "imageUri":
            "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png"
        }
      },
      "features":[
        {
          "type":"LOGO_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}
```
HTTP/HTTPS URL에서 이미지를 가져올 때 Google은 요청 완료를 보장할 수 없습니다. 지정된 호스트에서 요청을 거부하거나(예를 들어 요청 제한 또는 DoS 예방으로 인해) Google에서 악용 방지를 위해 사이트에 대한 요청을 제한하는 경우 요청이 실패할 수 있습니다. 프로덕션 애플리케이션의 외부 호스팅 이미지에 의존하지 않는 것이 좋습니다.

JSON 응답 형식

annotate 요청은 AnnotateImageResponse 유형의 JSON 응답을 수신합니다. 요청은 특징 유형에 따른 차이가 거의 없지만, 응답은 특징 유형별로 상당히 다를 수 있습니다. 자세한 내용은 Vision API 참조에서 확인하세요.

다음 코드에서는 아래 사진에 대한 라벨 감지 응답의 샘플을 보여줍니다.

{
  "responses": [
    {
      "labelAnnotations": [
        {
          "mid": "/m/0bt9lr",
          "description": "dog",
          "score": 0.97346616
        },
        {
          "mid": "/m/09686",
          "description": "vertebrate",
          "score": 0.85700572
        },
        {
          "mid": "/m/01pm38",
          "description": "clumber spaniel",
          "score": 0.84881884
        },
        {
          "mid": "/m/04rky",
          "description": "mammal",
          "score": 0.847575
        },
        {
          "mid": "/m/02wbgd",
          "description": "english cocker spaniel",
          "score": 0.75829375
        }
      ]
    }
  ]
}

클라이언트 라이브러리

Google은 다양한 프로그래밍 언어에서 요청 작성 및 전송, 응답 수신 및 파싱 과정을 단순화하는 클라이언트 라이브러리를 제공합니다.

설치 및 사용 방법은 클라이언트 라이브러리를 참조하세요.