PDF OCR to Word API Integration Guide

Turn scanned PDFs into editable Word documents. The PDF OCR to Word API recognizes printed text and returns a public .docx download link for document review, archive cleanup, and intake workflows.

Try the Demo with this two-page scanned PDF. The sample has no selectable text layer: its text must be recognized from the page images.

What the output preserves

Recognized text follows the source page order. Line breaks are preserved, and page breaks separate source pages, including blank-page positions. Word may reflow text, so the resulting physical page count can differ from the PDF.

This is text recognition, not original-layout restoration. Images, table structure, and complex formatting are not reproduced. Handwriting recognition and perfect accuracy are not guaranteed. Review important names, numbers, and other details against the source; scan quality affects results.

Request parameters

Send POST /v1/imagerecognition/pdf2word using multipart form data. Put appkey in the query string.

Parameter	Requirement	Description
appkey	Required query parameter	Your application key.
file	Exactly one input	Upload a PDF, at most 20 MiB and 50 pages.
file_url	Alternative to file	Public HTTP(S) PDF link, at most 2048 characters. Do not submit both inputs.
lang	Optional; default en	en, zh-CN, zh-TW, en+zh-CN, or en+zh-TW.
filename	Optional; default result.docx	Download filename, normalized to .docx, at most 128 characters including the suffix. Paths and unsafe names are rejected.

English is the default. Use zh-CN for Simplified Chinese, zh-TW for Traditional Chinese, or combine either with English using the corresponding en+ option.

Upload a PDF

curl --request POST \
  'https://api.gugudata.io/v1/imagerecognition/pdf2word?appkey=YOUR_APPKEY' \
  --form 'file=@scan.pdf;type=application/pdf' \
  --form 'lang=en' \
  --form 'filename=review.docx'

Submit a public PDF link

curl --request POST \
  'https://api.gugudata.io/v1/imagerecognition/pdf2word?appkey=YOUR_APPKEY' \
  --form-string 'file_url=https://gugudata.io/assets/demo/pdf2text-demo.pdf' \
  --form-string 'lang=en'

Python example

import requests

response = requests.post(
    "https://api.gugudata.io/v1/imagerecognition/pdf2word",
    params={"appkey": "YOUR_APPKEY"},
    files={"file_url": (None, "https://gugudata.io/assets/demo/pdf2text-demo.pdf"),
           "lang": (None, "en")},
    timeout=90,
)
response.raise_for_status()
payload = response.json()
if payload["dataStatus"]["statusCode"] != 200:
    raise RuntimeError("Conversion did not succeed")
print(payload["data"]["wordPath"])

Response and download

The success envelope contains dataStatus and data. The only public result field is data.wordPath, a string containing the generated HTTPS DOCX download URL. Request audit information contains only input type, available size/page statistics, and language—not document text or your chosen filename.

Download the file after conversion and save it in your own document system. The link is public; permanent hosting is not guaranteed. The file uses the MIME type application/vnd.openxmlformats-officedocument.wordprocessingml.document and can be opened in Word or another DOCX-compatible editor.

The Demo generates a real Word document and reuses it for 15 minutes. X-GuGuData-Demo-Mode indicates live or cached; X-GuGuData-Generated-At identifies when the result was generated. Its response parameters link to the actual source PDF.

Errors and limits

HTTP status	Meaning
400	Missing or conflicting input, unsupported language, or invalid filename.
413	PDF exceeds 20 MiB or 50 pages. No silent truncation occurs.
422	Invalid, damaged, encrypted, or entirely unrecognizable PDF; rendering or output limits exceeded.
502	PDF download failed, processing timed out, or conversion returned an invalid result.
503	Conversion capacity or file storage is temporarily unavailable.
401 / 403 / 429	Authentication, permission/quota, or request-rate restriction.

Parameter errors use business code 400; conversion errors use business code 500. Check both HTTP status and the response envelope. Do not immediately repeat a timed-out conversion: first check your job state to avoid unnecessary duplicate work.

Choosing a document workflow

Use this API when reviewers need editable text in a familiar document format. For page-level strings and combined text, use PDF OCR to Text. For PDFs that already contain selectable text, see PDF Parsing and Formatted Output.

Keep the original PDF alongside the edited document so reviewers can verify OCR output. For collections of documents, submit one PDF per request and track each result in your application.