How to Use the PDF.ai Parse API

Publish date

Sep 19, 2026

AI summary

The Parse API converts PDFs into reusable markdown, structured contents, and a docId, supporting standard (1 credit per page) or advanced (2 credits per page) quality, optional LLM image processing, and caching that costs zero credits; it’s the first step for downstream Extract or Ask calls, requiring an API key, and includes guidance on usage, credits, and best‑practice workflow.

Language

People look up a Parse API when a PDF is not ready for chat or field extraction yet. They need searchable markdown, page contents, and a docId they can reuse on later Extract, Split, or Ask calls.

This page is the PDF → markdown / contents path on the PDF.ai API v2 Parse endpoint. It does not replace the API Hub (keys and plan live there). It does not re-rank the head term pdf api. For the first-request path (key + first call), see How to Get Started with the PDF.ai API. For the browser parse job (not code), see Parse PDF: Turn a Document into Structured Data.

What Parse is for

After a clean Parse call on PDF.ai API v2, three things should be true:

You sent a file, a url, or a reusable docId

The response includes markdown, contents (with page numbers and bounding boxes), pageCount, and a docId

You know whether credits applied (new parse) or the result was served from cache (0 credits)

Docs: Parse.

Practical rule: Parse answers "turn this PDF into text I can reuse." Extract answers "give me these fields." Ask answers a free-form question. Use Parse first when your next step is RAG, markdown storage, or a cached docId for Extract / Split / Ask.

Browser parse vs Parse API

Path	Best when	What you get
Web parse / product UI	One file, no code	Readable output in the browser
API `POST /v2/parse`	Automation, your product, batches	JSON (`markdown` · `contents` · `docId`) with an `X-API-Key`

Credits before you scale quality

From the live Parse and credit usage docs:

standard quality: 1 credit × page count (supports lang_list for OCR)

advanced quality: 2 credits × page count (Vision Language Model path; no language list required)

Optional LLM on images: +1 credit per 5 images (rounded up) when llm=true

Cached results for the same docId and settings: 0 credits

Examples from the Parse docs:

10-page PDF, standard, no LLM → 10 credits

10-page PDF, advanced, no LLM → 20 credits

10-page PDF, standard, LLM on, 12 images → base 10 + LLM 3 = 13 credits

Any cached result → 0 credits

API plan examples on credit usage:

Free: $0/month for 200 credits/month, no credit card required

Paid examples: $49 / 3,000, $99 / 10,000, $249 / 30,000, $599 / 100,000 credits per month

Generate the key and manage the plan on https://pdf.ai/developer. The docs say the key is shown only once when generated.

Practical rule: prove the pipeline on standard first. Switch to advanced only when standard OCR misses layout you care about.

How to call Parse

1. Have an API key

Open https://pdf.ai/developer, generate a key, store it as a secret. Send it as the X-API-Key header on every call.

2. POST the PDF

Endpoint from the docs: POST https://pdf.ai/api/v2/parse

Content type: multipart/form-data.

Provide one of:

file — upload the PDF

url — public URL of the PDF

docId — reuse a previously parsed document (cached responses cost 0 credits when settings match)

Optional (from Parse):

quality: standard (default) or advanced

lang_list: languages for standard OCR (default ["en"])

llm: enable LLM processing for images (default false)

Example shape (Python), matching the docs sample:

import requests

url = "https://pdf.ai/api/v2/parse"
headers = {"X-API-Key": "YOUR_API_KEY"}

with open("/path/to/document.pdf", "rb") as f:
    files = {"file": f}
    data = {
        "quality": "standard",
        "lang_list": '["en"]'
    }
    response = requests.post(url, headers=headers, files=files, data=data)

print(response.json())

A successful response includes success, markdown, contents (each item can include bbox, content, pageNumber, and optional image fields), pageCount, and docId.

3. Keep the `docId` for the next call

The docs note that using a docId caches parse results for later calls with the same settings. That cache also lets later /extract and /split calls skip parse credits when they reuse the same docId.

Store docId next to the source file id in your system. Re-parse only when the file or quality settings change.

4. Check the output before you trust it

Confirm success, a non-empty markdown (or contents), and a docId

Spot-check one contents[].pageNumber against the source PDF

If you get Invalid API key / No API key present, fix the header before you change quality

If scanned pages look empty on standard, retry with quality=advanced or confirm lang_list matches the document language

Practical rule: a long markdown string is not a verified extract. If you need named fields, call Extract next with this docId and a schema.

When Parse is the wrong tool

You only need one chat answer in a browser. Use How to Chat with a PDF. No API key required for that job.

You need named fields as JSON. Use POST https://pdf.ai/api/v2/extract with a schema (How to Use the PDF.ai Extract API). Prefer a cached docId from Parse first.

You need a free-form answer in code. Use POST https://pdf.ai/api/v2/ask with a prior docId (How to Use the PDF.ai Ask API). Ask is 3 credits × total page count across the docIds you query, and the document must be parsed first.

You wanted a generic “pdf api” category hub. Stay on https://pdf.ai/developer. This page is the Parse how-to, not a replacement hub.

A short action plan

Open https://pdf.ai/developer, create a key, store it once.

Check credit usage against page count and quality (standard vs advanced).

POST https://pdf.ai/api/v2/parse on a short PDF; save the docId.

Spot-check markdown / contents against the source PDF, then call Extract or Ask with that docId if the next step needs fields or answers.

Sibling guides: How to Get Started with the PDF.ai API, How to Use the PDF.ai Extract API, How to Use the PDF.ai Ask API, PDF OCR API: Run OCR from Your Code, How to Parse a PDF.

If you want the rest of the PDF workflow after the text is clean, start at PDF.ai. Use the Parse API when the next step is your pipeline, not a single upload box.