EPUB Parsing API

Parse EPUB ebooks to structured JSON. Chapters in reading order, book metadata and embedded images are kept, chapter by chapter. The .epub file is read directly, with no Calibre install and no conversion to PDF.

Books as Structured Data

An .epub file is a zip archive holding a small set of files. META-INF/container.xml points to an .opf file (the OPF, the book's manifest). The OPF lists every file in the book and has a spine that sets the reading order. The content itself is XHTML, usually one file per chapter. Images, fonts and CSS sit alongside.

Many ebook tools convert an EPUB to PDF or plain text, which loses chapter boundaries, metadata and image references. AILANG Parse follows the EPUB's own structure (container → OPF → spine → XHTML) and returns each chapter as a section block, in reading order.

EPUB chapters and HTML pages come out in the same block format, so one piece of code handles both.

Raw EPUB Structure vs Structured Output

Raw OPF + chapter XHTML
<!-- content.opf -->
<package version="3.0">
 <metadata>
  <dc:title>A Tale of Two Cities</dc:title>
  <dc:creator>Charles Dickens</dc:creator>
  <dc:language>en</dc:language>
 </metadata>
 <manifest>
  <item id="ch1" href="ch1.xhtml"
        media-type="application/xhtml+xml"/>
  <item id="ch2" href="ch2.xhtml"
        media-type="application/xhtml+xml"/>
 </manifest>
 <spine>
  <itemref idref="ch1"/>
  <itemref idref="ch2"/>
 </spine>
</package>

<!-- ch1.xhtml -->
<h1>Book the First</h1>
<p>It was the best of times,
   it was the worst of times...</p>
Structured output
{
  "metadata": {
    "title": "A Tale of Two Cities",
    "author": "Charles Dickens",
    "language": "en"
  },
  "blocks": [
    {
      "type": "section",
      "kind": "chapter:ch1.xhtml",
      "blocks": [
        {
          "type": "heading",
          "level": 1,
          "text": "Book the First"
        },
        {
          "type": "text",
          "text": "It was the best of times, it was the worst of times..."
        }
      ]
    },
    {
      "type": "section",
      "kind": "chapter:ch2.xhtml",
      "blocks": [ ... ]
    }
  ]
}

What Gets Extracted

Chapters in Reading Order

The OPF spine sets the reading order. Each spine item becomes a section block with kind: "chapter:<href>", in the order an ebook reader would show them.

OPF Metadata

The standard (Dublin Core) fields from the OPF: dc:title, dc:creator, dc:language, dc:identifier (often the ISBN), dc:date, dc:publisher. Use them to index, search or export a library.

Headings, Paragraphs, Lists

Each chapter is parsed the same way as a standalone HTML file. Headings (h1–h6), paragraphs, ordered and unordered lists, blockquotes and inline emphasis become typed blocks.

Tables & Code Blocks

Reference works, technical books and cookbooks often contain tables and <pre><code> blocks. Both are kept as tables and code blocks, not flattened to text.

Embedded Images

Each image reference (<img src="...">) becomes an image block with its path inside the EPUB. Useful for pulling out covers or captioning figures.

No Calibre, No PDF Step

Nothing else to install: no calibre, no ebook-convert, no PDF step in between. The same parser runs in the CLI and in the browser.

Spine & Reading Order

EPUB chapter files are not necessarily in filename order. Only the OPF spine gives the reading order. AILANG Parse follows the spine, so chapters come out in the order the author intended, even if the files have names like x4j2-zb.xhtml.

Each chapter is its own section block, so your code can split or embed the book by chapter, or build a table of contents from the headings.

from ailang_parse import DocParse

result = DocParse(api_key="...").parse_file("book.epub")

print(result.metadata.title, "by", result.metadata.author)

for chapter in result.blocks:
    if chapter.type != "section":
        continue
    print("---", chapter.kind, "---")
    for block in chapter.blocks:
        if block.type == "heading":
            print("H" + str(block.level), block.text)

Use Cases

Project Gutenberg & Public Domain

Process tens of thousands of EPUBs from Project Gutenberg, Standard Ebooks or the Internet Archive with one parser and one output format, with no special handling per source.

Ebook RAG & Semantic Search

Each chapter can be retrieved as one chunk. Embed by chapter or by heading, not by an arbitrary 512-token window that cuts a sentence in two.

Accessibility Tooling

Generate audio versions, large-print exports or simplified-language editions. Chapter boundaries and headings carry over to the output.

Format Migration

Convert EPUB to Markdown, HTML or DOCX while keeping chapter structure, headings, lists and image references. See HTML parsing for the inverse direction.

Browser-Based Library Tools

Drop an EPUB into the Workbench. It is parsed in your browser tab and never leaves your device. Useful for organising a personal library without uploading purchased books.

Citation & Quote Extraction

Go through the chapters to extract every quotation, blockquote or section heading for citation databases, study guides or literary analysis.

Try It

Workbench (in-browser)

Drop an EPUB file into the Workbench. It is parsed in your browser by the same parser the CLI uses. No upload, no signup.

CLI

# Parse an EPUB file
docparse book.epub

# Convert EPUB to Markdown
docparse book.epub --convert book.md

# Convert EPUB to HTML
docparse book.epub --convert book.html

API

curl -X POST https://docparse.ailang.sunholo.com/api/v1/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "filepath=@book.epub" \
  -F "outputFormat=blocks"

Parse in Browser    API Reference

Frequently Asked Questions

How do I parse an EPUB file to JSON?

Drop it into the Workbench, send it to the API, or use the Python/JS/Go/R SDK. The parser reads META-INF/container.xml to find the OPF, follows its spine, and parses each XHTML chapter directly, with no Calibre install and no conversion to PDF.

Are chapters parsed in reading order?

Yes. The OPF spine sets the reading order. AILANG Parse follows it and returns each chapter as a section block in that order, whatever the files are called.

Does EPUB parsing need Calibre or any external tool?

No. The container file, the OPF and the chapter XHTML are all read directly from the .epub file. Nothing else needs to be installed.

What metadata is extracted from EPUB?

Dublin Core fields from the OPF: dc:title, dc:creator, dc:language, dc:identifier (ISBN), dc:date, dc:publisher.

Does EPUB parsing run in the browser?

Yes. The file is parsed in your browser tab (using WebAssembly) by the same parser the CLI uses. It never leaves your device.