API 레퍼런스

강력하고 간단한 RESTful API - 몇 줄의 코드로 전문적인 PDF를 전자책으로 변환하는 기능을 구현하세요

API 요청

기본 URL:

https://fusion-api.oomol.com/v1

인증

모든 요청은 Authorization 헤더에 API 키가 필요합니다 (형식: Bearer YOUR_API_KEY)

Authorization: Bearer YOUR_API_KEY

POST/pdf-transform-markdown/submit

PDF to Markdown 작업 제출

PDF 파일 URL을 업로드하고 Markdown 형식으로 변환하는 작업을 제출합니다

요청 매개변수

pdfURL - PDF 파일 클라우드 URL (문자열, 필수, 파일 업로드 API에서 획득)
model - 변환 모델 (문자열, 필수, 고정 값: "gundam")
filename - 확장자를 제외한 출력 파일 이름 (선택 사항), 파일 식별을 용이하게 하는 데 사용됩니다
ignore_pdf_errors - PDF 파싱 오류 무시 (선택 사항, 기본값: true)
ignore_ocr_errors - OCR 오류 무시 (선택 사항, 기본값: true)

요청 예시

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

응답 예시

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

GET/pdf-transform-markdown/result/:taskId

PDF to Markdown 결과 조회

작업 ID로 변환 작업 상태와 결과를 조회합니다

URL 매개변수

taskId - 작업 ID (제출 API에서 반환된 sessionID)

응답 예시 (처리 중)

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

응답 예시 (완료)

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

응답 예시 (실패)

{
  "success": false,
  "state": "failed",
  "progress": 0,
  "error": "변환 실패 사유"
}

POST/pdf-transform-epub/submit

PDF to EPUB 작업 제출

PDF 파일 URL을 업로드하고 EPUB 형식으로 변환하는 작업을 제출합니다

요청 매개변수

pdfURL - PDF 파일 클라우드 URL (문자열, 필수, 파일 업로드 API에서 획득)
model - 변환 모델 (문자열, 필수, 고정 값: "gundam")
filename - 확장자를 제외한 출력 파일 이름 (선택 사항), 파일 식별을 용이하게 하는 데 사용됩니다
ignore_pdf_errors - PDF 파싱 오류 무시 (선택 사항, 기본값: true)
ignore_ocr_errors - OCR 오류 무시 (선택 사항, 기본값: true)

요청 예시

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

응답 예시

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

GET/pdf-transform-epub/result/:taskId

PDF to EPUB 결과 조회

작업 ID로 변환 작업 상태와 결과를 조회합니다

URL 매개변수

taskId - 작업 ID (제출 API에서 반환된 sessionID)

응답 예시 (처리 중)

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

응답 예시 (완료)

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

응답 예시 (실패)

{
  "success": false,
  "state": "failed",
  "progress": 0,
  "error": "변환 실패 사유"
}

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

PDF Craft API와 상호 작용하기 위한 Python SDK입니다. 인증, 작업 제출, 결과 폴링을 처리하여 PDF를 Markdown 또는 EPUB로 변환하는 과정을 간소화합니다.

GitHub에서 보기

설치

pip install pdf-craft-sdk

기본 사용법

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}")

진행률 추적을 통한 로컬 파일 업로드

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
)

원격 PDF 변환

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}")

고급 사용법 (단계별)

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}")

구성 옵션

max_wait_ms: 최대 대기 시간(밀리초) (기본값: 7200000, 즉 2시간)
check_interval_ms: 초기 폴링 간격(밀리초) (기본값: 1000)
max_check_interval_ms: 최대 폴링 간격(밀리초) (기본값: 5000)
backoff_factor: 간격 증가를 위한 배수 또는 PollingStrategy enum 사용 (기본값: PollingStrategy.EXPONENTIAL / 1.5)
model: 변환에 사용할 모델 (기본값: '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

PDF Craft API와 상호 작용하기 위한 TypeScript SDK입니다. 인증, 작업 제출, 결과 폴링을 처리하여 PDF를 Markdown 또는 EPUB로 변환하는 과정을 간소화합니다.

GitHub에서 보기

설치

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

기본 사용법

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();

진행률 추적을 통한 로컬 파일 업로드

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
});

일괄 처리

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}`);

고급 사용법 (단계별)

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}`);

구성 옵션

formatType: FormatType.Markdown | FormatType.EPUB (기본값: FormatType.Markdown)
model: 사용할 모델 (기본값: 'gundam')
wait: 완료를 기다릴지 여부 (기본값: true)
maxWaitMs: 최대 대기 시간(밀리초) (기본값: 7200000, 즉 2시간)
checkIntervalMs: 초기 폴링 간격(밀리초) (기본값: 1000)
maxCheckIntervalMs: 최대 폴링 간격(밀리초) (기본값: 5000)
backoffFactor: 간격 증가 배수 또는 PollingStrategy enum 사용 (기본값: 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
});