메인 콘텐츠로 건너뛰기

API Key 발급 API 사용 방법

API Key 발급 API 사용하기​

API key 발급 API를 사용하여 발급한 API key를 이용하는 경우, 다음과 같은 구현 방법을 고려할 수 있습니다.

  1. 애플리케이션 사용자를 어떤 방법으로든 인증합니다.
  2. 인증에 성공한 후, 서버 측에서 API key 발급 API를 사용하여 유효 기간 등을 설정한 API key를 발급하여 애플리케이션에 전송합니다.
  3. 애플리케이션에서는 발급된 API key를 사용하여 AmiVoice API를 이용합니다.

다음은 API key 발급 API 사용 방법에 대해 설명합니다. API 세부 사항은 참조를 확인하십시오.

엔드포인트​

POST https://acp-api.amivoice.com/issue_service_authorization

요청​

API key 발급 API를 사용하려면 서비스 ID(요청 본문에 지정하며 매개변수 이름은 sid)와 서비스 비밀번호(동일하게 spw), 또는 마이페이지에서 API key 발급 기능을 부여하여 발급한 API key(Authorization 헤더에 지정) 중 하나가 필요합니다. sid와 spw에는 마이페이지의 "接続情報" 연결 정보에 기재된 [サービス ID] 서비스 ID와 [サービスパスワード] 서비스 비밀번호를 설정하십시오.

또한 API key 발급 API에서는 유효 기간과 IP 주소 제한을 부여할 수 있습니다. 유효 시간(요청 매개변수 이름은 epi)은 임의로 설정할 수 있습니다. epi에 숫자로 설정하는 경우, 단위는 밀리초입니다. 기타 설정 방법은 참조를 확인하십시오. epi를 생략한 경우, 기본값으로 30000(30초)이 설정됩니다. API key를 발급한 후, 실제로 AmiVoice API 요청을 전송할 때까지의 시간을 고려하여 설정하십시오. IP 주소 제한을 부여하는 경우 ipa에 API key를 사용할 수 있는 접속 원본 IP 주소를 지정할 수 있습니다.

API key 발급 기능은 부여할 수 없습니다.

노트

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

주의

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

요청 예시​

다음은 curl 명령어를 사용하여 API key를 발급하는 예시입니다.

예시 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 대신 API key를 사용하는 경우는 다음과 같습니다.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d epi=30000 \
     -d ipa=203.0.113.253 \
     -H "Authorization: Bearer {API_KEY_발급_기능_있는_API_KEY}"

예시 2

유효 기간으로, 시간 단위를 사용한 문자열(아래는 2시간)로 지정할 수도 있습니다. IP 주소를 범위로 지정하여 허용하려면 CIDR로 지정할 수 있습니다.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={서비스ID} \
     -d spw={서비스비밀번호} \
     -d epi=2h \
     -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=2026/07/31 \
     -d ipa=203.0.113.0/24,198.51.100.0/24

응답​

요청이 성공하면, 응답은 일반 텍스트로 발급된 API key를 반환합니다. 이를 그대로 요청 매개변수의 authorization 키로 설정할 수 있습니다.

오류 발생 시 대처 방법​

발급한 API Key로 연결 인증이 실패하는 경우​

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

authorization 키에 의한 인증 요청을 받는 시점이 API key에 설정된 유효 기간 일시를 지난 경우, 음성 인식 서비스는 다음과 같은 오류를 반환하므로 다시 API key를 가져와서 재시도하십시오.

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은 API key의 유효 기간 일시, -21s는 유효 기간으로부터의 지연 시간입니다.

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

p can't feed audio data to recognizer server

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

잘못된 ID, 잘못된 비밀번호로 인한 인증 오류​

API key 발급 API에 지정하는 서비스 ID, 서비스 비밀번호가 잘못된 경우에도 API key는 발급됩니다. AmiVoice API 요청 시 잘못된 서비스 ID, 비밀번호로 생성된 유효하지 않은 API key를 지정하면 다음과 같은 인증 오류를 반환합니다.

HTTP 인터페이스의 오류 응답

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

WebSocket 인터페이스의 오류 응답

s can't validate service authorization

이 경우에는 API key 발급 요청 시 지정하는 서비스 ID(sid), 서비스 비밀번호(spw)가 올바른 값인지 확인하십시오.