Image on Blank Page API – Embed Images and PDFs on DIN A4

Photos or small documents often need to sit on a standard page – DIN A4, Letter, or a custom size – centered and properly scaled. Reportlab or similar tools can do it, but you need layout math and format handling. An image on blank page API that embeds content on a configurable page would simplify that workflow.

Why Building an Image on Blank Page Solution Yourself Takes Weeks

If you try to build this yourself, you'll quickly find that you must compute scaling to fit the content within the page, center it, and handle different aspect ratios. Reportlab, PyMuPDF, or PIL can do it, but you need to manage DPI, margins, and coordinate systems. For PDFs, render each page to an image first, then embed. Building a robust image on blank page API takes layout logic and testing.

How the MaraDocs Image on Blank Page API Solves This in Minutes

The MaraDocs API supports embed_in_blank_page in img.toPdf and img.ocrToPdf. Specify page size (e.g. 210x297 mm for A4, or Letter, or a custom size) and position (e.g. center). The API handles scaling, aspect ratio, and margins. For PDFs: render to image with pdf.toImg, then use img.toPdf with embed_in_blank_page. No layout math, no DPI conversions, no format handling on your side. One or two API calls and you get a properly formatted PDF.

Image on Blank Page Workflow: Validate, Embed, Download

For images: validate, then img.toPdf with options.embed_in_blank_page – specify page size (e.g. 210x297 mm for A4) and position (e.g. center). For PDFs: validate, use pdf.toImg to render pages to images, then img.toPdf with embedding options. The result is a PDF handle you can download or pass to OCR, composition, or optimization. The API handles scaling, centering, and format conversion; you avoid layout math and coordinate systems.

Why MaraDocs is Different: Workspaces, Webview, and German Data Privacy

Most document APIs force you to upload, process, download, then re-upload for the next step. With MaraDocs, files stay in your workspace. Chain with OCR, composition, or compression – the PDF handle flows directly to the next operation. No re-upload, fewer round-trips.

When layout or scaling needs a manual tweak – margins, positioning, or page size – open app.maradocs.io for manual review and adjustment. Your users get full manual control when automation hits an edge case.

All processing runs in Germany (Maramia GmbH), encrypted at rest and in transit. Workspaces expire after 7 days. No data leaves the EU. For GDPR-sensitive document workflows, this matters.

TypeScript Code for Embedding Images in PDF Pages

API reference: 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: upload, validate, embed on A4, download
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: upload, validate, render page to image, embed, download
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 });

Python Code for Embed Image in PDF Page

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

import requests
import time

API_URL = "https://api.maradocs.io/v1"
headers = {"Authorization": f"Bearer {WORKSPACE_SECRET}"}

def poll(url, job_id):
    while True:
        r = requests.get(f"{url}/{job_id}", headers=headers).json()
        if r["status"] == "complete":
            return r["response"]["response"]
        time.sleep(1)

# 1. Upload, 2. Validate image
upload = requests.post(f"{API_URL}/data/upload", headers=headers, files={"file": (...)}).json()
val = requests.post(f"{API_URL}/img/validate", headers=headers,
    json={"unvalidated_file_handle": upload["unvalidated_file_handle"]}).json()
img_handle = poll(f"{API_URL}/img/validate", val["job_id"])["img_handle"]

# 3. Convert to PDF with embed_in_blank_page
to_pdf = requests.post(f"{API_URL}/img/to/pdf", headers=headers, json={
    "img_handle": img_handle,
    "options": {"embed_in_blank_page": {"size": {"width": 210, "height": 297}, "position": "center"}},
}).json()
result = poll(f"{API_URL}/img/to/pdf", to_pdf["job_id"])

# 4. Download
pdf_resp = requests.get(f"{API_URL}/data/download/pdf", headers=headers,
    params={"pdf_handle": result["pdf_handle"]})
with open("on_a4.pdf", "wb") as out:
    out.write(pdf_resp.content)

Summary and Next Steps

An image on blank page API for DIN A4 and custom sizes is ready. MaraDocs supports images directly; for PDFs, render to image first. See Document Scanner, PDF Handling, Text Recognition, and PDF Compression for related workflows.

---

Try it: MaraDocs API | TypeScript SDK

---