Chapter 05: API 인터페이스

5.1 RESTful API 설계

API는 언어 AI 시스템에 접근하는 관문입니다. WIA-LANG-005 Phase 2는 일관되고 직관적이며 확장 가능한 API를 정의합니다.

// API 기본 구조
const BASE_URL = 'https://api.wia-lang-005.org/v1';

interface APIRequest {
  language: string;      // ISO 639-3 코드
  input: any;
  options?: RequestOptions;
}

interface APIResponse<T> {
  status: 'success' | 'error';
  data: T;
  metadata: {
    requestId: string;
    timestamp: string;
    latencyMs: number;
    modelVersion: string;
  };
  usage: {
    characters: number;
    tokens: number;
    creditsUsed: number;
  };
}

5.2 핵심 API 엔드포인트

엔드포인트	메서드	기능	용도
/v1/translate	POST	번역	텍스트 번역
/v1/asr	POST	음성 인식	음성→텍스트
/v1/tts	POST	음성 합성	텍스트→음성
/v1/complete	POST	텍스트 생성	자동 완성
/v1/analyze	POST	언어 분석	형태소/품사
/v1/languages	GET	언어 목록	지원 언어 조회

번역 API

// 번역 API 클라이언트
class TranslationClient {
  private apiKey: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async translate(request: TranslateRequest): Promise<TranslateResponse> {
    const response = await fetch(`${BASE_URL}/translate`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`,
        'X-WIA-Version': '1.0.0'
      },
      body: JSON.stringify({
        source_language: request.sourceLanguage,
        target_language: request.targetLanguage,
        text: request.text,
        options: {
          formality: request.formality || 'polite',
          domain: request.domain || 'general',
          alternatives: request.alternatives || 3
        }
      })
    });

    return response.json();
  }
}

// 사용 예시
const client = new TranslationClient('your-api-key');
const result = await client.translate({
  sourceLanguage: 'ain',
  targetLanguage: 'ja',
  text: 'イランカラプテ',
  formality: 'polite'
});

console.log(result.data.translation);  // 'こんにちは'
console.log(result.data.confidence);   // 0.92

음성 인식 API (ASR)

// ASR API
interface ASRRequest {
  audio: string;       // Base64 인코딩
  language: string;
  format: 'wav' | 'mp3' | 'flac';
  sampleRate?: number;
}

interface ASRResponse {
  transcription: string;
  confidence: number;
  timestamps: WordTimestamp[];
  alternatives?: Alternative[];
}

async function transcribeAudio(
  audioFile: File,
  language: string
): Promise<ASRResponse> {
  const base64Audio = await fileToBase64(audioFile);

  const response = await fetch(`${BASE_URL}/asr`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      audio: base64Audio,
      language: language,
      format: 'wav',
      options: {
        timestamps: true,
        punctuation: true,
        profanity_filter: false
      }
    })
  });

  return response.json();
}

5.3 인증 및 권한

권한 레벨	용도	Rate Limit	기능
Free	개발/테스트	100 req/day	기본 API
Developer	프로덕션	10,000 req/day	+ 배치 처리
Enterprise	대규모	무제한	+ 전용 인프라
Community	언어 공동체	무제한	자체 언어 전용

5.4 SDK 구현

// TypeScript SDK
import { WIALangClient } from '@wia/lang-005-sdk';

const client = new WIALangClient({
  apiKey: process.env.WIA_API_KEY,
  defaultLanguage: 'ain',
  timeout: 30000
});

// 번역
const translation = await client.translate({
  text: 'イランカラプテ',
  to: 'ja'
});

// 음성 인식
const transcription = await client.transcribe(audioBuffer, {
  language: 'ain',
  format: 'wav'
});

// 음성 합성
const audio = await client.synthesize('イランカラプテ', {
  language: 'ain',
  voice: 'reiko',
  speed: 1.0
});

// 스트리밍 번역
for await (const chunk of client.translateStream(longText, 'ja')) {
  process.stdout.write(chunk);
}

✏️ 복습 문제

1.

RESTful API 설계 원칙과 WIA-LANG-005 적용 방식을 설명하시오.

2.

번역 API의 요청/응답 구조를 구현하시오.

3.

ASR API에서 스트리밍 처리가 필요한 이유를 논하시오.

4.

언어 공동체 특별 권한의 의미와 弘益人間 철학의 연관성을 설명하시오.

5.

Rate Limiting 구현 방법과 공정한 자원 분배 전략을 제시하시오.

6.

SDK 설계 시 고려해야 할 사용자 경험 요소를 나열하시오.

7.

TranslationClient 클래스를 에러 처리를 포함하여 확장 구현하시오.

8.

GraphQL vs REST API의 장단점을 저자원 언어 AI 맥락에서 비교하시오.

© 2025 SmileStory Co., Ltd. / WIA · 弘益人間