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.
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.
Confirm that your key and network work before you upload files. A balance check costs no credits and creates no translation job.
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.
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.
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());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.
| Step | Method and path | What to keep |
|---|---|---|
| Request an upload | POST /upload/presign | upload_url, upload_headers, finalize_token |
| Send the file | PUT to the returned upload_url | Success response; this request carries no API key |
| Confirm the upload | POST /upload/finalize | document.id |
| Create a translation | POST /jobs | Job id |
| Check the status | GET /jobs/{job_id} | completed or failed |
| List the results | GET /artifacts?job_id={job_id} | Artifact IDs and formats |
| Download a result | GET /artifacts/{artifact_id}/download | File 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.
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.
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.| Status | Check first | What to do |
|---|---|---|
401 / 403 | Key, permissions, resource ownership | Fix the credentials or permissions; do not retry blindly |
402 | Available credits | Top up, then submit again |
409 | Idempotency key and body, resource state | Query the original operation before starting a new one |
422 | Field errors in the response | Fix the parameters or the file |
429 | Business code and Retry-After | Rate and queue limits can be waited out; a used-up key budget must be raised first |
5xx | Temporary service error | Bounded 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.
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.