How to Use the PDF.ai Split API

What Split is for

• You sent a split_description JSON array (each item has a name, optional description) plus a file, a url, or a reusable docId

• The response includes result.splits (each with name, pages, and conf) and a docId

• You know the credit mix: Split is always 2 credits × page count, and Parse credits apply only when you did not pass a cached docId

Practical rule: Split answers "which pages belong to these named sections?" Parse answers "turn this PDF into text I can reuse." Extract answers "give me these fields." Ask answers a free-form question. Use Split when the next step needs section boundaries, not a full-file answer.

Browser split tool vs Split API

Credits before you scale page count

• Split credits: always 2 credits × page count

• Parse credits: charged when you send a file or url (see Parse); 0 parse credits when you pass a cached docId

• Optional parse quality when you upload: standard (default) or advanced; lang_list defaults to ["en"]

• Total: Parse credits + Split credits

• 10-page PDF, cached docId → parse 0 + split 20 = 20 credits

• 5-page PDF, not cached, advanced quality → parse 10 + split 10 = 20 credits

• 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

Practical rule: Parse once, keep the docId, then Split (and Extract / Ask) against that cache so you are not paying parse credits on every section probe.

How to call Split

1. Have an API key

2. Prefer a cached docId

3. POST with split_description

• split_description — JSON array; each object needs a name, and may include a description

• docId — reuse a previously parsed document

• url — public URL of the PDF

• file — upload the PDF

• quality: standard (default) or advanced (applies when parsing is part of this call)

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

import requests
import json

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

split_description = [
    {"name": "Introduction", "description": "Opening section"},
    {"name": "Conclusion", "description": "Summary section"}
]

data = {
    "docId": "your-document-id",
    "split_description": json.dumps(split_description)
}

response = requests.post(url, headers=headers, data=data)
print(response.json())

4. Check the output before you trust it

• Confirm success, a non-empty result.splits array, and a docId

• Spot-check one section's pages against the source PDF

• Treat conf as a routing signal: low-confidence ranges need a human look or a clearer description

• If you get Invalid API key / No API key present, fix the header before you rewrite section names

• If a section returns empty pages, tighten the description or confirm the section exists in that file

Practical rule: page ranges are not extracted fields. If you need named JSON fields from those pages, call Extract next with the same docId and a schema.

When Split is the wrong tool

• You only need to cut one PDF into smaller files in a browser. Use Split PDF. No API key required for that job.

• You need searchable markdown / contents first. Use POST https://pdf.ai/api/v2/parse (How to Use the PDF.ai Parse API), then pass the docId into Split.

• 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 first.

• You need a free-form answer in code. Use POST https://pdf.ai/api/v2/ask (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 Split how-to, not a replacement hub.

A short action plan

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

2. Check credit usage against page count (2 × pages for Split, plus Parse if uncached).

3. Prefer POST https://pdf.ai/api/v2/parse on a short PDF, save the docId, then POST https://pdf.ai/api/v2/split with a clear split_description.

4. Spot-check result.splits[].pages and conf against the source PDF, then call Extract or Ask with that docId if the next step needs fields or answers.