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로 변경하는 과정은 다음과 같습니다.
- 신규 Application을 생성하고 Client ID와 Secret Key를 발급받습니다(4월 28일 이후 신규 생성되는 Application은 자동으로 v2 버전의 Client ID와 Secret Key로 생성됩니다).
- 신규 Application에 이용할 AI·NAVER API를 등록합니다.
- 아래 가이드에 따라, 기존 서비스에서 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의 개발 가이드는 동일한가요?
- 아닙니다. Application v2 전용 개발 가이드를 참고하시기 바랍니다.
Q. v2용 CSR 및 Maps 서비스 이용을 위한 SDK는 어디서 다운로드할 수 있나요?
- 공통 가이드에서 필요한 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
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"
}
}