AI·NAVER API 변경 가이드

2018년 4월 27일 AI·NAVER API 서비스의 관리 기능의 개선에 따른 변경 가이드입니다.

사용하기 전에

Q. v1과 v2가 무엇인가요?

  • 2018년 4월 27일 AI·NAVER API 아키텍처가 개선되었습니다. 개선 이후 API 서비스 이용 방식 및 기능에 차이가 있으므로 이를 구분하기 위해서 4월 27일 이전에 생성한 Application은 v1, 4월 28일 이후에 생성한 Application은 v2로 지칭하고 있습니다.

Q. Application v2를 이용하면 어떤 점이 편리한가요?

  • 서비스 이용 한도를 고객이 직접 설정하고 변경할 수 있습니다.
  • 일별 이용 한도뿐 아니라 월별 이용 한도도 설정할 수 있습니다.
  • API 호출 수뿐 아니라 API 이용량(예: Papago의 경우 글자 수) 일별 통계도 조회할 수 있습니다.
  • v1 대비 이용 한도가 대폭 상향되었습니다.

Q. 기능이 개선된 v2는 v1보다 이용 요금이 높은가요?

  • 아닙니다. 기능이 개선된 v2도 기존 v1과 이용 요금이 동일합니다.

Q. 기존 Application v1을 이용하고 있는 경우, Application v2를 이용하려면 어떻게 해야 하나요?

  • v1을 v2로 변경하는 과정은 다음과 같습니다.
    1. 신규 Application을 생성하고 Client ID와 Secret Key를 발급받습니다(4월 28일 이후 신규 생성되는 Application은 자동으로 v2 버전의 Client ID와 Secret Key로 생성됩니다).
    2. 신규 Application에 이용할 AI·NAVER API를 등록합니다.
    3. 아래 가이드에 따라, 기존 서비스에서 AI·NAVER API 호출 시 이용되는 파라미터(API URL, Client ID, Secret Key 등)를 변경합니다.
  • SDK로 제공되는 CSR 및 Maps의 경우 v2용 SDK를 다시 적용해야 합니다.

Q. 이용하고 있는 Application이 v1인지 v2인지는 어떻게 알 수 있나요?

  • 네이버 클라우드 플랫폼 콘솔의 AI·NAVER API 서비스 화면에서 보유한 Application을 조회하면 v1과 v2의 Application 목록이 탭으로 구분되어 있습니다.

Q. Application v1도 계속 이용할 수 있나요?

  • 아닙니다. Application v1은 2018년 10월 31일까지만 서비스됩니다. 이후에는 서비스가 종료되니, 그 전에 Application v2으로 이전하시는 것을 권장합니다. 또한, 2018년 7월 1일 이후에는 Application v1에 신규 AI·NAVER API 추가가 제한되니 참고하시기 바랍니다.

Q. 네이버 클라우드 플랫폼 콘솔의 AI·NAVER API 서비스 화면에서 Application v1이 보이지 않습니다.

  • Application v1을 보유한 고객만 콘솔 화면에서 Application v1 목록이 보입니다. Application v2만 보유한 고객은 콘솔 화면에서 Application v1 목록이 보이지 않습니다.

Q. v1과 v2의 개발 가이드는 동일한가요?

Q. v2용 CSR 및 Maps 서비스 이용을 위한 SDK는 어디서 다운로드할 수 있나요?

Q. 어떤 경우에 인증 에러 70이 발생하나요?

  • 아래와 같은 경우 인증 에러 70이 발생할 수 있습니다.
    • CSR과 Maps SDK가 v2 전용이 아닌 경우
    • v1용 SDK에 v2용 Client ID 및 Secret Key를 사용할 경우
    • Client ID를 잘못 입력한 경우
    • Android Package 이름이나 iOS bundle ID가 NCP console에 입력한 값과 다른 경우

Q. 2018년 4월 27일 이후에는 추가로 Application v1은 생성할 수 있나요?

  • 아닙니다. Application v1은 2018년 10월 31일까지만 서비스됩니다. 이후에는 서비스가 종료되니, 그 이전에 Application v2으로 이전하시기를 권장드립니다. 또한, 2018년 7월 1일 이후에는 Application v1에 신규 AI·NAVER API 추가가 제한되니 참고하시기 바랍니다.

Q. v2로 변경할 때 새로 생성해야 하는 항목은 무엇이 있나요?

  • Application, SDK, Client ID, Secret Key가 있습니다.

변경 개요

개선 대상 서비스

  • Papago(NMT, SMT, Korean Name Romanizer)
  • Clova(CSR, CSS, CFR)
  • Maps
  • CAPTCHA
  • nShortURL
  • Search Trend

주요 개선 항목

주요 개선 항목 이전(v1) 이후(v2)
서비스 이용 한도의 종류 일별 한도 제공 일별에 추가적인 월별 한도 제공
서비스 이용 한도의 설정 직접 설정 불가 직접 설정 변경 가능
서비스 이용 한도의 범위 하기 상세 설명 참고 대폭 상향
이용량 조회 익일부터 조회 가능, 한 달만 제공, API 호출 수만 제공 실시간 조회, 세 달까지 제공, API 호출 수 및 과금 단위별 제공

변경 일정 요약

일정 변경 내용
2018 년 4월 27일 개선을 위한 배포 작업
배포 작업 이후 기존 Application으로 신규 생성 불가
2018 년 6월 30일 기존 Application의 서비스 추가 불가
2018 년 10월 31일 기존 Application 사용 중지

변경 사항 요약

주요 변경 사항 설명
API URL 별첨된 URL로 변경
Client ID, Client Secret 27일 이후 신규 등록한 Application 정보로 변경
인증 파라미터 변경 인증을 위한 Client ID, Client Secret의 이름 변경
SDK SDK로 제공되는 서비스(CSR, Maps)의 신규 SDK로의 변경 적용
에러 코드 일부 예외에 대한 결과값의 변경 적용(인증 오류 발생나 쿼터 한도 도달 혹은 서비스 사용 불가 등)
이용 한도 시간 기준을 UTC+9 기반에서 글로벌 서비스를 고려한 UTC 기준으로 변경 적용

변경 상세

기본 이용 한도 변경

Applcation별 Service는 일별/월별 이용 한도가 제한적으로 설정되어 있습니다. v2의 경우 UI에서 직접 이용 한도를 조절할 수 있습니다.

서비스명 이용 한도(v1) 이용 한도(v2) - default
Clova Speech Recognition 매일 36,000 초 매일 30,000 초 / 매월 300,000초
Clova Speech Synthesis 매일 100,000 글자 매일 100,000 글자 / 매월 3,000,000 글자
Clova Face Recognition 매일 50,000 건 매일 50,000 건 / 매월 300,000 건
Papago NMT 매일 5,000,000 글자 매일 5,000,000 글자 / 매월 30,000,000 글자
Papago SMT 매일 5,000,000 글자 매일 5,000,000 글자 / 매월 30,000,000 글자
Papago Korean Name Romanizer 매일 25,000 건 매일 25,000 건 / 매월 750,000 건
Maps (Web) 매일 200,000 건 매일 200,000 건 / 매월 6,000,000 건
Maps (Mobile) 매일 200,000 건 매일 200,000 건 / 매월 6,000,000 건
CAPTCHA (Image) 매일 10,000,000 건 매일 10,000,000 건 / 매월 300,000,000 건
CAPTCHA (Audio) 매일 200,000 건 매일 200,000 건 / 매월 6,000,000 건
nShortURL 매일 25,000 건 매일 25,000 건 / 매월 750,000 건
SearchTrend 매일 1,000 건 매일 1,000 건 / 매월 30,000 건

API URL

API명 이전(v1) 이후(v2) 포맷
nShortURL https://openapi.naver.com/v1/util/shorturl (GET/POST) https://naveropenapi.apigw.ntruss.com/util/v1/shorturl (GET) JSON, XML
CAPTCHA(Image) https://openapi.naver.com/v1/captcha/nkey (GET) https://naveropenapi.apigw.ntruss.com/captcha/v1/nkey (GET) JSON
CAPTCHA(Image) https://openapi.naver.com/v1/captcha/ncaptcha.bin (GET) https://naveropenapi.apigw.ntruss.com/captcha-bin/v1/ncaptcha (GET) JPG
CAPTCHA(Audio) https://openapi.naver.com/v1/captcha/skey (GET) https://naveropenapi.apigw.ntruss.com/scaptcha/v1/nkey (GET) JSON
CAPTCHA(Audio) https://openapi.naver.com/v1/captcha/scaptcha (GET) https://naveropenapi.apigw.ntruss.com/scaptcha-bin/v1/scaptcha (GET) WAV
Clova Speech Synthesis https://openapi.naver.com/v1/voice/tts.bin (POST) https://naveropenapi.apigw.ntruss.com/voice/v1/tts (POST) MP3
Papago SMT https://openapi.naver.com/v1/language/translate (POST) https://naveropenapi.apigw.ntruss.com/smt/v1/translation (POST) JSON
Papago NMT https://openapi.naver.com/v1/papago/n2mt (POST) https://naveropenapi.apigw.ntruss.com/nmt/v1/translation (POST) JSON
Clova Speech Recognition 하기 별도 설명 하기 별도 설명 JSON
Maps https://openapi.map.naver.com/openapi/v3/maps.js?clientId=CLIENT_ID (GET) https://openapi.map.naver.com/openapi/v3/maps.js?ncpClientId=CLIENT_ID (GET) -
Maps https://openapi.naver.com/v1/map/geocode (GET) https://naveropenapi.apigw.ntruss.com/map/v1/geocode (GET) JSON, XML
Maps https://openapi.naver.com/v1/map/reversegeocode (GET) https://naveropenapi.apigw.ntruss.com/map/v1/reversegeocode (GET) JSON, XML
Maps https://openapi.naver.com/v1/map/staticmap.bin (GET) https://naveropenapi.apigw.ntruss.com/map-static/v1/staticmap (GET) JPG, PNG
Search Trend https://openapi.naver.com/v1/datalab/search (POST) https://naveropenapi.apigw.ntruss.com/datalab/v1/search (POST) JSON

Client ID, Client Secret

항목 이전(v1) 이후(v2)
Client ID X-Naver-Client-Id X-NCP-APIGW-API-KEY-ID
Client Sccret X-Naver-Client-Secret X-NCP-APIGW-API-KEY

SDK

항목 이전(v1) 이후(v2)
MAP Android SDK Git https://github.com/navermaps/maps.android https://github.com/NaverCloudPlatform/maps.android
MAP Android jCenter compile 'com.naver.maps.open:naver-map-api:2.1.2@aar' compile 'com.naver.maps.open:naver-map-ncp-api:2.1.5@aar'
MAP iOS SDK Git https://github.com/navermaps/maps.ios https://github.com/NaverCloudPlatform/naverspeech-sdk-ios
CSR Android SDK Git https://github.com/naver/naverspeech-sdk-android https://github.com/NaverCloudPlatform/naverspeech-sdk-android
CSR Android jCenter compile 'com.naver.speech.clientapi:naverspeech-sdk-android:1.1.1' compile 'com.naver.speech.clientapi:naverspeech-ncp-sdk-android:1.1.3'
CSR iOS SDK Git https://github.com/naver/naverspeech-sdk-ios https://github.com/NaverCloudPlatform/naverspeech-sdk-ios

에러 코드

HTTP 상태 코드 이전(v1) 이후(v2)
401(Authentication Failed) 애플리케이션 클라이언트 아이디와 시크릿 값이 없거나 잘못된 경우 애플리케이션 클라이언트 아이디와 시크릿 값이 없거나 잘못된 경우
403(서버가 허용하지 않는 호출) HTTPS가 아닌 HTTP로 호출한 경우 404 에러로 변경
404(API 없음) API 요청 URL이 잘못된 경우 API 요청 URL이 잘못된 경우
405(메서드 허용 안함) HTTP 메서드를 잘못하여 호출한 경우(POST인데 GET으로 호출) 404 에러로 변경
400(요청 변수 확인), 403(호출 금지), 500(서버 오류) 필수 요청 변수가 빠졌거나 요청 변수 이름이 잘못된 경우 필수 요청 변수가 빠졌거나 요청 변수 이름이 잘못된 경우
400(요청 변수 확인), 403(호출 금지), 500(서버 오류) 요청 변수 값을 URL 인코딩하지 않고 전송한 경우 요청 변수 값을 URL 인코딩하지 않고 전송한 경우
429(Quota Exceeded) 오픈 API를 호출할 때 일 또는 월 허용량을 초과한 경우 오픈 API를 호출할 때 일 또는 월 허용량을 초과한 경우
429(Quota Exceeded) - 해당 API 신청을 하지 않은 경우
429(Throttle Limited) - Rate를 초과한 경우
429(Rate Limited) - Rate를 초과한 경우
500(서버 오류) API는 정상적으로 호출했지만 API 서버 유지보수나 시스템 오류로 인한 에러가 발생한 경우 API는 정상적으로 호출했지만 API 서버 유지보수나 시스템 오류로 인한 에러가 발생한 경우

기존(v1) 에러 코드 형식

{
  "errorMessage": "Authentication failed (인증에 실패하였습니다.)",
  "errorCode": "024"
}

이후(v2) 에러 코드 형식

{
  "error": {
    "errorCode": "300",
    "message": "Not Found Exception"
  }
}

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...