문서 번역 API | Document-Translator.com

빠른 시작

로그인하고 API 키 만들기. 키를 서버의 비밀 설정에 저장하세요. API 번역에는 선불 크레딧이 필요하며, 브라우저 무료 사용량은 적용되지 않습니다.
클라이언트에서 문서의 텍스트를 추출하고 각 세그먼트에 고유 ID를 지정한 다음 견적을 요청하세요. 문서를 다시 구성할 수 있도록 원본을 로컬에 보관하세요.
견적 ID, 안정적인 멱등성 키, 동일한 payload로 시작하세요. 준비될 때까지 상태를 확인하고 번역된 세그먼트를 가져온 다음 문서를 다시 구성하세요.

번역 API는 추출된 텍스트를 받아 번역된 세그먼트를 반환합니다. 클라이언트에서 완성된 파일을 만든 다음, 원하면 나중에 다운로드할 수 있도록 번역된 파일을 저장하세요. 원본 파일은 업로드하지 마세요.

견적 받기

POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "version": "document-ir/1",
  "format": "txt",
  "fingerprint": "<64-character SHA-256 of the source file>",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

응답에는 견적 ID, 원본 단어 수, 정확한 크레딧 비용, 만료 시간이 포함됩니다. 견적은 10분 동안 유효합니다. 견적을 요청해도 크레딧이 예약되거나 문서 텍스트가 저장되지는 않습니다.

번역 시작하기

POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "quoteId": "<quote id>",
  "idempotencyKey": "<stable key, 16–80 letters, digits, underscores or hyphens>",
  "payload": {
    "version": "document-ir/1",
    "format": "txt",
    "fingerprint": "<the same source fingerprint>",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

시작할 때 처음에 받은 견적 payload를 다시 보내세요. 서버는 텍스트를 저장하거나 크레딧을 예약하기 전에 소유자와 표준 해시를 확인합니다. JSON 객체 키의 순서는 상관없지만 텍스트, 세그먼트 순서, 형식, 지문 또는 언어를 변경하려면 새 견적이 필요합니다.

문서 번역 워크플로 만들기

애플리케이션에서 텍스트를 추출하고 다운로드 파일을 다시 구성하세요. 위에 표시된 페이로드를 전송한 다음, 반환된 세그먼트 ID를 사용해 각 번역문을 해당 문서에 다시 넣으세요.

// Run this on your server. Keep your API key private.
const response = await fetch(
  'https://document-translator.com/api/v1/quotes',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  }
);
if (!response.ok) throw new Error('Quote request failed');
const quote = await response.json();
// Show the price before starting with the same payload.

DOCX는 지원되는 원본 구조를 유지합니다. PDF 내보내기는 텍스트 흐름을 재구성하며 원본 페이지 레이아웃을 정확히 재현하지 않습니다. 스캔한 PDF와 암호로 보호된 PDF는 지원하지 않습니다. 중요한 번역과 서식을 사용하기 전에 검토하세요.

번역 크레딧 및 API 키

각 API 문서는 업로드 한도 내에서 계정 크레딧 1개를 사용합니다. 번역 시작 시 크레딧이 예약되고, 검증을 마친 번역이 완성되면 한 번 청구됩니다. 가입 보너스 크레딧은 API에서 사용할 수 있으며, 일일 무료 이용 한도는 웹사이트에서만 사용할 수 있습니다.

계정당 활성 API 키를 최대 5개 만들 수 있습니다. 키는 한 번만 표시되고 해시로 저장되며 계정에서 해지할 수 있습니다. 활성 키는 같은 계정의 다른 키로 만든 작업을 포함해 해당 계정의 유료 번역에 액세스할 수 있습니다. 키로 로그인하거나 결제할 수는 없습니다.

재시도 및 중단된 요청

시작 요청의 처리 결과가 불확실한 경우 같은 견적 ID, 페이로드, 멱등성 키를 사용하세요. 내용이 동일한 요청을 재시도하면 추가 요금 없이 기존 작업이 반환됩니다. 페이로드가 변경되었거나 다른 견적에 이미 사용된 키를 재사용하면 409가 반환됩니다. 작업 및 멱등성 메타데이터는 종료 후 7일 동안 보관됩니다.

원문 텍스트를 사용할 수 있는 동안 재개 가능한 실패 작업을 다시 시도할 수 있습니다. 재시도해도 작업 ID는 유지되며 완료된 청크는 재사용됩니다. 작업은 최대 세 번 처리할 수 있습니다. 다운로드에 실패하면 새 번역을 시작하지 않고 결과 엔드포인트를 다시 요청할 수 있습니다.

상태 확인 및 다운로드

GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

일괄 상태 조회에는 최대 10개의 ID를 지정할 수 있으며, 권한이 있고 삭제되지 않은 작업만 { jobs: [...] }에 반환됩니다. 처리 중에는 약 5초마다, 대기 중에는 약 15초마다 상태를 확인하세요. 10개가 넘는 작업을 복구할 때는 일괄 조회를 번갈아 진행하세요. 탭이 숨겨져 있으면 상태 확인을 일시 중지하고, 작업이 종료되거나 복구할 수 없는 권한 오류가 발생하면 중지하세요.

상태가 ready가 되면 동일한 계정 인증으로 결과를 가져오세요. 결과에는 로컬에서 재구성할 수 있도록 번역된 세그먼트 매핑이 포함됩니다. 결과는 완료 후 24시간 동안 이용할 수 있으며, 유효하지 않은 입력은 생성 후 1시간이 지나면 만료됩니다. 만료된 결과에는 410이 반환됩니다. 삭제되었거나 접근할 수 없는 작업에는 404가 반환됩니다.

완성된 파일을 저장하려면 바이너리 본문, Content-Length, 일치하는 Content-Type을 사용해 PUT 요청을 보내세요. 지원되는 확장자는 docx, pdf, txt, md이며, 형식별로 파일 하나씩 저장할 수 있고 출력 파일 크기는 최대 50 MB입니다. 저장에 성공한 파일을 다시 저장해도 기존 파일이 유지됩니다. GET 요청으로 저장된 파일을 다운로드할 수 있으며, 작업 상태의 savedFormats에 사용 가능한 형식이 표시됩니다. 저장과 다운로드에는 동일한 작업 소유권 확인이 적용되고 추가 크레딧이 들지 않으며 24시간 기한도 연장되지 않습니다.

DELETE는 완료되지 않은 작업을 취소하거나 사용 가능한 텍스트와 저장된 파일을 삭제합니다. 완료된 결과를 삭제해도 크레딧은 환불되지 않으며 다운로드 기간도 연장되지 않습니다. 이번 릴리스에는 완료 웹훅이 없습니다.

계정 잔액 및 내역

GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balance

기록은 현재 소유자에게만 표시되며, 응답으로 반환된 페이지네이션 커서를 사용합니다. 잔액 엔드포인트는 브라우저 계정 세션을 사용하고 로그인 및 잔액에 관한 최소한의 정보만 반환합니다. Checkout이 대기 중인 동안에는 5초마다 최대 10회 조회하세요. 페이지가 숨겨져 있으면 조회를 일시 중지하고, 크레딧이 지급되거나 계정에서 로그아웃하면 중단하세요.

제한 및 오류

문서당 원문 최대 50,000단어, 추출 문자 400,000자, 텍스트 세그먼트 12,000개를 지원합니다. 브라우저에서 원본 파일은 25 MB, PDF는 100페이지로 제한됩니다.
계정당 대기 중이거나 처리 중인 문서는 최대 100개입니다. 시작과 재시도에는 동일한 속도 제한이 적용됩니다. 429 응답의 Retry-After를 준수하고, 일시적인 실패에는 제한된 백오프를 사용하세요.
번역된 세그먼트가 누락되거나 중복되거나 형식이 잘못된 경우, 게시 및 결제 전에 유효성 검사에 실패합니다. 완료되지 않은 작업이 실패하거나 취소되면 예약된 크레딧이 반환됩니다.

오류에는 오류 메시지와 코드가 포함됩니다. 400은 잘못된 입력, 401은 잘못된 인증 정보, 402는 크레딧 부족, 404는 이용할 수 없는 작업, 409는 견적 또는 상태 충돌, 410은 만료, 429는 요청 빈도 또는 용량 제한, 503은 서비스 이용 불가를 뜻합니다.

원본 문서는 사용자 기기에 남습니다. 추출된 텍스트는 번역 제공업체에서 처리하며, 저장된 번역 파일은 다운로드할 수 있도록 비공개로 보관됩니다. 임시 저장 데이터는 일정에 따라 정리되며, 제공업체의 보관 정책도 적용됩니다. 개인정보 세부 정보