Document Conversion¶

Convert documents between PDF, DOCX, EPUB, HTML, DOC, RTF, ODT, and TXT, and render PDF pages to images. Two endpoints cover the streaming download workflow (URL source) plus the format-specific POST endpoints for inline base64 files.

Base URL¶

https://convert.toolkitapi.io

Endpoints¶

Method	Endpoint	Purpose
GET	/v1/convert/document	Convert a URL document → streamed file download
GET	/v1/convert/document (PDF→images)	Render PDF pages → JSON list of Base64 images

Authentication is via the X-API-Key header (or Authorization: Bearer).

Supported pairs¶

Source	Targets
pdf	docx, epub, png, jpeg
docx	pdf
epub	pdf
html	pdf
doc, rtf, odt, txt	pdf, docx (LibreOffice sidecar)

For inline Base64 files (no URL), use the format-specific endpoints: POST /v1/convert/docx-to-pdf, POST /v1/convert/pdf-to-docx, POST /v1/convert/epub-to-pdf, POST /v1/convert/pdf-to-epub, POST /v1/convert/html-to-pdf, POST /v1/convert/pdf-to-images.

---

GET /v1/convert/document¶

Fetch a document from a public URL, convert it, and stream the result back.

Query parameters¶

Parameter	Type	Required	Description
url	string	yes	Public URL of the source document
from_format	string	yes	Source format (e.g. docx)
to_format	string	yes	Target format (e.g. pdf)
pages	string	no	Page selection for PDF conversions (e.g. 1-3,5)
dpi	integer 72–600	no	DPI for PDF→image (default 150)
page_size	string	no	Page size for HTML→PDF (default A4)
title	string	no	EPUB title
author	string	no	EPUB author
filename	string ≤ 255	no	Download filename

Response¶

200 OK. For single-document outputs, the converted file bytes are returned with the matching Content-Type and a Content-Disposition: attachment header. For PDF→images, a JSON body containing a list of Base64 images is returned instead.

Example — DOCX → PDF (curl)¶

curl -L "https://convert.toolkitapi.io/v1/convert/document?url=https://example.com/report.docx&from_format=docx&to_format=pdf&filename=report.pdf" \
  -H "X-API-Key: $CONVERT_API_KEY" \
  -o report.pdf

Example — PDF → PNG pages (Python)¶

import base64
from pathlib import Path

import httpx

resp = httpx.get(
    "https://convert.toolkitapi.io/v1/convert/document",
    headers={"X-API-Key": CONVERT_API_KEY},
    params={
        "url": "https://example.com/slides.pdf",
        "from_format": "pdf",
        "to_format": "png",
        "pages": "1-3",
        "dpi": 150,
    },
)
resp.raise_for_status()
payload = resp.json()

for i, page in enumerate(payload.get("pages", []), start=1):
    Path(f"slide_{i}.png").write_bytes(base64.b64decode(page["image"]))

Example — HTML → PDF (JavaScript)¶

const url = new URL("https://convert.toolkitapi.io/v1/convert/document");
url.searchParams.set("from_format", "html");
url.searchParams.set("to_format", "pdf");
url.searchParams.set("page_size", "A4");

const resp = await fetch(url, { headers: { "X-API-Key": process.env.CONVERT_API_KEY } });
const pdf = Buffer.from(await resp.arrayBuffer());
await import("node:fs/promises").then(fs => fs.writeFile("page.pdf", pdf));

Example — EPUB → PDF with metadata¶

curl -L "https://convert.toolkitapi.io/v1/convert/document?url=https://example.com/book.epub&from_format=epub&to_format=pdf&title=My%20Book&author=Jane%20Doe" \
  -H "X-API-Key: $CONVERT_API_KEY" \
  -o book.pdf

Example — proxy pattern (hide the API key)¶

# Flask example
import httpx
from flask import Response, request

@app.get("/docs/convert")
def convert_document():
    upstream = httpx.get(
        "https://convert.toolkitapi.io/v1/convert/document",
        headers={"X-API-Key": CONVERT_API_KEY},
        params=request.args,
    )
    return Response(
        upstream.content,
        mimetype=upstream.headers.get("Content-Type", "application/octet-stream"),
        headers={"Content-Disposition": upstream.headers.get("Content-Disposition", "attachment")},
    )

---

Notes¶

• Maximum file size: 20 MB for PDF/DOCX/EPUB inputs (enforced with 413); the general document pipeline caps at 50 MB.
• Signatures are validated — PDFs must start with %PDF, DOCX/EPUB with PK.
• LibreOffice sidecar: DOC/RTF/ODT/TXT conversions depend on the sidecar; if it's unavailable the API returns 502.
• Prefer the POST format-specific endpoints when the file is already in memory (Base64). When storage (MinIO) is enabled, responses include a presigned file_url instead of inline Base64.

---

Errors¶

Status	Meaning
400	Invalid source content or unhandled conversion pair
401	Missing or invalid API key
413	Source document exceeds the maximum size
422	Validation error (e.g. empty HTML)
500	Conversion engine unavailable
502	LibreOffice sidecar failure

See Error Handling for the shared error envelope.