object detection (객체 탐지)

객체 탐지 API

입력받은 이미지로부터 객체를 탐지하고 객체의 클래스명, 바운딩 박스등 그 결과를 반환하는 REST API입니다. 이미지에서 다음과 같은 정보를 분석합니다.

  • 감지된 각 객체의 분석한 정보
    • 탐지된 객체의 클래스 번호
    • 탐지된 객체의 클래스 이름
    • 탐지된 객체의 수
    • 탐지된 객체의 바운딩 박스용 좌표
    • 탐지된 객체별 확률값

요청

POST https://naveropenapi.apigw.ntruss.com/vision-obj/v1/detect

요청 헤더

헤더명 설명
X-NCP-APIGW-API-KEY-ID 앱 등록 시 발급받은 Client ID
X-NCP-APIGW-API-KEY-ID:{Client ID}
X-NCP-APIGW-API-KEY 앱 등록 시 발급 받은 Client Secret
X-NCP-APIGW-API-KEY:{Client Secret}
Content-Type 바이너리 전송 형식
Content-Type: multipart/form-data

요청 바디

필드명 필수 여부 타입 제약 사항 설명
image Yes Binary 최대 2MB 이미지 데이터 지원 분석할 이미지

응답

응답 바디

필드 이름 데이터 타입 설명
predictions[0]['detection_classes'] List 탐지된 객체의 클래스 번호
predictions[0]['detection_names'] List 탐지된 객체의 클래스 이름
predictions[0]['num_detections'] Number 탐지된 객체의 수
predictions[0]['detection_boxes'] List 탐지된 객체의 바운딩 박스 좌표 (x1, y1, x2, y2)
predictions[0]['detection_scores'] List 탐지된 객체의 정확도 확률값

예시

요청 예시

[HTTP Request Header]
POST /vision-obj/v1/detect HTTP/1.1
Host: naveropenapi.apigw.ntruss.com
Content-Type: multipart/form-data; boundary={boundary-text}
X-NCP-APIGW-API-KEY-ID: {앱 등록 시 발급받은 Client ID}
X-NCP-APIGW-API-KEY: {앱 등록 시 발급 받은 Client Secret}
Content-Length: 96703

--{boundary-text}
Content-Disposition: form-data; name="image"; filename="test.jpg"
Content-Type: image/jpeg

{image binary data}
--{boundary-text}--

응답 예시

// 객체가 존재하는 경우
{
    "predictions": [
        {
            "num_detections": 3,
            "detection_classes": [
                18.0,
                18.0,
                3.0
            ],
            "detection_names": [
                "dog",
                "dog",
                "car"
            ],
            "detection_scores": [
                0.998164,
                0.997666,
                0.622512
            ],
            "detection_boxes": [
                [
                    0.0565129,
                    0.376249,
                    0.960169,
                    0.979782
                ],
                [
                    0.0280469,
                    0.0325073,
                    0.867158,
                    0.314543
                ],
                [
                    0.0,
                    0.700688,
                    0.099921,
                    0.795676
                ]
            ]
        }
    ]
}

// 객체가 존재하지 않는 경우
{
    "predictions": []
}

API 예제

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLConnection;

// Object Detection API 예제
public class APIExamFace {

    public static void main(String[] args) {

        StringBuffer reqStr = new StringBuffer();
        String clientId = "YOUR_CLIENT_ID";//애플리케이션 클라이언트 아이디값";
        String clientSecret = "YOUR_CLIENT_SECRET";//애플리케이션 클라이언트 시크릿값";

        try {
            String paramName = "image"; // 파라미터명은 image로 지정
            String imgFile = "이미지 파일 경로 ";
            File uploadFile = new File(imgFile);
            String apiURL = "https://naveropenapi.apigw.ntruss.com/vision-obj/v1/detect"; // 객체 인식
            URL url = new URL(apiURL);
            HttpURLConnection con = (HttpURLConnection)url.openConnection();
            con.setUseCaches(false);
            con.setDoOutput(true);
            con.setDoInput(true);
            // multipart request
            String boundary = "---" + System.currentTimeMillis() + "---";
            con.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
            con.setRequestProperty("X-NCP-APIGW-API-KEY-ID", clientId);
            con.setRequestProperty("X-NCP-APIGW-API-KEY", clientSecret);
            OutputStream outputStream = con.getOutputStream();
            PrintWriter writer = new PrintWriter(new OutputStreamWriter(outputStream, "UTF-8"), true);
            String LINE_FEED = "\r\n";
            // file 추가
            String fileName = uploadFile.getName();
            writer.append("--" + boundary).append(LINE_FEED);
            writer.append("Content-Disposition: form-data; name=\"" + paramName + "\"; filename=\"" + fileName + "\"").append(LINE_FEED);
            writer.append("Content-Type: "  + URLConnection.guessContentTypeFromName(fileName)).append(LINE_FEED);
            writer.append(LINE_FEED);
            writer.flush();
            FileInputStream inputStream = new FileInputStream(uploadFile);
            byte[] buffer = new byte[4096];
            int bytesRead = -1;
            while ((bytesRead = inputStream.read(buffer)) != -1) {
                outputStream.write(buffer, 0, bytesRead);
            }
            outputStream.flush();
            inputStream.close();
            writer.append(LINE_FEED).flush();
            writer.append("--" + boundary + "--").append(LINE_FEED);
            writer.close();
            BufferedReader br = null;
            int responseCode = con.getResponseCode();
            if(responseCode==200) { // 정상 호출
                br = new BufferedReader(new InputStreamReader(con.getInputStream()));
            } else {  // 오류 발생
                System.out.println("error!!!!!!! responseCode= " + responseCode);
                br = new BufferedReader(new InputStreamReader(con.getInputStream()));
            }
            String inputLine;
            if(br != null) {
                StringBuffer response = new StringBuffer();
                while ((inputLine = br.readLine()) != null) {
                    response.append(inputLine);
                }
                br.close();
                System.out.println(response.toString());
            } else {
                System.out.println("error !!!");
            }
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}
<?php
  // 객체 인식 Open API 예제
  $client_id = "YOUR_CLIENT_ID";
  $client_secret = "YOUR_CLIENT_SECRET";
  $url = "https://naveropenapi.apigw.ntruss.com/vision-obj/v1/detect"; // 객체 인식
  $is_post = true;
  $ch = curl_init();
  $filename = "test.jpg";
  $filesize = filesize($filename);
  echo "filesize=".$filesize;
  if($filesize > 2*1024*1024) {
      echo "2MB 이하의 이미지를 올려주세요.";
      exit;
  }
  $file_name = 'YOUR_FILE_NAME'; // 업로드할 파일명
  $cfile = curl_file_create($file_name,'image/jpeg','test_name');
  $postvars = array("filename" => $filename, "image" => $cfile);
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, $is_post);
  curl_setopt($ch, CURLOPT_INFILESIZE, $filesize);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $postvars);
  curl_setopt($ch, CURLINFO_HEADER_OUT, true);
  $headers = array();
  $headers[] = "X-NCP-APIGW-API-KEY-ID: ".$client_id;
  $headers[] = "X-NCP-APIGW-API-KEY: ".$client_secret;
  $headers[] = "Content-Type:multipart/form-data";
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec ($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  // 헤더 내용 출력
  $headerSent = curl_getinfo($ch, CURLINFO_HEADER_OUT );
  echo $headerSent;
  echo "<br />[status_code]:".$status_code."<br />";
  curl_close ($ch);
  if($status_code == 200) {
    echo $response;
  } else {
    echo "Error 내용:".$response;
  }
?>
var express = require('express');
var app = express();
var client_id = 'YOUR_CLIENT_ID';
var client_secret = 'YOUR_CLIENT_SECRET';
var fs = require('fs');
app.get('/face', function (req, res) {
   var request = require('request');
   var api_url = 'https://naveropenapi.apigw.ntruss.com/vision-obj/v1/detect'; // 객체 인식

   var _formData = {
     image:'image',
     image: fs.createReadStream(__dirname + 'YOUR_FILE_NAME'); // FILE 이름
   };
    var _req = request.post({url:api_url, formData:_formData,
      headers: {'X-NCP-APIGW-API-KEY-ID':client_id, 'X-NCP-APIGW-API-KEY': client_secret}}).on('response', function(response) {
       console.log(response.statusCode) // 200
       console.log(response.headers['content-type'])
    });
    console.log( request.head  );
    _req.pipe(res); // 브라우저로 출력
 });

 app.listen(3000, function () {
   console.log('http://127.0.0.1:3000/face app listening on port 3000!');
 });
import os
import sys
import requests
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
url = "https://naveropenapi.apigw.ntruss.com/vision-obj/v1/detect" // 객체 인식
files = {'image': open('YOUR_FILE_NAME', 'rb')}
headers = {'X-NCP-APIGW-API-KEY-ID': client_id, 'X-NCP-APIGW-API-KEY': client_secret }
response = requests.post(url,  files=files, headers=headers)
rescode = response.status_code
if(rescode==200):
    print (response.text)
else:
    print("Error Code:" + rescode)
using System;
using System.Net;
using System.Text;
using System.IO;
using System.Collections.Generic;
using System.Collections.Specialized;

namespace NaverAPI_Guide
{
    public class APIExamFace
    {
        static void Main(string[] args)
        {
            string boundary = "----------------------------" + DateTime.Now.Ticks.ToString("x");
            string FilePath = "YOUR_FILE_NAME";
            FileStream fs = new FileStream(FilePath, FileMode.Open, FileAccess.Read);
            byte[] fileData = new byte[fs.Length];
            fs.Read(fileData, 0, fileData.Length);
            fs.Close();

            string CRLF = "\r\n";
            string postData = "--" + boundary + CRLF + "Content-Disposition: form-data; name=\"image\"; filename=\"";
            postData += Path.GetFileName(FilePath) + "\"" + CRLF +"Content-Type: image/jpeg" + CRLF + CRLF;
            string footer = CRLF + "--" + boundary + "--" + CRLF;

            Stream DataStream = new MemoryStream();
            DataStream.Write(Encoding.UTF8.GetBytes(postData), 0, Encoding.UTF8.GetByteCount(postData));
            DataStream.Write(fileData, 0, fileData.Length);
            DataStream.Write(Encoding.UTF8.GetBytes("\r\n"), 0, 2);
            DataStream.Write(Encoding.UTF8.GetBytes(footer), 0, Encoding.UTF8.GetByteCount(footer));
            DataStream.Position = 0;
            byte[] formData = new byte[DataStream.Length];
            DataStream.Read(formData, 0, formData.Length);
            DataStream.Close();

            string url = "https://naveropenapi.apigw.ntruss.com/vision-obj/v1/detect"; // 객체 인식
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
            request.Headers.Add("X-NCP-APIGW-API-KEY-ID", "YOUR_CLIENT_ID");
            request.Headers.Add("X-NCP-APIGW-API-KEY", "YOUR_CLIENT_SECRET");
            request.Method = "POST";
            request.ContentType = "multipart/form-data; boundary=" + boundary;
            request.ContentLength = formData.Length;
            using (Stream requestStream = request.GetRequestStream())
            {
                requestStream.Write(formData, 0, formData.Length);
                requestStream.Close();
            }
            HttpWebResponse response = (HttpWebResponse)request.GetResponse();
            Stream stream = response.GetResponseStream();
            StreamReader reader = new StreamReader(stream, Encoding.UTF8);
            string text = reader.ReadToEnd();
            stream.Close();
            response.Close();
            reader.Close();
            Console.WriteLine(text);
        }
    }
}

오류 코드

발생 시점 Http status code API Error Code Error message Description
서비스진입 전 400 ER-A01 Unsupported method. 지원하지 않는 메서드
서비스진입 전 400 ER-A02 Bas request. 잘못된 요청
서비스진입 전 400 ER-A03 image parameter is needed. image 파라미터 누락
서비스진입 전 400 ER-A04 No image in request. 이미지 없음
서비스 내부 400 ER-B01 Wrong file type. 잘못된 파일 타입(이미지가 아닌 파일)
서비스 내부 400 ER-B02 Image size is too large. 이미지 크기 2MB 초과
서비스 내부 500 ER-B03 Inference Error. 분석 실패
서비스 내부 500 ER-B04 Internal server error. 내부서버오류