image (캡차 이미지)

이미지 캡차 API

이미지 캡차 API는 자동 입력 방지를 위해 사람의 눈으로 식별 가능한 문자가 포함된 이미지를 전송하고 입력값을 검증하는 REST API입니다.

비로그인 오픈 API 이므로 GET 으로 호출할 때 HTTP 헤더에 애플리케이션 등록 시 발급받은 Client ID와 Client Secret 값을 같이 전송해 활용할 수 있습니다.

캡차 기능 구현 절차는 다음과 같습니다.

  1. 캡차키를 발급 요청하여 발급받습니다.
  2. 발급받은 캡차키를 이용해 캡차 이미지를 요청하여 발급받습니다.
  3. 사용자가 이미지를 보고 입력한 값을 캡차키와 비교합니다.

캡차 API에는 캡차키 발급/비교 API와 캡차 이미지 요청 API 가 있습니다. 캡차키 발급/비교 API는 위의 1, 3 번 기능을 제공하고 캡차 이미지 요청 API는 2 번 기능을 제공합니다.

요청

  • 캡차 키 발급
curl "https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=0" \
	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id 값}" \
	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret 값}" -v
  • 이미지 파일 요청
curl "https://naveropenapi.apigw.ntruss.com/captcha-bin/v1/ncaptcha?key=t521bp3qM7Qyk2X2&X-NCP-APIGW-API-KEY-ID={애플리케이션 등록 시 발급받은 client id 값}" -v > image.jpg
  • 캡차 입력값 비교
curl "https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=1&key=eioDb7T8M703uht0&value=1PUNUST" \
	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id 값}" \
	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret 값}" -v

요청 파라미터

  • 캡차 키 발급
요청 변수명 타입 필수 여부 기본값 설명
code integer N 0 0 인 경우 키발급. (1 인 경우 키와 입력값 비교. 생략 시 0 으로 동작)
  • 이미지 캡차 파일 요청
요청 변수명 타입 필수 여부 기본값 설명
key string Y - 캡차 키 발급 API 호출로 받은 키 값
  • 캡차 입력값 비교
요청 변수명 타입 필수 여부 기본값 설명
code integer 0 N 캡차 키와 입력값 비교로 동작하도록 이 값을 1로 설정해야 함. 생략 시 0(키발급)으로 동작
key string Y - 캡차 키 발급 API 호출로 받은 키 값
value string Y - 이미지 캡차를 보고 사용자가 입력하는 값

요청 헤더

  • 캡차 키 발급, 캡차 입력값 비교
헤더 명 설명
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}

응답

응답 바디

  • 캡차 키 발급 요청시
필드 타입 설명
key string 캡차 키 발급 API 호출로 받은 키 값
  • 캡차 이미지 파일 요청시

JPG 포맷의 이미지 데이터

  • 캡차 입력값 비교 요청시
필드 타입 설명
result boolean 정답이 맞은 경우 true, 정답이 틀린 경우 false
responseTime string 정답을 맞추는데 걸린 시간. 응답 범위 -1 ~ 7200 사이의 값.

예시

요청 예시

  • 캡차 키 발급
> GET /v1/captcha/nkey?code=0 HTTP/1.1
> Host: naveropenapi.apigw.ntruss.com
> User-Agent: curl/7.49.1
> Accept: */*
> X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id 값}
> X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret 값}
  • 이미지캡차 파일 요청
> GET /v1/captcha-bin/ncaptcha.bin?key=t521bp3qM7Qyk2X2&X-NCP-APIGW-API-KEY-ID={애플리케이션 등록 시 발급받은 client id 값} HTTP/1.1
> Host: naveropenapi.apigw.ntruss.com
> User-Agent: curl/7.49.1
> Accept: */*
  • 캡차 입력값 비교
> GET /v1/captcha/nkey?code=1&key=eioDb7T8M703uht0&value=1PUNUST HTTP/1.1
> Host: naveropenapi.apigw.ntruss.com
> User-Agent: curl/7.49.1
> Accept: */*
> X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id 값}
> X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret 값}

응답 예시

  • 캡차 키 발급
< HTTP/1.1 200 OK
< Server: nginx
< Date: Tue, 04 Oct 2016 05:20:47 GMT
< Content-Type: text/plain;charset=UTF-8
< Content-Length: 26
< Connection: keep-alive
< Keep-Alive: timeout=5
< Vary: Accept-Encoding
< Pragma: no-cache
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< Cache-Control: no-cache
< Cache-Control: no-store
<
* Connection #0 to host naveropenapi.apigw.ntruss.com left intact
{"key":"t521bp3qM7Qyk2X2"}
  • 이미지 캡차 파일 요청
< HTTP/1.1 200 OK
< Server: nginx
< Date: Tue, 04 Oct 2016 05:21:24 GMT
< Content-Type: image/jpeg;charset=UTF-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< Keep-Alive: timeout=5
< Pragma: no-cache
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< Cache-Control: no-cache
< Cache-Control: no-store
  • 캡차 입력값 비교
< HTTP/1.1 403 Forbidden
< Server: nginx
< Date: Tue, 04 Oct 2016 05:25:21 GMT
< Content-Type: application/json;charset=UTF-8
< Content-Length: 66
< Connection: keep-alive
< Keep-Alive: timeout=5
< Vary: Accept-Encoding
< Pragma: no-cache
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< Cache-Control: no-cache
< Cache-Control: no-store
* Connection #0 to host naveropenapi.apigw.ntruss.com left intact
{"result":true,"responseTime":84.6}

API 예제

네이버 캡차 API 예제는 1) 캡차 키 발급 2) 캡차 이미지 수신 3) 캡차 입력값 비교 예제로 구성되어 있습니다.

// 네이버 캡차 API 예제 - 키발급
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;

public class APIExamCaptchaNkey {

    public static void main(String[] args) {
        String clientId = "YOUR_CLIENT_ID";//애플리케이션 클라이언트 아이디값";
        String clientSecret = "YOUR_CLIENT_SECRET";//애플리케이션 클라이언트 시크릿값";
        try {
            String code = "0"; // 키 발급시 0,  캡차 이미지 비교시 1로 세팅
            String apiURL = "https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=" + code;
            URL url = new URL(apiURL);
            HttpURLConnection con = (HttpURLConnection)url.openConnection();
            con.setRequestMethod("GET");
            con.setRequestProperty("X-NCP-APIGW-API-KEY-ID", clientId);
            con.setRequestProperty("X-NCP-APIGW-API-KEY", clientSecret);
            int responseCode = con.getResponseCode();
            BufferedReader br;
            if(responseCode==200) { // 정상 호출
                br = new BufferedReader(new InputStreamReader(con.getInputStream()));
            } else {  // 에러 발생
                br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
            }
            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = br.readLine()) != null) {
                response.append(inputLine);
            }
            br.close();
            System.out.println(response.toString());
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}

// 네이버 캡차 API 예제 - 캡차 이미지 수신
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Date;

public class APIExamCaptchaImage {

    public static void main(String[] args) {
        String clientId = "YOUR_CLIENT_ID";//애플리케이션 클라이언트 아이디값";
        try {
            String key = "CAPTCHA_KEY"; // https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey 호출로 받은 키값
            String apiURL = "https://naveropenapi.apigw.ntruss.com/captcha-bin/v1/ncaptcha?key=" + key + "&X-NCP-APIGW-API-KEY-ID" + clientId;
            URL url = new URL(apiURL);
            HttpURLConnection con = (HttpURLConnection)url.openConnection();
            con.setRequestMethod("GET");
            int responseCode = con.getResponseCode();
            BufferedReader br;
            if(responseCode==200) { // 정상 호출
                InputStream is = con.getInputStream();
                int read = 0;
                byte[] bytes = new byte[1024];
                // 랜덤한 이름으로 파일 생성
                String tempname = Long.valueOf(new Date().getTime()).toString();
                File f = new File(tempname + ".jpg");
                f.createNewFile();
                OutputStream outputStream = new FileOutputStream(f);
                while ((read =is.read(bytes)) != -1) {
                    outputStream.write(bytes, 0, read);
                }
                is.close();
            } else {  // 에러 발생
                br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
                String inputLine;
                StringBuffer response = new StringBuffer();
                while ((inputLine = br.readLine()) != null) {
                    response.append(inputLine);
                }
                br.close();
                System.out.println(response.toString());
            }
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}

// 네이버 캡차 API 예제 - 입력값 비교
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class APIExamCaptchaNkeyResult {

    public static void main(String[] args) {
        String clientId = "YOUR_CLIENT_ID";//애플리케이션 클라이언트 아이디값";
        String clientSecret = "YOUR_CLIENT_SECRET";//애플리케이션 클라이언트 시크릿값";
        try {
            String code = "1"; // 키 발급시 0,  캡차 이미지 비교시 1로 세팅
            String key = "CAPTCHA_KEY"; // 캡차 키 발급시 받은 키값
            String value = "USER_VALUE"; // 사용자가 입력한 캡차 이미지 글자값
            String apiURL = "https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=" + code +"&key="+ key + "&value="+ value;

            URL url = new URL(apiURL);
            HttpURLConnection con = (HttpURLConnection)url.openConnection();
            con.setRequestMethod("GET");
            con.setRequestProperty("X-NCP-APIGW-API-KEY-ID", clientId);
            con.setRequestProperty("X-NCP-APIGW-API-KEY", clientSecret);
            int responseCode = con.getResponseCode();
            BufferedReader br;
            if(responseCode==200) { // 정상 호출
                br = new BufferedReader(new InputStreamReader(con.getInputStream()));
            } else {  // 에러 발생
                br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
            }
            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = br.readLine()) != null) {
                response.append(inputLine);
            }
            br.close();
            System.out.println(response.toString());
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}
<?php
  // 네이버 캡차 Open API 예제 - 키 발급
  $client_id = "YOUR_CLIENT_ID";
  $client_secret = "YOUR_CLIENT_SECRET";
  $code = "0";
  $url = "https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=".$code;
  $is_post = false;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, $is_post);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $headers = array();
  $headers[] = "X-NCP-APIGW-API-KEY-ID: ".$client_id;
  $headers[] = "X-NCP-APIGW-API-KEY: ".$client_secret;
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec ($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "status_code:".$status_code."<br />";
  curl_close ($ch);
  if($status_code == 200) {
    echo $response;
  } else {
    echo "Error 내용:".$response;
  }
?>

// 네이버 캡차 Open API 예제 - 이미지수신
<?php
  $client_id = "YOUR_CLIENT_ID";
  $key = "CAPTCHA_KEY";
  $url = "https://naveropenapi.apigw.ntruss.com/captcha-bin/v1/ncaptcha?key=".$key."&X-NCP-APIGW-API-KEY-ID=".$client_id;
  $is_post = false;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, $is_post);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec ($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "status_code:".$status_code."<br />";
  curl_close ($ch);
  if($status_code == 200) {
    //echo $response;
    $fp = fopen("captcha.jpg", "w+");
    fwrite($fp, $response);
    fclose($fp);
    echo "<img src='captcha.jpg'>";
  } else {
    echo "Error 내용:".$response;
  }
?>
// 네이버 캡차 Open API 예제 - 키 입력값 비교
<?php
  $client_id = "YOUR_CLIENT_ID";
  $client_secret = "YOUR_CLIENT_SECRET";
  $key = "CAPTCHA_KEY";
  $code = "1";
  $value = "USER_VALUE";
  $url = "https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=".$code."&key=".$key."&value=".$value;
  $is_post = false;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, $is_post);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $headers = array();
  $headers[] = "X-NCP-APIGW-API-KEY-ID: ".$client_id;
  $headers[] = "X-NCP-APIGW-API-KEY: ".$client_secret;
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec ($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "status_code:".$status_code."<br />";
  curl_close ($ch);
  if($status_code == 200) {
    echo $response;
  } else {
    echo "Error 내용:".$response;
  }
?>
// 네이버 캡차 API 예제 - 키발급
var express = require('express');
var app = express();
var client_id = 'YOUR_CLIENT_ID';
var client_secret = 'YOUR_CLIENT_SECRET';
var code = "0";
app.get('/captcha/nkey', function (req, res) {
   var api_url = 'https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=' + code;
   var request = require('request');
   var options = {
       url: api_url,
       headers: {'X-NCP-APIGW-API-KEY-ID':client_id, 'X-NCP-APIGW-API-KEY': client_secret}
    };
   request.get(options, function (error, response, body) {
     if (!error && response.statusCode == 200) {
       res.writeHead(200, {'Content-Type': 'text/json;charset=utf-8'});
       res.end(body);
     } else {
       res.status(response.statusCode).end();
       console.log('error = ' + response.statusCode);
     }
   });
 });
 app.listen(3000, function () {
   console.log('http://127.0.0.1:3000/captcha/nkey app listening on port 3000!');
 });

// 네이버 캡차 API 예제 - 이미지수신
var express = require('express');
var app = express();
var client_id = 'YOUR_CLIENT_ID';
var fs = require('fs');
app.get('/captcha/image', function (req, res) {
   var api_url = 'https://naveropenapi.apigw.ntruss.com/captcha-bin/v1/ncaptcha?key=' + req.query.key + "&X-NCP-APIGW-API-KEY-ID=" + client_id;
   var request = require('request');
   var options = {
       url: api_url
    };
    var writeStream = fs.createWriteStream('./captcha.jpg');
    var _req = request.get(options).on('response', function(response) {
       console.log(response.statusCode) // 200
       console.log(response.headers['content-type'])
    });
  _req.pipe(writeStream); // file로 출력
  _req.pipe(res); // 브라우저로 출력
 });
 app.listen(3000, function () {
   console.log('http://127.0.0.1:3000/captcha/image?key=캡차키 app listening on port 3000!');
 });

// 네이버 캡차 Open API 예제 - 키 입력값 비교
var express = require('express');
var app = express();
var client_id = 'YOUR_CLIENT_ID';
var client_secret = 'YOUR_CLIENT_SECRET';
var code = "1";
app.get('/captcha/result', function (req, res) {
   var api_url = 'https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=' + code + '&key=' + req.query.key + '&value=' + req.query.value;
   var request = require('request');
   var options = {
       url: api_url,
       headers: {'X-NCP-APIGW-API-KEY-ID':client_id, 'X-NCP-APIGW-API-KEY': client_secret}
    };
   request.get(options, function (error, response, body) {
     if (!error && response.statusCode == 200) {
       res.writeHead(200, {'Content-Type': 'text/json;charset=utf-8'});
       res.end(body);
     } else {
       res.status(response.statusCode).end();
       console.log('error = ' + response.statusCode);
     }
   });
 });
 app.listen(3000, function () {
   console.log('http://127.0.0.1:3000/captcha/result?key=캡차키&value=캡차밸류 app listening on port 3000!');
 })
# Python 3.4 버전 예제입니다.
# 네이버 캡차 API 예제 - 키발급
import os
import sys
import urllib.request
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
code = "0"
url = "https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=" + code
request = urllib.request.Request(url)
request.add_header("X-NCP-APIGW-API-KEY-ID",client_id)
request.add_header("X-NCP-APIGW-API-KEY",client_secret)
response = urllib.request.urlopen(request)
rescode = response.getcode()
if(rescode==200):
    response_body = response.read()
    print(response_body.decode('utf-8'))
else:
    print("Error Code:" + rescode)

# 네이버 캡차 API 예제 - 이미지수신
import os
import sys
import urllib.request
client_id = "YOUR_CLIENT_ID"
key = "YOUR_CAPTCHA_KEY" # 캡차 Key 값
url = "https://naveropenapi.apigw.ntruss.com/captcha-bin/v1/ncaptcha?key=" + key + "&X-NCP-APIGW-API-KEY-ID=" + client_id;
request = urllib.request.Request(url)
response = urllib.request.urlopen(request)
rescode = response.getcode()
if(rescode==200):
    print("캡차 이미지 저장")
    response_body = response.read()
    with open('captcha.jpg', 'wb') as f:
        f.write(response_body)
else:
    print("Error Code:" + rescode)

# 네이버 캡차 Open API 예제 - 키 입력값 비교
import os
import sys
import urllib.request
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
code = "1"
key = "YOUR_CAPTCHA_KEY"
value = "YOUR_CAPTCHA_VALUE"
url = "https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=" + code + "&key=" + key + "&value=" + value
request = urllib.request.Request(url)
request.add_header("X-NCP-APIGW-API-KEY-ID",client_id)
request.add_header("X-NCP-APIGW-API-KEY",client_secret)
response = urllib.request.urlopen(request)
rescode = response.getcode()
if(rescode==200):
    response_body = response.read()
    print(response_body.decode('utf-8'))
else:
    print("Error Code:" + rescode)
// 네이버 캡차 API 예제 - 키발급
using System;
using System.Net;
using System.Text;
using System.IO;

namespace NaverAPI_Guide
{
    public class APIExamCaptchaNkey
    {
        static void Main(string[] args)
        {
            string code = "0"; // 키 발급시 0,  캡차 이미지 비교시 1로 세팅
            string url = "https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=" + code;
            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");
            HttpWebResponse response = (HttpWebResponse)request.GetResponse();
            string status = response.StatusCode.ToString();
            if(status == "OK")
            {
                Stream stream = response.GetResponseStream();
                StreamReader reader = new StreamReader(stream, Encoding.UTF8);
                string text = reader.ReadToEnd();
                Console.WriteLine(text);
            }
            else
            {
                Console.WriteLine("Error 발생=" + status);
            }
        }
    }
}
// 네이버 캡차 API 예제 - 이미지수신
using System;
using System.Net;
using System.Text;
using System.IO;

namespace NaverAPI_Guide
{
    public class APIExamCaptchaImage
    {
        static void Main(string[] args)
        {
            string key = "KEY-INPUT"; // https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey 호출로 받은 키값
            string url = "https://naveropenapi.apigw.ntruss.com/captcha/v1/ncaptcha?key=" + key + "&X-NCP-APIGW-API-KEY-ID=YOUR-CLIENT-ID";
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
            HttpWebResponse response = (HttpWebResponse)request.GetResponse();
            string status = response.StatusCode.ToString();
            Console.WriteLine("status="+ status);
            using (Stream output = File.OpenWrite("c:/captcha.jpg"))
            using (Stream input = response.GetResponseStream())
            {
                input.CopyTo(output);
            }
            Console.WriteLine("c:/captcha.jpg was created");
        }
    }
}

// 네이버 캡차 Open API 예제 - 키 입력값 비교
using System;
using System.Net;
using System.Text;
using System.IO;

namespace NaverAPI_Guide
{
    public class APIExamCaptchaNkeyResult
    {
        static void Main(string[] args)
        {
            string code = "1"; // 키 발급시 0,  캡차 이미지 비교시 1로 세팅
            string key = "KEY-INPUT";  // 캡차 키 발급시 받은 키값
            string value = "VALUE-INPUT";  // 사용자가 입력한 캡차 이미지 글자값
            string url = "https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey?code=" + code + "&key=" + key + "&value=" + value;
            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");
            HttpWebResponse response = (HttpWebResponse)request.GetResponse();
            string status = response.StatusCode.ToString();
            if(status == "OK")
            {
                Stream stream = response.GetResponseStream();
                StreamReader reader = new StreamReader(stream, Encoding.UTF8);
                string text = reader.ReadToEnd();
                Console.WriteLine(text);
            }
            else
            {
                Console.WriteLine("Error 발생=" + status);
            }
        }
    }
}

에러 코드

HttpStatusCode ErrorCode ErrorMessage
400 CT002 Unissued image(이미지 발급을 하지 않음)
403 CT001 Invalid key. (키가 만료되거나 없는 키)
500 CT500 System error
아쉬운 점이 있다면 이야기해 주세요.
0/5000
내용을 입력해 주세요
의견 보내기