Skip to content

Bring document workflows into your app

From uploading one file to translating it, checking progress and downloading the result. Every step is explained in the order you integrate, with entry points for file management, document processing and audio and video services.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · API key authentication · file translation runs as asynchronous jobs

This site describes the cloud HTTP API.

01 Start with a request that costs no credits

Section titled “01 Start with a request that costs no credits”

Confirm that your key and network work before you upload files. A balance check costs no credits and creates no translation job.

  1. Get an API key

    Sign in to the API console and create a key that starts with sk_. Use a separate key for each application and give it a budget.

    A key acts for the account that created it. Keep it on the server and read it from an environment variable; never put it in web page source or a public repository.

  2. Check the balance

    Set the environment variable OMNIDOC_API_KEY, then run any of the examples below. Success returns JSON; 401 means the key has a problem and needs checking. Never show the full key in tickets, screenshots or logs.

    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"

A successful upload only means the file is stored. After you create a job, wait for it to reach a final state, then list and download its results.

StepMethod and pathWhat to keep
Request an uploadPOST /upload/presignupload_url, upload_headers, finalize_token
Send the filePUT to the returned upload_urlSuccess response; this request carries no API key
Confirm the uploadPOST /upload/finalizedocument.id
Create a translationPOST /jobsJob id
Check the statusGET /jobs/{job_id}completed or failed
List the resultsGET /artifacts?job_id={job_id}Artifact IDs and formats
Download a resultGET /artifacts/{artifact_id}/downloadFile bytes and the response file name

For the direct upload, send the upload_headers from the server exactly as returned, and never send X-API-Key to the storage address. If the upload address expires or the transfer fails, request a new one. Details: upload protocol, quick start, complete Node.js workflow and translation request fields.

Each entry lists the paths, request fields and examples. Your account’s service status and your key’s limits apply to all of them.

An API key identifies an account. It is not a public download password for a file.

Request header

Use X-API-Key: sk_… or Authorization: Bearer sk_…, one of the two per request. Send Content-Type: application/json with JSON bodies.

What a key can reach

A key reaches only the resources its account may use; the service status, the key’s budget and the allowed translation settings still apply. Account changes and creating, rotating or revoking keys happen in the console.

See authentication, budgets and rotation and services and permissions.

05 Build failure handling into the integration

Section titled “05 Build failure handling into the integration”

A timeout does not mean the job was not created. Tell retryable errors apart from requests that need fixing, so nothing is submitted or processed twice.

  • Idempotent creation: generate an Idempotency-Key for each new create operation; when you retry the same operation, reuse the original key and the exact same request body. Document operations, media jobs and voice creation require the key; for other create endpoints see their reference pages.
  • Asynchronous notifications: polling is fine for a first integration; for continuous progress use SSE, and to receive final states in the background use a webhook.
StatusCheck firstWhat to do
401 / 403Key, permissions, resource ownershipFix the credentials or permissions; do not retry blindly
402Available creditsTop up, then submit again
409Idempotency key and body, resource stateQuery the original operation before starting a new one
422Field errors in the responseFix the parameters or the file
429Business code and Retry-AfterRate and queue limits can be waited out; a used-up key budget must be raised first
5xxTemporary service errorBounded exponential backoff; keep the idempotency key for create requests

Keep the X-Request-Id response header, the request time and the path for troubleshooting; never log the full key. All error codes and retry examples are in the error reference.

06 Check how billing works before you integrate

Section titled “06 Check how billing works before you integrate”

No credits

Uploading, checking jobs, downloading results, and reading the balance and settlement records cost no credits; neither do glossaries, projects, tags, search and sharing.

Billed by usage

File translation, document tools, instant translation and audio and video services are settled at their prices by actual usage; creating a job is not the final charge.

Before a job starts, only the balance threshold is checked; after it finishes, the actual usage is charged. If the balance falls short, the difference is recorded as debt, and credits that arrive later pay it off first. You can reconcile charges and refunds per job or per credit operation. When a key’s budget is used up, you can still query the jobs, results and records under that key.