# PDF Parsing and Formatted Output
Extract PDF text as HTML, plain text, Markdown, or JSON.
## API Overview
- **HTTP Protocol:** HTTPS
- **HTTP Method:** POST
- **HTTP Endpoint:** https://api.gugudata.io/v1/imagerecognition/pdf2format
- **Response Type:** application/json; charset=utf-8
- **DEMO Endpoint:** https://api.gugudata.io/v1/imagerecognition/pdf2format/demo
- **Live Demo:** https://gugudata.io/demo/pdf2format
- **Postman:** https://www.postman.com/gugudata/gugudata-io
- **LLM Page:** https://gugudata.io/details/pdf2format/llm
- **Raw Markdown:** https://gugudata.io/details/pdf2format/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
- Four useful text formats: Choose HTML, plain text, Markdown, or a JSON string.
- Page-aware output: Keep the original page order, with numbered sections in HTML, Markdown, and JSON.
- Multilingual documents: Extract readable text already present in PDFs, including Chinese and English.
- Upload or link input: Submit a PDF file or a publicly accessible PDF URL.
- Browser-ready text: Display extracted text as a readable UTF-8 HTML document.
- Document workflows: Prepare PDF text for search, indexing, and content processing.
## API Request Parameters
| Name | Type | Is Required | Default Value | Remark |
| --- | --- | --- | --- | --- |
| appkey | string | true | YOUR_APPKEY | API key used to authenticate the request. |
| type | string | true | html | Output format: html, text (alias txt), markdown (alias md), or json. The result is always a string. |
| pdffile | file | false | | PDF upload. Provide exactly one of pdffile, file, or file_url. Maximum 20 MiB and 100 pages. Encrypted, damaged, and textless PDFs are not supported. |
| file | file | false | | Compatible alias for pdffile. Do not combine it with another input. |
| file_url | string | false | https://storage.gugudata.io/pdf/demo.pdf | Public HTTP or HTTPS PDF URL, as an alternative to a file upload. |
## API Response Parameters
| Name | Type | Remark |
| --- | --- | --- |
| dataStatus.requestParameter | string | Privacy-safe summary of the normalized request. |
| dataStatus.statusCode | integer | Application-level status code. |
| dataStatus.statusDescription | string | Human-readable application status message. |
| dataStatus.responseDateTime | string | Time at which the response was generated. |
| dataStatus.dataTotalCount | integer | Number of matching or returned records for this request. |
| data.result | string | Extracted HTML, plain text, Markdown, or serialized JSON containing ordered page text. Parse this string again when type=json. Does not include OCR, images, or complex layout reconstruction. |
## 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 100 pages. |
| 422 | PDF cannot be converted. | Check that the PDF is readable, unencrypted, and contains text. Output must not exceed 20 MiB. |
| 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 retrieval or conversion response failed. | Check that the public PDF URL can be downloaded. |
| 503 | Conversion is temporarily unavailable. | Try again later. |
## cURL Example
```bash
curl --location 'https://api.gugudata.io/v1/imagerecognition/pdf2format?appkey=YOUR_APPKEY' --form 'type=html' --form 'pdffile=@localfile_path.pdf'
```