API documentation

Access & authentication

Email your project, verified iSomor account email, document workflow and expected volume. We will reply with the review outcome. On approval, receive credentials, the base URL and an initial allowance together; no second key-creation step. Send Authorization: Bearer <API_KEY> with every request. Store the key only in server-side environment variables, never cookies, URLs, frontends or AI prompts. Contact support for rotation or revocation without sending the full key.

The command below sets the production ISOMOR_API_BASE_URL, including /api/isomor/v1 without a trailing slash. Set ISOMOR_API_KEY using your server-side secret manager; keep the real key out of command history and code. The curl examples read these variables and prompt you to set any missing values. Use Content-Type: application/json for JSON and multipart/form-data for uploads, with a client-generated boundary. Responses use JSON and HTTP status codes distinguish success from errors.

export ISOMOR_API_BASE_URL="https://tryisomor.com/api/isomor/v1"

support@tryisomor.com

Call sequence

Read capabilities → upload PDF → use the returned id as file_id → create a job and save job_id → poll status → get download links. Check allowance before creating if needed, but a balance read is not a reservation. Follow the idempotency and retry rules below to avoid duplicate jobs.

Downloads & quick start

Import the OpenAPI file into a compatible development tool; baseUrl defaults to the production API URL. The Python example requires Python 3.10 or newer, with no third-party dependencies. Configure both environment variables above before running it.

• Download OpenAPI 3.1 ↓
• Download the complete Python example ↓

This command translates page 1, uses at most 1 credit and retrieves translated and bilingual PDFs. --submit uploads the file and submits a translation; without --submit or --resume, no requests are sent. When changing the page selection, review --max-credits too. If the estimate exceeds the cap, the file is uploaded but no translation is created.

python3 translate_pdf.py \
  --file ./sample.pdf --target zh --pages 1 \
  --max-credits 1 --output ./translation-001 --submit

Resume the same job after interruption

Keep the output directory and use credentials for the same project. The example saves the original request and idempotency key; known jobs are queried, not recreated. It stops when an unknown creation outcome is outside the safe retry window. Existing files with matching saved hashes are skipped, and expired download links are refreshed. Each run waits up to 600 seconds by default; --timeout supports up to 3600 seconds.

python3 translate_pdf.py --output ./translation-001 --resume

The output directory contains private PDFs and state.json recovery data. Do not commit it to Git or share it publicly. Credentials are not saved in state or forwarded to download URLs. Existing files are not overwritten; uploads without a returned file ID are not retried automatically.

Errors & retries

Errors use error.code, error.message and request_id. Share request_id with support, not full keys, download links or document content.

{
  "error": {
    "code": "quota_exceeded",
    "message": "The API allowance is insufficient."
  },
  "request_id": "req_example"
}

400invalid_request

Fix missing fields, JSON or idempotency key.

401invalid_api_key

Check key validity, expiry or revocation; do not retry automatically.

403insufficient_scope

Contact support for the required scope.

404not_found

Check the ID and integration owner; another owner's resource also returns 404.

409idempotency_conflict

Retry the original parameters and key; use a new key only for an intentional new job.

409result_not_ready / job_failed

Poll pending jobs; inspect error on failure instead of looping on results.

413 / 422file_too_large / unsupported_pdf

Correct the PDF size or content. Invalid languages or pages return 400 invalid_request; do not retry unchanged.

429quota_exceeded

Stop new jobs and request more allowance by email; a short wait will not restore it.

403quota_expired

Contact support to renew expired allowance; accepted jobs continue processing.

429concurrency_limit / storage_limit

Wait for active jobs when concurrency is full; contact support when input storage is full.

429rate_limited

Wait Retry-After seconds and back off; reuse the key for job creation.

503service_unavailable

Use exponential backoff; retain the original creation key to avoid duplicate work.

Idempotency window: 24 hours. One integration identity, endpoint and Idempotency-Key identify one job. Repeating the same parameters returns that job; changing parameters returns 409. On creation timeout or 5xx, retry only with the original key and parameters within the window. If the window expired and the job ID is unknown, contact support instead of blindly creating again. Upload retries may create another file but do not start translation.

Allowance & file limits

Approved API integrations receive an initial free allowance. Amount, expiry and conversion rules are confirmed by email. Request increases by email; there is no automatic billing. Allowance is reserved at job creation, settled on success and released on confirmed failure. Read /quota for your available balance. New jobs require sufficient allowance.

Supports original digital PDFs, asynchronous single-file jobs, and translated / bilingual PDFs. Scans are not supported, even after OCR. No OCR, Office, webhooks, batch creation or cancellation endpoint. File size, pages, concurrency and rate limits come from /capabilities. Download links expire and can be requested again; expiry does not mean file deletion. Text is sent to Google Gemini; read the privacy policy and verify results.