Incrustar imágenes como documentos en páginas PDF DIN A4

Las fotos o documentos pequeños a menudo deben colocarse en una página estándar – DIN A4, Letter o un tamaño personalizado – centrados y correctamente escalados. Reportlab o herramientas similares pueden lograrlo, pero requieren matemáticas de diseño y manejo de formatos. Una API para colocar imágenes en páginas en blanco que incruste contenido en una página configurable simplificaría este flujo de trabajo.

Por qué crear tu propia solución para colocar imágenes en páginas en blanco lleva semanas

Quien quiera construirlo por sí mismo descubrirá rápidamente que debe calcular el escalado para ajustar el contenido dentro de la página, centrarlo y considerar diferentes proporciones. Reportlab, PyMuPDF o PIL pueden hacerlo – pero hay que gestionar DPI, márgenes y sistemas de coordenadas. Para PDFs: primero renderizar cada página como imagen, luego incrustarla. Construir una API robusta para incrustar imágenes en páginas requiere lógica de diseño y pruebas.

Cómo la API de MaraDocs para colocar imágenes en páginas en blanco lo resuelve en minutos

La API de MaraDocs soporta embed_in_blank_page en img.toPdf e img.ocrToPdf. Especifica el tamaño de página (por ejemplo, 210×297 mm para A4, o Letter, o un tamaño personalizado) y posición (por ejemplo, centro). La API se encarga del escalado, proporción y márgenes. Para PDFs: renderiza en imágenes con pdf.toImg, luego usa img.toPdf con embed_in_blank_page. Sin matemáticas de diseño, sin conversiones de DPI, sin manejo de formatos en tu lado. Una o dos llamadas a la API y obtienes un PDF correctamente formateado.

Flujo de trabajo: Validar, Incrustar, Descargar

Para imágenes: valida, luego img.toPdf con options.embed_in_blank_page – especifica tamaño de página (por ejemplo, 210×297 mm para A4) y posición (por ejemplo, centro). Para PDFs: valida, usa pdf.toImg para renderizar páginas como imágenes, luego img.toPdf con opciones de incrustación. El resultado es un identificador de PDF que puede descargarse o pasarse a OCR, composición u optimización. La API se encarga del escalado, centrado y conversión de formato; se eliminan las matemáticas de diseño y sistemas de coordenadas.

Qué diferencia a MaraDocs: Workspaces, vista web y ley de protección de datos alemana

La mayoría de las APIs de documentos obligan a subir, procesar, descargar y volver a subir para el siguiente paso. En MaraDocs los archivos permanecen en el workspace. Encadena con OCR, composición o compresión – el identificador de PDF fluye directamente a la siguiente operación. Sin volver a subir, menos viajes de ida y vuelta.

Cuando el diseño o escalado necesita ajuste manual – márgenes, posicionamiento o tamaño de página – se puede abrir app.maradocs.io para revisión y ajuste manual. Los usuarios obtienen control manual completo cuando la automatización alcanza sus límites.

Todo el procesamiento ocurre en Alemania (Maramia GmbH), cifrado en reposo y durante la transmisión. Los workspaces expiran después de 7 días. Ningún dato sale de la UE. Para flujos de trabajo de documentos sensibles a la protección de datos, esto es relevante.

Código TypeScript para incrustar imágenes en páginas PDF

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

// Imagen: subir, validar, incrustar en A4, descargar
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: subir, validar, renderizar página como imagen, incrustar, descargar
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 });

Código Python para incrustar imágenes en páginas PDF

Referencia de 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()

Resumen y próximos pasos

Una API para colocar imágenes en páginas en blanco para DIN A4 y tamaños personalizados está disponible. MaraDocs soporta imágenes directamente; para PDFs primero renderiza en imágenes. Más flujos de trabajo relacionados: Escáner de documentos, Procesamiento de PDF, Reconocimiento de texto y Compresión de PDF.

---

Pruébalo ahora: API de MaraDocs | SDK de TypeScript

---