요청 헤더
X-API-Key: sk_… 또는 Authorization: Bearer sk_… 중 하나를 요청당 하나씩 사용하십시오. JSON 본문과 함께 Content-Type: application/json를 전송하십시오.
Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · API 키 인증 · 파일 번역은 비동기 작업으로 실행됩니다
이 사이트는 클라우드 HTTP API를 설명합니다.
파일을 업로드하기 전에 키와 네트워크가 정상 작동하는지 확인하십시오. 잔액 확인은 크레딧이 소모되지 않으며 번역 작업도 생성하지 않습니다.
API 키를 얻으세요
API 콘솔 에 로그인하여 sk_로 시작하는 키를 생성하십시오. 각 애플리케이션마다 별도의 키를 사용하고 예산을 설정하십시오.
키는 해당 키를 생성한 계정에 대해 유효합니다. 이를 서버에 저장하고 환경 변수에서 읽어오며, 웹 페이지 소스나 공개 리포지토리에는 절대 포함하지 마십시오.
잔액 확인하기
환경 변수 OMNIDOC_API_KEY를 설정한 다음 아래 예제 중 하나를 실행하십시오. 성공 시 JSON이 반환되며, 401은 키에 문제가 있어 점검이 필요함을 의미합니다. 티켓, 스크린샷 또는 로그에는 절대로 전체 키를 노출하지 마십시오.
export OMNIDOC_API_KEY="sk_your_key"curl --fail-with-body --silent --show-error \ 'https://omnidoc.top/api/v1/billing/credits/balance' \ -H "X-API-Key: $OMNIDOC_API_KEY"import osimport requests
response = requests.get( "https://omnidoc.top/api/v1/billing/credits/balance", headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]}, timeout=30,)response.raise_for_status()print(response.json())// Node.js 20+, save as balance.mjsconst apiKey = process.env.OMNIDOC_API_KEY;if (!apiKey) throw new Error('Set OMNIDOC_API_KEY');const response = await fetch('https://omnidoc.top/api/v1/billing/credits/balance', { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(30_000),});if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);console.log(await response.json());성공적인 업로드는 파일이 저장되었음을 의미할 뿐입니다. 작업을 생성한 후 최종 상태에 도달할 때까지 기다린 다음, 결과를 나열하고 다운로드하십시오.
| 단계 | 방법 및 경로 | 유지할 내용 |
|---|---|---|
| 업로드 요청 | POST /upload/presign | upload_url, upload_headers, finalize_token |
| 파일을 보내세요 | PUT을 반환된 upload_url로 | 성공 응답; 이 요청에는 API 키가 포함되어 있지 않습니다. |
| 업로드를 확인하세요 | POST /upload/finalize | document.id |
| 번역문을 생성하십시오. | POST /jobs | 작업 id |
| 상태 확인 | GET /jobs/{job_id} | completed 또는 failed |
| 결과를 나열하십시오. | GET /artifacts?job_id={job_id} | 아티팩트 ID 및 형식 |
| 결과 다운로드 | GET /artifacts/{artifact_id}/download | 파일 바이트 및 응답 파일 이름 |
직접 업로드의 경우, 서버에서 반환된 그대로 upload_headers를 전송하고, 저장소 주소에는 절대 X-API-Key을 보내지 마십시오. 업로드 주소가 만료되거나 전송에 실패한 경우, 새 주소를 요청하십시오. 자세한 내용: 업로드 프로토콜 , 빠른 시작 , 완전한 Node.js 워크플로우 및 번역 요청 필드 .
각 항목에는 경로, 요청 필드 및 예시가 나열되어 있습니다. 귀하 계정의 서비스 상태와 키 한도는 이들 모두에 적용됩니다.
API 키는 계정을 식별합니다. 파일의 공개 다운로드 비밀번호가 아닙니다.
요청 헤더
X-API-Key: sk_… 또는 Authorization: Bearer sk_… 중 하나를 요청당 하나씩 사용하십시오. JSON 본문과 함께 Content-Type: application/json를 전송하십시오.
키가 도달할 수 있는 범위
키는 해당 계정이 사용할 수 있는 리소스에만 접근하며, 서비스 상태, 키의 예산 및 허용된 번역 설정은 여전히 적용됩니다. 계정 변경과 키 생성, 휠 rotation 또는 취소는 콘솔에서 이루어집니다.
인증, 예산 및 로테이션과 서비스 및 권한을 참조하십시오.
시간 초과가 발생했다고 해서 작업이 생성되지 않은 것은 아닙니다. 수정이 필요한 요청과 달리 재시도 가능한 오류를 구분하여, 동일한 작업이 두 번 제출되거나 처리되지 않도록 하십시오.
Idempotency-Key을 생성합니다. 동일한 작업을 재시도할 때는 원래 키와 정확히 동일한 요청 본문을 재사용하십시오. 문서 작업, 미디어 작업 및 음성 생성에는 해당 키가 필요합니다. 기타 생성 엔드포인트에 대해서는 해당 참조 페이지를 참조하십시오.| 상태 | 먼저 확인하세요 | 해야 할 일 |
|---|---|---|
401 / 403 | 키, 권한, 리소스 소유권 | 자격 증명 또는 권한을 수정하십시오; 무작정 재시도하지 마십시오. |
402 | 사용 가능한 크레딧 | 충전한 후 다시 제출하세요. |
409 | 멱등 키 및 본문, 리소스 상태 | 새로운 작업을 시작하기 전에 원래 작업을 조회하십시오. |
422 | 응답의 필드 오류 | 매개변수 또는 파일을 수정하십시오. |
429 | 비즈니스 code 및 Retry-After | 레이트 및 대기열 제한은 시간이 지나면 해소될 수 있습니다. 사용된 키 할당량을 먼저 재충전해야 합니다. |
5xx | 임시 서비스 오류 | 제한된 지수 백오프; 생성 요청에 대해 등습성 키를 유지합니다. |
X-Request-Id 응답 헤더, 요청 시간 및 경로는 문제 해결을 위해 유지하되, 전체 키를 로그에 기록하지 마십시오. 모든 오류 코드와 재시도 예제는 오류 참조에 나와 있습니다.
크레딧 없음
업로드, 작업 확인, 결과 다운로드, 잔액 및 정산 기록 조회에는 크레딧이 사용되지 않으며, 용어집, 프로젝트, 태그, 검색 및 공유 역시 마찬가지입니다.
사용량에 따라 과금됨
파일 번역, 문서 도구, 실시간 번역 및 오디오·비디오 서비스는 실제 사용량에 따라 요금이 부과되며, 작업 생성 자체가 최종 비용은 아닙니다.
작업이 시작되기 전에는 잔액 임계값만 확인되며, 작업이 완료된 후 실제 사용량이 청구됩니다. 잔액이 부족한 경우 차액은 부채로 기록되며, 이후 입금되는 크레딧이 먼저 상환됩니다. 청구 및 환불 내역은 작업별 또는 크레딧 운영별로 정산할 수 있습니다. 키의 예산이 소진된 경우에도 해당 키 아래의 작업, 결과 및 기록을 조회할 수 있습니다.