번역 작업 생성
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/json| 필드 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
document_id | 문자열 | ✅ | — | 확인된 문서의 ID |
target_lang | 문자열 | ✅ | — | 대상 언어 코드 |
source_lang | 문자열 | — | 자동 감지 | 소스 언어 코드 |
engine | 문자열 | — | xr-397b | 번역 설정 ID, 번역 설정 참조 |
output_mode | 문자열 | — | bilingual | single 또는 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로 종료되며, 비용이 청구되지 않고 다른 작업에는 영향을 미치지 않습니다. 작업이 완료되면 실제 사용량이 청구되며, 비용이 잔액을 초과하면 잔액이 마이너스가 되고, 이후 입금된 크레딧이 먼저 부채를 상환합니다. 또한 잔액이 마이너스 상태에서는 새로운 작업을 시작할 수 없으므로 충전해야 합니다. 크레딧 및 사용량 을 참조하십시오.
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를 사용하고, 동일한 제출을 재시도할 때만 기존 키를 재사용하십시오.