# PDF OCR to Text API
Extract searchable text from scanned PDFs.
## API Overview
- **HTTP Protocol:** HTTPS
- **HTTP Method:** POST
- **HTTP Endpoint:** https://api.gugudata.io/v1/imagerecognition/pdf2text
- **Response Type:** application/json; charset=utf-8
- **DEMO Endpoint:** https://api.gugudata.io/v1/imagerecognition/pdf2text/demo
- **Live Demo:** https://gugudata.io/demo/pdf2text
- **Postman:** https://www.postman.com/gugudata/gugudata-io
- **LLM Page:** https://gugudata.io/details/pdf2text/llm
- **Raw Markdown:** https://gugudata.io/details/pdf2text/llm.md
## Remote MCP
- **MCP Endpoint:** https://mcp.gugudata.io/mcp
- **MCP Guide:** https://gugudata.io/mcp/
- **Authorization:** OAuth authorization opens in the browser; do not paste appkeys into MCP clients.
- **Tool Scope:** MCP clients receive GuGuData API tools available to the authorized account.
## Data & API Features
- Scanned PDF recognition: Upload a PDF and receive page-level recognized text plus combined full text for search, review, and automation.
- Page-by-page text: Receive one text entry per page in document order, including empty entries for blank pages.
- Combined document text: Store extracted text beside the source PDF so historical scans, contracts, receipts, and forms become searchable.
- English and Chinese options: Choose English, Simplified Chinese, Traditional Chinese, or an English and Chinese combination.
- Document workflows: Call the endpoint from document queues, ingestion services, or back-office automation for repeated PDF processing.
- Upload or PDF link: Upload a PDF or submit a public PDF link for automated document intake.
## API Request Parameters
| Name | Type | Is Required | Default Value | Remark |
| --- | --- | --- | --- | --- |
| appkey | string | true | YOUR_APPKEY | API key used to authenticate the request. |
| file | file | false | | Upload a PDF. Provide exactly one of file or file_url. Maximum 20 MiB and 50 pages. |
| file_url | string | false | | Public HTTP(S) PDF URL, up to 2048 characters. Provide exactly one of file or file_url. |
| lang | string | false | en | en, zh-CN, zh-TW, en+zh-CN, or en+zh-TW. Recognition quality depends on the scan. |
## API Response Parameters
| Name | Type | Remark |
| --- | --- | --- |
| resultText | array<string> | Recognized text in page order; blank pages retain an empty string. |
| text | string | Nonempty page text joined by two newline characters. |
## API Response Status Codes
| Status Code | Explanation of Status Code | Remarks |
| --- | --- | --- |
| 200 | Request processed successfully. | Some endpoints expose a separate application-level status field in the response body, such as `dataStatus.statusCode`. |
| 400 | Invalid request parameters or request format. | Check required fields, data types, and request body format. |
| 401 | Missing or unknown application key. | Provide a valid `appkey` with the request. |
| 403 | The application key is recognized but access is not allowed. | The key may be expired, inactive, or not permitted for the requested API. |
| 413 | PDF exceeds the size or page limit. | Use a PDF of at most 20 MiB and 50 pages. |
| 422 | PDF cannot be recognized. | Use an unencrypted PDF with legible printed text. |
| 429 | Request rate or trial usage limit exceeded. | Reduce request frequency and retry with backoff. If a trial allowance is exhausted, check Trial Keys for remaining requests and subscribe to continue. |
| 500 | Internal service error. | Retry later or contact support if the error persists. |
| 502 | PDF download or recognition failed. | Check the PDF link and try again later. |
| 503 | Recognition is temporarily unavailable. | Try again later. |
## cURL Example
```bash
curl --location 'https://api.gugudata.io/v1/imagerecognition/pdf2text?appkey=YOUR_APPKEY' --form 'file=@localfile_path.pdf' --form 'lang=en'
```