감정 분석 API Reference

카카오 i 클라우드의 감정 분석 API를 호출할 때 필요한 개발 정보는 다음과 같습니다.

Request

Request Syntax

코드 예제 Request Syntax

curl -X POST "{API Endpoint URL}" \
  -H "x-api-key: {API Key}" \
  -H 'Content-Type: application/json' \
  --data '{"msg": "발화1|발화2|발화3"}'

API의 호출 방식은 application/json으로 Request Body만 허용하며, 파라미터 전달은 아래의 방식을 따릅니다.

표 API 호출 방식

메서드	요청 URL
POST	요청 Body에 application/json으로 표현된 데이터

Request Header

표 Request Header

파라미터	타입	필수여부	설명
x-api-key	String	필수	{API Key}: API 호출 시 필요한 인증키 - 카카오 i 클라우드 콘솔 > Conversation > 도메인 탭의 [인증 정보] 버튼 클릭해 조회
Content-Type	String	필수	다음의 방식을 지원 - application/json

Request Elements

표 Request Elements

파라미터	타입	필수여부	설명
msg	String, Float	필수	감정을 분석할 대화 세션 - |으로 발화 구분 - 분석할 발화의 선행 발화만을 고려하여 발화 감정 예측 (뒤의 발화는 고려 X) - 조건 1: 각 발화는 앞의 발화 4개까지만 고려하여 모델 작동 (ex. 6번째 발화는 2, 3, 4, 5번째 발화를 고려함) - 조건 2: 각 발화는 입력 캐릭터 수 제한은 없으나, 앞에서부터 100개의 캐릭터만 사용됨 - 조건 3: 뒷 부분의 입력의 길이에 따라 현재 감정 예측 확률이 미미하게 변동할 수 있음 - 발화를 입력하지 않은 경우(ex. “ “, | 등) 오류 처리 - 입력 타입은 float, string이 될 수 있으며, 이를 string으로 변환시켜 모델 작동

Response

Response Syntax

코드 예제 Response Syntax

{
  "turn_id":
    {
      "utterance","발화1",
      "candidates": [{"value": "감정 카테고리", "prob": "해당 감정 확률"},... ],
      "emotion": {"value": "가장 높은 확률의 감정 카테고리", "prob": "해당 감정 확률"} # Top 1의 감정을 알고 싶은 경우
    },
  ...
}

Response Elements

표 Response Elements

필드	타입	필수 여부	설명
turn_id ▼	Object	필수	발화 순서 - 0부터 시작
utterance	String	필수	사용자 입력 발화
candidates ▼	List[dict]	필수	전체 감정 카테고리 및 감정 확률 리스트
value	String	필수	감정 카테고리 - 감정없음, 놀람, 두려움, 불확실, 슬픔, 싫음, 좋음, 지루함, 창피함
prob	Float	필수	감정 확률 (백분율)
emotion ▼	Object	필수	일순위 감정 카테고리 및 감정 확률
value	String	필수	확률이 가장 높은 감정 카테고리
prob	Float	필수	해당 카테고리의 감정 확률(백분율)
release	String	필수	API의 버전

Status Code

표 Status Code

응답 코드	응답 내용	설명
200	-	API 호출 성공
400	Bad Request	요청 주소가 잘못된 경우
	INVALID_SIGNATURE	요청 Endpoint 주소의 signature가 잘못된 경우
	UNSUPPORTED_PARAMETER	msg가 입력되었지만, 인식할 문장이 없는 경우 - ex. {“msg” : “ ”}
	Value_Error_Missing	msg 파라미터가 입력되지 않은 경우
	MODEL_INFERENCE	모델의 입력부분에서 예기치 못한 에러가 발생한 경우 (정상입력에 대해서는 발생하지 않음)
401	Authentication failed	x-api-key 헤더가 없거나 값이 잘못된 경우
404	NOT FOUND	지원하지 않는 Method로 요청을 보낸 경우
405	Method Not Allowed	지원하지 않는 Method로 요청을 보낸 경우
413	Request Entity Too Large	요청의 크기가 제한보다 큰 경우
415	Unsupported content type	Content Type 헤더가 없거나 규격에 맞지 않는 경우
422	INVALID_PARAMETER_VALUE	msg에 다른 타입이 입력될 경우 (ex. object type)
425	Domain not found	요청한 도메인이 삭제되어 없을 경우
	Domain not deployed	요청한 도메인이 아직 배포되지 않은 경우
429	Too many Requests	설정한 한도를 초과해서 요청한 경우
503	INTERNAL ERROR	예상하지 못한 서버 오류가 발생한 경우

안내
제시된 감정 분석 API 성능보다 더 높은 성능이 필요한 경우에는 헬프데스크 > 기술문의 또는 상담 및 도입 문의으로 문의하시기 바랍니다.