` | keiner | Regex-Positivliste und Sperrliste, jeweils maximal 50 Einträge. Die Sperrliste wird als zweites angewendet. |
| `sameDomainOnly`, `respectRobots` | `boolean` | `true`, keiner | Auf der Ausgangsdomain bleiben und die Robots-Regeln der Website berücksichtigen. |
### Lookup
Kategorisierte Websuche, die die besten Treffer auf Wunsch automatisch rendert. Endpunkt-Referenz: [Lookup](/de/docs/v2-lookup).
```java
LookupResult search = client.v2.lookup("best static site generators",
LookupOptions.builder()
.category("web") // web, news, images, scholar, patents, maps
.numResults(10)
.country("us")
.timeFilter("month") // hour, day, week, month, year
.perceiveTop(3) // die 3 besten Treffer automatisch rendern
.build());
search.results().forEach(hit -> {
System.out.println(hit.position() + " " + hit.title() + " " + hit.url());
if (hit.perceive() != null) System.out.println(" quality " + hit.perceive().renderQuality());
});
```
Mit `perceiveTop` über 0 (0 bis 10, Standard 0) werden die URLs der ersten N Treffer über perceive gerendert, und jeder Treffer trägt sein vollständiges `PerceiveResult` inline auf `hit.perceive()`. `numResults` läuft von 1 bis 100 und ist standardmäßig 10; `page` läuft von 1 bis 10.
### Distill
Schemagesteuerte strukturierte Extraktion über eine oder mehrere Seiten. Endpunkt-Referenz: [Distill](/de/docs/v2-distill).
```java
DistillResult extraction = client.v2.distill(
DistillOptions.builder(Map.of("products", "list of product names with their listed price"))
.urls(List.of("https://example.com/catalog"))
.cssSchema(CssSchema.builder(".product-card", List.of(
CssField.builder("name", "text").selector("h3").build(),
CssField.builder("price", "text").selector(".price").build()))
.targetField("products")
.build())
.build());
extraction.results().forEach(item ->
System.out.println(item.data() + " via " + item.extractionTier()));
```
Das optionale `cssSchema` führt zuerst einen kostenlosen CSS-Durchlauf aus; nur die Felder, die es nicht beantworten kann, steigen in die LLM-Stufe auf, und `item.extractionTier()` meldet, welcher Weg den Datensatz erzeugt hat (`css`, `llm`, `mixed` oder `none`). Du kannst die URLs auch zuerst ermitteln lassen, statt sie aufzulisten:
```java
client.v2.distill(
DistillOptions.builder(Map.of("title", "page title", "summary", "one-line summary"))
.discoverFrom(new DistillDiscoverFrom("https://example.com", "sitemap", 10))
.build());
```
Genau eines von `urls` (maximal 50) und `discoverFrom` muss gesetzt sein, und `schema` ist von der Builder-Factory vorgeschrieben. Beide Regeln werden clientseitig geprüft und werfen eine `IllegalArgumentException`, bevor eine Anfrage rausgeht.
### Ingest
Verwandle eine ganze Website oder einen Satz hochgeladener Dokumente über eine einzige Pipeline in gechunktes, RAG-fertiges JSONL. Ingest arbeitet immer asynchron. Endpunkt-Referenz: [Ingest](/de/docs/v2-ingest).
```java
// Von einer Website
IngestJob job = client.v2.ingest(IngestOptions.builder()
.mode("sitemap") // "urls" (Standard), "sitemap", "crawl"
.url("https://docs.example.com")
.maxPages(100)
.chunk(new IngestChunkOptions(512, 1)) // maxWords, sentenceOverlap
.webhookUrl("https://my.app/hooks/enconvert")
.build());
// Oder aus hochgeladenen Dateien
IngestJob fileJob = client.v2.ingestFiles(
List.of(new FileInput(Files.readAllBytes(Path.of("handbook.pdf")), "handbook.pdf"),
new FileInput(Files.readAllBytes(Path.of("notes.docx")), "notes.docx")),
IngestFilesOptions.builder().chunk(new IngestChunkOptions(512, 1)).build());
// Auf das JSONL pollen
IngestJob status = client.v2.getIngestJob(job.jobId());
if ("completed".equals(status.status())) {
System.out.println(status.outputUrl() + " (" + status.totalChunks() + " chunks)");
}
client.v2.listIngestJobs(V2ListOptions.builder().limit(20).build());
client.v2.cancelIngestJob(job.jobId()); // idempotent
```
`ingestFiles` akzeptiert PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT und MD sowie ältere und ODF-Office-Formate. Das Chunking liegt standardmäßig bei 512 Wörtern (32 bis 4000) mit 1 Satz Überlappung (0 bis 10). `mode` ist standardmäßig `urls`, was eine nicht leere `urls`-Liste verlangt und `url` verbietet; jeder andere Modus verlangt eine Start-`url` und verbietet `urls`. Das SDK erzwingt diese Paarung vor dem Senden.
Abschluss-Webhooks sind HMAC-signiert. Hole dir das Secret und die Header-Namen, die du zur Verifikation einer Zustellung brauchst, rotiere es bei einem Leck und stoße eine Zustellung neu an, die dein Endpunkt verpasst hat:
```java
WebhookSecret secret = client.v2.getWebhookSecret();
System.out.println(secret.signatureHeader() + " " + secret.signatureScheme());
client.v2.rotateWebhookSecret(); // alte Signaturen verifizieren sofort nicht mehr
WebhookRetryResult retry = client.v2.retryIngestWebhook(job.jobId());
System.out.println(retry.delivered() + " after " + retry.attempts() + " attempts");
```
### Watch
Wiederkehrende Änderungsüberwachung einer URL, mit Benachrichtigung per E-Mail und Webhook. Endpunkt-Referenz: [Watch](/de/docs/v2-watch).
```java
Watcher watcher = client.v2.createWatcher("https://example.com/pricing",
WatchCreateOptions.builder()
.frequencyMinutes(60) // 60 bis 43200, Untergrenze eine Stunde
.diffMode("auto") // auto, text, structured, tables, metadata
.webhookUrl("https://my.app/hooks/changes")
.notifyEmail(true)
.build());
WatcherSnapshotList history = client.v2.getWatcherSnapshots(watcher.watcherId(),
SnapshotListOptions.builder().limit(10).build());
history.snapshots().forEach(s ->
System.out.println(s.checkedAt() + " changed=" + s.hasChanges()
+ " similarity=" + s.similarity()));
client.v2.updateWatcher(watcher.watcherId(), WatcherUpdate.builder().status("paused").build());
client.v2.updateWatcher(watcher.watcherId(), WatcherUpdate.builder().webhookUrl("").build());
client.v2.deleteWatcher(watcher.watcherId()); // Soft Delete, idempotent
```
`listWatchers()` und `getWatcher(watcherId)` lesen sie wieder aus. `updateWatcher` verlangt mindestens ein Feld und wirft andernfalls eine `IllegalArgumentException`. Ein ausdrücklich leerer String für `webhookUrl` löscht den Webhook, während ein null-Wert "keine Änderung" bedeutet. `deleteWatcher` ist ein Soft Delete: Es gibt den als gelöscht markierten Watcher mit Status `deleted` zurück, und ein gelöschter Watcher liest sich danach als `404`.
Snapshot-Diffs enthalten nicht vertrauenswürdige Seiteninhalte. WatcherSnapshot.changes() ist Rohtext, der aus der überwachten Seite stammt. Escape ihn, bevor du ihn in einem Dashboard, einer E-Mail oder einer Chat-Nachricht darstellst.
---
## PDF-Optionen
`PdfOptions` wird von `convertUrlToPdf`, `convertWebsiteToPdf`, `convertDocument`, `convertToPdf` und `PerceiveOptions.pdfOptions` gemeinsam genutzt.
```java
client.convertUrlToPdf("https://internal.example.com/report",
UrlToPdfOptions.builder()
.pdfOptions(PdfOptions.builder()
.pageSize("A4")
.orientation("landscape")
.margins(new PdfMargins(10.0, 10.0, 15.0, 15.0))
.scale(0.9)
.header(new PdfHeaderFooter("Quarterly Report", 15.0))
.footer(new PdfHeaderFooter("Confidential", 12.0))
.build())
.auth(new HttpBasicAuth("user", "pass"))
.cookies(List.of(BrowserCookie.builder("session", "abc123").domain("internal.example.com").build()))
.headers(Map.of("X-Tenant", "acme"))
.saveTo("report.pdf")
.build());
```
| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `pageSize` | `String` | `"A4"`, `"A3"`, `"Letter"`, `"Legal"` und Ähnliches. |
| `pageWidth`, `pageHeight` | `double` | Eigene Maße. Gemeinsam gesetzt überschreiben sie `pageSize`. |
| `orientation` | `String` | `"portrait"` oder `"landscape"`. |
| `margins` | `PdfMargins` | Record aus `top`, `bottom`, `left`, `right`. Jedes null-Feld wird weggelassen. |
| `scale` | `double` | Render-Skalierung, zum Beispiel `0.9` für 90 Prozent. |
| `grayscale` | `boolean` | Wandelt das PDF nachträglich in Graustufen um. |
| `header`, `footer` | `PdfHeaderFooter` | Record aus `content` (maximal 2000 Zeichen) und `height`. |
`BrowserCookie` braucht Name und Wert sowie entweder `domain` oder `url`; wenn `domain` ohne `path` gesetzt ist, setzt die API `path` standardmäßig auf `/`. Kombiniere `auth` nicht mit einem expliziten `Authorization`-Header, denn die API lehnt diesen Konflikt ab.
---
## Fehlerbehandlung
Jede SDK-Exception erbt von `EnconvertException`, das wiederum von `RuntimeException` erbt, nichts erzwingt an deinen Aufrufstellen also eine `throws`-Klausel. Fange die spezifischen Unterklassen zuerst ab.
```java
try {
client.convertUrlToPdf("https://example.com");
} catch (AuthenticationException e) {
System.err.println("Invalid or missing API key");
} catch (QuotaException e) {
System.err.println("Request refused with 402: " + e.getMessage());
} catch (RateLimitException e) {
System.err.println("Too many requests, back off and retry");
} catch (ApiException e) {
System.err.println("API error [" + e.getStatusCode() + "]: " + e.getMessage());
}
```
| Klasse | Ausgelöst bei | Statuscode |
|-------|-----------|-------------|
| `AuthenticationException` | Fehlender, ungültiger oder nicht berechtigter API-Key | `401`, `403` |
| `QuotaException` | HTTP 402 | `402` |
| `RateLimitException` | Zu viele Anfragen | `429` |
| `ApiException` | Jede andere 4xx- oder 5xx-Antwort | der tatsächliche Code |
| `EnconvertException` | Basisklasse, wird auch bei Transportfehlern, einer unterbrochenen Anfrage oder einer nicht lesbaren Eingabedatei ausgelöst | keiner |
Clientseitige Validierung (ein nicht unterstütztes Konvertierungspaar, ein fehlendes distill-Schema, ein leeres Watcher-Update, die falsche Anzahl Ausgaben für `perceiveDirect`) wirft eine `IllegalArgumentException`, bevor eine Anfrage gestellt wird. Die Zuordnung der Meldungen für Serverantworten findest du in der Referenz [Fehlercodes](/de/docs/error-codes).
---
## Timeout-Recovery
Lange URL-Renders und große Dokumentkonvertierungen können das Reverse-Proxy-Timeout überdauern, selbst wenn die Konvertierung am Ende erfolgreich ist. Das SDK behandelt das transparent:
1. Vor jeder Anfrage für eine einzelne URL oder einen Datei-Upload erzeugt das SDK eine UUID und sendet sie als `job_id`.
2. Kommt die Anfrage mit 5xx zurück, wechselt das SDK dazu, `GET /v1/convert/status/{jobId}` alle 3 Sekunden abzufragen.
3. Bei `success` gibt es das Ergebnis zurück. Bei `failed` wirft es eine `ApiException` mit der Fehlermeldung des Servers.
4. Die Polling-Frist beträgt 5 Minuten. Danach wirft es `ApiException(504, "Conversion timed out")`.
Du schreibst dafür keinen Code. Wenn eine erfolgreiche Antwort `job_id` weglässt, trägt das SDK die selbst erzeugte ID nach, `result.jobId()` ist also immer mit `getJobStatus` verwendbar.
Website-Batch-Übermittlungen sind bewusst ausgenommen. convertWebsiteToPdf und convertWebsiteToScreenshot haben keine Job-Zeile zum Abfragen, ein 5xx bedeutet dort also, dass die Übermittlung selbst fehlgeschlagen ist, und wird direkt gemeldet. V2-Endpunkte nutzen ebenfalls kein Job-Polling; ihre asynchronen Abläufe laufen über getPerceiveBatch und getIngestJob.
---
## Konfiguration
```java
Enconvert client = Enconvert.builder(System.getenv("ENCONVERT_API_KEY"))
.baseUrl("https://api.enconvert.com")
.timeout(Duration.ofSeconds(300))
.build();
```
Drei Konstruktoren stehen als Kurzform bereit: `new Enconvert(apiKey)`, `new Enconvert(apiKey, baseUrl)` und `new Enconvert(apiKey, baseUrl, timeout)`.
| Option | Typ | Standard | Beschreibung |
|--------|------|---------|-------------|
| `apiKey` | `String` | erforderlich | Privater API-Key. Ein null-Wert oder leerer Wert wirft eine `IllegalArgumentException`. |
| `baseUrl` | `String` | `https://api.enconvert.com` | Basis-URL der API. Abschließende Schrägstriche werden entfernt. |
| `timeout` | `Duration` | 300 Sekunden | Gilt sowohl als Verbindungs-Timeout als auch als Timeout pro Anfrage. |
Der Key reist im Header `X-API-Key`. Vorsignierte Download-URLs werden ohne ihn abgerufen, da sie bereits signiert sind. Key-Typen behandelt die [Authentifizierung](/de/docs/authentication); Keys erstellst und verwaltest du im [Dashboard](/de/dashboard).
Schreibe den API-Key niemals fest in den Code. Lies ihn aus einer Umgebungsvariablen oder deinem Secret-Manager. Das SDK ist ausschließlich serverseitig: Ein privater Key darf nicht in einem Desktop- oder Mobile-Artefakt ausgeliefert werden, das ein Nutzer entpacken kann.
---
## Ergebnisform
Jede Konvertierung einer einzelnen Datei oder einer einzelnen URL gibt dasselbe Record zurück:
```java
public record ConversionResult(
String presignedUrl,
String objectKey,
String filename,
Long fileSize,
Double conversionTimeSeconds,
String jobId) {}
```
Die vorsignierte URL ist zeitlich begrenzt. Übergib `saveTo` (oder rufe die URL selbst ab) und speichere die Bytes in deinem eigenen Bucket, wenn sie diese Frist überdauern sollen.
Die anderen Antwort-Records, mit denen du am häufigsten zu tun hast:
| Record | Wichtige Accessoren |
|--------|---------------|
| `JobStatus` | `status()` (`processing`, `success`, `failed`), `presignedUrl()`, `objectKey()`, `error()` |
| `BatchStatus` | `status()`, `total()`, `completed()`, `failed()`, `inProgress()`, `zipDownloadUrl()`, `items()` |
| `PerceiveResult` | `operationId()`, `renderQuality()`, `statusCode()`, `deductions()`, `outputs()`, `structured()`, `cacheHit()`, `warnings()` |
| `V2OutputArtifact` | `url()`, `objectKey()`, `sizeBytes()`, `contentType()`, `expiresIn()` |
| `PerceiveDirectResult` | `content()`, `contentType()`, `filename()`, `renderQuality()`, `contentHash()` |
| `IngestJob` | `jobId()`, `status()`, `pagesProcessed()`, `totalChunks()`, `outputUrl()`, `webhookDelivered()` |
| `Watcher` | `watcherId()`, `status()`, `frequencyMinutes()`, `checksCount()`, `nextCheckAt()`, `lastChangeAt()` |
Felder, deren Struktur durch deine eigene Anfrage bestimmt wird (`structured`, `data`, `trackFields`, Snapshot-`changes`), werden als Gson-`JsonObject` bereitgestellt und unverändert durchgereicht. Zeichenketten-basierte Aufzählungen bleiben `String` und werden nicht zu Java-`enum`-Konstanten, ein neuerer API-Wert bricht also nie die Deserialisierung in einem älteren SDK-Build. `com.enconvert.model.v2.V2Enums` enthält jeden akzeptierten Wert als tippfehlersichere Konstante.
---
## Quelle und Issues
- **Maven Central:** `com.enconvert:enconvert-sdk:0.0.1`
- **GitHub:** [conversionapi/java-sdk](https://github.com/conversionapi/java-sdk)
- **Lizenz:** MIT
- **Weitere Clients:** [alle SDKs](/de/docs/sdks) · [Endpunkt-Referenz](/de/docs/endpoints-overview) · [Preise](/de/pricing)
---
## Häufig gestellte Fragen
### Wie konvertiere ich Dateien in Java mit einer Maven-Abhängigkeit?
Füge `com.enconvert:enconvert-sdk:0.0.1` zu deiner `pom.xml` oder `build.gradle` hinzu, baue einen Client mit `new Enconvert(System.getenv("ENCONVERT_API_KEY"))` und rufe eine typisierte Methode wie `convertUrlToPdf`, `convertImage`, `convertDocument` oder `convertToPdf` auf. Übergib `saveTo` im Options-Builder, um die Ausgabe direkt auf die Festplatte zu schreiben, statt die vorsignierte URL selbst zu verarbeiten.
### Wie konvertiere ich eine URL in Java in ein PDF?
Rufe `client.convertUrlToPdf(url, UrlToPdfOptions.builder().saveTo("page.pdf").build())` auf. Setze `singlePage(false)`, um anhand von `pdfOptions.pageSize` zu paginieren, statt eine einzige fortlaufende Seite zu erzeugen, und übergib `auth`, `cookies` oder `headers` für eine Seite hinter einem Login.
### Wie konvertiere ich DOCX in Java in ein PDF?
Rufe `client.convertDocument(Path.of("report.docx"), ConvertDocumentOptions.builder().saveTo("report.pdf").build())` auf. Das Ausgabeformat ist standardmäßig `pdf`, du setzt `outputFormat` also nur, wenn du etwas anderes willst, zum Beispiel `yaml` aus einer `.json`-Eingabe. Für Formate ohne eigenes Paar, etwa EPUB oder RTF, nimm `convertToPdf`.
### Wie konvertiere ich HEIC in Java in WebP?
Rufe `client.convertImage(Path.of("photo.heic"), ConvertImageOptions.builder("webp").saveTo("photo.webp").build())` auf. Das Eingabeformat ergibt sich aus der Dateiendung, und das Ausgabeformat ist das erforderliche Builder-Argument. `jpeg`, `png`, `svg`, `heic` und `webp` konvertieren alle untereinander, und `pdf` wird zu `jpeg` gerastert. Eine Methode zum Komprimieren an Ort und Stelle gibt es in diesem Client nicht.
### Wie scrape ich aus Java eine Webseite in sauberes Markdown?
Es gibt zwei Wege. `client.convertUrlToMarkdown(url, ...)` liefert GitHub Flavored Markdown mit YAML-Frontmatter als herunterladbare Datei. `client.v2.perceive(url, PerceiveOptions.builder().outputs(List.of("markdown")).build())` liefert denselben Inhalt als agentenfertiges Artefakt mit einem `renderQuality`-Wert, Extraktionsoptionen und Cache-Steuerung. Nimm perceive, wenn ein schlechter Lesevorgang erkennbar sein muss statt still zu bleiben.
### Was ist renderQuality und warum trägt jeder Lesevorgang einen Wert?
`renderQuality` ist ein Wert von 0.0 bis 1.0, der an jedem V2-Render hängt. Ein hoher Wert bedeutet, dass die Seite sauber gerendert wurde; ein niedriger Wert bedeutet, dass etwas dazwischenkam, etwa eine Bot-Challenge, eine Cookie-Wall, ein Login-Bildschirm, eine HTTP-Fehlerseite oder eine leere SPA-Hülle. Der Inhalt wird trotzdem zurückgegeben, mit gefüllten `warnings()` und `deductions()`, sodass deine Pipeline den Lesevorgang verwerfen oder wiederholen kann, statt eine Challenge-Seite so an ein Modell zu geben, als wäre sie der Artikel.
### Wie verwandle ich eine Doku-Website in Java in RAG-fertige Chunks?
Rufe `client.v2.ingest(IngestOptions.builder().mode("sitemap").url("https://docs.example.com").maxPages(100).chunk(new IngestChunkOptions(512, 1)).build())` auf. Der Job ist asynchron, frage also entweder `getIngestJob(jobId)` ab, bis der Status `completed` lautet, und lies `outputUrl()` für das JSONL, oder setze `webhookUrl` und verifiziere die HMAC-Signatur mit dem Secret aus `getWebhookSecret()`. Für lokale Dokumente statt einer Website nimm `ingestFiles`.
### Wie geht das SDK mit Konvertierungen um, die das Proxy-Timeout überdauern?
Vor jeder Anfrage für eine einzelne URL oder einen Datei-Upload erzeugt es eine UUID und sendet sie als `job_id`. Gibt die Anfrage 5xx zurück, fragt es `GET /v1/convert/status/{jobId}` alle 3 Sekunden ab, bis der Job `success` oder `failed` meldet, mit einer Frist von 5 Minuten, nach der es `ApiException(504, "Conversion timed out")` wirft. Batch-Übermittlungen für ganze Websites sind ausgenommen, weil sie keine Job-Zeile zum Abfragen haben.
### Welche Java-Version verlangt das SDK, und was zieht es nach?
Java 17 oder neuer. HTTP läuft über den `java.net.http.HttpClient` des JDK, und Gson ist das einzige Drittanbieter-Artefakt auf dem Classpath. Antworten sind Java-Records, ein modernes `switch` oder Pattern-Matching darüber funktioniert also wie erwartet. Der Client ist threadsicher: Halte eine Instanz und teile sie.