---
seo_title: Batch-Dateikonvertierungs-API: URLs zu PDF & ZIP | EnConvert
meta_desc: Konvertiere mehrere URLs in einer Anfrage mit POST /v1/convert/url-to-pdf in PDF oder Screenshots. Batch-Konvertierungs-API mit ZIP-Ausgabe, Webhooks und Polling.
keywords: mehrere urls in pdf umwandeln api, batch pdf konvertierung api, bulk url zu pdf api, screenshot api für mehrere urls, batch konvertierungsstatus abfragen, zip ausgabe pdf api, asynchrone batch konvertierung api, webhook callback bei batch konvertierung
---

# Batch-Dateikonvertierungs-API

Die EnConvert Batch-API konvertiert mehrere URLs in einer einzigen Anfrage: Übergib ein Array von URLs an `/v1/convert/url-to-pdf` oder `/v1/convert/url-to-screenshot` und erhalte eine HTTP-202-Antwort mit einer `batch_id`. Jede URL wird asynchron im Hintergrund konvertiert, und die Ergebnisse werden als vorsignierte Download-URLs geliefert, entweder eine pro Datei oder gebündelt in einem einzigen ZIP-Archiv. Verfolge den Fortschritt durch Polling von `GET /v1/convert/batch/{batch_id}`, oder lass dich per Webhook-Callback oder E-Mail benachrichtigen, sobald der Vorgang abgeschlossen ist.

<div class="alert alert-warning">
<strong>Nur private Keys:</strong> Batch-Verarbeitung ist nur verfügbar, wenn du dich mit einem <strong>privaten API-Key</strong> authentifizierst (<code>X-API-Key: sk_...</code>). Öffentliche Keys sind auf synchrone Anfragen mit einer einzelnen URL beschränkt.
</div>

---

## Funktionsweise

1. Sende eine Anfrage mit einem **Array von URLs** im Parameter `url` an entweder `/v1/convert/url-to-pdf` oder `/v1/convert/url-to-screenshot`.
2. Die API validiert den Batch gegen die Limits deines Plans und gibt **HTTP 202** mit einer `batch_id` zurück.
3. Jede URL wird im Hintergrund konvertiert und berechnet eine Op. Die gesamte Batch-Anzahl wird vorab gegen dein verbleibendes monatliches Ops-Kontingent geprüft, bevor die Verarbeitung beginnt.
4. Verfolge den Fortschritt über `GET /v1/convert/batch/{batch_id}` oder erhalte bei Abschluss einen Webhook-Callback oder eine E-Mail-Benachrichtigung.
5. Lade die Ergebnisse über vorsignierte URLs in der Batch-Statusantwort herunter.

---

## Ausgabemodi

### Einzelmodus (Standard)

Jede URL erzeugt eine separate Datei. Jede Datei erhält ihre eigene vorsignierte Download-URL in der Batch-Statusantwort.

**Anfrage:**

```bash
curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": [
      "https://example.com/page-1",
      "https://example.com/page-2",
      "https://example.com/page-3"
    ]
  }'
```

**Antwort (HTTP 202 Accepted):**

```json
{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 3,
    "output_format": "individual"
}
```

<div class="alert alert-info">
<strong>Hinweis:</strong> Beim Übergeben mehrerer URLs wird <code>async_mode</code> automatisch auf <code>true</code> gesetzt, unabhängig davon, ob du es explizit in der Anfrage angibst.
</div>

### ZIP-Bundle-Modus

Setze `output_format` auf `true`, um alle konvertierten Dateien gebündelt in einem einzigen ZIP-Archiv zu erhalten. Erfordert einen Plan mit Zugriff auf ZIP-Ausgabe.

**Anfrage:**

```bash
curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": [
      "https://example.com/page-1",
      "https://example.com/page-2",
      "https://example.com/page-3"
    ],
    "output_format": true,
    "output_filename": "monthly-reports"
  }'
```

**Antwort (HTTP 202 Accepted):**

```json
{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 3,
    "output_format": "zip"
}
```

Im ZIP-Modus werden alle URLs sequenziell verarbeitet, und die erfolgreichen Ergebnisse werden in einem einzigen ZIP-Archiv mit dem Namen `{output_filename}_{timestamp}.zip` gebündelt (oder `batch_{timestamp}.zip`, falls kein benutzerdefinierter Name angegeben wird).

---

## Batch-Parameter

| Parameter | Type | Default | Beschreibung | Plan-Freischaltung |
|-----------|------|---------|-------------|-------------|
| `url` | `string[]` | *(erforderlich)* | Array der zu konvertierenden URLs. | -- |
| `output_format` | `boolean` | `false` | Auf `true` setzen, um alle Ergebnisse in einem ZIP-Archiv zu bündeln. Erfordert mehrere URLs. | Erfordert Zugriff auf ZIP-Ausgabe |
| `output_filename` | `string` | Automatisch generiert | Benutzerdefinierter Dateiname für die Ausgabe. Im ZIP-Modus wird damit das ZIP-Archiv benannt. | -- |
| `async_mode` | `boolean` | `true` (implizit) | Für Batch immer `true`. Wird automatisch aktiviert, wenn mehrere URLs angegeben werden. | Erfordert Async-Zugriff |
| `notification_email` | `string` | E-Mail des Projektinhabers | E-Mail-Adresse, die bei Abschluss benachrichtigt wird. Falls weggelassen, wird standardmäßig die E-Mail des Projektinhabers verwendet. | -- |
| `callback_url` | `string` | `null` | Webhook-URL, die bei Abschluss ein POST erhält. | Erfordert Webhook-Zugriff |
| `direct_download` | -- | -- | **Nicht unterstützt** für Batch. Gibt einen 400-Fehler zurück, wenn bei mehreren URLs gesetzt. | -- |

### Browser- & Rendering-Parameter

Diese Einstellungen gelten für jede URL im Batch:

| Parameter | Type | Default | Beschreibung |
|-----------|------|---------|-------------|
| `viewport_width` | `integer` | `1920` | Breite des Browser-Viewports in Pixeln. |
| `viewport_height` | `integer` | `1080` | Höhe des Browser-Viewports in Pixeln. |
| `single_page` | `boolean` | `true` | Als einzelne durchgehende Seite rendern (nur url-to-pdf). |
| `load_media` | `boolean` | `true` | Warten, bis Bilder und Medien geladen sind. |
| `enable_scroll` | `boolean` | `true` | Seiten scrollen, um Lazy-Loaded-Inhalte auszulösen. |
| `handle_sticky_header` | `boolean` | `true` | Sticky/fixierte Header erkennen und behandeln. |
| `handle_cookies` | `boolean` | `true` | Cookie-Consent-Banner automatisch schließen. |
| `wait_for_images` | `boolean` | `true` | Warten, bis alle Bilder vollständig geladen sind. |

### Authentifizierung & benutzerdefinierte Anfragen

Diese gelten für jede URL im Batch. Erfordern einen Plan mit Basic-Auth-Zugriff.

| Parameter | Type | Default | Beschreibung |
|-----------|------|---------|-------------|
| `auth` | `object` | `null` | HTTP-Basic-Auth-Zugangsdaten: `{"username": "...", "password": "..."}`. |
| `cookies` | `array` | `null` | Array von Cookie-Objekten, die vor jedem Seitenaufruf injiziert werden. Max. 50. |
| `headers` | `object` | `null` | Benutzerdefinierte HTTP-Header, die mit jeder Anfrage gesendet werden. Max. 20. |

### PDF-Optionen (nur url-to-pdf)

Übergib ein `pdf_options`-Objekt, um die PDF-Ausgabeformatierung für jede Seite im Batch zu steuern:

| Parameter | Type | Default | Beschreibung |
|-----------|------|---------|-------------|
| `page_size` | `string` | `"A4"` | Benannte Seitengröße. |
| `orientation` | `string` | `"portrait"` | `"portrait"` oder `"landscape"`. |
| `margins` | `object` | `{"top": 10, "bottom": 10, "left": 10, "right": 10}` | Ränder in mm. |
| `grayscale` | `boolean` | `false` | Graustufenausgabe via Ghostscript. |

---

## Batch-Status-Polling

Verwende den Batch-Status-Endpoint, um den Fortschritt zu prüfen und Download-URLs abzurufen.

```
GET /v1/convert/batch/{batch_id}
X-API-Key: sk_your_private_key
```

Ersetze `{batch_id}` durch die `batch_id`, die von der ursprünglichen Anfrage zurückgegeben wurde.

### Verarbeitungsstatus

Während Konvertierungen noch laufen:

```json
{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "total": 3,
    "completed": 1,
    "failed": 0,
    "in_progress": 2,
    "output_mode": "individual",
    "zip_download_url": null,
    "items": [
        {
            "source_url": "https://example.com/page-1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 184320,
            "duration": "3.12"
        },
        {
            "source_url": "https://example.com/page-2",
            "status": "In Progress",
            "download_url": null,
            "output_file_size": null,
            "duration": null
        },
        {
            "source_url": "https://example.com/page-3",
            "status": "In Progress",
            "download_url": null,
            "output_file_size": null,
            "duration": null
        }
    ]
}
```

### Abgeschlossener Status

Wenn alle URLs erfolgreich konvertiert wurden:

```json
{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "total": 3,
    "completed": 3,
    "failed": 0,
    "in_progress": 0,
    "output_mode": "individual",
    "zip_download_url": null,
    "items": [
        {
            "source_url": "https://example.com/page-1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 184320,
            "duration": "3.12"
        },
        {
            "source_url": "https://example.com/page-2",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 210944,
            "duration": "4.55"
        },
        {
            "source_url": "https://example.com/page-3",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 97280,
            "duration": "2.87"
        }
    ]
}
```

### Teilweiser Status

Wenn alle URLs abgeschlossen sind, aber einige fehlgeschlagen sind:

```json
{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "partial",
    "total": 3,
    "completed": 2,
    "failed": 1,
    "in_progress": 0,
    "output_mode": "individual",
    "zip_download_url": null,
    "items": [
        {
            "source_url": "https://example.com/page-1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 184320,
            "duration": "3.12"
        },
        {
            "source_url": "https://example.com/page-2",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 210944,
            "duration": "4.55"
        },
        {
            "source_url": "https://invalid-url.example",
            "status": "Failed",
            "download_url": null,
            "output_file_size": null,
            "duration": "0.87"
        }
    ]
}
```

### Abgeschlossen im ZIP-Modus

Im ZIP-Modus wird eine einzelne `zip_download_url` für das gesamte Archiv bereitgestellt:

```json
{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "total": 3,
    "completed": 3,
    "failed": 0,
    "in_progress": 0,
    "output_mode": "zip",
    "zip_download_url": "https://spaces.example.com/...",
    "items": [
        {
            "source_url": "https://example.com/page-1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 184320,
            "duration": "3.12"
        },
        {
            "source_url": "https://example.com/page-2",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 210944,
            "duration": "4.55"
        },
        {
            "source_url": "https://example.com/page-3",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 97280,
            "duration": "2.87"
        }
    ]
}
```

### Batch-Statuswerte

| Status | Bedeutung |
|--------|---------|
| `processing` | Mindestens eine URL wird noch konvertiert. |
| `completed` | Alle URLs wurden erfolgreich konvertiert. |
| `partial` | Alle URLs sind abgeschlossen, aber einige sind fehlgeschlagen. |
| `failed` | Alle URLs sind fehlgeschlagen. |

---

## Webhook-Callbacks

Gib in der Anfrage eine `callback_url` an, um bei Abschluss automatisch eine POST-Benachrichtigung zu erhalten. Der Webhook wird mit `Content-Type: application/json` und einem 30-Sekunden-Timeout gesendet. Bei Zustellungsfehlern werden keine Wiederholungsversuche unternommen.

### Callback im Einzelmodus

Im Einzelmodus wird **für jede URL bei Abschluss ein separater Webhook-POST gesendet**:

```json
{
    "job_id": "12345",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-pdf/page1_20260405_123456789.pdf",
    "filename": "page1_20260405_123456789.pdf",
    "file_size": 184320
}
```

### Callback im ZIP-Modus

Im ZIP-Modus wird **ein einziger Webhook-POST gesendet, wenn der gesamte Batch abgeschlossen ist**:

```json
{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-pdf/batch_20260405_123456789.zip",
    "filename": "batch_20260405_123456789.zip",
    "file_size": 456789,
    "total_tasks": 3,
    "successful_tasks": 2,
    "failed_tasks": 1,
    "tasks": [
        {"url": "https://example.com/page-1", "status": "success", "filename": "page1.pdf"},
        {"url": "https://example.com/page-2", "status": "success", "filename": "page2.pdf"},
        {"url": "https://invalid.example", "status": "failed", "error": "Page load timeout"}
    ]
}
```

<div class="alert alert-info">
<strong>Unterschied im Benachrichtigungsverhalten:</strong> Im Einzelmodus erhältst du N separate Webhook-POSTs (einen pro URL) und N separate E-Mails. Im ZIP-Modus erhältst du einen Webhook-POST und eine E-Mail für den gesamten Batch. Berücksichtige dies beim Entwurf deines Webhook-Handlers.
</div>

---

## E-Mail-Benachrichtigungen

Bei Abschluss des Batches wird eine E-Mail an `notification_email` gesendet. Wird keine `notification_email` angegeben, wird die E-Mail standardmäßig an die E-Mail-Adresse des Projektinhabers gesendet.

Die E-Mail enthält:

- Job-Status (success/failed) mit farbigem Banner
- Batch-ID
- Bei Batch-Jobs: eine Tabelle mit jeder URL, ihrem Status und dem Ausgabedateinamen
- Ein Link zum Herunterladen der Ergebnisse über das Dashboard

---

## Freischaltung nach Abo-Plan

| Feature | Founding | Indie | Studio | Enterprise |
|---------|------|---------|-----|------------|
| Batch-Verarbeitung | Nein | Ja | Ja | Ja |
| Async-Modus | Nein | Ja | Ja | Ja |
| ZIP-Ausgabebündelung | Nein | Nein | Ja | Ja |
| Webhook-Callbacks | Nein | Nein | Ja | Ja |
| HTTP Basic Auth / Cookies / Headers | Nein | Ja | Ja | Ja |
| Batch-Größenlimit | 0 | Planabhängig | Planabhängig | Unbegrenzt |
| Monatliche Konvertierungen | 100 | Planabhängig | Planabhängig | Unbegrenzt |

---

## Codebeispiele

### Python – Einzelmodus mit Polling

```python
import requests
import time

# Submit batch
response = requests.post(
    "https://api.enconvert.com/v1/convert/url-to-pdf",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": [
            "https://example.com/page-1",
            "https://example.com/page-2",
            "https://example.com/page-3"
        ]
    }
)

data = response.json()
batch_id = data["batch_id"]
print(f"Batch started: {batch_id} ({data['url_count']} URLs)")

# Poll for completion
while True:
    status = requests.get(
        f"https://api.enconvert.com/v1/convert/batch/{batch_id}",
        headers={"X-API-Key": "sk_your_private_key"}
    ).json()

    print(f"Status: {status['status']} ({status['completed']}/{status['total']})")

    if status["status"] in ("completed", "partial", "failed"):
        for item in status["items"]:
            if item["download_url"]:
                print(f"  {item['source_url']} -> {item['download_url']}")
        break

    time.sleep(5)
```

### Python – ZIP-Modus mit Webhook

```python
import requests

response = requests.post(
    "https://api.enconvert.com/v1/convert/url-to-pdf",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": [
            "https://example.com/page-1",
            "https://example.com/page-2",
            "https://example.com/page-3"
        ],
        "output_format": True,
        "output_filename": "monthly-reports",
        "callback_url": "https://your-server.com/webhook/enconvert",
        "pdf_options": {
            "page_size": "A4",
            "orientation": "portrait"
        }
    }
)

data = response.json()
print(f"Batch started: {data['batch_id']}")
print(f"URLs: {data['url_count']}, Format: {data['output_format']}")
# Results will be delivered to your webhook URL
```

### Node.js – Batch-Screenshots

```javascript
const response = await fetch("https://api.enconvert.com/v1/convert/url-to-screenshot", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_your_private_key"
    },
    body: JSON.stringify({
        url: [
            "https://example.com/page-1",
            "https://example.com/page-2",
            "https://example.com/page-3"
        ],
        output_format: true,
        output_filename: "screenshots-bundle"
    })
});

const data = await response.json();
console.log(`Batch ${data.batch_id}: ${data.url_count} screenshots queued`);
```

---

## Fehlerantworten

| Status | Bedingung |
|--------|-----------|
| `400 Bad Request` | `url` ist leer oder fehlt |
| `400 Bad Request` | `output_format=true` bei einer einzelnen URL (erfordert mehrere URLs) |
| `400 Bad Request` | `direct_download=true` bei mehreren URLs (nicht unterstützt) |
| `400 Bad Request` | `direct_download=true` mit `async_mode=true` |
| `400 Bad Request` | Öffentlicher Key versucht mehrere URLs |
| `402 Payment Required` | Batch würde das verbleibende monatliche Ops-Kontingent überschreiten |
| `402 Payment Required` | Speicherlimit erreicht |
| `403 Forbidden` | Async-Verarbeitung im aktuellen Plan nicht verfügbar |
| `403 Forbidden` | Batch-Verarbeitung nicht verfügbar (Batch-Limit ist 0) |
| `403 Forbidden` | Batch-Größe überschreitet das Batch-Limit des Plans |
| `403 Forbidden` | ZIP-Ausgabe im aktuellen Plan nicht verfügbar |
| `403 Forbidden` | Webhook-Callbacks im aktuellen Plan nicht verfügbar |
| `404 Not Found` | Batch nicht gefunden (falsche batch_id oder falsches Projekt) |

---

## Limits

| Limit | Wert |
|-------|-------|
| Batch-Größe | Planabhängig (Founding: deaktiviert) |
| Monatliche Konvertierungen | Planabhängig (gesamter Batch wird vorab geprüft) |
| Webhook-Zustellungs-Timeout | 30 Sekunden (keine Wiederholungsversuche) |
| Maximale Cookies pro Anfrage | 50 |
| Maximale benutzerdefinierte Header pro Anfrage | 20 |
| Aufbewahrungsdauer der Dateien | Planabhängig |

## Häufig gestellte Fragen

### Wie konvertiere ich mehrere URLs mit einer einzigen API-Anfrage in PDF?

Sende ein POST an `/v1/convert/url-to-pdf` mit einem Array von URLs im Parameter `url`, authentifiziert mit einem privaten API-Key (`sk_...`). Die API antwortet mit `HTTP 202` und einer `batch_id`, und jede URL wird im Hintergrund konvertiert.

### Kann ich alle Batch-Konvertierungsergebnisse in einer einzigen ZIP-Datei erhalten?

Ja. Setze `output_format` auf `true`, um alle erfolgreichen Ergebnisse in einem ZIP-Archiv mit dem Namen `{output_filename}_{timestamp}.zip` zu bündeln (oder `batch_{timestamp}.zip`, falls kein benutzerdefinierter Name angegeben wird). ZIP-Ausgabe erfordert einen Plan mit Zugriff auf ZIP-Ausgabe (Studio, Production oder Enterprise) und mehrere URLs in der Anfrage.

### Wie prüfe ich den Status eines Batch-Konvertierungsjobs?

Frage `GET /v1/convert/batch/{batch_id}` mit deinem privaten API-Key per Polling ab. Die Antwort meldet `processing`, `completed`, `partial` oder `failed`, zusammen mit URL-bezogenen Einträgen, die `download_url`, `output_file_size` und `duration` enthalten.

### Warum gibt meine Batch-Anfrage 403 Forbidden zurück?

Ein `403 Forbidden` bedeutet, dass eine Plan-Einschränkung ausgelöst wurde: Async-Verarbeitung ist in deinem Plan nicht verfügbar, Batch-Verarbeitung ist deaktiviert (Batch-Limit ist 0), die Batch-Größe überschreitet das Limit deines Plans, oder ein freischaltbares Feature wie ZIP-Ausgabe oder Webhook-Callbacks ist nicht in deinem Plan enthalten.

### Kann ich Batch-Verarbeitung mit einem öffentlichen API-Key verwenden?

Nein. Batch-Verarbeitung erfordert einen privaten API-Key (`sk_...`). Öffentliche Keys sind auf synchrone Anfragen mit einer einzelnen URL beschränkt, und das Absenden mehrerer URLs mit einem öffentlichen Key liefert `400 Bad Request` zurück.