Osadzanie obrazów jako dokumentów w plikach PDF na stronach A4

Zdjęcia lub małe dokumenty często muszą być umieszczone na stronie standardowej – A4, Letter lub w niestandardowym rozmiarze – wycentrowane i poprawnie przeskalowane. Reportlab lub podobne narzędzia mogą to osiągnąć, ale wymagają matematyki layoutu i obsługi formatów. API do umieszczania obrazów na pustych stronach, które osadza zawartość na konfigurowalnej stronie, uprościłoby ten proces.

Dlaczego stworzenie własnego rozwiązania do umieszczania obrazów na pustych stronach trwa tygodnie

Kto chce zbudować to samodzielnie, szybko odkrywa, że musi obliczyć skalowanie, aby dopasować zawartość do strony, wycentrować ją i uwzględnić różne proporcje. Reportlab, PyMuPDF lub PIL mogą to zrobić – ale trzeba zarządzać DPI, marginesami i systemami współrzędnych. Dla plików PDF: najpierw wyrenderować każdą stronę do obrazu, a następnie osadzić. Zbudowanie solidnego API do osadzania obrazów na stronach wymaga logiki layoutu i testów.

Jak API MaraDocs do umieszczania obrazów na pustych stronach rozwiązuje to w kilka minut

API MaraDocs obsługuje embed_in_blank_page w img.toPdf i img.ocrToPdf. Określ rozmiar strony (np. 210×297 mm dla A4, lub Letter, lub rozmiar niestandardowy) i pozycję (np. środek). API zajmuje się skalowaniem, proporcjami i marginesami. Dla plików PDF: wyrenderuj do obrazów za pomocą pdf.toImg, następnie użyj img.toPdf z embed_in_blank_page. Bez matematyki layoutu, bez konwersji DPI, bez obsługi formatów po Twojej stronie. Jedno lub dwa wywołania API i otrzymujesz poprawnie sformatowany PDF.

Workflow: Walidacja, osadzanie, pobieranie

Dla obrazów: waliduj, następnie img.toPdf z options.embed_in_blank_page – określ rozmiar strony (np. 210×297 mm dla A4) i pozycję (np. środek). Dla plików PDF: waliduj, użyj pdf.toImg do wyrenderowania stron jako obrazów, następnie img.toPdf z opcjami osadzania. Wynikiem jest uchwyt PDF, który można pobrać lub przekazać do OCR, kompozycji lub optymalizacji. API zajmuje się skalowaniem, centrowaniem i konwersją formatów; matematyka layoutu i systemy współrzędnych odpadają.

Co wyróżnia MaraDocs: Workspace, Webview i niemieckie prawo o ochronie danych

Większość API do dokumentów wymusza przesyłanie, przetwarzanie, pobieranie i ponowne przesyłanie dla następnego kroku. W MaraDocs pliki pozostają w workspace. Łącz z OCR, kompozycją lub kompresją – uchwyt PDF przepływa bezpośrednio do następnej operacji. Bez ponownego przesyłania, mniej transferów.

Gdy layout lub skalowanie wymaga ręcznej korekty – marginesy, pozycjonowanie lub rozmiar strony – można otworzyć app.maradocs.io do ręcznej weryfikacji i dostosowania. Użytkownicy otrzymują pełną kontrolę ręczną, gdy automatyzacja osiąga swoje granice.

Całe przetwarzanie odbywa się w Niemczech (Maramia GmbH), zaszyfrowane w spoczynku i podczas transmisji. Workspace wygasa po 7 dniach. Żadne dane nie opuszczają UE. Dla procesów dokumentowych wrażliwych na ochronę danych jest to istotne.

Kod TypeScript do osadzania obrazów na stronach PDF

Dokumentacja API: data/upload, img/validate, img/to/pdf, pdf/to/img, pdf/validate, data/download/pdf

import { MaraDocsClient } from "@maramia/maradocs-sdk-ts";
import { okImg } from "@maramia/maradocs-sdk-ts/models/img";
import { okPdf } from "@maramia/maradocs-sdk-ts/models/pdf";

const client = new MaraDocsClient({ workspaceSecret: workspace_secret });

// Obraz: prześlij, waliduj, osadź na A4, pobierz
const upImg = await client.data.upload(imageFile);
const valImg = await client.img.validate({ unvalidated_file_handle: upImg.unvalidated_file_handle });
const imgHandle = okImg(valImg);

const pdf = await client.img.toPdf({
  img_handle: imgHandle,
  options: {
    embed_in_blank_page: { size: { width: 210, height: 297 }, position: "center" },
  },
});
const blob = await client.data.downloadPdf({ pdf_handle: pdf.pdf_handle });

// PDF: prześlij, waliduj, wyrenderuj stronę jako obraz, osadź, pobierz
const upPdf = await client.data.upload(pdfFile);
const valPdf = await client.pdf.validate({ unvalidated_file_handle: upPdf.unvalidated_file_handle });
const imgResult = await client.pdf.toImg({
  pdf_handle: okPdf(valPdf),
  pages: [0],
});
const pdfPage = await client.img.toPdf({
  img_handle: imgResult.img_handles[0],
  options: { embed_in_blank_page: { size: { width: 210, height: 297 }, position: "center" } },
});
const blob2 = await client.data.downloadPdf({ pdf_handle: pdfPage.pdf_handle });

Kod Python do osadzania obrazów na stronach PDF

Dokumentacja API: data/upload, img/validate, img/to/pdf, data/download/pdf

# pip install python-decouple requests
"""Convert an image to a PDF on A4 using MaraDocs. Set ACCOUNT_SECRET in .env or environment."""

import sys
import time
from pathlib import Path

import requests
from decouple import config

API_URL = "https://api.maradocs.io/v1"


def create_workspace() -> dict:
    """Create a workspace and return auth headers."""
    r = requests.post(
        f"{API_URL}/workspace",
        headers={"Authorization": f"Bearer {config('ACCOUNT_SECRET')}"},
        json={"subaccount": None},
    )
    ws = r.json()
    return {"Authorization": f"Bearer {ws['workspace_secret']}"}


def upload_file(path: Path, auth: dict) -> dict:
    """Upload a file via two-step flow (signed URL + S3 POST). Returns unvalidated_file_handle."""
    data = path.read_bytes()
    resp = requests.post(
        f"{API_URL}/data/upload",
        headers={**auth, "Content-Type": "application/json"},
        json={"name": path.name, "size": len(data)},
    ).json()
    requests.post(
        resp["post_url"],
        data=resp.get("post_header", {}),
        files={"file": (path.name, data, "image/png")},
    )
    return resp["unvalidated_file_handle"]


def run_job(path: str, payload: dict, auth: dict, timeout: int = 60) -> dict:
    """Run a job and poll until complete. Returns the result (unwraps response if present)."""
    url = f"{API_URL}/{path}"
    r = requests.post(url, headers=auth, json=payload).json()
    job_id = r["job_id"]
    start = time.time()
    while time.time() - start < timeout:
        poll_r = requests.get(f"{url}/{job_id}", headers=auth)
        if poll_r.status_code == 200:
            return poll_r.json()
    raise TimeoutError(f"Job {path} timed out")


def download_pdf(pdf_handle: str, auth: dict) -> bytes:
    """Request signed URL and fetch PDF bytes."""
    r = requests.post(
        f"{API_URL}/data/download/pdf",
        headers=auth,
        json={"pdf_handle": pdf_handle},
    )
    info = r.json()
    dl = requests.get(info["url"], headers=info.get("headers", {}))
    return dl.content


def main() -> None:
    img_path = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("photo.png")
    auth = create_workspace()
    handle = upload_file(img_path, auth)
    validate = run_job("img/validate", {"unvalidated_file_handle": handle}, auth)
    img_handle = validate["response"]["img_handle"]
    result = run_job(
        "img/to/pdf",
        {
            "img_handle": img_handle,
            "options": {
                "embed_in_blank_page": {
                    "size": {"width": 210, "height": 297},
                    "position": "center",
                }
            },
        },
        auth,
    )
    pdf_handle = result.get("response", result).get("pdf_handle")
    Path("on_a4.pdf").write_bytes(download_pdf(pdf_handle, auth))
    print("on_a4.pdf created")


if __name__ == "__main__":
    main()

Podsumowanie i kolejne kroki

Dostępne jest API do umieszczania obrazów na pustych stronach dla A4 i rozmiarów niestandardowych. MaraDocs obsługuje obrazy bezpośrednio; dla plików PDF najpierw wyrenderuj do obrazów. Inne powiązane procesy: Skaner dokumentów, Przetwarzanie PDF, Rozpoznawanie tekstu i Kompresja PDF.

---

Wypróbuj teraz: API MaraDocs | TypeScript SDK

---