Translation API Reference

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

API URL

Translation API의 URL은 다음의 형식을 따릅니다.

POST /ai/translation/{signature} HTTP/1.1
Host: {host}
x-api-key: {AI API Key}
content-type: 1) application/json 
              2) multipart/form-data

파라미터	타입	필수여부	설명
service name	String	필수	서비스(API)명 입력 - translation로 고정
signature	String	필수	API Endpoint URL의 경로(Path) - 도메인목록 > AI API 인증정보 > API Endpoint URL에서 조회
host	String	필수	API Endpoint URL의 호스트(Host) - 도메인목록 > AI API 인증정보 > API Endpoint URL에서 조회
AI API Key	String	필수	Kakao i Cloud Console에서 발급받은 AI API 키 정보로 API 호출 시 필요 - API를 호출하는 주체를 구별하기 위한 고유의 식별자로, 암호화가 되어 있음 - 도메인목록 > AI API 인증정보 > AI API Key에서 조회
content-type	String	필수	다음의 방식을 지원 - application/json - multipart/form-data

API 호출 방식

Translation API의 호출 방식은 다음과 같이 두 가지 방식을 지원합니다.

메서드	구분	설명
POST	Header	application/json
	Header	multipart/form-data

코드 예제. application/json 방식

curl --location --request POST '{API Endpoint URL}' \
--header 'x-api-key: {AI API Key}' \
--header 'Content-Type: application/json' \
--data-raw '{
"q": "{번역 대상 문장}",
"source_lang": "{번역 대상 언어}",
"target_lang": "{번역 결과 언어}"
}'

코드 예제. multipart/form-data 방식

curl -v -X POST \
    -H "Content-Type: multipart/form-data" \
    -H "x-api-key: {AI API Key}" \
    --form "q={번역 대상 문장}" --form "source_lang={번역 대상 언어}" --form "target_lang={번역 결과 언어}" \
    "{API Endpoint URL}"

Translation API

Request

Request Syntax

코드 예제 POST 방식 application/json Request Syntax

curl --location --request POST 'https://7c412185-b2ea-4f2c-ac03-fcd32fec05e8.api.kr-central-1.kakaoi.io/service/translate/asdjkfhdksjhfkjsdh' \
--header 'x-api-key: abcdefghijk012345678910abcdefghi' \
--header 'Content-Type: application/json' \
--data-raw '{
"q": "안녕. 내 이름은 홍길동이야.",
"source_lang": "ko",
"target_lang": "en"
}'

코드 예제 POST 방식 multipart/form-data Request Syntax

curl -v -X POST \
    -H "Content-Type: multipart/form-data" \
    -H "x-api-key: abcdefghijk012345678910abcdefghi" \
    --form "q=안녕. 내 이름은 홍길동이야." --form "source_lang=ko" --form "target_lang=en" \
    "https://7c412185-b2ea-4f2c-ac03-fcd32fec05e8.api.kr-central-1.kakaoi.io/service/translate/asdjkfhdksjhfkjsdh"

Request Elements

파라미터	타입	필수여부	설명
q	String	필수	번역 대상 문장 - 최대 문장 크기: 5,000자
source_lang	String	선택	번역 대상 언어 - 지정하지 않으면 입력된 문장에서 자동으로 언어를 감지합니다.
target_lang	String	필수	번역 결과 언어

표 지원 언어 및 코드

언어	코드
한국어	ko
영어	en
일본어	ja
중국어	zh
베트남어	vi
인도네시아어	id
아랍어	ar
뱅골어	bn
독일어	de
스페인어	es
프랑스어	fr
힌디어	hi
이탈리아어	it
말레이시아어	ms
네덜란드어	nl
포르투갈어	pt
러시아어	ru
태국어	th
튀르키예어(터키어)	tr

Response

Response Syntax

{
  "source_lang": "ko",
  "target_lang": "en",
  "input": [
    [
      "안녕. 내 이름은 홍길동이야."
    ]
  ],
  "output": [
    [
      "Hi. My name is Hong Gil-dong."
    ]
  ],
  "model_version": "1",
  "elapsed": 0.1234
}

Response Elements

필드	타입	필수여부	설명	비고
source_lang	String	필수	번역 대상 언어
target_lang	String	필수	번역 결과 언어
input	Array	필수	번역 대상 문장 - 2차원 배열 타입으로 응답합니다. - 줄바꿈 문자를 기준으로 문단으로 나눈 뒤, 문장 단위로 한 번 더 분리한 결과를 제공합니다.
output	Array	필수	번역 결과 문장 - 2차원 배열 타입으로 응답합니다. - 줄바꿈 문자를 기준으로 문단으로 나눈 뒤, 문장 단위로 한 번 더 분리한 결과를 제공합니다.

Status Code

응답 코드	응답 내용	설명
200	-	API 호출 성공
400	Bad Request	요청 주소가 잘못된 경우
	INVALID_SIGNATURE	요청 Endpoint 주소의 signature가 잘못된 경우
401	Authentication failed	x-api-key 헤더가 없거나 값이 잘못된 경우
404	NOT FOUND	지원하지 않는 Method로 요청을 보낸 경우
405	Method Not Allowed	지원하지 않는 Method로 요청을 보낸 경우
413	Request Entity Too Large	요청의 크기가 제한보다 큰 경우
	EXCEED_MAX_LEN	번역할 문자열의 길이 초과 - 최대 문자열 크기: 5,000자
415	Unsupported content type	Content Type 헤더가 없거나 규격에 맞지 않는 경우
422	PARSE_EXCEPTION	- 요청에 필수 파라미터가 누락된 경우 - JSON 포맷에 어긋나는 경우
	UNSUPPORTED_LANG	- 지원하지 않는 언어 기입 - 소스 언어와 타겟 언어가 동일한 경우
425	Domain not found	요청한 도메인이 삭제되어 없을 경우
	Domain not deployed	요청한 도메인이 아직 배포되지 않은 경우
429	Too many Requests	설정한 한도를 초과해서 요청한 경우
503	INTERNAL ERROR	예상하지 못한 서버 오류가 발생한 경우

코드 예제 에러 코드 응답

{
    "ecode": "PARSE_EXCEPTION",
    "message": "lack of essential parameters: q, source_lang, target_lang",
    "status_code": 400
}

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