` | aucun | Liste blanche et liste noire d'expressions régulières, 50 entrées maximum chacune. La liste noire est appliquée en second. |
| `sameDomainOnly`, `respectRobots` | `boolean` | `true`, aucun | Rester sur le domaine de départ, et respecter les règles robots du site. |
### Lookup
Recherche web catégorisée, avec rendu automatique facultatif des meilleurs résultats. Référence de l'endpoint : [Lookup](/fr/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) // rend automatiquement les 3 premiers résultats
.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());
});
```
Avec `perceiveTop` supérieur à 0 (de 0 à 10, 0 par défaut), les N premières URL de résultats sont rendues via perceive et chaque résultat porte son `PerceiveResult` complet en ligne sur `hit.perceive()`. `numResults` va de 1 à 100 et vaut 10 par défaut ; `page` va de 1 à 10.
### Distill
Extraction structurée pilotée par schéma, sur une ou plusieurs pages. Référence de l'endpoint : [Distill](/fr/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()));
```
Le `cssSchema` facultatif exécute d'abord une passe CSS gratuite ; seuls les champs auxquels elle ne peut pas répondre escaladent vers le niveau LLM, et `item.extractionTier()` indique quel chemin a produit l'enregistrement (`css`, `llm`, `mixed` ou `none`). Vous pouvez aussi découvrir les URL au préalable au lieu de les lister :
```java
client.v2.distill(
DistillOptions.builder(Map.of("title", "page title", "summary", "one-line summary"))
.discoverFrom(new DistillDiscoverFrom("https://example.com", "sitemap", 10))
.build());
```
Exactement l'un de `urls` (50 maximum) et `discoverFrom` doit être défini, et `schema` est exigé par la fabrique du builder. Les deux règles sont vérifiées côté client et lèvent une `IllegalArgumentException` avant qu'aucune requête ne parte.
### Ingest
Transforme un site entier, ou un ensemble de documents envoyés, en JSONL découpé et prêt pour le RAG, à travers un seul pipeline. Ingest est toujours asynchrone. Référence de l'endpoint : [Ingest](/fr/docs/v2-ingest).
```java
// Depuis un site
IngestJob job = client.v2.ingest(IngestOptions.builder()
.mode("sitemap") // "urls" (par défaut), "sitemap", "crawl"
.url("https://docs.example.com")
.maxPages(100)
.chunk(new IngestChunkOptions(512, 1)) // maxWords, sentenceOverlap
.webhookUrl("https://my.app/hooks/enconvert")
.build());
// Ou depuis des fichiers envoyés
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());
// Interroger jusqu'à obtenir le JSONL
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` accepte les formats PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT et MD, ainsi que les formats bureautiques hérités et ODF. Le découpage vaut par défaut 512 mots (de 32 à 4000) avec 1 phrase de chevauchement (de 0 à 10). `mode` vaut `urls` par défaut, ce qui exige une liste `urls` non vide et interdit `url` ; tous les autres modes exigent une `url` de départ et interdisent `urls`. Le SDK vérifie cet appariement avant l'envoi.
Les webhooks de fin sont signés en HMAC. Récupérez le secret et les noms d'en-têtes dont vous avez besoin pour vérifier une livraison, faites-le tourner en cas de fuite, et relancez une livraison que votre endpoint aurait manquée :
```java
WebhookSecret secret = client.v2.getWebhookSecret();
System.out.println(secret.signatureHeader() + " " + secret.signatureScheme());
client.v2.rotateWebhookSecret(); // les anciennes signatures cessent aussitôt d'être valides
WebhookRetryResult retry = client.v2.retryIngestWebhook(job.jobId());
System.out.println(retry.delivered() + " after " + retry.attempts() + " attempts");
```
### Watch
Surveillance récurrente des changements sur une URL, avec notification par e-mail et par webhook. Référence de l'endpoint : [Watch](/fr/docs/v2-watch).
```java
Watcher watcher = client.v2.createWatcher("https://example.com/pricing",
WatchCreateOptions.builder()
.frequencyMinutes(60) // de 60 à 43200, plancher horaire
.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()); // suppression logique, idempotente
```
`listWatchers()` et `getWatcher(watcherId)` permettent de les relire. `updateWatcher` exige au moins un champ et lève sinon une `IllegalArgumentException`. Une chaîne vide explicite pour `webhookUrl` efface le webhook, tandis que la laisser à null signifie « aucun changement ». `deleteWatcher` est une suppression logique : elle renvoie le watcher marqué avec le statut `deleted`, et un watcher supprimé se relit ensuite en `404`.
Les diffs de snapshots contiennent du contenu de page non fiable. WatcherSnapshot.changes() est du texte brut repris de la page surveillée. Échappez-le avant de l'afficher dans un tableau de bord, un e-mail ou un message de chat.
---
## Options PDF
`PdfOptions` est partagé par `convertUrlToPdf`, `convertWebsiteToPdf`, `convertDocument`, `convertToPdf` et `PerceiveOptions.pdfOptions`.
```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());
```
| Champ | Type | Description |
|-------|------|-------------|
| `pageSize` | `String` | `"A4"`, `"A3"`, `"Letter"`, `"Legal"`, et similaires. |
| `pageWidth`, `pageHeight` | `double` | Dimensions personnalisées. Définies ensemble, elles remplacent `pageSize`. |
| `orientation` | `String` | `"portrait"` ou `"landscape"`. |
| `margins` | `PdfMargins` | Record composé de `top`, `bottom`, `left`, `right`. Tout champ null est omis. |
| `scale` | `double` | Échelle de rendu, par exemple `0.9` pour 90 pour cent. |
| `grayscale` | `boolean` | Post-traite le PDF en niveaux de gris. |
| `header`, `footer` | `PdfHeaderFooter` | Record composé de `content` (2000 caractères maximum) et `height`. |
`BrowserCookie` a besoin d'un nom et d'une valeur, plus soit `domain`, soit `url` ; lorsque `domain` est défini sans `path`, l'API fixe `path` à `/` par défaut. Ne combinez pas `auth` avec un en-tête `Authorization` explicite, car l'API rejette ce conflit.
---
## Gestion des erreurs
Chaque exception du SDK hérite d'`EnconvertException`, qui hérite elle-même de `RuntimeException` : rien ne vous impose donc une clause `throws` sur vos sites d'appel. Attrapez d'abord les sous-classes spécifiques.
```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());
}
```
| Classe | Déclenchée sur | Code de statut |
|-------|-----------|-------------|
| `AuthenticationException` | Clé API manquante, invalide ou non autorisée | `401`, `403` |
| `QuotaException` | HTTP 402 | `402` |
| `RateLimitException` | Trop de requêtes | `429` |
| `ApiException` | Toute autre réponse 4xx ou 5xx | le code réel |
| `EnconvertException` | Classe de base, également levée en cas d'échec de transport, de requête interrompue ou de fichier d'entrée illisible | aucun |
La validation côté client (paire de conversion non prise en charge, schéma distill manquant, mise à jour de watcher vide, mauvais nombre de sorties pour `perceiveDirect`) lève une `IllegalArgumentException` avant qu'aucune requête ne soit émise. La table des messages des réponses serveur se trouve dans la référence [Codes d'erreur](/fr/docs/error-codes).
---
## Récupération des timeouts
Les rendus d'URL longs et les conversions de documents volumineux peuvent survivre au timeout du reverse proxy, même quand la conversion finit par réussir. Le SDK gère cela de manière transparente :
1. Avant chaque requête d'URL unique ou d'envoi de fichier, le SDK génère un UUID et l'envoie en tant que `job_id`.
2. Si la requête revient en 5xx, le SDK bascule vers le polling de `GET /v1/convert/status/{jobId}` toutes les 3 secondes.
3. Sur `success`, il renvoie le résultat. Sur `failed`, il lève une `ApiException` portant le message d'erreur du serveur.
4. Le délai maximal de polling est de 5 minutes. Au-delà, il lève `ApiException(504, "Conversion timed out")`.
Vous n'avez aucun code à écrire pour cela. Si une réponse réussie omet `job_id`, le SDK y réinjecte l'identifiant qu'il a généré, si bien que `result.jobId()` reste toujours utilisable avec `getJobStatus`.
Les soumissions de lots de site entier sont volontairement exclues. convertWebsiteToPdf et convertWebsiteToScreenshot n'ont pas de ligne de job à interroger : un 5xx signifie donc que la soumission elle-même a échoué, et l'erreur remonte directement. Les endpoints V2 n'utilisent pas non plus le polling de job ; leurs flux asynchrones passent par getPerceiveBatch et getIngestJob.
---
## Configuration
```java
Enconvert client = Enconvert.builder(System.getenv("ENCONVERT_API_KEY"))
.baseUrl("https://api.enconvert.com")
.timeout(Duration.ofSeconds(300))
.build();
```
Trois constructeurs sont disponibles comme raccourcis : `new Enconvert(apiKey)`, `new Enconvert(apiKey, baseUrl)` et `new Enconvert(apiKey, baseUrl, timeout)`.
| Option | Type | Par défaut | Description |
|--------|------|---------|-------------|
| `apiKey` | `String` | obligatoire | Clé API privée. Une valeur null ou vide lève une `IllegalArgumentException`. |
| `baseUrl` | `String` | `https://api.enconvert.com` | URL de base de l'API. Les barres obliques finales sont supprimées. |
| `timeout` | `Duration` | 300 secondes | Appliqué à la fois comme timeout de connexion et comme timeout par requête. |
La clé voyage dans l'en-tête `X-API-Key`. Les URL de téléchargement présignées sont récupérées sans elle, puisqu'elles sont déjà signées. Les types de clés sont traités dans [Authentification](/fr/docs/authentication) ; créez et gérez vos clés depuis le [tableau de bord](/fr/dashboard).
Ne codez jamais la clé API en dur. Lisez-la depuis une variable d'environnement ou votre gestionnaire de secrets. Le SDK est côté serveur uniquement : une clé privée ne doit pas être livrée dans un artefact desktop ou mobile qu'un utilisateur peut décompresser.
---
## Structure du résultat
Chaque conversion de fichier unique et d'URL unique renvoie le même record :
```java
public record ConversionResult(
String presignedUrl,
String objectKey,
String filename,
Long fileSize,
Double conversionTimeSeconds,
String jobId) {}
```
L'URL présignée est valable un temps limité. Passez `saveTo` (ou récupérez l'URL vous-même) et stockez les octets dans votre propre bucket si vous voulez qu'ils lui survivent.
Les autres records de réponse que vous manipulerez le plus souvent :
| Record | Accesseurs principaux |
|--------|---------------|
| `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()` |
Les champs dont la forme est définie par votre propre requête (`structured`, `data`, `trackFields`, les `changes` d'un snapshot) sont exposés en `JsonObject` Gson et passent sans modification. Les énumérations à valeurs textuelles restent des `String` plutôt que de devenir des constantes `enum` Java : une nouvelle valeur de l'API ne casse donc jamais la désérialisation sur une version plus ancienne du SDK. `com.enconvert.model.v2.V2Enums` contient chaque valeur acceptée sous forme de constante à l'abri des fautes de frappe.
---
## Source et problèmes
- **Maven Central :** `com.enconvert:enconvert-sdk:0.0.1`
- **GitHub :** [conversionapi/java-sdk](https://github.com/conversionapi/java-sdk)
- **Licence :** MIT
- **Autres clients :** [tous les SDK](/fr/docs/sdks) · [référence des endpoints](/fr/docs/endpoints-overview) · [tarifs](/fr/pricing)
---
## Questions fréquentes
### Comment convertir des fichiers en Java avec une dépendance Maven ?
Ajoutez `com.enconvert:enconvert-sdk:0.0.1` à votre `pom.xml` ou votre `build.gradle`, construisez un client avec `new Enconvert(System.getenv("ENCONVERT_API_KEY"))`, et appelez une méthode typée comme `convertUrlToPdf`, `convertImage`, `convertDocument` ou `convertToPdf`. Passez `saveTo` sur le builder d'options pour écrire la sortie directement sur le disque au lieu de gérer vous-même l'URL présignée.
### Comment convertir une URL en PDF en Java ?
Appelez `client.convertUrlToPdf(url, UrlToPdfOptions.builder().saveTo("page.pdf").build())`. Définissez `singlePage(false)` pour paginer selon `pdfOptions.pageSize` au lieu de produire une seule page continue, et passez `auth`, `cookies` ou `headers` pour une page derrière une authentification.
### Comment convertir un DOCX en PDF en Java ?
Appelez `client.convertDocument(Path.of("report.docx"), ConvertDocumentOptions.builder().saveTo("report.pdf").build())`. Le format de sortie vaut `pdf` par défaut : vous ne définissez donc `outputFormat` que lorsque vous voulez autre chose, par exemple `yaml` à partir d'une entrée `.json`. Pour les formats sans paire dédiée, comme l'EPUB ou le RTF, utilisez `convertToPdf`.
### Comment convertir du HEIC en WebP en Java ?
Appelez `client.convertImage(Path.of("photo.heic"), ConvertImageOptions.builder("webp").saveTo("photo.webp").build())`. Le format d'entrée vient de l'extension du fichier et le format de sortie est l'argument obligatoire du builder. `jpeg`, `png`, `svg`, `heic` et `webp` se convertissent tous les uns vers les autres, et `pdf` se rastérise en `jpeg`. Ce client ne propose pas de méthode de compression sur place.
### Comment récupérer une page web en Markdown propre depuis Java ?
Deux chemins. `client.convertUrlToMarkdown(url, ...)` renvoie du Markdown GitHub-Flavored avec un frontmatter YAML, sous forme de fichier téléchargeable. `client.v2.perceive(url, PerceiveOptions.builder().outputs(List.of("markdown")).build())` renvoie le même contenu sous forme d'artefact prêt pour un agent, avec un score `renderQuality`, des options d'extraction et un contrôle du cache. Utilisez perceive quand une mauvaise lecture doit être détectable plutôt que silencieuse.
### Qu'est-ce que renderQuality et pourquoi chaque lecture en porte-t-il un ?
`renderQuality` est un score de 0.0 à 1.0 attaché à chaque rendu V2. Un score élevé signifie que la page s'est rendue proprement ; un score bas signifie que quelque chose s'est interposé, par exemple un challenge anti-bot, un mur de cookies, un écran de connexion, une page d'erreur HTTP ou une coquille SPA vide. Le contenu est tout de même renvoyé, avec `warnings()` et `deductions()` renseignés, pour que votre pipeline puisse écarter ou relancer la lecture au lieu d'injecter une page de challenge dans un modèle comme s'il s'agissait de l'article.
### Comment transformer un site de documentation en fragments prêts pour le RAG en Java ?
Appelez `client.v2.ingest(IngestOptions.builder().mode("sitemap").url("https://docs.example.com").maxPages(100).chunk(new IngestChunkOptions(512, 1)).build())`. Le job est asynchrone : soit vous interrogez `getIngestJob(jobId)` jusqu'à ce que le statut soit `completed` puis lisez `outputUrl()` pour récupérer le JSONL, soit vous définissez `webhookUrl` et vérifiez la signature HMAC avec le secret renvoyé par `getWebhookSecret()`. Pour des documents locaux plutôt qu'un site, utilisez `ingestFiles`.
### Comment le SDK gère-t-il les conversions qui dépassent le timeout du proxy ?
Avant chaque requête d'URL unique ou d'envoi de fichier, il génère un UUID et l'envoie comme `job_id`. Si la requête renvoie un 5xx, il interroge `GET /v1/convert/status/{jobId}` toutes les 3 secondes jusqu'à ce que le job signale `success` ou `failed`, avec un délai maximal de 5 minutes au-delà duquel il lève `ApiException(504, "Conversion timed out")`. Les soumissions de lots de site entier sont exclues, parce qu'elles n'ont pas de ligne de job à interroger.
### Quelle version de Java le SDK exige-t-il, et qu'embarque-t-il ?
Java 17 ou plus récent. Le HTTP passe par le `java.net.http.HttpClient` du JDK, et Gson est le seul artefact tiers sur le classpath. Les réponses sont des records Java : un `switch` moderne ou un pattern matching sur ces types fonctionne donc comme attendu. Le client est thread-safe : gardez une seule instance et partagez-la.