Skip to main content
PDF Craft

API Reference

Powerful, simple RESTful API - implement professional PDF to eBook conversion in just a few lines of code

API Requests

Base URL:
https://fusion-api.oomol.com/v1
POST/pdf-transform-markdown/submit

Submit PDF to Markdown Task

Upload PDF file URL and submit task to convert to Markdown format

Request Parameters

  • pdfURL - PDF file cloud URL (string, required, obtained from file upload API)
  • model - Conversion model (string, required, fixed value: "gundam")
  • filename - Output file name without extension (optional), used for easier file recognition
  • ignore_pdf_errors - Ignore PDF parsing errors (optional, default: true)
  • ignore_ocr_errors - Ignore OCR errors (optional, default: true)

Request Example

{
  "pdfURL": "https://pdfcraft.ai/examples/api-quickstart.pdf",
  "model": "gundam",
  "filename": "my-document",
  "ignore_pdf_errors": true,
  "ignore_ocr_errors": true
}

Response Example

{
  "success": true,
  "sessionID": "019aa097-f28d-7000-8d56-6a2987a7b144"
}
GET/pdf-transform-markdown/result/:taskId

Query PDF to Markdown Result

Query conversion task status and result by task ID

URL Parameters

  • taskId - Task ID (sessionID returned from submit API)

Response Example (Processing)

{
  "success": true,
  "state": "processing",
  "progress": 66
}

Response Example (Completed)

{
  "success": true,
  "state": "completed",
  "progress": 100,
  "data": {
    "downloadURL": "https://cdn.oomol.com/result.md"
  }
}

Response Example (Failed)

{
  "success": false,
  "state": "failed",
  "progress": 0,
  "error": "Conversion failure reason"
}
POST/pdf-transform-epub/submit

Submit PDF to EPUB Task

Upload PDF file URL and submit task to convert to EPUB format

Request Parameters

  • pdfURL - PDF file cloud URL (string, required, obtained from file upload API)
  • model - Conversion model (string, required, fixed value: "gundam")
  • filename - Output file name without extension (optional), used for easier file recognition
  • ignore_pdf_errors - Ignore PDF parsing errors (optional, default: true)
  • ignore_ocr_errors - Ignore OCR errors (optional, default: true)

Request Example

{
  "pdfURL": "https://pdfcraft.ai/examples/api-quickstart.pdf",
  "model": "gundam",
  "filename": "my-document",
  "ignore_pdf_errors": true,
  "ignore_ocr_errors": true
}

Response Example

{
  "success": true,
  "sessionID": "019aa097-f28d-7000-8d56-6a2987a7b144"
}
GET/pdf-transform-epub/result/:taskId

Query PDF to EPUB Result

Query conversion task status and result by task ID

URL Parameters

  • taskId - Task ID (sessionID returned from submit API)

Response Example (Processing)

{
  "success": true,
  "state": "processing",
  "progress": 66
}

Response Example (Completed)

{
  "success": true,
  "state": "completed",
  "progress": 100,
  "data": {
    "downloadURL": "https://cdn.oomol.com/result.epub"
  }
}

Response Example (Failed)

{
  "success": false,
  "state": "failed",
  "progress": 0,
  "error": "Conversion failure reason"
}

cURL

# 1. Submit PDF to Markdown task
curl -X POST https://fusion-api.oomol.com/v1/pdf-transform-markdown/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "pdfURL": "https://pdfcraft.ai/examples/api-quickstart.pdf",
    "model": "gundam",
    "filename": "my-document"
  }'


# Response: {"success": true, "sessionID": "019aa097-f28d-7000-8d56-6a2987a7b144"}


# 2. Query conversion result
curl -X GET https://fusion-api.oomol.com/v1/pdf-transform-markdown/result/019aa097-f28d-7000-8d56-6a2987a7b144 \
  -H "Authorization: Bearer YOUR_API_KEY"


# Response: {"success": true, "state": "completed", "data": {"downloadURL": "https://cdn.oomol.com/result.md"}}

Python SDK

A Python SDK for interacting with the PDF Craft API. It simplifies the process of converting PDFs to Markdown or EPUB by handling authentication, task submission, and result polling.

View on GitHub

Installation

pip install pdf-craft-sdk

Basic Usage

from pdf_craft_sdk import PDFCraftClient


# Initialize the client
client = PDFCraftClient(api_key="YOUR_API_KEY")


# Convert a local PDF to Markdown
try:
    download_url = client.convert_local_pdf("document.pdf")
    print(f"Conversion successful! Download URL: {download_url}")
except Exception as e:
    print(f"An error occurred: {e}")

Local File Upload with Progress Tracking

from pdf_craft_sdk import PDFCraftClient, UploadProgress


def on_progress(progress: UploadProgress):
    print(f"Upload: {progress.percentage:.2f}% - Part {progress.current_part}/{progress.total_parts}")


client = PDFCraftClient(api_key="YOUR_API_KEY")


# Upload local file with progress tracking
download_url = client.convert_local_pdf(
    "large_document.pdf",
    progress_callback=on_progress
)

Remote PDF Conversion

from pdf_craft_sdk import PDFCraftClient, FormatType


client = PDFCraftClient(api_key="YOUR_API_KEY")


# Convert remote PDF to EPUB
download_url = client.convert(
    pdf_url="https://example.com/file.pdf",
    format_type=FormatType.EPUB,
    includes_footnotes=True
)
print(f"Download URL: {download_url}")

Advanced Usage (Step-by-Step)

from pdf_craft_sdk import PDFCraftClient, FormatType


client = PDFCraftClient(api_key="YOUR_API_KEY")


# Step 1: Upload file
cache_url = client.upload_file("document.pdf")


# Step 2: Submit conversion task
task_id = client.submit_conversion(
    cache_url,
    format_type=FormatType.MARKDOWN
)
print(f"Task submitted. ID: {task_id}")


# Step 3: Wait for completion
download_url = client.wait_for_completion(task_id)
print(f"Download URL: {download_url}")

Configuration Options

  • max_wait_ms: Maximum wait time in milliseconds (default: 7200000, i.e., 2 hours)
  • check_interval_ms: Initial polling interval in milliseconds (default: 1000)
  • max_check_interval_ms: Maximum polling interval in milliseconds (default: 5000)
  • backoff_factor: Multiplier for increasing interval, or use PollingStrategy enum (default: PollingStrategy.EXPONENTIAL / 1.5)
  • model: The model to use for conversion (default: 'gundam')
from pdf_craft_sdk import PDFCraftClient, FormatType, PollingStrategy


client = PDFCraftClient(api_key="YOUR_API_KEY")


# Example with custom polling configuration
download_url = client.convert(
    pdf_url="https://example.com/file.pdf",
    format_type=FormatType.MARKDOWN,
    model="gundam",
    includes_footnotes=True,
    ignore_pdf_errors=True,
    ignore_ocr_errors=True,
    max_wait_ms=600000,           # Maximum wait time: 10 minutes
    check_interval_ms=2000,       # Initial polling interval: 2 seconds
    max_check_interval_ms=10000,  # Maximum polling interval: 10 seconds
    backoff_factor=PollingStrategy.EXPONENTIAL  # or 1.5
)

TypeScript SDK

A TypeScript SDK for interacting with the PDF Craft API. It simplifies the process of converting PDFs to Markdown or EPUB by handling authentication, task submission, and result polling.

View on GitHub

Installation

npm install pdf-craft-sdk-ts
# or
yarn add pdf-craft-sdk-ts

Basic Usage

import { PDFCraftClient, FormatType } from 'pdf-craft-sdk-ts';


const client = new PDFCraftClient("YOUR_API_KEY");


async function main() {
    try {
        const downloadUrl = await client.convert("cache://your-pdf-file.pdf", {
            formatType: FormatType.Markdown
        });
        console.log(`Success! Download: ${downloadUrl}`);
    } catch (error) {
        console.error("Error:", error);
    }
}


main();

Local File Upload with Progress Tracking

import { PDFCraftClient, FormatType, UploadProgress } from 'pdf-craft-sdk-ts';


const client = new PDFCraftClient("YOUR_API_KEY");


const onProgress = (progress: UploadProgress) => {
    console.log(`Progress: ${progress.percentage.toFixed(2)}%`);
    console.log(`Part ${progress.currentPart}/${progress.totalParts}`);
};


// Upload and convert local file
const downloadUrl = await client.convertLocalPdf("document.pdf", {
    formatType: FormatType.Markdown,
    progressCallback: onProgress,
    includesFootnotes: true,
    uploadMaxRetries: 5
});

Batch Processing

import { PDFCraftClient, FormatType } from 'pdf-craft-sdk-ts';


const client = new PDFCraftClient("YOUR_API_KEY");


// Create batch conversion
const files = [
    { url: "cache://file1.pdf", fileName: "document1.pdf" },
    { url: "cache://file2.pdf", fileName: "document2.pdf" }
];


const batch = await client.createBatch(files, FormatType.Markdown, false);
const result = await client.startBatch(batch.batchId);


// Monitor progress
const status = await client.getBatchStatus(batch.batchId);
console.log(`Completed: ${status.completedCount}/${status.totalCount}`);

Advanced Usage (Step-by-Step)

import { PDFCraftClient, FormatType } from 'pdf-craft-sdk-ts';


const client = new PDFCraftClient("YOUR_API_KEY");


// Step 1: Submit task
const taskId = await client.submitConversion(
    "cache://file.pdf",
    FormatType.Markdown
);
console.log(`Task submitted. ID: ${taskId}`);


// Step 2: Poll for completion
const downloadUrl = await client.waitForCompletion(
    taskId,
    FormatType.Markdown
);
console.log(`Download URL: ${downloadUrl}`);

Configuration Options

  • formatType: FormatType.Markdown | FormatType.EPUB (default: FormatType.Markdown)
  • model: Model to use (default: 'gundam')
  • wait: Whether to wait for completion (default: true)
  • maxWaitMs: Maximum wait time in milliseconds (default: 7200000, i.e., 2 hours)
  • checkIntervalMs: Initial polling interval in milliseconds (default: 1000)
  • maxCheckIntervalMs: Maximum polling interval in milliseconds (default: 5000)
  • backoffFactor: Multiplier for increasing interval, or use PollingStrategy enum (default: PollingStrategy.Exponential / 1.5)
import { PDFCraftClient, FormatType, PollingStrategy } from 'pdf-craft-sdk-ts';


const client = new PDFCraftClient("YOUR_API_KEY");


// Example with custom polling configuration
const downloadUrl = await client.convert("cache://file.pdf", {
    formatType: FormatType.Markdown,
    model: "gundam",
    wait: true,
    includesFootnotes: true,
    ignorePdfErrors: true,
    ignoreOcrErrors: true,
    maxWaitMs: 600000,           // Maximum wait time: 10 minutes
    checkIntervalMs: 2000,       // Initial polling interval: 2 seconds
    maxCheckIntervalMs: 10000,   // Maximum polling interval: 10 seconds
    backoffFactor: PollingStrategy.Exponential  // or use a number like 1.5
});