audio (캡차 음성)

개요

음성 캡차 API는 자동 입력 방지를 위해 숫자가 포함된 음성 메시지를 전송하고 입력값을 검증하는 REST API입니다.

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

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

캡차키를 발급 요청하여 발급받습니다.
발급받은 캡차키를 이용해 캡차 음성 메시지를 요청하여 발급받습니다.
사용자가 음성 메시지를 듣고 입력한 값을 캡차키와 비교합니다.

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

요청

캡차 키 발급

curl "https://naveropenapi.apigw.gov-ntruss.com/scaptcha/v1/skey?code=0" \
    -H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id 값}" \
    -H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret 값}" -v

음성 캡차 파일 요청

curl "https://naveropenapi.apigw.gov-ntruss.com/scaptcha-bin/v1/scaptcha?key=t521bp3qM7Qyk2X2&X-NCP-APIGW-API-KEY-ID={애플리케이션 등록 시 발급받은 client id 값}" -v > output.wav

캡차 입력값 비교

curl "https://naveropenapi.apigw.gov-ntruss.com/scaptcha/v1/skey?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 호출로 받은 키 값

캡차 음성 파일 요청시

wav 포맷의 음성 데이터

캡차 입력값 비교 요청시

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

예시

요청 예시

캡차 키 발급

> GET /scaptcha/v1/skey?code=0 HTTP/1.1
> Host: naveropenapi.apigw.gov-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 /scaptcha-bin/v1/scaptcha?key=t521bp3qM7Qyk2X2&X-NCP-APIGW-API-KEY-ID={애플리케이션 등록 시 발급받은 client id 값} HTTP/1.1
> Host: naveropenapi.apigw.gov-ntruss.com
> User-Agent: curl/7.49.1
> Accept: */*

캡차 입력값 비교

> GET /scaptcha/v1/skey?code=1&key=eioDb7T8M703uht0&value=1PUNUST HTTP/1.1
> Host: naveropenapi.apigw.gov-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.gov-ntruss.com left intact
{"key":"t521bp3qM7Qyk2X2"}

음성캡차 파일 요청

< HTTP/1.1 200 OK
< Server: nginx
< Date: Tue, 04 Oct 2016 05:21:24 GMT
< Content-Type: audio/wav;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.gov-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 APIExamCaptchaSkey {

    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.gov-ntruss.com/scaptcha/v1/skey?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 APIExamCaptchaAudio {

    public static void main(String[] args) {
        String clientId = "YOUR_CLIENT_ID";//애플리케이션 클라이언트 아이디값";
        try {
            String key = "CAPTCHA_KEY"; // https://naveropenapi.apigw.gov-ntruss.com/scaptcha/v1/skey 호출로 받은 키값
            String apiURL = "https://naveropenapi.apigw.gov-ntruss.com/scaptcha-bin/v1/scaptcha?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 + ".wav");
                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 APIExamCaptchaSkeyResult {

    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.gov-ntruss.com/scaptcha/v1/skey?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.gov-ntruss.com/scaptcha/v1/skey?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.gov-ntruss.com/scaptcha-bin/v1/scaptcha?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);
  curl_setopt($ch, CURLOPT_HTTPHEADER, null);
  $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.gov-ntruss.com/scaptcha/v1/skey?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.gov-ntruss.com/scaptcha/v1/skey?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/skey 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/wav', function (req, res) {
   var api_url = 'https://naveropenapi.apigw.gov-ntruss.com/scaptcha-bin/v1/scaptcha?key=' + req.query.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.wav');
    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/wav?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.gov-ntruss.com/scaptcha/v1/skey?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.gov-ntruss.com/scaptcha/v1/skey?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.gov-ntruss.com/scaptcha-bin/v1/scaptcha?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.wav', '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.gov-ntruss.com/scaptcha/v1/skey?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.gov-ntruss.com/scaptcha/v1/skey?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 APIExamCaptchaAudio
    {
        static void Main(string[] args)
        {
            string key = "KEY-INPUT"; // https://naveropenapi.apigw.gov-ntruss.com/scaptcha/v1/skey 호출로 받은 키값
            string url = "https://naveropenapi.apigw.gov-ntruss.com/scaptcha-bin/v1/scaptcha?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.wav"))
            using (Stream input = response.GetResponseStream())
            {
                input.CopyTo(output);
            }
            Console.WriteLine("c:/captcha.wav 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.gov-ntruss.com/scaptcha/v1/skey?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 wav(음성 발급을 하지 않음)
403	CT001	Invalid key. (키가 만료되거나 없는 키)
500	CT500	System error