Incorporare immagini come documenti in PDF su pagine DIN A4

Foto o piccoli documenti devono spesso essere posizionati su una pagina standard – DIN A4, Letter o dimensioni personalizzate – centrati e correttamente scalati. Reportlab o strumenti simili possono farlo, ma richiedono matematica di layout e gestione dei formati. Un'API per posizionare immagini su pagine vuote, che incorpora contenuti su una pagina configurabile, semplificerebbe questo flusso di lavoro.

Perché una soluzione personalizzata per posizionare immagini su pagine vuote richiede settimane

Chi vuole costruirla da sé scopre rapidamente che è necessario calcolare la scalatura per adattare il contenuto dentro la pagina, centrarlo e considerare diversi rapporti di aspetto. Reportlab, PyMuPDF o PIL possono farlo – ma bisogna gestire DPI, margini e sistemi di coordinate. Per i PDF: prima renderizzare ogni pagina in un'immagine, poi incorporarla. Costruire un'API robusta per incorporare immagini su pagine richiede logica di layout e test.

Come l'API MaraDocs per posizionare immagini su pagine vuote risolve tutto in minuti

L'API MaraDocs supporta embed_in_blank_page in img.toPdf e img.ocrToPdf. Specificare le dimensioni della pagina (es. 210×297 mm per A4, o Letter, o dimensioni personalizzate) e la posizione (es. centro). L'API gestisce scalatura, rapporto di aspetto e margini. Per i PDF: renderizzare in immagini con pdf.toImg, poi usare img.toPdf con embed_in_blank_page. Niente matematica di layout, nessuna conversione DPI, nessuna gestione dei formati sul proprio lato. Una o due chiamate API e si ottiene un PDF correttamente formattato.

Flusso di lavoro: Validare, Incorporare, Scaricare

Per le immagini: validare, poi img.toPdf con options.embed_in_blank_page – specificare le dimensioni della pagina (es. 210×297 mm per A4) e la posizione (es. centro). Per i PDF: validare, usare pdf.toImg per renderizzare le pagine come immagini, poi img.toPdf con le opzioni di incorporamento. Il risultato è un handle PDF che può essere scaricato o passato a OCR, composizione o ottimizzazione. L'API gestisce scalatura, centratura e conversione del formato; matematica di layout e sistemi di coordinate non sono necessari.

Cosa distingue MaraDocs: Workspace, Webview e normativa tedesca sulla privacy

La maggior parte delle API per documenti obbliga a caricare, elaborare, scaricare e ricaricare per il passaggio successivo. Con MaraDocs i file rimangono nel workspace. Si possono concatenare OCR, composizione o compressione – l'handle PDF fluisce direttamente all'operazione successiva. Nessun nuovo caricamento, meno roundtrip.

Se layout o scalatura devono essere regolati manualmente – margini, posizionamento o dimensioni pagina – si può aprire app.maradocs.io per controllo e regolazione manuale. Gli utenti ottengono pieno controllo manuale quando l'automazione raggiunge i suoi limiti.

Tutta l'elaborazione avviene in Germania (Maramia GmbH), crittografata a riposo e in transito. I workspace scadono dopo 7 giorni. Nessun dato lascia l'UE. Per flussi di lavoro documentali sensibili alla privacy, questo è rilevante.

Codice TypeScript per incorporare immagini in pagine PDF

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

// Immagine: caricare, validare, incorporare su A4, scaricare
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: caricare, validare, renderizzare pagina come immagine, incorporare, scaricare
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 });

Codice Python per incorporare immagini in pagine PDF

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

Riepilogo e prossimi passi

È disponibile un'API per posizionare immagini su pagine vuote per DIN A4 e dimensioni personalizzate. MaraDocs supporta direttamente le immagini; per i PDF prima renderizzare in immagini. Altri flussi di lavoro correlati: Scanner documenti, Elaborazione PDF, Riconoscimento testo e Compressione PDF.

---

Prova ora: API MaraDocs | SDK TypeScript

---