# Mit Dateien arbeiten

Wie Sie Eingabedateien an eine Anfrage anhängen: ein einzelnes PDF, eine geordnete Liste zum Zusammenführen, ein zweites Bild für Wasserzeichen und die Grenzen für jede Form.

Eingaben werden als binäre Teile einer Anfrage vom Typ `multipart/form-data`
gesendet. Die meisten Aktionen nehmen genau ein PDF im Feld `file` entgegen,
zwei Aktionen brauchen mehr: Das Zusammenführen erwartet ein geordnetes Array
von Dateien, und das Bildwasserzeichen erwartet neben dem PDF einen zweiten
binären Teil. Diese Seite behandelt alle drei Formen der Eingabe.

## Eine einzelne Datei

Die Voreinstellung. Hängen Sie ein PDF im Feld `file` an und fügen Sie die
Optionen der Aktion als String-Felder hinzu:

```bash title="cURL"
curl https://api.pdfblocks.com/v1/extract_pages \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F pages='1..3' \
  -o extract.pdf
```

Das `@` in `-F file=@input.pdf` sagt cURL, dass es den Inhalt der Datei senden
soll. Jede Aktion mit einer einzigen Eingabe (Wasserzeichen, Sicherheit,
Seitenoperationen, Aufteilungen) funktioniert so.

## Mehrere Dateien: Zusammenführen

[Dokumente zusammenführen](/docs/api/merge-pdf-documents) ist die eine Aktion,
die ein Array akzeptiert. Senden Sie das Feld `file` **mehr als einmal**, dann
werden die Dokumente in der Reihenfolge zusammengeführt, in der die Teile in der
Anfrage stehen. Geben Sie mindestens eine Datei an; in einem einzigen Aufruf
können Sie viele senden.

<Warning>
  Die Reihenfolge ergibt sich aus der Position: Senden Sie die Teile deshalb in
  der Reihenfolge, in der sie zusammengeführt werden sollen. Wenn Ihr
  HTTP-Client ein Formularobjekt bereitstellt, verwenden Sie dessen Methode
  *append* (nicht *set*), damit ein wiederholtes `file` Teile hinzufügt, statt
  den vorherigen zu überschreiben.
</Warning>

<CodeGroup>

```bash title="cURL"
curl https://api.pdfblocks.com/v1/merge_documents \
  -H 'X-API-Key: your_api_key' \
  -F file=@cover.pdf \
  -F file=@body.pdf \
  -F file=@appendix.pdf \
  -o merged.pdf
```

```python title="Python"
# pip install requests
import requests

files = [
    ('file', ('cover.pdf', open('cover.pdf', 'rb'), 'application/pdf')),
    ('file', ('body.pdf', open('body.pdf', 'rb'), 'application/pdf')),
    ('file', ('appendix.pdf', open('appendix.pdf', 'rb'), 'application/pdf')),
]

response = requests.post(
    'https://api.pdfblocks.com/v1/merge_documents',
    headers={'X-API-Key': 'your_api_key'},
    files=files,
)

response.raise_for_status()
with open('merged.pdf', 'wb') as output:
    output.write(response.content)
```

```javascript title="Node.js"
// Node.js 18+
import { readFile, writeFile } from 'node:fs/promises';

const body = new FormData();
for (const name of ['cover.pdf', 'body.pdf', 'appendix.pdf']) {
  body.append('file', new Blob([await readFile(name)]), name);
}

const response = await fetch('https://api.pdfblocks.com/v1/merge_documents', {
  method: 'POST',
  headers: { 'X-API-Key': 'your_api_key' },
  body,
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
await writeFile('merged.pdf', Buffer.from(await response.arrayBuffer()));
```

</CodeGroup>

<Note>
  Wenn sich das Feld `file` in Ihrem HTTP-Client nur umständlich wiederholen
  lässt (cURL in PHP, die Formularhelfer in Ruby), senden Sie stattdessen die
  nummerierten Felder `file_1` bis `file_10`; sie werden in numerischer
  Reihenfolge zusammengeführt. Verwenden Sie das wiederholte Array `file`, wenn
  Sie mehr als zehn Dokumente brauchen.
</Note>

## Ein Bild neben dem PDF: Bildwasserzeichen

[Ein Bildwasserzeichen hinzufügen](/docs/api/add-image-watermark-to-pdf) nimmt
zwei binäre Teile entgegen: das PDF in `file` und das Bild für das Wasserzeichen
in einem Feld `image`. Das Bild muss **PNG oder JPEG** sein. Beide Teile sind
erforderlich.

```bash title="cURL"
curl https://api.pdfblocks.com/v1/add_image_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F image=@logo.png \
  -o watermarked.pdf
```

Die übrigen Felder (`transparency`, `margin`, `pages`) sind gewöhnliche
String-Optionen; ihre Wertebereiche und Voreinstellungen stehen in der Referenz
der Aktion.

## Zulässige Eingaben und Größe

- Die Eingabe `file` (und jede zusammengeführte Datei) muss ein lesbares PDF
  sein. Eine Datei, die sich nicht als PDF parsen lässt, liefert ein `400`, das
  das Feld `file` nennt. Siehe [Fehler](/docs/api/errors).
- Die Eingabe `image` für das Bildwasserzeichen muss PNG oder JPEG sein.
- Welche Seiten eine Aktion anfasst, ist eine andere Frage als die, wie Sie die
  Datei anhängen. Drücken Sie die Seitenauswahl mit dem Feld `pages` aus, das
  unter [Seiten auswählen](/docs/api/selecting-pages) dokumentiert ist.

Für große Dokumente, also Upload und Download als Stream, Zeitlimits und
Wiederholungen, siehe [Mit großen Dateien
arbeiten](/docs/api/working-with-large-files).