Merge API — Free Tier + Pay-As-You-Go
Merge PDFs, videos, images, and audio files programmatically. Upload-order concatenation with per-type engines.
What it does
The Merge API is `POST /v1/convert/merge` — a multipart request carrying two or more `file` parts plus a `mergeType` of `pdf`, `video`, `audio` or `image` (PDF is the default). Input extensions are checked against the chosen type before the job is queued, so a stray file returns a 400 instead of failing inside the engine. PDF merge runs on pdf-lib and appends every page in upload order; page content and page-level annotations copy across, but the document outline (bookmarks) and AcroForm fields are not rebuilt in the merged file.
Video merge probes each input first: when codec, resolution, frame rate, pixel format and audio codec all match, it stream-copies through FFmpeg's concat demuxer; when they don't, every input is normalised to the first file's geometry as H.264/AAC before concatenation. Audio merge concatenates tracks end to end and can insert a fixed silence between them with `options={"gap":2}` (0-10 seconds). Image merge composites up to 20 images onto one canvas — `options={"layout":"vertical"}` (the default), `horizontal`, `grid`, `grid2x2` or `grid3x3` — and writes PNG, JPEG or WebP.
Pass `targetFormat` to pin the output container; otherwise PDF merges emit PDF, image merges emit PNG, and audio/video merges follow the first input.
Supported formats
Source formats (12)
- mp4
- mov
- mkv
- webm
- jpg
- png
- webp
- mp3
- wav
- flac
- m4a
Target formats (11)
- mp4
- mov
- mkv
- webm
- png
- jpg
- webp
- mp3
- wav
- flac
Quick start
Every sample posts the job, then polls /v1/status/{jobId} until it finishes, with your API key in the X-Api-Key header. The parameter names below are the ones the endpoint actually accepts — anything else is dropped rather than rejected.
curl -X POST https://api.convertintomp4.com/v1/convert/merge \
-H "X-Api-Key: ck_your_api_key" \
-F "file=@page1.pdf" \
-F "file=@page2.pdf" \
-F "file=@page3.pdf" \
-F "mergeType=pdf"import { readFileSync } from "node:fs";
const apiKey = process.env.CIM4_API_KEY;
// Two or more "file" parts, merged in upload order.
const form = new FormData();
for (const name of ["page1.pdf", "page2.pdf", "page3.pdf"]) {
form.append("file", new Blob([readFileSync(name)]), name);
}
form.append("mergeType", "pdf");
const { jobId } = await fetch(`https://api.convertintomp4.com/v1/convert/merge`, {
method: "POST",
headers: { "X-Api-Key": apiKey },
body: form,
}).then((r) => r.json());
let job;
do {
await new Promise((r) => setTimeout(r, 2000));
job = await fetch(`https://api.convertintomp4.com/v1/status/${jobId}`, {
headers: { "X-Api-Key": apiKey },
}).then((r) => r.json());
} while (job.status !== "completed" && job.status !== "failed");
console.log("Merged:", job.result?.downloadUrl);import time, requests
api_key = "ck_your_api_key"
names = ["page1.pdf", "page2.pdf", "page3.pdf"]
# Two or more "file" parts, merged in upload order.
files = [("file", (n, open(n, "rb"), "application/pdf")) for n in names]
job = requests.post(
"https://api.convertintomp4.com/v1/convert/merge",
headers={"X-Api-Key": api_key},
files=files,
data={"mergeType": "pdf"},
).json()
while True:
status = requests.get(
f"https://api.convertintomp4.com/v1/status/{job['jobId']}",
headers={"X-Api-Key": api_key},
).json()
if status["status"] in ("completed", "failed"):
break
time.sleep(2)
print("Merged:", status.get("result", {}).get("downloadUrl"))Features
- One endpoint (`POST /v1/convert/merge`) for PDF, video, audio and image merges
- Input extensions validated per merge type before queueing — a 400, not an engine crash
- PDF: every page appended in upload order via pdf-lib
- Video: stream-copy concat when inputs match, automatic H.264/AAC normalisation when they don't
- Audio: optional fixed silence between tracks (`gap`, 0-10 seconds)
- Image: vertical, horizontal or grid composites, up to 20 files
- Minimum two files per job; `targetFormat` pins the output container
Pricing
From $9.99/mo (Pro) or $24.99/mo (Business) — or pay-as-you-go on the API plan.
Free tier: 5 conversions/day, 100 MB file size, no API key required (IP-gated). Pro $9.99/mo: 100/day (2,000/month), 2 GB files. Business $24.99/mo: 1,000/day (20,000/month), 10 GB files, GPU encoding, dedicated support.
See full pricing breakdown →Built for production
99.9% uptime SLA
Multi-region failover, transparent status page, 60-second response-time guarantee on Business.
Encryption + auto-delete
TLS 1.2+ in transit, AES-256 at rest. Files deleted after 1h / 24h / 7d depending on plan, or instantly via DELETE endpoint. See the security page.
~7s median latency
Most sub-100 MB jobs complete in 6-9 seconds. Webhook-driven async for heavier workloads; waitForJob for synchronous flows.
Frequently Asked Questions
Does PDF merge preserve bookmarks and form fields?
No. The merge copies pages from each input into a new document, so page content and page-level annotations survive, but the document outline (bookmarks) and AcroForm field definitions are not rebuilt in the output. If bookmarks matter, keep the source files and rebuild the outline in a PDF editor after merging.
What happens if input videos have different resolutions?
Every input is probed first. If codec, resolution, frame rate, pixel format and audio codec match across all files, the merge is a stream copy through FFmpeg's concat demuxer — fast and lossless. If anything differs, each input is re-encoded to the first file's geometry as H.264/AAC and the identical intermediates are concatenated. There is no parameter to pin a different common resolution.
Can I merge images into a multi-page PDF?
Not through this endpoint — image merge composites the inputs into a single image canvas. For one PDF page per image, use `POST /v1/convert` with an image source, `targetFormat=pdf` and `combineImages=true`, sending the first image as `file` and the rest as `additionalFile` parts. Page order follows upload order.
How is the merge order controlled?
By the order of the multipart `file` parts. There is no reorder parameter — send the files in the order you want them concatenated. The first file also decides the default output format for audio and video merges.
How many files can one merge job take?
At least two. Image merge is hard-capped at 20 inputs and returns a clear error above that. PDF, audio and video merges have no fixed file count, but they are bounded by the per-file upload limit and by the 45-minute merge job timeout, so very large batches are safer split across several jobs.
Related APIs
- Compression APICompress video, image, PDF, and audio files programmatically. Quality presets, resolution scaling, and a real byte-ceiling mode for video and audio.
- Split APIPull a page range out of a PDF or cut a time range out of a video or audio file via API. One output per request.
- OCR APIOptical character recognition for scanned PDFs and images via API. Tesseract, searchable-PDF or plain-text output, 17 language packs.
- Watermark APIAdd a text or image watermark to PDFs, videos, and images via API. Nine anchor positions, opacity, size, and colour.
- File Conversion APIOne unified file conversion API for video, audio, image, document, ebook, archive, and font formats — 255 formats, 2,290+ conversion pairs.
- Convert APIProduction-grade file conversion API with 9 language SDKs, async webhooks, and cloud-to-cloud workflows. Free tier available.
Or browse the full catalogue of 23 API products →
Get an API key
Start integrating the Merge API in five minutes. Read the docs, grab a key, and ship your first conversion before the trial coffee cools.