콘텐츠로 이동

번역 작업 생성

POST /api/v1/jobs
Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f
Content-Type: application/json
필드유형필수기본값설명
document_id문자열✅—확인된 문서의 ID
target_lang문자열✅—대상 언어 코드
source_lang문자열—자동 감지소스 언어 코드
engine문자열—xr-397b번역 설정 ID, 번역 설정 참조
output_mode문자열—bilingualsingle 또는 bilingual
glossary_id문자열——이 계정의 용어집 ID입니다. 용어집은 결제가 완료된 계정에만 생성되며(최소 1건의 성공적인 결제 필요), 미결제 상태에서 요청 시 403가 반환됩니다.
include_images불리언—false또한 문서 이미지 내의 텍스트도 번역합니다.
context_translation불리언—false컨텍스트 향상 기능을 활성화합니다.
style_preset문자열——스타일 사전 설정

생성된 작업은 대기열에 들어갑니다. 각 계정은 동시에 최대 5개의 파일을 처리하며, 추가 작업이 계속 생성되고 대기열이 자동으로 진행되어 앞선 작업이 완료되는 순서대로 처리됩니다. 작업이 대기 중일 때, 해당 작업의 stage_message에는 대기 중인 작업 수가 표시됩니다.

작업이 시작되기 전에 잔액이 임계값과 비교됩니다: PDF 형식은 “페이지 × 2 크레딧” 이상의 잔액이 필요하며, 다른 형식은 원본 텍스트 길이를 기준으로 최소 2 크레딧이 요구됩니다. 잔액으로 파일을 시작할 수 없는 경우 해당 작업은 status=failed 및 quota_exceeded=true로 종료되며, 비용이 청구되지 않고 다른 작업에는 영향을 미치지 않습니다. 작업이 완료되면 실제 사용량이 청구되며, 비용이 잔액을 초과하면 잔액이 마이너스가 되고, 이후 입금된 크레딧이 먼저 부채를 상환합니다. 또한 잔액이 마이너스 상태에서는 새로운 작업을 시작할 수 없으므로 충전해야 합니다. 크레딧 및 사용량 을 참조하십시오.

Terminal window
curl --fail-with-body -X POST https://omnidoc.top/api/v1/jobs \
-H "X-API-Key: $OMNIDOC_API_KEY" \
-H "Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f" \
-H "Content-Type: application/json" \
-d '{"document_id":"4q8mx2q9z1k7p6ra","target_lang":"en"}'

응답 201 (서버의 stage_message는 중국어입니다):

{
"id": "q3f8s6c2a9m1k4tx",
"document_id": "4q8mx2q9z1k7p6ra",
"source_lang": null,
"target_lang": "en",
"engine": "xr-397b",
"status": "pending",
"stage": "queued",
"stage_progress": 0,
"stage_message": "排队中",
"time_cost": 0,
"error_msg": null,
"quota_exceeded": false,
"queue_position": null,
"created_at": "2026-10-01T12:01:00Z",
"updated_at": "2026-10-01T12:01:00Z"
}
상태원인
403키가 선택한 설정을 허용하지 않거나, 미결제 계정에서 glossary_id이 전송되었습니다.
404해당 문서 또는 용어집이 존재하지 않거나, 삭제되었거나, 다른 계정에 속합니다.
415파일 형식은 변환할 수 없습니다.
422파일이 비어 있거나 번역 가능한 텍스트가 없거나 매개변수가 잘못되었습니다.
429요청이 너무 많거나 대기열이 가득 찼습니다. Retry-After 후에 다시 시도해 주세요.

Idempotency-Key는 선택 사항이지만 모든 제출물에 권장됩니다. 키는 1~128개의 표시 가능한 ASCII 문자로 구성되며, 동일한 자격 증명에 대해 무기한 유효합니다:

  • 동일한 키, 동일한 본문: 원래 작업(실패한 작업 포함)을 반환하며, 중복으로 생성되거나 청구되는 항목은 없습니다.
  • 동일한 키, 다른 본체: 409 (idempotency_request_conflict).
  • 원래 작업이 삭제되었습니다: 410 (idempotency_job_gone).

각 새로운 제출에는 새 UUID를 사용하고, 동일한 제출을 재시도할 때만 기존 키를 재사용하십시오.