Document-Translator.com
메뉴
KO

문서 번역 API

앱이나 워크플로에 문서 번역을 추가하세요. 추출한 텍스트를 보내고 원하는 언어로 번역한 다음, 자체 클라이언트에서 문서를 다시 구성하세요. 구독 없이 선불 크레딧을 사용할 수 있습니다.

빠른 시작

  1. 로그인하고 API 키 만들기. 해당 .env 항목을 예제와 같은 위치에 있는 비공개 .env 파일에 복사하세요. API 번역에는 계정 크레딧이 사용되며, 사용 조건을 충족하는 가입 크레딧도 포함됩니다. 웹사이트의 일일 사용 한도는 적용되지 않습니다. 키를 커밋하거나 공개 브라우저 코드에 넣지 마세요.
  2. Node.js 예제 다운로드. Node.js 22 이상을 사용하세요. 패키지는 필요하지 않습니다. UTF-8 인코딩의 짧은 텍스트 문서를 같은 폴더에 input.txt로 저장하세요. 이 예제는 최대 16,000자를 지원합니다. 더 큰 문서는 아래 API를 통해 여러 세그먼트로 처리하세요.
  3. 첫 번째 명령을 실행해 크레딧을 사용하지 않고 견적을 확인하세요. 내용을 검토한 다음 두 번째 명령을 실행해 스페인어로 번역하고 translated.txt로 저장하세요. 필요한 경우 언어와 경로를 바꾸세요.
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt --start

예제는 결과가 준비될 때까지 상태를 확인하며 기존 출력 파일을 덮어쓰지 않습니다. 중단 후에는 .translation.json 체크포인트를 보존하고 같은 명령을 다시 실행하세요. 추가 요금 없이 기존 작업과 다운로드를 복구합니다. 체크포인트에는 문서 텍스트나 API 키가 포함되지 않습니다. 대기 시간 초과가 처리를 취소하지는 않습니다.

번역 API는 추출한 텍스트를 받아 번역된 세그먼트를 반환합니다. 선택적 비공개 백업을 통해 완료 후 24시간까지 문서를 복구할 수 있습니다. 완성된 문서는 클라이언트에서 재구성하세요.

또는 https://document-translator.com/developers/을 복사해 AI 에이전트에 전달하고 시작하는 데 도움을 받으세요.

문서 번역 워크플로 만들기

애플리케이션에서 안정적인 세그먼트 ID를 사용해 텍스트를 추출하세요. 아래에 표시된 페이로드를 전송한 다음, 반환된 각 ID를 사용해 번역문을 문서에 다시 넣으세요.

견적 받기

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

{
  "version": "document-ir/8",
  "format": "txt",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

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

견적은 기본적으로 엄격한 출력을 사용합니다. 부분 결과를 허용하려면 견적 URL에 output=best-effort-v1을 추가하세요. 준비된 결과에는 outcome과 issues가 포함되므로 사용 전에 확인하세요. 이 정책은 견적 시 고정됩니다.

POST /api/v1/quotes?output=best-effort-v1

번역 시작하기

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

{
  "quoteId": "<quote id>",
  "idempotencyKey": "my-document-0001",
  "payload": {
    "version": "document-ir/8",
    "format": "txt",
    "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

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

번역된 결과 읽기

GET /api/v1/translations/JOB_ID/result
Authorization: Bearer doctr_...

{
  "version": "document-ir/8",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

세그먼트 ID를 사용해 파일을 재구성하세요. 결과 엔드포인트는 완성된 문서가 아니라 JSON을 반환합니다. 공백, 링크, 스타일 및 기타 번역할 수 없는 구조는 클라이언트에서 유지하세요. 각 세그먼트에는 a–z, 0–9, 밑줄 또는 하이픈을 사용해 1~48자 길이의 고유한 ID가 필요합니다. 세그먼트 텍스트는 최대 16,000 UTF-16 코드 단위까지 허용됩니다. 지문은 원본 파일 바이트의 소문자 SHA-256 해시입니다.

사이트에서 문서를 분석하고 재구성합니다. API 클라이언트는 추출한 텍스트를 보내고 파일을 직접 재구성합니다. 브라우저 OCR은 6개 언어의 선명한 스캔을 지원합니다. 홈페이지 FAQ를 참고하세요. 복잡한 레이아웃은 추가 페이지나 읽기 쉬운 대체 파일을 사용할 수 있습니다.

cURL로 견적 요청

위의 견적 JSON을 payload.json으로 저장하고 셸에서 DOCUMENT_TRANSLATOR_API_KEY를 설정하세요. 이 명령은 견적만 요청합니다. 작업을 시작하려면 반환된 견적 ID와 동일한 페이로드를 시작 JSON에 넣어 번역 엔드포인트로 전송하세요.

curl https://document-translator.com/api/v1/quotes \
  -H "Authorization: Bearer $DOCUMENT_TRANSLATOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

PowerShell에서는 curl.exe와 $env:DOCUMENT_TRANSLATOR_API_KEY를 사용하세요. 위에 표시된 백슬래시 줄 연속 대신 명령을 한 줄로 작성하세요.

번역 크레딧 및 API 키

API 문서 하나당 한 계정 크레딧이 한도 내에서 예약됩니다. 엄격 모드 작업은 검증을 마치고 결과가 준비된 경우에만 크레딧이 차감되며, 실패하거나 취소된 미완료 작업은 예약이 해제됩니다. 최선 노력 모드에서는 작은 누락이 있더라도 합의된 크레딧이 사용될 수 있지만, 큰 누락이나 치명적인 오류가 있으면 예약이 해제됩니다. 준비된 모든 결과에 크레딧이 차감된다고 가정하지 말고 outcome.creditOutcome과 outcome.completion을 확인하세요.

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

재시도 및 중단된 요청

GET /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID
DELETE /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID

시작 요청의 처리 결과가 불확실한 경우 같은 견적 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

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

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

queued → processing → ready
                   ↘ failed / cancelled / expired

{"jobs":[{"id":"<job id>","state":"processing","completedChunks":1,"totalChunks":2}]}

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

PUT /api/v1/translations/{id}/files/docx
X-Download-Kind: reading-copy
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: {bytes}

{binary DOCX body}

GET /api/v1/translations/{id}

{"savedFormats":["docx"],"savedDownloads":[{"format":"docx","kind":"reading-copy"}]}

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

PUT /api/v1/translations/{id}/manifest
Content-Type: application/json
Content-Length: {bytes, maximum 2 MiB}

{"version":1,"parserVersion":"document-ir/8","fingerprint":"{original SHA-256}","ocr":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/8
X-Source-SHA256: {original SHA-256}

{unchanged original bytes}

GET /api/v1/translations/{id}
// sourceBackup is available only after both saves
GET /api/v1/translations/{id}/manifest
GET /api/v1/translations/{id}/source

계정 잔액 및 내역

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회 조회하세요. 페이지가 숨겨져 있으면 조회를 일시 중지하고, 크레딧이 지급되거나 계정에서 로그아웃하면 중단하세요.

n8n, Make 및 Zapier

비밀 Bearer 인증 정보를 사용하는 HTTP 요청 단계를 추가하세요. 먼저 텍스트를 추출하고, JSON 페이로드를 견적 엔드포인트로 POST한 다음, 견적 ID와 페이로드, 16–80자의 안정적인 멱등성 키를 번역 엔드포인트로 POST하세요. 대기 시간을 추가하고 준비될 때까지 GET으로 상태를 확인한 후 결과를 가져와 번역된 텍스트를 재구성하거나 저장하세요. 견적 ID와 재시도 키를 워크플로 기록에 저장하세요. 전용 커넥터나 multipart 업로드는 필요하지 않습니다.

제한 및 오류

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

다운로드를 복구할 수 있도록 번역 완료 후 24시간까지 원본 문서의 비공개 사본을 보관합니다. 번역을 삭제하면 더 일찍 제거할 수 있습니다. 번역 제공업체에는 추출한 텍스트만 전송됩니다. 개인정보 세부 정보