원타임 APPKEY

APPKEY의 안전한 취급

APPKEY는 애플리케이션이 AmiVoice API를 이용할 때의 '서비스 인증 키 문자열'로, 유출될 경우 악용될 우려가 있습니다. APPKEY를 애플리케이션에 내장하면 악의적인 제3자에 의해 애플리케이션에서 APPKEY가 추출될 가능성이 있습니다. 일반적으로 자신이 소유한 APPKEY를 애플리케이션 사용자의 기기로 전송하지 마십시오. 대신 유출되어도 영향 범위를 최소화할 수 있도록 유효 기간이 있는 원타임 APPKEY를 사용하십시오.

노트

원타임 APPKEY는 마이페이지에 기재된 APPKEY와 동일한 기능을 가진 '서비스 인증 키 문자열'이지만, '발행 일시와 유효 시간'에 기반하여 '유효 기간 일시'가 설정되어 있다는 점이 다릅니다. 또한, 접속 IP 주소에 제한을 둘 수 있습니다.
원타임 APPKEY의 발행 수에는 제한이 없습니다.

주의

특히 웹 애플리케이션의 경우, HTML이나 JavaScript에 APPKEY를 기재하면 웹사이트 사용자가 볼 수 있으므로 피해주십시오.
APPKEY를 애플리케이션에 내장하는 것을 피할 수 없는 경우에는 APPKEY를 난독화, 암호화해주십시오. 난독화, 암호화를 통해 애플리케이션에서 APPKEY를 추출하기 어렵게 만들 수 있습니다.
2025/06/30 마이페이지 개편 이전에 생성된 계정의 APPKEY 및 발행된 원타임 APPKEY는 삭제할 수 없습니다. 삭제하려면 탈퇴 후 새로운 계정을 만들어야 합니다.
2025/06/30 마이페이지 개편 이후 마이페이지에서 발행된 APPKEY는 마이페이지에서 수동으로 삭제가 가능합니다. 원타임 APPKEY 발행 API를 사용하여 발행된 APPKEY는 삭제할 수 없습니다.

원타임 APPKEY 사용하기

원타임 APPKEY를 사용할 경우, 다음과 같은 구현 방법을 고려할 수 있습니다.

애플리케이션 사용자를 어떤 방법으로든 인증합니다
인증에 성공한 후, 서버 측에서 유효 기간을 설정한 원타임 APPKEY를 발행하여 애플리케이션으로 전송합니다
애플리케이션에서는 원타임 APPKEY를 사용하여 AmiVoice API를 이용합니다

다음은 원타임 APPKEY 발행 API의 사용 방법을 설명합니다.

요청

원타임 APPKEY 발행 API를 사용하려면 서비스 ID(요청 본문에 지정하며, 파라미터명은 sid)와 서비스 비밀번호(마찬가지로 spw), 또는 마이페이지에서 "APPKEY 発行可能"으로 설정하여 발행한 APPKEY(Authorization 헤더에 지정)의 설정이 필요합니다. sid와 spw에는 마이페이지의 "接続情報"에 기재된 [サービス ID]의 서비스 ID와 [サービスパスワード]의 서비스 비밀번호를 가져와서 설정하십시오.

노트

서비스 비밀번호와 마이페이지 로그인용 비밀번호는 다릅니다.

주의

sid와 spw는 요청 본문에 application/x-www-form-urlencoded 형식으로 설정하십시오. 쿼리 파라미터(URL 끝에 ?를 붙여 기재하는 방법)로는 지정하지 마십시오. 요청 시 HTTP 메소드는 POST입니다.

유효 시간(요청 파라미터명은 epi)은 임의로 설정할 수 있습니다. epi에 숫자로 설정하는 경우, 밀리초 단위로 지정합니다. 기타 설정 방법은 참조를 확인하십시오. epi를 생략한 경우 기본값으로 30000(30초)이 설정됩니다. 원타임 APPKEY를 발행한 후 실제로 AmiVoice API 요청을 보내기까지의 시간을 고려하여 설정하십시오. ipa에 APPKEY를 사용할 수 있는 IP 주소를 지정할 수 있습니다.

curl 명령어를 사용하여 원타임 APPKEY를 발행해보겠습니다.

예시1

IP 주소 203.0.113.253에서의 접속만 제한하고, 유효 기간을 발행으로부터 30초 후로 설정합니다.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={서비스ID} \
     -d spw={서비스비밀번호} \
     -d epi=30000 \
     -d ipa=203.0.113.253

sid와 spw 대신 APPKEY를 사용하는 경우는 다음과 같습니다.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d epi=30000 \
     -d ipa=203.0.113.253 \
     -H "Authorization: Bearer {APPKEY 발행 가능한 APPKEY}"

예시2

IP 주소를 범위로 지정하여 허용하고 싶은 경우, CIDR로 지정할 수 있습니다.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={서비스ID} \
     -d spw={서비스비밀번호} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24

예시3

IP 주소나 그 범위는 쉼표로 구분하여 여러 개 지정할 수도 있습니다.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={서비스ID} \
     -d spw={서비스비밀번호} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24,198.51.100.0/24

응답

응답은 plain text로, 원타임 APPKEY를 반환합니다. 그대로 요청 파라미터의 authorization 키로 설정할 수 있습니다.

오류 시 대처 방법

원타임 APPKEY로 인한 연결 인증 실패 사례

지연(기간 만료)으로 인한 인증 오류

authorization 키에 의한 인증 요청을 받는 시점이 원타임 APPKEY에 설정된 유효 기간 일시를 지난 경우, 음성 인식 서비스는 다음과 같은 오류를 반환하므로 다시 원타임 APPKEY를 취득하여 재시도해주십시오.

HTTP 인터페이스의 오류 응답

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket 인터페이스의 오류 응답

s service authorization has expired: 20XX/XX/XX XX:XX:XX.000 +0000 (-21s)

s 응답에 포함된 20XX/XX/XX XX:XX:XX.000은 원타임 APPKEY의 유효 기간 일시, -21s는 유효 기간으로부터의 지연 시간입니다.

s 명령 응답 패킷에서는 오류가 발생하지 않은 경우에도 첫 번째 p 패킷 전송까지 시간이 경과하여 유효 기간 일시를 지나버린 경우에는 첫 번째 p 패킷 전송 직후에 다음과 같은 오류 응답이 반환됩니다.

p can't feed audio data to recognizer server

p 패킷 전송 시작이 성공한 후에는 중간에 유효 기간이 만료되지 않습니다.

잘못된 ID로 인한 인증 오류

원타임 APPKEY 발행 API에 지정하는 서비스 ID・서비스 비밀번호가 잘못된 경우에도 원타임 APPKEY는 발행됩니다. AmiVoice API 요청 시 잘못된 서비스 ID, 비밀번호로 생성된 부적절한 원타임 APPKEY를 지정하면 다음과 같은 인증 오류를 반환합니다.

HTTP 인터페이스의 오류 응답

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket 인터페이스의 오류 응답

s can't verify service authorization

이 경우에는 원타임 APPKEY 발행 요청 시 지정하는 서비스 ID(sid), 서비스 비밀번호(spw)가 올바른 값인지 확인해주십시오.

원타임 APPKEY 발행 API의 자세한 내용은 참조의 원타임 APPKEY 발행 API를 참조해주십시오.

비동기 HTTP 인터페이스에서 원타임 APPKEY를 사용하는 경우

비동기 HTTP 인터페이스에서 원타임 APPKEY를 사용하는 경우에는 유효 기간을 충분히 길게 설정해주십시오. 일반적으로 음성 인식 시작까지 몇 분의 시간이 소요됩니다. 또한, 혼잡 시에는 매우 드물게 일단 중지했다가 재개하는 경우도 있어 인식 중에도 인증이 필요할 수 있습니다.

APPKEY 발행 가능한 APPKEY

2025/06/30 마이페이지 개편 이후, 마이페이지에서는 APPKEY를 발행할 수 있는 APPKEY를 발행할 수 있게 되었습니다. 이렇게 발행한 APPKEY는 원타임 APPKEY 발행 API 요청 시 서비스 ID(sid)와 서비스 비밀번호(spw) 대신 인증에 사용할 수 있습니다. APPKEY 발행 가능한 APPKEY로 발행하려면 APPKEY 발행 시 ワンタイムAPPKEYの発行 설정 화면에서 [APPKEY] 항목의 [発行可能] 체크박스에 체크를 해주십시오.

원타임 APPKEY 삭제

2025/06/30 마이페이지 개편 이후 마이페이지에서 발행된 APPKEY는 마이페이지에서 수동으로 삭제가 가능합니다. 다음은 삭제 절차를 설명합니다.

마이페이지의 ダッシュボード 대시보드에 접속합니다. 이 링크에서 직접 접속할 수 있습니다. 마이페이지 접속에는 로그인이 필요합니다.
[接続情報]에서 삭제하려는 APPKEY의 체크박스에 체크한 후, [削除] 버튼을 클릭합니다.
[APPKEYの削除]라는 확인 화면이 표시되므로 APPKEY에 오류가 없는지 확인한 후 [削除] 버튼을 클릭합니다.
계정에 등록된 이메일 주소로 인증 코드가 전송됩니다. 이 코드를 마이페이지에 표시된 [認証コードの確認] 화면에 입력하고 [送信] 버튼을 클릭합니다.
APPKEY 삭제가 완료되고 계정에 등록된 이메일 주소로 APPKEY 삭제를 알리는 메일이 도착합니다.

APPKEY의 안전한 취급​

원타임 APPKEY 사용하기​

요청​

응답​

오류 시 대처 방법​

원타임 APPKEY로 인한 연결 인증 실패 사례​

지연(기간 만료)으로 인한 인증 오류​

잘못된 ID로 인한 인증 오류​

비동기 HTTP 인터페이스에서 원타임 APPKEY를 사용하는 경우​

APPKEY 발행 가능한 APPKEY​

원타임 APPKEY 삭제​