---
name: "pdf123-add-image"
description: "Adds a image onto a set location on the PDF. Runs the PDF123 \"Add image\" tool (pdf123.xyz) over its REST API with curl, no account needed. Use when the user wants this done to their file. Also known as: 叠加图片, Añadir imagen, छवि चढ़ाएँ, إضافة صورة, Adicionar imagem, Tambah gambar, Ajouter une image, Наложить изображение, 画像の重ね合わせ, Bild einfügen, 이미지 겹치기, Chèn ảnh, Görüntü ekle, 疊加圖片, Aggiungi immagine, วางภาพ, Dodaj obraz, Накласти зображення, Afbeelding plaatsen, Tambah imej, Lägg till bild, Προσθήκη εικόνας, Добавяне на изображение, Afegeix una imatge, Weka picha."
compatibility: "Needs curl 7.76+ and outbound HTTPS to pdf123.xyz, or PDFX_API_BASE pointing at a self-hosted pdfx-server."
---

# Add image (PDF123)

Adds a image onto a set location on the PDF.

Web version: https://pdf123.xyz/add-image · All tools: https://pdf123.xyz/skills/pdf123.md

## When to use

- Place a PNG logo on page 1
- Repeat a mark on every page at a fixed point
- Drop an SVG through WeasyPrint when you accept print fidelity

## Run it

Replace the sample file names and values with the user's, then run:

```bash
API="${PDFX_API_BASE:-https://pdf123.xyz}"
curl -sS --fail-with-body -X POST "$API/api/v1/misc/add-image" \
  -F "fileInput=@input.pdf" \
  -F "imageFile=@imageFile.png" \
  -F "x=0" \
  -F "y=0" \
  -F "everyPage=false" \
  --output-dir "pdf123-output/$(date +%Y%m%d-%H%M%S)" --create-dirs -OJ -w '%{filename_effective} %{content_type}\n'
```

## Inputs

Everything is `multipart/form-data`. The command above already sends each field with its default; keep them all and change only the values the user asked for, since some endpoints reject a missing optional field.

| Field | Type | Required | Default | Notes |
| --- | --- | --- | --- | --- |
| `fileInput` | file | yes | | .pdf (one file) |
| `imageFile` | file | yes | | Image file: .png, .jpg, .jpeg, .svg |
| `x` | number | yes | `0` | X position |
| `y` | number | yes | `0` | Y position |
| `everyPage` | choice | yes | `false` | Apply to. One of: `false` (First page only), `true` (Every page) |

## Result

curl saves the result in a new `pdf123-output/<timestamp>/` directory under the server's file name and prints its path and content type. Several output files come back as one ZIP. Tell the user where the file is.

## Limits

- No scale/opacity fields
- Giant rasters become giant PDF placements
- Transparent PNG areas are not preserved: images are converted to RGB, so transparent pixels take the colour stored under them, often black
- Password-protected files need the password; API callers run Unlock first
- Upload limit on this website: 500 MB per file, sent in chunks above about 95 MB. A single direct API request body is capped at 100 MB.

## Errors

- A non-zero curl exit means the request failed. The saved file then holds `application/problem+json`; read it and report its `detail` to the user instead of retrying blindly.
- `413`: the upload exceeds 100 MiB. `429`: wait for `Retry-After` seconds, then retry once.
- Send `X-API-KEY: $PDFX_API_KEY` only if the user has a PDF123 API key; anonymous calls work without it.

## Privacy

Files are uploaded to the API host, processed, and deleted once the response is sent. For confidential files, ask before uploading, or use a self-hosted server via `PDFX_API_BASE`.