자동 번역 API는 번역 타입과 번역기를 간단하게 설정할 수 있는 API입니다. 실시간 동기식 번역과 비동기식 번역을 모두 지원하여 유연한 번역 환경을 제공합니다.
자동 번역 API 종류는 크게 실시간 번역이 가능한 동기 번역 API와 실시간 번역이 불가능한 비동기 번역 요청 API 및 비동기 번역 결과 확인 API가 있습니다.
참고 사항
지원 텍스트 형식
동기 번역 API와 비동기 번역 API에서 지원하는 각 텍스트 형식은 아래와 같습니다.
- 동기 번역 API: 일반 텍스트 및 HTML 형식 지원
- 비동기 번역 API: Markdown 형식 지원
프로젝트 매칭 방법
자동 번역 API에서는 앱센터에 등록된 각 게임 프로젝트 별로 번역 서비스를 매칭할 수 있는 두 가지 방법을 제공합니다.
- 자동 번역 서비스와 1대1 매칭: 각 프로젝트 별로 사용하는 서비스를 등록
- 하나의 자동 번역 서비스 호출 시, 프로젝트 ID를 입력하여 매칭: 각 프로젝트 ID를 인자 값으로 추가하여 API 호출
번역 지원 언어
Hive에서 지원하는 번역 언어는 총 16가지로 아래와 같습니다.
언어 | 언어별 표기법 | Hive 언어코드 |
---|---|---|
한국어 | 한국어 | ko |
영어 | English | en |
일본어 | 日本語 | ja |
중국어 간체 | 简体中文 | zh-hans |
중국어 번체 | 繁體中文 | zh-hant |
프랑스어 | Français | fr |
독일어 | Deutsch | de |
러시아어 | русский | ru |
스페인어 | Español | es |
포르투갈어 | Português | pt |
인도네시아어 | Bahasa Indonesia | id |
베트남어 | tiếng Việt | vi |
태국어 | ไทย | th |
이탈리아어 | Italiano | it |
터키어 | Türkçe | tr |
아랍어 | العربية | ar |
사전 준비 사항
자동 번역 API 사용을 위한 사전 준비 사항은 아래와 같습니다.
1. 서비스키(appKey), 비밀키 확인
- Hive 콘솔 > AI 서비스 > 자동 번역 > 자동 번역 시스템 > 서비스 관리에서 서비스를 등록합니다.
- 제품에 대한 서비스키(구 앱키)와 비밀키를 확인합니다.
2. Signature(서명) 확인
API 서버의 백오피스에서는 서비스키와 비밀키를 사용하여 Signature(서명)을 생성합니다.
Hive 콘솔 > AI 서비스 > 자동 번역 > 자동 번역 시스템 > 서비스 관리에서 키 관리 선택하여 생성된 서명을 확인합니다. 생성된 서명 코드 예시는 아래와 같습니다.
※ 서명은 앱키와 암호키를 사용하여 HmacSHA256 인코딩한 Base64 값입니다.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
import hmac import hashlib import base64 app_key = "your_app_key" secret_key = "your_secret_key" # HMAC SHA-256 사용 signature_bytes = hmac.new(secret_key.encode('utf-8'), app_key.encode('utf-8'), hashlib.sha256).digest() signature = base64.b64encode(signature_bytes).decode('utf-8') # HTTP 요청에 서명 추가 # ... |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException { String appKey = "your_app_key"; String secretKey = "your_secret_key"; // HMAC SHA-256 사용 Mac sha256_HMAC = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); sha256_HMAC.init(secretKeySpec); // 서명 생성 byte[] signatureBytes = sha256_HMAC.doFinal(appKey.getBytes(StandardCharsets.UTF_8)); String signature = Base64.getEncoder().encodeToString(signatureBytes); // HTTP 요청에 서명 추가 // ... } |
동기 번역 API
실시간 동기 방식으로 번역 요청과 번역 결과를 한 개의 API 요청 및 응답으로 처리합니다.
API 응답에서 바로 번역 결과가 제공되기 때문에 번역 결과를 확인하는 API가 존재하지 않습니다.
동기 번역 텍스트 타입으로, 전/후처리가 필요하지 않은 일반 텍스트와 HTML 텍스트 형식을 지원합니다.
Request URL
LIVE URL | https://ats.withhive.com/api/translate/sync https://ats.withhive.com/api/translate/sync/{project_id} |
HTTP Method | POST |
Content-Type | application/json |
Data Format | JSON |
Request Path
필드명 | 설명 | 타입 | 필수 여부 | 상세 | 예시 |
---|---|---|---|---|---|
project_id | 앱센터 프로젝트 ID | String | N | 1. 값이 있는 경우 : 프로젝트 ID로 집계2. 값이 없는 경우 : “없음” 으로 집계 | com.com2us.project1 |
Request Header
필드명 | 설명 | 타입 | 필수 여부 | 상세 | 예시 |
---|---|---|---|---|---|
Signature | 인증을 위한 서명 값 | String | Y | 앱 키 값을 비밀 키를 사용하여 HmacSHA256 인코딩 한 값 | IWusOMIBN8D/0HqgZ7/58e4rgS05E+nka3Ya9vc+yiY= |
Request Body
필드명 | 설명 | 타입 | 필수 여부 | 상세 | 예시 |
---|---|---|---|---|---|
info | 앱 키 정보 객체 | Object | Y | ||
info > app_key | 앱 키 값 | String | Y | 802890479467404e | |
info > meta_data | 자동번역 서비스에서 집계하지는 않으나, 로그로 저장하는 값 | Object | N | JSON Object String 변환 시, 1kb 이내 | {“game” : “MLB”} or [{“key1”:“blabla”}] |
text | 번역 요청 내용 | String | Y | ※ 문자열 Json 이스케이프 필요 | “ \”등록\” 절차에 대한 문의” |
from | 번역 요청 언어 | String | Y | “text”에 해당하는 언어 코드번역 지원 언어 및 Hive 언어코드 참고
※ “auto” 입력 시, 자동 감지 (소문자) |
1. (자동 감지) “auto”2. (한국어) “ko” |
to | 번역 응답 언어 | String | Y | “,” 구분자로 분리 하여 여러 언어 요청 가능번역 지원 언어 및 Hive 언어코드 참고 | 1. (단일 언어 번역)“en”2. (다중 언어 번역)“en, fr, de” |
Response
필드명 | 설명 | 타입 | 상세 | 예시 |
---|---|---|---|---|
result | 결과값 | Object | ||
result > code | 결과 코드 | Integer | Response Code 참고 | 성공 시 ‘200’ |
result > msg | 결과 메시지 | String | Response Code 참고 | 성공 시 ‘Success’ |
content | 번역 결과 | Object | ||
content > data > translateMsg | 번역값 배열 | Array | ||
content > data > translateMsg > detectedLanguage | 입력 언어 관련 값 | Object | ※ “번역 요청 언어 (from)“이 “auto” 인 경우 존재 | |
content > data > translateMsg > detectedLanguage > language | 입력 언어 감지 값 | String | 번역 지원 언어 및 Hive 언어코드 참고 | |
content > data > translateMsg > detectedLanguage > score | 입력 언어 감지 스코어 (1에 가까울수록 정확) | Number (Float) | 1.0 | |
content > data > translateMsg > translations | 번역 텍스트 배열 | Array | 언어별 배열로 노출 | |
content > data > translateMsg > translations > text | 번역 텍스트 | String | Json 이스케이프 문자열 | Inquiries about the \”Registration\” process |
content > data > translateMsg > translations > to | 번역 언어 국가 코드 | String | “en” |
Response Code
코드 | 텍스트 | 비고 |
---|---|---|
200 | “success” | 성공 |
400 | <> is Missing or Incorrect request |
실패 – 요청 파라미터 누락 or
실패 – 파싱 불가능 (JSON 오류) |
401 | Wrong Signature | 실패 – 서명 키 이상 |
404 | Unregistered app key | 실패 – 등록되지 않은 앱 키 |
404 | Unregistered job uuid | 실패 – 등록되지 않은 job uuid |
500 | Internal Server Error (or Some message) | 실패 – 서버 내부 오류 |
Request Example
1 2 3 4 5 6 7 8 9 10 11 12 |
curl --request POST \ --url https://ats.withhive.com/api/translate/sync \ --header 'Content-Type: application/json' \ --header 'Signature: IWusOMIBN8D/0HqgZ7/58e4rgS05E+nka3Ya9vc+yiY=' \ --data '{ "info":{ "app_key":"802890479467404e" }, "text":"서버 계정 신청서 계정 생성 다국어 콘텐츠 관리 절차에 대한 문의", "to":"en,fr,de", "from" : "ko" }' |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
import requests url = "https://ats.withhive.com/api/translate/sync" payload = { "info": {"app_key": "802890479467404e"}, "text": "서버 계정 신청서 계정 생성 다국어 콘텐츠 관리 절차에 대한 문의", "to": "en,fr,de", "from": "ko" } headers = { "Content-Type": "application/json", "Signature": "IWusOMIBN8D/0HqgZ7/58e4rgS05E+nka3Ya9vc+yiY=" } response = requests.request("POST", url, json=payload, headers=headers) print(response.text) |
1 2 3 4 5 6 7 8 9 10 11 12 |
OkHttpClient client = new OkHttpClient(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, "{\n \"info\":{\n \"app_key\":\"802890479467404e\"\n },\n \"text\":\"서버 계정 신청서 계정 생성 다국어 콘텐츠 관리 절차에 대한 문의\",\n \"to\":\"en,fr,de\",\n \"from\" : \"ko\"\n}"); Request request = new Request.Builder() .url("https://ats.withhive.com/api/translate/sync") .post(body) .addHeader("Content-Type", "application/json") .addHeader("Signature", "IWusOMIBN8D/0HqgZ7/58e4rgS05E+nka3Ya9vc+yiY=") .build(); Response response = client.newCall(request).execute(); |
Response Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
{ "result" : { "code" : 200, "msg" : "Success" }, "content" : { "data" : { "translateMsg":[{ "detectedLanguage":{ "language":"ko", "score":-1.0 }, "translations":[{ "text":"Server Account Application Create an account Inquiries about the multilingual content management process", "to":"en" }, { "text":"Demande de compte serveur Créer un compte Demandes de renseignements sur le processus de gestion de contenu multilingue", "to":"fr" }, { "text":"Server-Konto-Anwendung Konto erstellen Anfragen zum mehrsprachigen Content-Management-Prozess", "to":"de" }] }] } } } |
비동기 번역 요청 API
비동기 방식의 번역 API는 번역 요청과 번역 응답을 구분하여 두 개의 API로 처리합니다.
크게 요청에 해당하는 ‘비동기 번역 요청 API’와 응답에 해당하는 ‘비동기 번역 결과 확인 API’가 있습니다.
바동기 번역 텍스트 타입으로, 전/후처리가 필요한 마크다운 텍스트 형식을 지원합니다.
Request URL
LIVE URL | https://ats.withhive.com/api/translate/async https://ats.withhive.com/api/translate/async/{project_id} |
HTTP Method | POST |
Content-Type | application/json |
Data Format | JSON |
Request Path
필드명 | 설명 | 타입 | 필수 여부 | 상세 | 예시 |
---|---|---|---|---|---|
project_id | 앱센터 프로젝트 ID | String | Y | 1. 값이 있는 경우 : 프로젝트 ID로 집계2. 값이 없는 경우 : “없음” 으로 집계 | com.com2us.project1 |
Request Header
필드명 | 설명 | 타입 | 필수 여부 | 상세 | 예시 |
---|---|---|---|---|---|
Signature | 인증을 위한 서명 값 | String | Y | 앱 키 값을 비밀 키를 사용하여 HmacSHA256 인코딩 한 값 | pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c= |
Request Body
필드명 | 설명 | 타입 | 필수 여부 | 상세 | 예시 |
---|---|---|---|---|---|
info | 앱 키 정보 객체 | Object | Y | ||
info > app_key | 앱 키 값 | String | Y | 802890479467404e | |
info > meta_data | 자동번역 서비스에서 집계하지는 않으나, 로그로 저장하는 값 | Object | N | JSON Object String 변환 시, 1kb 이내 | {“game” : “MLB”} or [{“key1”:“blabla”}] |
text | 번역 요청 내용 | String | Y | ※ 문자열 Json 이스케이프 필요 | “ \”등록\” 절차에 대한 문의” |
from | 번역 요청 언어 | String | Y | “text”에 해당하는 언어 코드번역 지원 언어 및 Hive 언어코드 참고
※ async 번역은 번역 요청 내용에 대한 언어 자동감지를 지원하지 않습니다. |
|
to | 번역 응답 언어 | String | Y | “,” 구분자로 분리 하여 여러 언어 요청 가능번역 지원 언어 및 Hive 언어코드 참고 | 1. (단일 언어 번역)“en”2. (다중 언어 번역)“en, fr, de” |
Response
/api/translate/async/result/{uuid} 임
필드명 | 설명 | 타입 | 상세 | 예시 |
---|---|---|---|---|
result | 결과값 | Object | ||
result > code | 결과 코드 | Integer | Response Code 참고 | 성공 시 ‘200’ |
result > msg | 결과 메시지 | String | Response Code 참고 | 성공 시 ‘Success’ |
content | 번역 결과값 | Object | ||
content > uuid | 번역 결과 ID | String | UUID4 형식 ID 번역 상태 확인을 위한 ID |
62fe5786-0bb8-4cd0-b51a-6d6f6bfe2bac |
content > resultUrl | 번역 상태 확인을 위한 URL | String |
Response Code
코드 | 텍스트 | 비고 |
---|---|---|
200 | “success” | 성공 |
400 | <> is Missing or Incorrect request |
실패 – 요청 파라미터 누락 or
실패 – 파싱 불가능 (JSON 오류) |
401 | Wrong Signature | 실패 – 서명 키 이상 |
404 | Unregistered app key | 실패 – 등록되지 않은 앱 키 |
404 | Unregistered job uuid | 실패 – 등록되지 않은 job uuid |
500 | Internal Server Error (or Some message) | 실패 – 서버 내부 오류 |
Request Example
1 2 3 4 5 6 7 8 9 10 11 12 13 |
curl --request POST \ --url https://ats.withhive.com/api/translate/async \ --header 'Content-Type: application/json' \ --header 'Signature: pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=' \ --data '{ "info":{ "app_key":"815e3d8d6e7443ba" }, "text":"# Markdown Cheat Sheet ......", "to":"ko,ja,zh-hant", "from":"en" } ' |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
import requests url = "https://ats.withhive.com/api/translate/async" payload = { "info": {"app_key": "815e3d8d6e7443ba"}, "text": "# Markdown Cheat Sheet ......", "to": "ko,ja,zh-hant", "from": "en" } headers = { "Content-Type": "application/json", "Signature": "pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=" } response = requests.request("POST", url, json=payload, headers=headers) print(response.text) |
1 2 3 4 5 6 7 8 9 10 11 12 13 |
OkHttpClient client = new OkHttpClient(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, "{\n \"info\":{\n \"app_key\":\"815e3d8d6e7443ba\"\n },\n\t\"text\":\"# Markdown Cheat Sheet ......\",\n \"to\":\"ko,ja,zh-hant\",\n\t\t\"from\":\"en\"\n}\n"); Request request = new Request.Builder() .url("https://ats.withhive.com/api/translate/async") .post(body) .addHeader("Content-Type", "application/json") .addHeader("Signature", "pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=") .build(); Response response = client.newCall(request).execute(); |
Response Example
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "result": { "code": 200, "msg": "Success" }, "content": { "uuid": "d2a36ba1-1bb3-43aa-ac57-46576d27eb37", "resultUrl": "https://test-ats.withhive.com/api/translate/async/result/d2a36ba1-1bb3-43aa-ac57-46576d27eb37" } } |
비동기 번역 결과 확인 API
비동기 번역 결과 확인 API는 비동기 번역 요청에 대한 번역 결과를 리턴합니다. 즉 요청과 응답을 구분하여 처리하는 비동기 API 중, 응답에 해당하는 API입니다.
Request URL
LIVE URL | https://ats.withhive.com/api/translate/async/result/{uuid} |
HTTP Method | GET |
Request Path
필드명 | 설명 | 타입 | 필수 여부 | 상세 | 예시 |
---|---|---|---|---|---|
uuid | 번역 결과 ID, 비동기 번역 요청에 대한 상태 응답 값 | String | Y | 생성으로부터 ~Nday까지 확인 가능 | 5c8ded49-9ee2-412a-a0ab-a4018a0dc093 |
Request Header
필드명 | 설명 | 타입 | 필수 여부 | 상세 | 예시 |
---|---|---|---|---|---|
Signature | 인증을 위한 서명 값 | String | Y | 앱 키 값을 비밀 키를 사용하여 HmacSHA256 인코딩 한 값 | pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c= |
Response
필드명 | 설명 | 타입 | 상세 | 예시 |
---|---|---|---|---|
result | 결과값 배열 | Object | ||
result > code | 결과 코드 | Integer | Response Code 참고 | 성공 시 ‘200’ |
result > msg | 결과 메시지 | String | Response Code 참고 | 성공 시 ‘Success’ |
content | 번역 결과 | Object | ||
content | 번역 결과 | Object | ||
content > status | 번역 상태값 | Object | 번역 상태 정보 | |
content > status > code | 번역 상태 코드 | Integer | 100 / 101 / 102 / 199 | |
content > status > mag | 번역 상태 메시지 | String | “completed(100)”/ “waiting(101)” / “processing(102)” / “failed(199)” | |
content > data | 번역 결과값 | Object | ※ result>status>msg 값이 “waiting” / “processing” / “failed” 인 경우 필드 없음, “completed”인 경우만 존재 |
|
content > data > translateMsg | 번역값 배열 | Array | ||
content > data > translateMsg > translations | 번역 텍스트 배열 | Array | 언어별 배열로 노출 | |
content > data > translateMsg > translations > text | 번역 텍스트 | String | Json 이스케이프 문자열 | Inquiries about the \”Registration\” process |
content > data > translateMsg > translations > to | 번역 언어 국가 코드 | String | “en” |
Response Code
코드 | 텍스트 | 비고 |
---|---|---|
200 | “success” | 성공 |
400 | <> is Missing or Incorrect request |
실패 – 요청 파라미터 누락 or
실패 – 파싱 불가능 (JSON 오류) |
401 | Wrong Signature | 실패 – 서명 키 이상 |
404 | Unregistered app key | 실패 – 등록되지 않은 앱 키 |
404 | Unregistered job uuid | 실패 – 등록되지 않은 job uuid |
500 | Internal Server Error (or Some message) | 실패 – 서버 내부 오류 |
Request Example
1 2 3 4 |
curl --request GET \ --url https://test-ats.withhive.com/api/translate/async/result/3f8891e9-513a-4e91-b0b6-ac9aabbbf6d2 \ --header 'Content-Type: application/json' \ --header 'Signature: pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=' |
1 2 3 4 5 6 7 8 9 10 11 12 |
import requests url = "https://ats.withhive.com/api/translate/async/result/3f8891e9-513a-4e91-b0b6-ac9aabbbf6d2" headers = { "Content-Type": "application/json", "Signature": "pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=" } response = requests.request("GET", url, headers=headers) print(response.text) |
1 2 3 4 5 6 7 8 9 10 |
OkHttpClient client = new OkHttpClient(); Request request = new Request.Builder() .url("https://ats.withhive.com/api/translate/async/result/3f8891e9-513a-4e91-b0b6-ac9aabbbf6d2") .get() .addHeader("Content-Type", "application/json") .addHeader("Signature", "pczeZ91N/ijDBZ80ktNdTDPhnmEK98a3AIsTui46o9c=") .build(); Response response = client.newCall(request).execute(); |
Response Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
{ "result": { "code": 200, "msg": "Success" }, "content": { "status": { "code": 100, "msg": "completed" }, "data": { "translateMsg": [ { "translations": [ { "text": "# Markdown 치트 시트\r\n\r\n......", "to": "ko" }, { "text": "# Markdownチートシート\r\n\r\n......", "to": "ja" }, { "text": "# Markdown 備忘單\r\n\r\n......", "to": "zh-hant" } ] } ] } } } |