시작하기

PolyLingo HTTP API를 사용하여 일반 텍스트, Markdown, JSON, 또는 HTML을 구조를 유지하면서 번역하세요. 이 가이드는 프로덕션 엔드포인트, 인증, 그리고 첫 번째 성공적인 요청을 다룹니다.

기본 URL

모든 예제는 프로덕션 API를 사용합니다:

URL
프로덕션https://api.usepolylingo.com/v1

아래의 모든 경로는 해당 기본 URL에 상대적입니다 (예: POST /translate는 POST https://api.usepolylingo.com/v1/translate를 의미합니다).

자신의 PolyLingo API 인스턴스를 운영하는 경우, 호스트를 배포 URL로 바꾸고 /v1 접두사는 별도로 설정하지 않았다면 유지하세요.

인증

보호된 엔드포인트는 Authorization 헤더에 API 키를 기대합니다:

Authorization: Bearer <your_api_key>

키 받기: PolyLingo 앱 내 API 키에서 생성하세요. 전체 키는 한 번만 보이므로 안전한 곳(환경 변수나 비밀 관리자)에 저장하세요. 키는 같은 화면에서 취소할 수 있습니다.

보안: 키를 비밀번호처럼 다루세요. 키가 사용자에게 노출되지 않도록 서버에서 API를 호출하는 것을 권장합니다.

헤더가 없거나 잘못되었거나 키가 유효하지 않거나 취소된 경우, API는 401과 error: "invalid_api_key"를 응답합니다.

엔드포인트와 키

키 불필요GET /health — 빠른 가동 시간 확인
GET /languages — 지원하는 언어 코드
키 필요POST /translate — 콘텐츠 번역
POST /translate/batch — 여러 항목 번역
POST /jobs — 장시간 번역 작업 큐에 추가 (즉시 202 반환)
GET /jobs/:id — 작업 상태 폴링; 대기 중일 때 queue_position 포함
GET /usage — 인증된 계정의 사용량

첫 번째 요청 (cURL)

export POLYLINGO_API_KEY="pl_your_key_here"

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Hello\n\nThis is **bold**.",
    "format": "markdown",
    "targets": ["es", "fr"],
    "model": "standard"
  }'

성공적인 응답은 요청한 대상 언어별로 하나씩 translations 객체와 토큰 수가 포함된 usage 객체를 포함합니다.

첫 번째 요청 (Node.js)

Node.js **18+**는 fetch를 포함합니다:

const API_KEY = process.env.POLYLINGO_API_KEY
const res = await fetch('https://api.usepolylingo.com/v1/translate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    content: '# Hello\n\n**Bold** text.',
    format: 'markdown',
    targets: ['de', 'ja'],
    model: 'standard',
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${data.error}: ${data.message}`)
console.log(data.translations)

API 접근 가능 여부 확인

건강 상태 확인에는 키가 필요 없습니다:

curl -sS "https://api.usepolylingo.com/v1/health"

서비스가 작동 중임을 나타내는 작은 JSON 페이로드가 표시됩니다. targets로 전달할 수 있는 코드 목록은 **GET /languages**를 사용하세요.

CORS 및 브라우저 앱

API는 키가 신뢰할 수 없는 사이트에서 사용되지 않도록 특정 브라우저 출처에서 직접 호출하는 것을 제한할 수 있습니다. 서버 측 호출(Node, Python, 엣지 함수, 백엔드)은 CORS 제한을 받지 않습니다.

싱글 페이지 앱의 일반적인 패턴은: 프런트엔드가 백엔드와 통신하고, 백엔드가 API 키를 사용해 PolyLingo를 호출하는 것입니다.

다음 단계

  • API 참조 — 요청 및 응답 형식, 오류, 제한 사항.
시작하기 | PolyLingo | PolyLingo