Modulang

API Documentation

Modulang API를 활용하여 애플리케이션에 고품질 AI 번역을 통합하세요.
Powered by Gemma 3 27B

54개 언어 지원평균 응답 < 2초99.9% Uptime

Quick Start

  1. 계정 생성대시보드에서 API 키 발급
  2. API 키를 안전한 곳에 저장 (키는 생성 시 한 번만 표시됩니다)
  3. 아래 예제를 참고하여 번역 API 호출
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

POST/translate
텍스트를 소스 언어에서 타겟 언어로 번역합니다.

Request Body

ParameterTypeRequiredDescription
textstring필수번역할 텍스트 (최대 5,000자)
target_langstring필수타겟 언어 코드 (예: ko, en, ja)
source_langstring선택소스 언어 코드 (미지정 시 자동 감지)

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"
}
FieldTypeDescription
translated_textstring번역된 텍스트
source_langstring감지/지정된 소스 언어
target_langstring타겟 언어
tokens_usednumber사용된 총 토큰 수
prompt_tokensnumber입력 토큰 수
completion_tokensnumber출력 토큰 수
modelstring사용된 모델명
GET/health
API 서버 상태를 확인합니다. 인증 불필요.
curl https://api.modulang.com/v1/health

# Response
{
  "status": "healthy",
  "timestamp": "2026-02-01T12:00:00Z"
}

Best Practices

Batch Requests

여러 텍스트를 번역할 때는 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}`);
});
Retry with Backoff

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개 언어 간 번역을 지원합니다.

ar

Arabic

العربية

bg

Bulgarian

Български

bn

Bengali

বাংলা

ca

Catalan

Català

cs

Czech

Čeština

da

Danish

Dansk

de

German

Deutsch

el

Greek

Ελληνικά

en

English

English

es

Spanish

Español

et

Estonian

Eesti

fa

Persian

فارسی

fi

Finnish

Suomi

fil

Filipino

Filipino

fr

French

Français

gu

Gujarati

ગુજરાતી

he

Hebrew

עברית

hi

Hindi

हिन्दी

hr

Croatian

Hrvatski

hu

Hungarian

Magyar

id

Indonesian

Indonesia

is

Icelandic

Íslenska

it

Italian

Italiano

ja

Japanese

日本語

kn

Kannada

ಕನ್ನಡ

ko

Korean

한국어

lo

Lao

ລາວ

lt

Lithuanian

Lietuvių

lv

Latvian

Latviešu

ml

Malayalam

മലയാളം

mr

Marathi

मराठी

ms

Malay

Melayu

nl

Dutch

Nederlands

no

Norwegian

Norsk

pa

Punjabi

ਪੰਜਾਬੀ

pl

Polish

Polski

pt

Portuguese

Português

ro

Romanian

Română

ru

Russian

Русский

sk

Slovak

Slovenčina

sl

Slovenian

Slovenščina

sr

Serbian

Српски

sv

Swedish

Svenska

sw

Swahili

Kiswahili

ta

Tamil

தமிழ்

te

Telugu

తెలుగు

th

Thai

ไทย

tr

Turkish

Türkçe

uk

Ukrainian

Українська

ur

Urdu

اردو

vi

Vietnamese

Tiếng Việt

zh-CN

Chinese (Simplified)

简体中文

zh-TW

Chinese (Traditional)

繁體中文

zu

Zulu

isiZulu

Rate Limits & Quotas

API 사용량은 구독 플랜에 따라 제한됩니다. Rate limit 초과 시 429 에러가 반환됩니다.

PlanRequests/minDaily TokensMax Text Length
Free1010,0001,000자
Basic30100,0003,000자
Pro60500,0005,000자
EnterpriseCustomUnlimited10,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 CodeError CodeDescriptionSolution
400INVALID_REQUEST잘못된 요청 파라미터요청 본문 확인
400TEXT_TOO_LONG텍스트 길이 초과텍스트 분할
400UNSUPPORTED_LANGUAGE지원하지 않는 언어 코드지원 언어 목록 확인
401INVALID_API_KEY유효하지 않은 API 키API 키 확인
401EXPIRED_API_KEY만료된 API 키대시보드에서 키 갱신
403QUOTA_EXCEEDED일일 토큰 할당량 초과내일까지 대기 또는 플랜 업그레이드
403IP_NOT_ALLOWEDIP Whitelist에 없는 IP대시보드에서 IP 추가
429RATE_LIMIT_EXCEEDED분당 요청 한도 초과잠시 후 재시도 (지수 백오프 권장)
500INTERNAL_ERROR서버 내부 오류잠시 후 재시도
503SERVICE_UNAVAILABLE서비스 점검 중상태 페이지 확인

API Key Management

대시보드에서 API 키를 관리할 수 있습니다.

키 생성
용도별로 여러 API 키를 생성하세요. 각 키는 독립적으로 사용량이 추적됩니다.
키 순환 (Rotate)
보안을 위해 정기적으로 키를 순환하세요. 기존 키는 즉시 무효화됩니다.
IP Whitelist
특정 IP에서만 API 호출을 허용하도록 제한할 수 있습니다.
만료일 설정
임시 키에 만료일을 설정하여 자동으로 비활성화되도록 합니다.
사용량 모니터링
키별 사용량, 요청 로그, 에러율을 실시간으로 확인하세요.
키 비활성화
문제 발생 시 키를 즉시 비활성화하여 추가 피해를 방지하세요.

Support

API 사용 중 문제가 발생하거나 추가 지원이 필요하시면 언제든 연락주세요.