Name: PDF to Text API: Convert PDF to Text and Images
Brand: zsmartsoft
SKU: api-zsmartsoft-pdf-converter-api
Availability: InStock
Author: API Market

Ezzat Elbadrawy

# PDF Converter API

## Overview

The PDF Converter API turns PDF documents into plain text or into images. It has 4 endpoints on two paths. `/api/PdfToText` reads the text on each page and returns it as JSON, one entry per page. `/api/PdfToImage` renders pages as an image file in the format you choose, such as PNG, JPEG or TIFF. Each path works two ways: a POST endpoint that takes a PDF you upload in a multipart form, and a GET endpoint that takes the address of a PDF already on the public web and downloads it for you. All 4 endpoints accept the same `startPage` and `endPage` parameters, so you can convert the whole document or only a range of pages.

It is built for developers who need the content of a PDF without running their own PDF library: apps that read invoices and reports, search tools that index PDF files, and pipelines that need page previews or thumbnails. The text endpoints return a `status` field and a `data` array where each item has a `pageNo` and the `content` of that page, with lines separated by `\r\n`. The image endpoints return the image itself as a binary file (for example `image/png`) rather than JSON. When a conversion cannot be completed, the API returns a JSON body with `status` set to `Failure` and an `error` description, so always check `status` before you use the result.

## Features

*   **4 endpoints**: PDF to image by URL (GET), PDF to image from an upload (POST), PDF to text by URL (GET) and PDF to text from an upload (POST).
*   **Two ways to send a PDF**: Upload the file as the `pdfFile` field of a multipart form, or pass a public PDF address in the `url` query parameter.
*   **Text per page**: The text endpoints return one `data` item per page with its page number and text content.
*   **Image output formats**: `imgFormat` accepts `tifflzw`, `tif`, `jpeg`, `jpg`, `png`, `pnggray`, `png256`, `png16` and `png16m`. The default is TIFF.
*   **Page ranges**: `startPage` and `endPage` pick the pages to convert. Both default to `0`, which means from the first page and to the last page.
*   **Multi-page images**: The provider says TIFF output holds multiple pages in one file, while PNG or JPEG output for more than one page comes back as a zip file with one image per page.
*   **Clear failures**: A conversion that fails returns `{"status":"Failure","error":"..."}` with a description of the problem.
*   **Rate limit**: 10 requests per second on the Free plan, 50 on Pro and 500 on Mega.

## Use Cases

*   **Invoice and receipt capture**: Pull the invoice number and total out of a PDF invoice before you store it or match it to an order.
*   **Search indexing**: Extract the text of PDF reports, manuals and papers so they can be indexed by a search engine.
*   **Page previews**: Render the first page of an uploaded PDF as a PNG to show as a thumbnail or preview in your app.
*   **Web PDF processing**: Read a PDF that is already on a public website by passing its URL, without downloading it first.
*   **Document pipelines**: Feed page text into a parser or language model that picks out the fields your workflow needs.
*   **Archiving**: Convert PDF pages to TIFF images for systems that store scanned documents as images.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/zsmartsoft/pdf-converter-api
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. PDF to image from a PDF URL

Downloads the PDF at a public web address and returns the selected pages as an image file in the format set by `imgFormat`. It returns the image in the same way as the upload version in endpoint 2: an image file for a single page, or a zip file of images when you ask for several pages in PNG or JPEG. The PDF must be reachable without a login or any other authentication, and some hosts block the download, in which case the API returns a `Failure` response. URL-encode the address before you put it in the query string. The provider says the parameter can also be named `pdfUrl`.

**Method:** `GET`

**Endpoint:** `/api/PdfToImage`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | Public address of the PDF to convert, URL-encoded. | string | Yes | - | - |
| `imgFormat` | query | Output image format: `tifflzw`, `tif`, `jpeg`, `jpg`, `png`, `pnggray`, `png256`, `png16` or `png16m`. | string | No | tif | - |
| `startPage` | query | First page to convert. `0` means from the first page. | integer | No | 0 | - |
| `endPage` | query | Last page to convert. `0` means to the last page. | integer | No | 0 | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/zsmartsoft/pdf-converter-api/api/PdfToImage?url=https%3A%2F%2Fpdfobject.com%2Fpdf%2Fsample.pdf&imgFormat=png&startPage=0&endPage=0" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -o page1.png
```

The response body is the image file, so save it with `-o` instead of printing it.

#### 2. PDF to image from an uploaded file

Renders the pages of a PDF that you upload and returns them as an image file in the format set by `imgFormat`. Send the PDF as the `pdfFile` field of a `multipart/form-data` request. The response is binary, not JSON: in our test a one-page invoice PDF converted with `imgFormat=png` came back as a 5,868-byte PNG with content type `image/png` in about 1.4 seconds.

**Method:** `POST`

**Endpoint:** `/api/PdfToImage`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `pdfFile` | form | The PDF file to convert, sent as a multipart form file. | file (binary) | Yes | - | - |
| `imgFormat` | query | Output image format: `tifflzw`, `tif`, `jpeg`, `jpg`, `png`, `pnggray`, `png256`, `png16` or `png16m`. | string | No | tif | - |
| `startPage` | query | First page to convert. `0` means from the first page. | integer | No | 0 | - |
| `endPage` | query | Last page to convert. `0` means to the last page. | integer | No | 0 | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/zsmartsoft/pdf-converter-api/api/PdfToImage?imgFormat=png&startPage=0&endPage=0" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -F "pdfFile=@invoice.pdf" \
  -o invoice.png
```

The example file `invoice.pdf` is a one-page PDF with the text "Invoice 1042 Total 250 EUR". The response is the PNG image of that page (`image/png`, 5,868 bytes), which the `-o` option saves to `invoice.png`.

#### 3. PDF to text from a PDF URL

Downloads the PDF at a public web address and returns the text of the selected pages in the `data` array, one item per page. The PDF must be reachable without a login or any other authentication. URL-encode the address before you put it in the query string. The provider says the parameter can also be named `pdfUrl`. In our test the one-page sample PDF below took about 2.2 seconds.

**Method:** `GET`

**Endpoint:** `/api/PdfToText`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | Public address of the PDF to read, URL-encoded. | string | Yes | - | - |
| `startPage` | query | First page to read. `0` means from the first page. | integer | No | 0 | - |
| `endPage` | query | Last page to read. `0` means to the last page. | integer | No | 0 | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/zsmartsoft/pdf-converter-api/api/PdfToText?url=https%3A%2F%2Fpdfobject.com%2Fpdf%2Fsample.pdf&startPage=0&endPage=0" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "status": "Success",
  "data": [
    {
      "pageNo": 1,
      "content": "Sample PDF\r\nThis is a simple PDF ﬁle. Fun fun fun.\r\nLorem ipsum dolor sit amet, consectetuer adipiscing elit. Phasellus facilisis odio sed mi.\r\nCurabitur suscipit. Nullam vel nisi. Etiam semper ipsum ut lectus. Proin aliquam, erat eget\r\npharetra commodo, eros mi condimentum quam, sed commodo justo quam ut velit.\r\nInteger a erat. Cras laoreet ligula cursus enim. Aenean scelerisque velit et tellus.\r\nVestibulum dictum aliquet sem. Nulla facilisi. Vestibulum accumsan ante vitae elit. Nulla\r\nerat dolor, blandit in, rutrum quis, semper pulvinar, enim. Nullam varius congue risus.\r\nVivamus sollicitudin, metus ut interdum eleifend, nisi tellus pellentesque elit, tristique\r\naccumsan eros quam et risus. Suspendisse libero odio, mattis sit amet, aliquet eget,\r\nhendrerit vel, nulla. Sed vitae augue. Aliquam erat volutpat. Aliquam feugiat vulputate nisl.\r\nSuspendisse quis nulla pretium ante pretium mollis. Proin velit ligula, sagittis at, egestas a,\r\npulvinar quis, nisl.\r\nPellentesque sit amet lectus. Praesent pulvinar, nunc quis iaculis sagittis, justo quam\r\nlobortis tortor, sed vestibulum dui metus venenatis est. Nunc cursus ligula. Nulla facilisi.\r\nPhasellus ullamcorper consectetuer ante. Duis tincidunt, urna id condimentum luctus, nibh\r\nante vulputate sapien, id sagittis massa orci ut enim. Pellentesque vestibulum convallis\r\nsem. Nulla consequat quam ut nisl. Nullam est. Curabitur tincidunt dapibus lorem. Proin\r\nvelit turpis, scelerisque sit amet, iaculis nec, rhoncus ac, ipsum. Phasellus lorem arcu,\r\nfeugiat eu, gravida eu, consequat molestie, ipsum. Nullam vel est ut ipsum volutpat\r\nfeugiat. Aenean pellentesque.\r\nIn mauris. Pellentesque dui nisi, iaculis eu, rhoncus in, venenatis ac, ante. Ut odio justo,\r\nscelerisque vel, facilisis non, commodo a, pede. Cras nec massa sit amet tortor volutpat\r\nvarius. Donec lacinia, neque a luctus aliquet, pede massa imperdiet ante, at varius lorem\r\npede sed sapien. Fusce erat nibh, aliquet in, eleifend eget, commodo eget, erat. Fusce\r\nconsectetuer. Cras risus tortor, porttitor nec, tristique sed, convallis semper, eros. Fusce\r\nvulputate ipsum a mauris. Phasellus mollis. Curabitur sed urna. Aliquam nec sapien non\r\nnibh pulvinar convallis. Vivamus facilisis augue quis quam. Proin cursus aliquet metus.\r\nSuspendisse lacinia. Nulla at tellus ac turpis eleifend scelerisque. Maecenas a pede vitae\r\nenim commodo interdum. Donec odio. Sed sollicitudin dui vitae justo.\r\nMorbi elit nunc, facilisis a, mollis a, molestie at, lectus. Suspendisse eget mauris eu tellus\r\nmolestie cursus. Duis ut magna at justo dignissim condimentum. Cum sociis natoque\r\npenatibus et magnis dis parturient montes, nascetur ridiculus mus. Vivamus varius. Ut sit\r\namet diam suscipit mauris ornare aliquam. Sed varius. Duis arcu. Etiam tristique massa\r\neget dui. Phasellus congue. Aenean est erat, tincidunt eget, venenatis quis, commodo at,\r\nquam."
    }
  ]
}
```

#### 4. PDF to text from an uploaded file

Reads the text of a PDF that you upload and returns it in the `data` array, one item per page. Send the PDF as the `pdfFile` field of a `multipart/form-data` request. In our test a one-page invoice PDF took about 2.6 seconds.

**Method:** `POST`

**Endpoint:** `/api/PdfToText`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `pdfFile` | form | The PDF file to read, sent as a multipart form file. | file (binary) | Yes | - | - |
| `startPage` | query | First page to read. `0` means from the first page. | integer | No | 0 | - |
| `endPage` | query | Last page to read. `0` means to the last page. | integer | No | 0 | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/zsmartsoft/pdf-converter-api/api/PdfToText?startPage=0&endPage=0" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -F "pdfFile=@invoice.pdf"
```

The example file `invoice.pdf` is a one-page PDF with the text "Invoice 1042 Total 250 EUR".

**Example Response (200 OK):**

```json
{
  "status": "Success",
  "data": [
    {
      "pageNo": 1,
      "content": "Invoice 1042 Total 250 EUR"
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The conversion worked. The text endpoints return `status: "Success"` with the `data` array, and the image endpoints return the image or zip file. If you get JSON from an image endpoint, read it as an error. |
| 400 | Bad Request | The request could not be processed, for example the POST body has no `pdfFile` field, the GET request has no `url`, the file is not a readable PDF, or the PDF host refused the download. The body is `{"status":"Failure","error":"..."}` with the reason. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The path does not exist. Check that you are calling `/api/PdfToText` or `/api/PdfToImage` under the base URL. |
| 429 | Too Many Requests | You went over your plan's requests-per-second limit, or you have used all 5 calls of the Free plan. |
| 500 | Internal Server Error | Something failed while converting the PDF. The body is a `Failure` response with an `error` description. Retry after a short delay. |

## Rate Limits

The Free plan allows 10 requests per second, the Pro plan 50 and the Mega plan 500. The Free plan includes 5 calls in total over a 7-day trial, Pro includes 30,000 and Mega 300,000. On the Free plan the limit is hard, so requests after the 5th return `429 Too Many Requests`. On Pro and Mega you can keep calling after the included calls are used, and each extra call is billed at $0.001. Requests above your plan's per-second limit also return `429`. Back off before retrying and honour any `Retry-After` header. In our tests single-page conversions took about 1.4 to 2.6 seconds, and long PDFs or slow PDF hosts take longer, so set your client timeout well above that.

## FAQ

**Should I upload the PDF or pass a URL?**

Upload the file with POST when the PDF is on your own system or is not publicly reachable. Pass a URL with GET when the PDF is already on the public web. Some websites block automated downloads, and in that case the GET call fails with an error such as `{"status":"Failure","error":"Bad Request: Response Status is Forbidden"}`. If that happens, download the PDF yourself and upload it with POST.

**How do I know if a conversion failed?**

Check the `status` field. `Success` means `data` holds the page text. `Failure` means the conversion could not be completed and `error` describes why. For the image endpoints, a successful call returns an image or zip file, so if the response has a JSON content type, treat it as a `Failure` and read `error`.

**How do I convert only some pages?**

Set `startPage` and `endPage`. For example `startPage=2&endPage=5` converts pages 2 to 5. Both default to `0`, which means from the first page and to the last page, so leaving them out converts the whole document. Each item in the text response carries its `pageNo`, so you can tell the pages apart.

**What do I get when I convert several pages to an image?**

The provider recommends TIFF (`tif` or `tifflzw`, the default) for multi-page output, since one TIFF file can hold several pages. With PNG or JPEG formats, a single page returns one image, and several pages return a zip file that contains one image per page.

**Which image format should I choose?**

Set `imgFormat` to `png` for PNG pages or `jpeg` (or `jpg`) for JPEG pages, and keep the default `tif` (or `tifflzw`) when you want many pages in one file. The other accepted values, `pnggray`, `png256`, `png16` and `png16m`, are PNG variants. In our test a one-page invoice rendered with `imgFormat=png` was 5,868 bytes. Try the formats on your own documents to compare size and quality.

**Does it read scanned PDFs?**

The text endpoints read the text stored in the PDF. We have tested PDFs that contain real text only, and we have not tested scanned PDFs that contain only images of pages. For those, convert the pages to images and run them through an OCR service.

**How are line breaks returned in the text?**

Lines on a page are separated by `\r\n` inside each `content` string, as in the URL example above. Split on `\r\n` (or on `\n` and trim the `\r`) to get the lines.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


PDF to text API that extracts text page by page from uploaded PDFs or public PDF URLs as JSON, and converts PDF pages to PNG, JPEG or TIFF images.

PDF to Text API: Convert PDF to Text and Images