번역 API 문서

1. 01

   API 키 발급

   belindoc.com에 로그인한 뒤 오른쪽 위 프로필 메뉴에서 개발자 센터를 열고 키를 만듭니다. 키는 ft_로 시작하며 전체 값은 생성 직후 한 번만 표시됩니다.

2. 02

   파일 업로드

   먼저 사전 서명 URL을 받은 뒤 PUT으로 파일을 바로 올립니다. URL은 10분간 유효하며, 응답의 objectKey는 다음 단계에서 사용합니다.

   bash

   복사

   # 1. 사전 서명된 업로드 URL 발급 (10분간 유효)
   curl -X POST https://belindoc.com/api/external/translate/batchPresignedUploadUrl \
     -H "X-Api-Key: $BELINDOC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"fileNameList": ["contract.pdf"]}'
   
   # → data[0].persignedUploadUrl / data[0].objectKey
   
   # 2. PUT으로 파일을 해당 URL에 바로 업로드
   curl -X PUT "<persignedUploadUrl>" --upload-file contract.pdf

3. 03

   번역 제출

   fileList, sourceLanguage, targetLanguage, model은 필수입니다. 원문 언어에 AnyLanguage를 넣으면 자동 감지되며, 모델 이름은 하드코딩하지 말고 getModelList 응답을 기준으로 하세요.

   bash

   복사

   curl -X POST https://belindoc.com/api/external/translate/batchSubmitTranslateTask \
     -H "X-Api-Key: $BELINDOC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "fileList": [{ "fileName": "contract.pdf", "fileObjectKey": "<objectKey>" }],
       "sourceLanguage": "AnyLanguage",
       "targetLanguage": "zh-CN",
       "model": "Gemini-2.5-Flash"
     }'
   
   # → { "code": "200", "data": { "batchNo": "...", "fileList": [ ... ] } }

4. 04

   상태 조회 후 다운로드

   batchNo로 status가 3이 될 때까지 조회한 다음 다운로드 URL을 요청합니다. 이 엔드포인트는 SSE로 응답하며 링크는 [DONE] 이벤트에 담겨 옵니다.

   bash

   복사

   # 작업 폴링: status = 3이면 번역 결과 준비 완료
   curl -X POST https://belindoc.com/api/external/translate/searchTranslateFileByBatchNo \
     -H "X-Api-Key: $BELINDOC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"batchNo": "<batchNo>"}'
   
   # 번역 결과 다운로드 URL 발급: SSE 응답이며 링크는 [DONE] 이벤트에 담김
   curl -N -X POST https://belindoc.com/api/external/translate/getTranslateS3DownloadUrl \
     -H "X-Api-Key: $BELINDOC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"translateOrderNo": "<translateOrderNo>", "urlType": 2}'
   
   # event:[DONE]
   # data:{"url":"https://..."}

POST /api/external/translate/getModelList HTTP/1.1
Host: belindoc.com
Content-Type: application/json
X-Api-Key: ft_xxxxxxxxxxxxxxxxxxxxxxxx
language: zh

{}

{
  "code": "200",
  "msg": null,
  "requestId": "8f1c…",
  "data": { }
}

{
  "fileNameList": ["contract.pdf"]
}

{
  "code": "200",
  "data": [
    {
      "persignedUploadUrl": "https://s3.../contract.pdf?X-Amz-Signature=…",
      "objectKey": "translate/10086/2026/contract.pdf",
      "fileName": "contract.pdf",
      "storageType": 1
    }
  ]
}

{
  "fileObjectKey": "translate/10086/2026/contract.pdf",
  "storageType": 1
}

{
  "code": "200",
  "data": { "isOcr": 1, "isDoubleDeck": 0 }
}

{
  "fileList": [
    { "fileName": "contract.pdf", "fileObjectKey": "translate/10086/2026/contract.pdf" }
  ],
  "sourceLanguage": "AnyLanguage",
  "targetLanguage": "zh-CN",
  "model": "Gemini-2.5-Flash",
  "isOcr": 0,
  "terminologyCollectionId": "66f1c2a4b8d3e5f7a9c1b2d3"
}

{
  "code": "200",
  "data": {
    "batchNo": "B20260828173001",
    "fileList": [
      { "fileName": "contract.pdf", "fileObjectKey": "translate/10086/2026/contract.pdf" }
    ],
    "balanceHint": 0
  }
}

{
  "batchNo": "B20260828173001"
}

{
  "code": "200",
  "data": [
    {
      "translateOrderNo": "T20260828173002",
      "batchNo": "B20260828173001",
      "sourceFileName": "contract.pdf",
      "status": 3,
      "textNumber": 4820,
      "targetFileUrl": "https://s3.../contract_zh-CN.pdf?X-Amz-Signature=…"
    }
  ]
}

{
  "translateOrderNo": "T20260828173002",
  "urlType": 2,
  "isWatermark": 0
}

event:[PROCESS]
data:

event:[DONE]
data:{"translateOrderNo":"T20260828173002","url":"https://s3.../contract_zh-CN.pdf?X-Amz-Signature=…"}

{
  "code": "200",
  "data": {
    "en": {
      "AnyLanguage": "Any language",
      "zh-CN": "Simplified Chinese",
      "…": "…"
    },
    "zh": {
      "AnyLanguage": "任意语言",
      "zh-CN": "简体中文",
      "…": "…"
    },
    "…": {}
  }
}

{
  "sourceLanguage": "ja",
  "targetLanguage": "zh-CN",
  "sourceFileObjectKey": "video/10086/2026/lecture.mp4",
  "videoFileName": "lecture.mp4",
  "videoTaskParam": { "voiceRole": "clone", "subtitleType": 1 }
}

{}

{
  "code": "200",
  "data": {
    "userId": 10086,
    "translateQuota": 12000,
    "advancedTranslateQuota": 0,
    "ocrTranslateQuota": 800,
    "totalFreeTranslateQuota": 500,
    "useFreeTranslateQuota": 132
  }
}

번역 자체의 오류(사용량 부족, 미지원 파일, 중복 제출 등)는 별도 코드를 쓰며 msg는 language 헤더의 언어로 옵니다. 분기 처리는 msg가 아니라 code로 하세요.

같은 사용량, 별도 과금 없음

API 호출은 웹과 같은 페이지·영상 사용량을 같은 모델 계수로 차감합니다. API 전용 요금은 없습니다.

워터마크 규칙 동일

무료 구간에서는 PDF 번역본에 워터마크가 들어갑니다. 브라우저에서 받은 것과 똑같으며 API로 받아도 사라지지 않습니다.

호출 횟수는 제출 계열만 집계

키의 호출 횟수는 batchSubmitTranslateTask, submitVideoTranslate, submitVideoRewrite에서만 늘어납니다. 조회 계열은 아무리 폴링해도 집계되지 않습니다.

계정당 제출은 순차 처리

제출은 계정 단위로 잠깁니다. 앞선 제출이 접수 중일 때 다시 보내면 중복 작업 오류가 돌아오니, 병렬로 던지지 말고 잠시 뒤 재시도하세요.

OCR은 기본 꺼짐

isOcr는 스캔 문서일 때만 켜세요. OCR은 페이지 사용량에 더해 OCR 하위 한도까지 차감하므로, 텍스트 PDF에 켜두면 두 배로 소모됩니다. 확실하지 않으면 isOcr 엔드포인트로 먼저 확인하세요.