API Documentation
Modulang API를 활용하여 애플리케이션에 고품질 AI 번역을 통합하세요.
Powered by Gemma 3 27B
Quick Start
curl -X POST https://api.modulang.com/v1/translate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello, world!",
"source_lang": "en",
"target_lang": "ko"
}'Authentication
모든 API 요청은 Bearer 토큰 인증이 필요합니다. 대시보드에서 API 키를 생성하세요.
Authorization: Bearer mlk_xxxxxxxxxxxxxxxxxxxx보안 주의사항
- API 키는 절대 클라이언트 사이드 코드에 노출하지 마세요
- 키가 노출된 경우 즉시 대시보드에서 Rotate 하세요
- IP Whitelist 설정으로 보안을 강화할 수 있습니다
Base URL
https://api.modulang.com/v1모든 API 엔드포인트는 이 Base URL을 기준으로 합니다.
API Endpoints
/translateRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | 필수 | 번역할 텍스트 (최대 5,000자) |
target_lang | string | 필수 | 타겟 언어 코드 (예: ko, en, ja) |
source_lang | string | 선택 | 소스 언어 코드 (미지정 시 자동 감지) |
Code Examples
curl -X POST https://api.modulang.com/v1/translate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello, world!",
"source_lang": "en",
"target_lang": "ko"
}'Response 200 OK
{
"translated_text": "안녕, 세상아!",
"source_lang": "en",
"target_lang": "ko",
"tokens_used": 15,
"prompt_tokens": 8,
"completion_tokens": 7,
"model": "gemma-3-27b-it"
}| Field | Type | Description |
|---|---|---|
translated_text | string | 번역된 텍스트 |
source_lang | string | 감지/지정된 소스 언어 |
target_lang | string | 타겟 언어 |
tokens_used | number | 사용된 총 토큰 수 |
prompt_tokens | number | 입력 토큰 수 |
completion_tokens | number | 출력 토큰 수 |
model | string | 사용된 모델명 |
/healthcurl https://api.modulang.com/v1/health
# Response
{
"status": "healthy",
"timestamp": "2026-02-01T12:00:00Z"
}Best Practices
여러 텍스트를 번역할 때는 Promise.all을 사용하여 병렬로 요청하세요.
// Batch translation with Promise.all
const texts = [
{ text: 'Hello', target: 'ko' },
{ text: 'Goodbye', target: 'ja' },
{ text: 'Thank you', target: 'zh-CN' },
];
const results = await Promise.all(
texts.map(({ text, target }) =>
translate(text, 'en', target)
)
);
results.forEach((result, i) => {
console.log(`${texts[i].text} -> ${result.translated_text}`);
});Rate limit (429) 에러 발생 시 지수 백오프로 재시도하세요.
async function translateWithRetry(text, sourceLang, targetLang, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
return await translate(text, sourceLang, targetLang);
} catch (error) {
if (error.status === 429) {
// Rate limited - wait and retry
const waitTime = Math.pow(2, attempt) * 1000;
await new Promise(resolve => setTimeout(resolve, waitTime));
continue;
}
throw error;
}
}
throw new Error('Max retries exceeded');
}Performance Tips
- 소스 언어 지정: 자동 감지보다 직접 지정이 더 빠르고 정확합니다
- Connection Keep-Alive: HTTP/2 또는 Keep-Alive로 연결 재사용
- 텍스트 길이: 긴 텍스트는 문단 단위로 분할하여 요청
- 캐싱: 동일한 번역 결과는 클라이언트 측에서 캐싱 권장
Supported Languages
Modulang은 Gemma 3 기반으로 54개 언어 간 번역을 지원합니다.
arArabic
العربية
bgBulgarian
Български
bnBengali
বাংলা
caCatalan
Català
csCzech
Čeština
daDanish
Dansk
deGerman
Deutsch
elGreek
Ελληνικά
enEnglish
English
esSpanish
Español
etEstonian
Eesti
faPersian
فارسی
fiFinnish
Suomi
filFilipino
Filipino
frFrench
Français
guGujarati
ગુજરાતી
heHebrew
עברית
hiHindi
हिन्दी
hrCroatian
Hrvatski
huHungarian
Magyar
idIndonesian
Indonesia
isIcelandic
Íslenska
itItalian
Italiano
jaJapanese
日本語
knKannada
ಕನ್ನಡ
koKorean
한국어
loLao
ລາວ
ltLithuanian
Lietuvių
lvLatvian
Latviešu
mlMalayalam
മലയാളം
mrMarathi
मराठी
msMalay
Melayu
nlDutch
Nederlands
noNorwegian
Norsk
paPunjabi
ਪੰਜਾਬੀ
plPolish
Polski
ptPortuguese
Português
roRomanian
Română
ruRussian
Русский
skSlovak
Slovenčina
slSlovenian
Slovenščina
srSerbian
Српски
svSwedish
Svenska
swSwahili
Kiswahili
taTamil
தமிழ்
teTelugu
తెలుగు
thThai
ไทย
trTurkish
Türkçe
ukUkrainian
Українська
urUrdu
اردو
viVietnamese
Tiếng Việt
zh-CNChinese (Simplified)
简体中文
zh-TWChinese (Traditional)
繁體中文
zuZulu
isiZulu
Rate Limits & Quotas
API 사용량은 구독 플랜에 따라 제한됩니다. Rate limit 초과 시 429 에러가 반환됩니다.
| Plan | Requests/min | Daily Tokens | Max Text Length |
|---|---|---|---|
| Free | 10 | 10,000 | 1,000자 |
| Basic | 30 | 100,000 | 3,000자 |
| Pro | 60 | 500,000 | 5,000자 |
| Enterprise | Custom | Unlimited | 10,000자 |
Rate Limit Headers
모든 응답에 포함되는 Rate Limit 관련 헤더:
X-RateLimit-Limit: 60 # 분당 최대 요청 수
X-RateLimit-Remaining: 58 # 남은 요청 수
X-RateLimit-Reset: 1706792400 # 리셋 시간 (Unix timestamp)
X-Tokens-Used: 1523 # 오늘 사용한 토큰
X-Tokens-Remaining: 498477 # 남은 일일 토큰Error Codes
Error Response Format
{
"detail": "Invalid API key",
"error_code": "INVALID_API_KEY"
}| HTTP Code | Error Code | Description | Solution |
|---|---|---|---|
400 | INVALID_REQUEST | 잘못된 요청 파라미터 | 요청 본문 확인 |
400 | TEXT_TOO_LONG | 텍스트 길이 초과 | 텍스트 분할 |
400 | UNSUPPORTED_LANGUAGE | 지원하지 않는 언어 코드 | 지원 언어 목록 확인 |
401 | INVALID_API_KEY | 유효하지 않은 API 키 | API 키 확인 |
401 | EXPIRED_API_KEY | 만료된 API 키 | 대시보드에서 키 갱신 |
403 | QUOTA_EXCEEDED | 일일 토큰 할당량 초과 | 내일까지 대기 또는 플랜 업그레이드 |
403 | IP_NOT_ALLOWED | IP Whitelist에 없는 IP | 대시보드에서 IP 추가 |
429 | RATE_LIMIT_EXCEEDED | 분당 요청 한도 초과 | 잠시 후 재시도 (지수 백오프 권장) |
500 | INTERNAL_ERROR | 서버 내부 오류 | 잠시 후 재시도 |
503 | SERVICE_UNAVAILABLE | 서비스 점검 중 | 상태 페이지 확인 |
API Key Management
대시보드에서 API 키를 관리할 수 있습니다.
Support
API 사용 중 문제가 발생하거나 추가 지원이 필요하시면 언제든 연락주세요.