EPUB Parsing API

Books as Structured Data

An .epub file is a zip archive that hides a small filesystem inside it: META-INF/container.xml points to a .opf manifest, the OPF lists every resource and a spine defining the canonical reading order, and the actual content lives as XHTML files — one per chapter, sometimes more. Embedded images, fonts, and CSS sit alongside.

Most ebook tooling treats EPUB as a black box: convert to PDF, render to text, lose chapter boundaries, lose metadata, lose image references. AILANG Parse walks the EPUB structure directly — container → OPF → spine → XHTML — and emits each chapter as a SectionBlock in spine order.

Raw EPUB Structure vs Structured Output

<!-- 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>

{
  "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

Spine & Reading Order

EPUB chapter files do not have to be ordered by filename — the OPF spine is the only authoritative source of reading order. AILANG Parse follows the spine, so chapters always come out in the order the author intended, even if the underlying files are named x4j2-zb.xhtml.

Each chapter is its own SectionBlock, which means downstream code can chunk by chapter, embed by chapter, or render a table of contents from headings without flattening the book first.

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

Try It

Workbench (in-browser)

Drop an EPUB file into the Workbench — parsing runs in WebAssembly with the same AILANG parser used by the CLI. No upload, no signup.

CLI

# Parse an EPUB file
./bin/docparse book.epub

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

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

API

curl -X POST https://docparse.ailang.sunholo.com/api/v1/parse \
  -H "Content-Type: application/json" \
  -d '{"filepath":"book.epub","outputFormat":"json","apiKey":"YOUR_API_KEY"}'

Parse in Browser    API Reference