PaddleOCR API: self-hosted serving or the hosted API

Self-hosted or hosted: which one?#

Rule of thumb: use the hosted API to prototype or for low volume when uploading files is acceptable. Self-host when documents are confidential, when you need more than the free quota, or when you want your own models. Not sure you need HTTP at all? The Python API needs no server, and PaddleOCR.js runs OCR inside the browser.

Self-hosted HTTP serving in five minutes#

PaddleOCR doesn't have its own HTTP server. The docs say it "recommends using PaddleX for serving". PaddleX is installed automatically with paddleocr. There are two options. Basic serving is easy to set up. High-stability serving runs on NVIDIA Triton Inference Server.¹ Basic serving is a FastAPI app run by Uvicorn, so it is the "PaddleOCR FastAPI" server people search for. You don't have to write one.³

1. Install PaddleOCR and an engine#

   bashCopy

   python -m pip install paddlepaddle==3.2.0 paddleocr==3.7.0

   Pin the engine. In our install tests, a bare pip install paddlepaddle (3.3.1) crashes PaddleOCR 3.7.0 on CPU.

2. Add the serving plugin#

   bashCopy

   paddlex --install serving

   This pip-installs the serving extra of PaddleX: FastAPI, Uvicorn, Starlette, aiohttp, bce-python-sdk, filetype, pypdfium2, yarl and a pinned opencv-contrib-python==4.10.0.84. In our environment it took 18 seconds.³⁴

3. Start the server#

   bashCopy

   paddlex --serve --pipeline OCR

   The official doc says to expect output like this. Ours matched:¹

   textCopy

   INFO:     Started server process [63108]
   INFO:     Waiting for application startup.
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

4. Check it#

   bashCopy

   curl -s http://localhost:8080/health
   # {"logId":"9bce6482-...","errorCode":0,"errorMsg":"Healthy"}

   FastAPI also serves interactive docs at /docs and the schema at /openapi.json. On our OCR server the schema listed exactly two paths: /health and /ocr.⁴

Server options#

Endpoints and the request/response format#

Every pipeline uses JSON over POST. The path depends on the pipeline:²⁵

Request body for POST /ocr#

Response#

Success is HTTP 200 with logId, errorCode: 0, errorMsg: "Success" and result. On failure, errorCode equals the HTTP status.² Here is a real response from our server, trimmed:

{
  "logId": "11288c77-b7c3-4060-a177-19ca9adafc42",
  "errorCode": 0,
  "errorMsg": "Success",
  "result": {
    "ocrResults": [{
      "prunedResult": {
        "model_settings": {"use_doc_preprocessor": false, "use_textline_orientation": false},
        "dt_polys": [[[243, 167], [604, 120], [608, 151], [247, 198]], "..."],
        "text_det_params": {"limit_side_len": 64, "limit_type": "min", "thresh": 0.3,
                            "max_side_limit": 4000, "box_thresh": 0.6, "unclip_ratio": 1.5},
        "rec_texts": ["HARBOR STREET COFFEE", "214 Harbor Street, Portland ME", "..."],
        "rec_scores": ["..."],
        "rec_polys": ["..."],
        "rec_boxes": ["..."]
      }
    }],
    "dataInfo": {"width": 900, "height": 1200, "type": "image"}
  }
}

prunedResult is the same dict predict() returns in Python, minus input_path and page_index. So rec_texts, rec_scores, rec_polys and rec_boxes mean what they mean in the Python API. With visualization on, each page also gets ocrImage, docPreprocessingImage and inputImage as Base64 JPEGs.²

Those images get big. For one 900×1200 receipt, the default response was 1.23 MB. With "visualize": false it was 4.3 KB, and the three image keys were left out entirely rather than set to null. Read them with .get().⁴

Errors we triggered#

Client code: Python, curl, JavaScript#

The Python client below is copied verbatim from the official docs. We ran it unchanged against our server and it printed the 27 receipt lines.²⁴ The curl and JavaScript versions are derived by us from the documented request schema, because the OCR doc has no curl example. We tested both.

import base64
import requests

API_URL = "http://localhost:8080/ocr"
file_path = "./demo.jpg"

with open(file_path, "rb") as file:
    file_bytes = file.read()
    file_data = base64.b64encode(file_bytes).decode("ascii")

payload = {"file": file_data, "fileType": 1}

response = requests.post(API_URL, json=payload)

assert response.status_code == 200
result = response.json()["result"]
for i, res in enumerate(result["ocrResults"]):
    print(res["prunedResult"])
    ocr_img_path = f"ocr_{i}.jpg"
    with open(ocr_img_path, "wb") as f:
        f.write(base64.b64decode(res["ocrImage"]))
    print(f"Output image saved at {ocr_img_path}")

# GNU base64; -w0 disables line wrapping. Writing to a file avoids
# "argument list too long" on big images.
printf '{"file":"%s","fileType":1,"visualize":false}' "$(base64 -w0 demo.jpg)" > req.json

curl -s -X POST http://localhost:8080/ocr \
  -H "Content-Type: application/json" \
  -d @req.json | jq -r '.result.ocrResults[].prunedResult.rec_texts[]'

# Or pass a URL the server can reach (fileType is inferred from it):
curl -s -X POST http://localhost:8080/ocr -H "Content-Type: application/json" \
  -d '{"file":"https://example.com/invoice.pdf","visualize":false}'

// Node.js 18+ (global fetch). Tested on Node 22.
import { readFile } from "node:fs/promises";

const API_URL = "http://localhost:8080/ocr";
const bytes = await readFile("./demo.jpg");

const res = await fetch(API_URL, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    file: bytes.toString("base64"),
    fileType: 1,          // 0 = PDF, 1 = image; required for Base64 input
    visualize: false      // skip the Base64 result images
  })
});
const body = await res.json();
if (body.errorCode !== 0) throw new Error(`${body.errorCode}: ${body.errorMsg}`);

for (const page of body.result.ocrResults) {
  const { rec_texts, rec_scores } = page.prunedResult;
  rec_texts.forEach((t, i) => console.log(rec_scores[i].toFixed(3), t));
}

Calling from a web page: the server sends no CORS headers, and the browser's preflight OPTIONS request gets a 405. Send browser requests through your own backend or a same-origin reverse proxy. If you want OCR in the browser with no server, use PaddleOCR.js, as our online tool does.⁴

Configure the server: models, speed, page limits#

The default OCR pipeline in PaddleX 3.7.2 uses PP-OCRv6_medium for detection and recognition. It also turns on all three preprocessing models: document orientation (PP-LCNet_x1_0_doc_ori), unwarping (UVDoc) and text-line orientation.³ That is more work than the Python defaults most tutorials show. On our receipt, unwarping gave the same 27 lines but returned them in a different order. To change the defaults, export the config, edit it, and serve the file:⁵

paddlex --get_pipeline_config OCR --save_path ./
# → "The pipeline config has been saved to: OCR.yaml"

This is the edited config we served, as a diff from the export: PP-OCRv6 small models, no preprocessing, no images by default, and no 10-page cap. The Serving keys come from the official docs.¹²

use_doc_preprocessor: False      # was True
use_textline_orientation: False  # was True

SubModules:
  TextDetection:
    model_name: PP-OCRv6_small_det   # was PP-OCRv6_medium_det
  TextRecognition:
    model_name: PP-OCRv6_small_rec   # was PP-OCRv6_medium_rec

Serving:
  visualize: False          # requests can still send "visualize": true
  extra:
    max_num_input_imgs: null  # process every PDF page, not just the first 10

paddlex --serve --pipeline ./ocr_config.yaml --device cpu --port 8080

With this config the server read all 27 receipt lines. There was one slip: 0rder (with a zero) for "Order", which matches what PP-OCRv6 small does in our benchmark. Which tier to pick is covered on the models page.⁴

Large responses? Images can be returned as pre-signed URLs instead of Base64 with Serving.return_urls: true. The only storage backend supported is bos (Baidu object storage).¹

Docker#

We found no official Docker image for serving the plain OCR pipeline. The official images are for PaddleOCR-VL (below). This Dockerfile is ours. It only uses the documented commands. We built it, ran it, and got the same 27 lines back from /ocr. The image was 2.26 GB on disk.⁴

FROM python:3.12-slim

# OpenCV (pulled in by the serving plugin) needs these system libraries
RUN apt-get update \
 && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 libgomp1 \
 && rm -rf /var/lib/apt/lists/*

RUN python -m pip install --no-cache-dir paddlepaddle==3.2.0 paddleocr==3.7.0 \
 && paddlex --install serving -y

COPY ocr_config.yaml /app/ocr_config.yaml
EXPOSE 8080
CMD ["paddlex", "--serve", "--pipeline", "/app/ocr_config.yaml", "--device", "cpu"]

docker build -t paddleocr-serve .
# keep downloaded models between restarts
docker run -d -p 8080:8080 -v paddlex-models:/root/.paddlex paddleocr-serve
curl -s localhost:8080/health

Models are not baked in. They download into /root/.paddlex/official_models on first start (from Hugging Face by default), so mount that directory as a volume. For a GPU image, swap the engine for paddlepaddle-gpu from PaddlePaddle's own index, as shown on the install page.

Official images: PaddleOCR-VL#

For PaddleOCR-VL, Baidu publishes images on ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/. They need Docker ≥ 19.03, an NVIDIA GPU and a driver that supports CUDA 12.6+. The full API service is two containers, a VLM server plus the pipeline. You start it with docker compose up using the compose.yaml and .env from deploy/paddleocr_vl_docker/accelerators/nvidia-gpu/, and it listens on port 8080.⁶

# Must be executed in the directory containing the compose.yaml and .env files
docker compose up

The docs say this setup "can handle only one request at a time". For concurrent requests they point to deploy/paddleocr_vl_docker/hps/.⁶

High-stability serving#

High-stability serving is built on NVIDIA Triton. The PaddleOCR docs send you to the PaddleX serving guide for it. They also warn that it "may not match the performance of the 2.x version based on PaddleServing". Clients use the same request format as basic serving. Start with basic serving. Move to Triton when you need GPU batching, several instances, or more stability than one Uvicorn process gives you.¹

The official hosted API#

The "PaddleOCR official API" is Baidu's hosted service, linked from paddleocr.com, which redirects to AI Studio. In the docs' words, the SDKs "submit local files or file URLs to hosted PaddleOCR services, poll asynchronous jobs, and parse typed results. They do not run local PaddleOCR inference."⁷

Compare self-hosting: there, one POST /ocr to your own server returns the result directly and nothing leaves your network.

Get the "API key" (access token)#

There is no separate API key product. Sign in to AI Studio and copy the token from the Access Token page. All SDKs and the CLI read it from one environment variable:⁷

PADDLEOCR_BASE_URL overrides the service URL, for example to route through your own proxy.⁷

SDKs and CLI#

from paddleocr import PaddleOCRClient, Model

client = PaddleOCRClient()
result = client.ocr(
    file_url="https://example.com/invoice.pdf",
    model=Model.PP_OCRV5,
)
print(result.job_id, len(result.pages))
client.close()

import { Model, PaddleOCRClient } from "@paddleocr/api-sdk";

const client = new PaddleOCRClient();
const result = await client.ocr({
  fileUrl: "https://example.com/invoice.pdf",
  model: Model.PPOCRv5,
});
console.log(result.jobId, result.pages.length);

client, err := paddleocr.NewClient()
if err != nil {
	return err
}

result, err := client.OCR(ctx, &paddleocr.OCRRequest{
	Model:   paddleocr.PPOCRv5,
	FileURL: "https://example.com/invoice.pdf",
})
if err != nil {
	return err
}
fmt.Println(result.JobID, len(result.Pages))

paddleocr api \
  --model_type ocr \
  --model PP-OCRv5 \
  --file_path ./invoice.pdf \
  --request_timeout 300 \
  --poll_timeout 600 \
  --output ocr-result.json

These snippets are verbatim from the official SDK docs.⁷ Use file_path / filePath / FilePath for a local file, and pass exactly one of URL or path. Each OCR page in the Python result has pruned_result plus image URLs. For PDFs with tables, use parse_document() or --model_type doc_parsing, which return Markdown per page. Errors are typed (AuthError, RateLimitError, PollTimeoutError, …) and all inherit from PaddleOCRAPIError.⁷

Raw HTTP (derived from the SDK source)#

Calling it from another language? Here is the protocol the Python SDK speaks, read from its source.⁸ We have not run this ourselves because we didn't use a token for this page. Treat it as a map of the protocol, not a tested recipe.

BASE=https://paddleocr.aistudio-app.com/api/v2/ocr/jobs

# 1. Submit a local file (multipart). JSON with "fileUrl" instead of a file also works.
curl -s -X POST "$BASE" \
  -H "Authorization: Bearer $PADDLEOCR_ACCESS_TOKEN" \
  -F model=PP-OCRv6 -F 'optionalPayload={}' -F file=@invoice.pdf
#   → {"code": 0, "data": {"jobId": "..."}}

# 2. Poll until data.state is "done" (or "failed")
curl -s "$BASE/<jobId>" -H "Authorization: Bearer $PADDLEOCR_ACCESS_TOKEN"

# 3. Download data.resultUrl.jsonUrl: JSONL, one line per page

Quota, limits and the conflicting page caps#

Doc mistakes and look-alikes to avoid#

• Wrong endpoint in the OCR Node.js example: it uses /layout-parsing instead of /ocr (OCR.en.md:2471–2487).²
• Mislabelled API reference links. The "PP-OCRv5 API" link in the SDK docs opens the PaddleOCR-VL page, and the PP-OCRv5 page is behind the "PP-StructureV3 API" label. Go by the page title, not the link text.¹²
• npm look-alikes. The unscoped paddleocr and paddleocr-js packages are not from the PaddleOCR team. The official ones are scoped: @paddleocr/api-sdk (hosted API, Node.js) and @paddleocr/paddleocr-js (browser).¹¹
• PaddleHub serving (deploy/hubserving) is still in the repo from the 2.x era, but the 3.x serving guide recommends PaddleX. We have not checked whether hubserving works with 3.x. If you are upgrading old code, start with the migration guide.

Hooking OCR into an AI agent? The PaddleOCR MCP server can use your self-hosted server as its backend (basic serving only).

Questions#