Intégrer des images comme documents dans des PDF sur pages DIN A4

Les photos ou petits documents doivent souvent être placés sur une page standard – DIN A4, Letter ou une taille personnalisée – centrés et correctement mis à l'échelle. Reportlab ou des outils similaires peuvent le faire, mais nécessitent des calculs de mise en page et une gestion des formats. Une API pour placer des images sur pages vierges, qui intègre le contenu sur une page configurable, simplifierait ce workflow.

Pourquoi développer sa propre solution pour placer des images sur pages vierges prend des semaines

Ceux qui souhaitent le développer eux-mêmes découvrent rapidement qu'il faut calculer la mise à l'échelle pour ajuster le contenu dans la page, le centrer et prendre en compte différents rapports d'aspect. Reportlab, PyMuPDF ou PIL peuvent le faire – mais vous devez gérer les DPI, les marges et les systèmes de coordonnées. Pour les PDF : d'abord convertir chaque page en image, puis l'intégrer. Créer une API robuste pour intégrer des images sur des pages nécessite une logique de mise en page et des tests.

Comment l'API MaraDocs pour placer des images sur pages vierges résout cela en quelques minutes

L'API MaraDocs prend en charge embed_in_blank_page dans img.toPdf et img.ocrToPdf. Indiquez la taille de page (par ex. 210×297 mm pour A4, ou Letter, ou une taille personnalisée) et la position (par ex. centre). L'API gère la mise à l'échelle, le rapport d'aspect et les marges. Pour les PDF : convertissez en images avec pdf.toImg, puis utilisez img.toPdf avec embed_in_blank_page. Pas de calculs de mise en page, pas de conversions DPI, pas de gestion de formats de votre côté. Un ou deux appels API et vous obtenez un PDF correctement formaté.

Workflow : Valider, Intégrer, Télécharger

Pour les images : validez, puis img.toPdf avec options.embed_in_blank_page – indiquez la taille de page (par ex. 210×297 mm pour A4) et la position (par ex. centre). Pour les PDF : validez, utilisez pdf.toImg pour convertir les pages en images, puis img.toPdf avec les options d'intégration. Le résultat est un handle PDF qui peut être téléchargé ou transmis à l'OCR, la composition ou l'optimisation. L'API gère la mise à l'échelle, le centrage et la conversion de format ; les calculs de mise en page et systèmes de coordonnées sont éliminés.

Ce qui distingue MaraDocs : Workspaces, Webview et droit allemand de protection des données

La plupart des API de documents obligent à téléverser, traiter, télécharger et téléverser à nouveau pour l'étape suivante. Avec MaraDocs, les fichiers restent dans le workspace. Enchaînez avec l'OCR, la composition ou la compression – le handle PDF passe directement à l'opération suivante. Pas de nouveau téléversement, moins d'allers-retours.

Si la mise en page ou la mise à l'échelle doit être ajustée manuellement – marges, positionnement ou taille de page – vous pouvez ouvrir app.maradocs.io pour une vérification et un ajustement manuels. Les utilisateurs obtiennent un contrôle manuel complet lorsque l'automatisation atteint ses limites.

Tout le traitement se fait en Allemagne (Maramia GmbH), chiffré au repos et en transit. Les workspaces expirent après 7 jours. Aucune donnée ne quitte l'UE. Pour les workflows de documents sensibles en matière de protection des données, c'est pertinent.

Code TypeScript pour intégrer des images dans des pages PDF

Référence 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 });

// Image : téléverser, valider, intégrer sur A4, télécharger
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 : téléverser, valider, convertir page en image, intégrer, télécharger
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 });

Code Python pour intégrer des images dans des pages PDF

Référence 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()

Résumé et prochaines étapes

Une API pour placer des images sur pages vierges en DIN A4 et formats personnalisés est disponible. MaraDocs prend en charge les images directement ; pour les PDF, convertissez d'abord en images. Autres workflows connexes : Scanner de documents, Traitement PDF, Reconnaissance de texte et Compression PDF.

---

Essayez maintenant : API MaraDocs | SDK TypeScript

---