OCR API V2

Quick start

RapidAPI subscribers should use the API Base URL shown by RapidAPI in the marketplace/code snippets (the *.p.rapidapi.com gateway). Direct configured clients use https://ocrapi.vnconvert.com.

Authentication

Marketplace authentication is handled by RapidAPI. Direct Bearer access is reserved for configured API clients. Use a unique Idempotency-Key for every logical create request; retrying the same logical request with the same key returns the existing job.

Create job

Create a job using either a URL or a direct multipart upload. Public inputs are PDF, PNG, JPG, JPEG and BMP. Outputs are DOCX or XLSX.

If optional request fields are omitted, the API uses output_format=docx, pages=all and lang=auto. RapidAPI examples may use pages=1 for a quick test; that does not change the API default of all.

URL input

POST /v2/jobs
Idempotency-Key: your-unique-key

{
  "input": {"type":"url","format":"pdf","url":"https://example.com/scan.pdf"},
  "output": {"format":"docx"},
  "params": {"pages":"1-10","lang":"auto"}
}

output and params are optional. Omitting both uses the request defaults above.

Upload input

POST /v2/jobs/upload
Content-Type: multipart/form-data
Idempotency-Key: your-unique-key

file=<document.pdf>
output_format=docx
pages=1-10
lang=auto

Only file and Idempotency-Key are required. The other multipart fields may be omitted to use the defaults above.

Job status

GET /v2/jobs/{job_id}

Public states are queued, waiting_resource, processing, completed, failed and timeout. The response includes poll_after_seconds; wait at least that long before the next status request and stop polling on a terminal state.

A public job response exposes the product-facing fields below. Fields may be null until that part of the job lifecycle is available.

{
  "ok": true,
  "job": {
    "job_id": "20260917T042635Z-...",
    "request_id": "...",
    "status": "completed",
    "input": {
      "filename": "scan.pdf",
      "size_bytes": 123456,
      "sha256": "...",
      "total_pages": 12
    },
    "output": {
      "filename": "scan.docx",
      "size_bytes": 234567,
      "format": "docx",
      "sha256": "..."
    },
    "params": {
      "pages": "1-3,5",
      "selected_pages_count": 4,
      "lang": "auto"
    },
    "created_at": "...",
    "started_at": "...",
    "completed_at": "...",
    "expires_at": "...",
    "poll_after_seconds": 0,
    "result": {
      "available": true,
      "endpoint": "/v2/jobs/{job_id}/result",
      "filename": "scan.docx",
      "size_bytes": 234567
    },
    "error": null
  }
}

When a job fails, error contains code, message and retryable. Internal worker information, resource details, raw operational events and provider information are not public response fields.

Download result

GET /v2/jobs/{job_id}/result

Download only when result.available is true. Results are streamed from an authenticated endpoint and are not exposed as public static URLs.

The response body is the completed binary DOCX or XLSX file. The response Content-Type matches the output format:

DOCX: application/vnd.openxmlformats-officedocument.wordprocessingml.document
XLSX: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Content-Disposition provides the downloadable .docx or .xlsx filename.

Pricing & Pages billing

From $0.015/page. Billed by successfully processed pages. Failed or timed-out jobs are not billed. Status checks and result downloads do not add to Pages usage. View current plans on RapidAPI when marketplace access is published.

Page selection

Use all or ascending non-overlapping ranges such as 1-3,5,8. If pages is omitted, the default is all. One selected OCR page is one usage page. Image inputs contain one page.

Limits

A PDF may contain more pages than the selected-page limit when the requested selection remains within the limit.

Retention & privacy

HTTPS is used for transport. Results are private authenticated downloads. Source files are deleted after processing. Results are deleted after 2 hours. Job metadata and operational logs may be retained for reliability, billing integrity, abuse prevention and support.

Errors

Errors use a stable public structure with code, message and retryable. Codes include unsupported_file_type, file_too_large, invalid_pages, page_limit_exceeded, unsupported_language, processing_timeout and result_expired. Processing failures use generic public messages rather than raw provider errors.

Languages

auto is the default. Public language values use the canonical codes below; aliases such as zh-CN, zh-TW and zh-HK are not accepted.

OpenAPI schema

The machine-readable OpenAPI schema is available at /openapi.json.