콘텐츠로 이동

앱에 문서 워크플로를 통합하세요

파일 하나를 업로드하는 것부터 번역, 진행 상태 확인, 결과 다운로드에 이르기까지 모든 단계가 통합 과정의 순서대로 설명되며, 파일 관리, 문서 처리 및 오디오·비디오 서비스에 대한 진입점도 제공됩니다.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · API 키 인증 · 파일 번역은 비동기 작업으로 실행됩니다

이 사이트는 클라우드 HTTP API를 설명합니다.

01 크레딧이 소모되지 않는 요청으로 시작하십시오.

섹션 제목: “01 크레딧이 소모되지 않는 요청으로 시작하십시오.”

파일을 업로드하기 전에 키와 네트워크가 정상 작동하는지 확인하십시오. 잔액 확인은 크레딧이 소모되지 않으며 번역 작업도 생성하지 않습니다.

  1. API 키를 얻으세요

    API 콘솔 에 로그인하여 sk_로 시작하는 키를 생성하십시오. 각 애플리케이션마다 별도의 키를 사용하고 예산을 설정하십시오.

    키는 해당 키를 생성한 계정에 대해 유효합니다. 이를 서버에 저장하고 환경 변수에서 읽어오며, 웹 페이지 소스나 공개 리포지토리에는 절대 포함하지 마십시오.

  2. 잔액 확인하기

    환경 변수 OMNIDOC_API_KEY를 설정한 다음 아래 예제 중 하나를 실행하십시오. 성공 시 JSON이 반환되며, 401은 키에 문제가 있어 점검이 필요함을 의미합니다. 티켓, 스크린샷 또는 로그에는 절대로 전체 키를 노출하지 마십시오.

    Terminal window
    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"

성공적인 업로드는 파일이 저장되었음을 의미할 뿐입니다. 작업을 생성한 후 최종 상태에 도달할 때까지 기다린 다음, 결과를 나열하고 다운로드하십시오.

단계방법 및 경로유지할 내용
업로드 요청POST /upload/presignupload_url, upload_headers, finalize_token
파일을 보내세요PUT을 반환된 upload_url로성공 응답; 이 요청에는 API 키가 포함되어 있지 않습니다.
업로드를 확인하세요POST /upload/finalizedocument.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 또는 취소는 콘솔에서 이루어집니다.

인증, 예산 및 로테이션과 서비스 및 권한을 참조하십시오.

05 통합에 빌드 실패 처리 기능 추가

섹션 제목: “05 통합에 빌드 실패 처리 기능 추가”

시간 초과가 발생했다고 해서 작업이 생성되지 않은 것은 아닙니다. 수정이 필요한 요청과 달리 재시도 가능한 오류를 구분하여, 동일한 작업이 두 번 제출되거나 처리되지 않도록 하십시오.

  • 멱등 생성 : 각 신규 생성 작업에 대해 Idempotency-Key을 생성합니다. 동일한 작업을 재시도할 때는 원래 키와 정확히 동일한 요청 본문을 재사용하십시오. 문서 작업, 미디어 작업 및 음성 생성에는 해당 키가 필요합니다. 기타 생성 엔드포인트에 대해서는 해당 참조 페이지를 참조하십시오.
  • 비동기 알림 : 초기 통합에는 폴링이 적합하며, 지속적인 진행을 위해 SSE 를 사용하고, 백그라운드에서 최종 상태를 수신하려면 웹훅 를 사용합니다.
상태먼저 확인하세요해야 할 일
401 / 403키, 권한, 리소스 소유권자격 증명 또는 권한을 수정하십시오; 무작정 재시도하지 마십시오.
402사용 가능한 크레딧충전한 후 다시 제출하세요.
409멱등 키 및 본문, 리소스 상태새로운 작업을 시작하기 전에 원래 작업을 조회하십시오.
422응답의 필드 오류매개변수 또는 파일을 수정하십시오.
429비즈니스 code 및 Retry-After레이트 및 대기열 제한은 시간이 지나면 해소될 수 있습니다. 사용된 키 할당량을 먼저 재충전해야 합니다.
5xx임시 서비스 오류제한된 지수 백오프; 생성 요청에 대해 등습성 키를 유지합니다.

X-Request-Id 응답 헤더, 요청 시간 및 경로는 문제 해결을 위해 유지하되, 전체 키를 로그에 기록하지 마십시오. 모든 오류 코드와 재시도 예제는 오류 참조에 나와 있습니다.

06 통합하기 전에 청구 방식을 확인하세요

섹션 제목: “06 통합하기 전에 청구 방식을 확인하세요”

크레딧 없음

업로드, 작업 확인, 결과 다운로드, 잔액 및 정산 기록 조회에는 크레딧이 사용되지 않으며, 용어집, 프로젝트, 태그, 검색 및 공유 역시 마찬가지입니다.

사용량에 따라 과금됨

파일 번역, 문서 도구, 실시간 번역 및 오디오·비디오 서비스는 실제 사용량에 따라 요금이 부과되며, 작업 생성 자체가 최종 비용은 아닙니다.

작업이 시작되기 전에는 잔액 임계값만 확인되며, 작업이 완료된 후 실제 사용량이 청구됩니다. 잔액이 부족한 경우 차액은 부채로 기록되며, 이후 입금되는 크레딧이 먼저 상환됩니다. 청구 및 환불 내역은 작업별 또는 크레딧 운영별로 정산할 수 있습니다. 키의 예산이 소진된 경우에도 해당 키 아래의 작업, 결과 및 기록을 조회할 수 있습니다.