SDK Python de conversion de fichiers#

enconvert est le client Python officiel de l'API EnConvert : un seul pip install, une seule clé API, et des méthodes typées pour convertir des fichiers et pour lire le web en direct. Il tourne sur Python 3.9 ou plus récent avec une seule dépendance runtime, requests, et embarque des annotations de type en ligne ainsi qu'un marqueur py.typed pour que mypy et Pyright voient tout. Le client a deux surfaces. Douze méthodes de conversion couvrent 43 paires {input}-to-{output}, plus URL vers PDF, capture d'écran et Markdown. L'espace de noms client.v2 ajoute la web intelligence : perceive, discover, lookup, distill, ingest et watch.

Installation#

pip install enconvert

uv add enconvert et poetry add enconvert fonctionnent de la même façon. requests est la seule dépendance runtime, et les stubs de types sont livrés dans la wheel : il n'y a donc aucun package types- à aller chercher.

Démarrage rapide#

Lisez une page comme votre agent devrait le faire, avec un score de qualité attaché, puis convertissez un fichier local via le même client.

import os

from enconvert import Enconvert

client = Enconvert(api_key=os.environ["ENCONVERT_API_KEY"])

op = client.v2.perceive("https://example.com", outputs=["markdown", "structured"])
print(op.outputs["markdown"].url, op.render_quality)

print(client.convert_to_pdf("report.docx", save_to="report.pdf").presigned_url)

Toutes les méthodes sont synchrones et bloquantes. Le SDK est exclusivement côté serveur : il s'authentifie avec une clé API privée, alors ne le livrez jamais à l'intérieur d'un client desktop, mobile ou navigateur. Récupérez une clé depuis votre tableau de bord, et consultez Authentification pour comprendre la portée des clés.

Ce que le client expose#

Enconvert constitue toute la surface publique. Les méthodes de conversion sont accrochées directement au client ; tout ce qui touche au web vit sous client.v2.

Tous les arguments qui suivent le premier argument positionnel sont nommés uniquement, en snake_case, et facultatifs sauf indication contraire dans un tableau. Les résultats sont des dataclasses figées : construisez donc une nouvelle instance plutôt que d'en muter une. Les formes REST se trouvent dans la vue d'ensemble des endpoints.

Conversion de fichiers#

Chaque méthode de conversion accepte save_to (un str ou un os.PathLike ; le résultat y est écrit en flux et les répertoires parents sont créés) et output_filename (remplace le nom généré). Les deux sont omis des tableaux ci-dessous.

convert_url_to_pdf#

Rendez en PDF n'importe quelle URL accessible.

result = client.convert_url_to_pdf(
    "https://example.com", single_page=False, viewport_width=1440, save_to="report.pdf"
)
print(result.presigned_url, result.file_size)

load_media et enable_scroll valent tous deux True par défaut : le premier attend les images et les vidéos, le second fait défiler de haut en bas pour que les chargements différés se déclenchent. Trois options supplémentaires permettent d'atteindre des pages derrière une porte : auth (HttpBasicAuth), cookies (list[BrowserCookie]) et headers (dict[str, str]).

convert_url_to_screenshot#

Capturez un PNG de n'importe quelle URL.

client.convert_url_to_screenshot("https://example.com", viewport_width=1440, save_to="shot.png")

Accepte les mêmes options de fenêtre, de médias, de défilement, de nom de fichier et d'accès navigateur que convert_url_to_pdf, sans single_page ni pdf_options.

convert_url_to_markdown#

Extrayez du Markdown GitHub-Flavored propre depuis une URL. La navigation, les pieds de page, les publicités et les scripts sont supprimés, le corps principal de l'article est conservé, et un frontmatter YAML avec titre, description, url, liens et images est ajouté en tête.

client.convert_url_to_markdown("https://example.com/article", save_to="article.md")

Même jeu d'options que convert_url_to_screenshot. Quand vous voulez en plus un score de qualité, les métadonnées de la page ou une extraction structurée sur la même lecture, utilisez plutôt v2.perceive.

convert_image#

Convertissez entre jpeg, png, svg, heic et webp, ou rastérisez un PDF en JPEG. Le format d'entrée vient de l'extension du nom de fichier.

client.convert_image("photo.heic", output_format="webp", save_to="photo.webp")
client.convert_image("scan.pdf", output_format="jpeg", save_to="scan.jpeg")

output_format est obligatoire et doit valoir jpeg, png, svg, heic ou webp ; les alias jpg, yml, htm et md sont normalisés pour vous. file accepte une chaîne de chemin, un os.PathLike, des bytes bruts, ou un wrapper FileData(data, filename). Les bytes bruts ne portent aucun nom de fichier et sont téléversés sous upload.bin : préférez donc FileData chaque fois que l'extension compte.

from pathlib import Path

from enconvert import FileData

blob = FileData(data=Path("photo.heic").read_bytes(), filename="photo.heic")
client.convert_image(blob, output_format="webp", save_to="photo.webp")

convert_document#

Convertissez des documents et des formats de données. output_format vaut "pdf" par défaut, et pdf_options est pris en compte lorsque la sortie est un PDF.

from enconvert import PdfMargins, PdfOptions

client.convert_document("report.docx", save_to="report.pdf")
client.convert_document("data.json", output_format="yaml", save_to="data.yaml")
client.convert_document(
    "README.md", pdf_options=PdfOptions(page_size="A4", margins=PdfMargins(top=20)), save_to="r.pdf"
)

Entrées prises en charge : .doc, .docx, .xls, .xlsx, .ppt, .pptx, .html, .htm, .odt, .ods, .odp, .ots, .pages, .numbers, .md, .markdown, .csv, .json, .xml, .yaml, .yml, .toml.

EPUB n'a pas de paire de document dédiée. Faites passer les .epub par convert_to_pdf ou convert_to_markdown.

convert_to_markdown#

Détectez automatiquement un document téléversé côté serveur et récupérez du Markdown propre. C'est la brique d'ingestion RAG pour un fichier unique.

client.convert_to_markdown("handbook.docx", save_to="handbook.md")

Entrées acceptées : PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT et MD, ainsi que les formats bureautiques anciens et ODF. Les images ne sont pas prises en charge ici, et l'endpoint n'accepte aucune option PDF. Pour un site entier plutôt qu'un seul fichier, utilisez v2.ingest.

convert_to_pdf#

Détectez automatiquement un fichier téléversé côté serveur et récupérez un PDF.

from enconvert import PdfOptions

client.convert_to_pdf("slides.pptx", save_to="slides.pdf")
client.convert_to_pdf("scan.pdf", pdf_options=PdfOptions(grayscale=True), save_to="gray.pdf")

Entrées acceptées : bureautique, ODF, Pages, Numbers, RTF, CSV, HTML, Markdown, texte brut, images matricielles, SVG, EPUB, et un PDF existant transmis tel quel. Comme une entrée .pdf est transmise telle quelle, cette méthode fait aussi office de normaliseur en niveaux de gris.

convert_website_to_pdf et convert_website_to_screenshot#

Découvrez chaque page d'un site, convertissez-les toutes en arrière-plan, et récupérez un seul ZIP. Les deux méthodes sont asynchrones par conception et renvoient immédiatement un BatchSubmission.

batch = client.convert_website_to_pdf(
    "https://example.com", crawl_mode="sitemap", exclude_patterns=["/blog/tag/"]
)
print(batch.batch_id, batch.url_count, batch.discovery_method)

status = client.wait_for_batch(batch.batch_id, save_to="site.zip")
print(status.completed, "of", status.total, "pages converted")

for item in client.get_batch_status(batch.batch_id).items:
    print(item.source_url, item.status, item.download_url)

Les options de rendu par page s'appliquent aussi à chaque URL découverte : viewport_width, viewport_height, load_media, enable_scroll, auth, cookies et headers. Tout ce qui reste non défini conserve la valeur par défaut de la passerelle.

wait_for_batch accepte interval_seconds (défaut 5.0), timeout_seconds (défaut 1800.0) et save_to. Il lève APIError(504, ...) si le lot est toujours en traitement une fois l'échéance passée.

Paires de conversion prises en charge#

Le SDK embarque une copie de la carte des conversions de la passerelle et rejette localement une paire non implémentée, avant tout aller-retour réseau, en nommant dans le message les sorties valides pour cette entrée.

Cela fait 43 paires implémentées. Vérifiez-les par programme :

from enconvert import IMPLEMENTED_CONVERSIONS, valid_outputs_for

valid_outputs_for("json")                  # ['csv', 'toml', 'xml', 'yaml']
"heic-to-webp" in IMPLEMENTED_CONVERSIONS  # True

La référence complète des paramètres vit dans Paramètres et options.

Web intelligence (V2)#

Chaque lecture V2 porte render_quality, un flottant de 0.0 à 1.0 qui dit avec quelle honnêteté la page s'est rendue. Un écran de défi, un mur de cookies, une porte de connexion, une page d'erreur HTTP ou une coquille vide d'application monopage revient avec un score bas, une table deductions nommant ce qui s'est déclenché, et une liste warnings. Le contenu est tout de même renvoyé, simplement signalé : une mauvaise lecture n'entre donc jamais discrètement dans le contexte de votre agent. Traitez le score comme une porte et vérifiez-le avant d'utiliser le texte. PerceiveResult, PerceiveDirectResult, DistillItem, LookupItem.perceive et WatcherSnapshot l'exposent tous. Les concepts se trouvent dans la vue d'ensemble V2.

Perceive#

Rendez une URL sous forme d'artefacts prêts pour un agent. Synchrone : l'appel renvoie l'opération terminée avec des URL d'artefacts signées.

op = client.v2.perceive(
    "https://example.com",
    outputs=["markdown", "screenshot", "structured"],
    extract=["tables", "metadata"],
    only_main_content=True,
)

print(op.render_quality)            # de 0.0 à 1.0
print(op.status_code)               # statut HTTP de la page elle-même
print(op.deductions)                # par ex. {"login_wall": 0.65}
print(op.outputs["markdown"].url)   # URL signée, 15 minutes
print(op.structured)

if (op.render_quality or 0) < 0.6:
    print("Low-confidence read:", op.warnings)

Également acceptés : schema (dict, un schéma d'extraction libre transmis intact), js_code (str, exécuté dans la page avant la capture), wait_timeout_ms (int), headers (dict[str, str]), cookies (list[BrowserCookie]), auth (HttpBasicAuth), proxy_url (str), geolocation (dict), action_chain (list[dict] d'étapes scriptées de clic, de saisie et de défilement), pdf_options (PdfOptions, appliqué à la sortie pdf), mobile (bool) et respect_robots (bool). perceive_batch prend le jeu identique, sauf direct_download.

Les URL d'artefacts sont resignées à chaque lecture : appelez donc client.v2.get_perceive_operation(op.operation_id) pour en obtenir une fraîche, plutôt que de mettre la chaîne en cache.

Octets bruts, sans aller-retour par URL signée. perceive_direct force direct_download et vous remet l'artefact lui-même, avec les métadonnées lues dans les en-têtes de la réponse.

direct = client.v2.perceive_direct("https://example.com", outputs=["markdown"])
print(direct.filename, direct.content_type, len(direct.content), direct.render_quality)

raw = client.v2.download_perceive_artifact(op.operation_id, output="markdown")

perceive_direct exige exactement une sortie produisant un artefact parmi markdown, html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links et images. structured peut accompagner la demande mais reste en ligne côté serveur ; passez autre chose et le SDK lève EnconvertError avant d'envoyer la requête. Sur download_perceive_artifact, output peut être omis lorsque l'opération n'a produit qu'un seul artefact, et un artefact sorti de sa fenêtre de rétention répond 410.

Lots. Jusqu'à 1000 URL partagent un seul bloc d'options. Les petits lots se terminent en ligne ; les plus gros reviennent avec le statut "queued", alors interrogez l'identifiant de tâche.

batch = client.v2.perceive_batch(
    ["https://a.example.com", "https://b.example.com"], outputs=["markdown"], output_mode="zip"
)

done = client.v2.get_perceive_batch(batch.job_id)
print(done.status, done.completed, done.failed, done.pending)
for item in done.items:
    print(item.url, item.render_quality)

output_mode vaut "manifest" (défaut) ou "zip" ; quand il vaut "zip", le bundle terminé se trouve sur done.zip.url. Détails dans Perceive.

Discover#

Énumérez les URL d'un site sans aucun rendu navigateur, ce qui en fait la première étape peu coûteuse avant de percevoir quoi que ce soit.

found = client.v2.discover(
    "https://example.com", mode="hybrid", max_urls=200, exclude_patterns=["/tag/"]
)
print(found.total, found.truncated, found.sources)

include_patterns et exclude_patterns (tous deux list[str]) filtrent l'ensemble de résultats. DiscoverResult.sources contient les décomptes bruts par source avant déduplication, par exemple {"sitemap": 42, "crawl": 30}. Pour aller plus loin : Discover.

Lookup#

Lancez une recherche web catégorisée, en rendant éventuellement les meilleurs résultats dans le même appel.

search = client.v2.lookup(
    "best static site generators", category="web", num_results=10, perceive_top=3
)

for hit in search.results:
    quality = hit.perceive.render_quality if hit.perceive else None
    print(hit.position, hit.title, hit.url, quality)

Également acceptés : country (str), locale (str), location (str) pour les requêtes sensibles à la géographie, et autocorrect (bool). LookupResult porte answer_box, knowledge_graph, perceive_operation_ids et perceive_top, ce dernier indiquant combien de résultats ont réellement été rendus, ce qui peut être inférieur à ce que vous avez demandé. Référence dans Lookup.

Distill#

Extraction structurée pilotée par schéma sur une ou plusieurs pages. Fournissez exactement l'un de urls ou discover_from ; schema est toujours obligatoire. Les deux règles sont appliquées côté client et lèvent EnconvertError avant qu'une requête ne parte.

from enconvert import CssField, CssSchema

extraction = client.v2.distill(
    urls=["https://example.com/pricing"],
    schema={"plans": "list of plan names with monthly prices"},
    css_schema=CssSchema(
        base_selector=".plan-card",
        fields=[
            CssField(name="name", type="text", selector="h3"),
            CssField(name="price", type="text", selector=".price"),
        ],
        target_field="plans",
    ),
)

for item in extraction.results:
    print(item.url, item.extraction_tier, item.fields_from_css, item.fields_from_llm, item.data)

Le css_schema facultatif s'exécute en premier et répond à tout ce que les sélecteurs peuvent atteindre. Seuls les champs qu'il manque escaladent vers le niveau modèle de langage, et extraction_tier sur chaque élément indique quel chemin a été emprunté : css, llm, mixed ou none.

Découvrir et extraire en un seul appel :

from enconvert import DistillDiscoverFrom

client.v2.distill(
    discover_from=DistillDiscoverFrom(url="https://example.com", mode="sitemap", max_pages=10),
    schema={"title": "page title"},
)

Également acceptés : wait_for (str), wait_timeout_ms (int), headers (dict[str, str]), cookies (list[BrowserCookie]) et respect_robots (bool). CssField prend en charge les types text, attribute, html, regex, nested, list et nested_list, avec les options attribute, pattern, default, transform (lowercase, uppercase, strip) et des fields imbriqués jusqu'à cinq niveaux de profondeur. Voir Distill.

Ingest#

Transformez un site entier, une liste d'URL explicite, ou un lot de documents téléversés en JSONL découpé et prêt pour le RAG. Ingest est toujours asynchrone.

import time

from enconvert import IngestChunkOptions

job = client.v2.ingest(
    mode="sitemap",
    url="https://docs.example.com",
    max_pages=100,
    chunk=IngestChunkOptions(max_words=512, sentence_overlap=1),
    webhook_url="https://my.app/hooks/enconvert",
)

status = client.v2.get_ingest_job(job.job_id)
while status.status in ("queued", "discovering", "processing"):
    time.sleep(10)
    status = client.v2.get_ingest_job(job.job_id)

print(status.status, status.pages_processed, status.total_chunks, status.output_url)

Les fichiers téléversés suivent le même cycle de vie de tâche sous le mode files. PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT et MD, ainsi que les formats bureautiques anciens et ODF sont acceptés, et chaque entrée peut être un chemin, un os.PathLike, des bytes bruts ou un FileData.

file_job = client.v2.ingest_files(["handbook.pdf", "notes.docx"])

Les options de forme de crawl et de rendu sont acceptées elles aussi : max_depth, same_domain_only, include_patterns, exclude_patterns, respect_robots, wait_for et wait_timeout_ms. ingest_files ne prend que chunk et webhook_url.

for summary in client.v2.list_ingest_jobs(limit=20).jobs:
    print(summary.job_id, summary.status, summary.total_chunks)

client.v2.cancel_ingest_job(job.job_id)
client.v2.retry_ingest_webhook(job.job_id)

secret = client.v2.get_webhook_secret()
print(secret.signature_header, secret.signature_scheme, secret.replay_tolerance_seconds)
client.v2.rotate_webhook_secret()

cancel_ingest_job est idempotent ; annuler une tâche déjà terminale la renvoie inchangée. retry_ingest_webhook répond 409 quand la tâche n'est pas terminée et 400 quand aucun webhook n'était configuré. rotate_webhook_secret invalide immédiatement le secret précédent. Couverture plus approfondie dans Ingest.

Watch#

Refaites le rendu d'une URL à une cadence fixe et faites-vous prévenir quand elle change.

watcher = client.v2.create_watcher(
    "https://example.com/pricing",
    frequency_minutes=60,
    diff_mode="auto",
    webhook_url="https://my.app/hooks/changes",
    notify_email=True,
)

for snap in client.v2.get_watcher_snapshots(watcher.watcher_id, limit=10).snapshots:
    print(snap.checked_at, snap.has_changes, snap.similarity, snap.change_count)

client.v2.list_watchers(limit=20)
client.v2.update_watcher(watcher.watcher_id, status="paused")
client.v2.update_watcher(watcher.watcher_id, webhook_url="")
client.v2.delete_watcher(watcher.watcher_id)

update_watcher a besoin d'au moins un champ et lève EnconvertError sinon ; status accepte "active" ou "paused", et un webhook_url vide efface le webhook. delete_watcher est une suppression douce et idempotente qui renvoie l'observateur marqué supprimé avec le statut "deleted", après quoi l'observateur répond 404.

Le moteur de diff et les charges utiles de notification sont documentés dans Watch.

Options PDF#

PdfOptions est une dataclass figée partagée par convert_url_to_pdf, convert_website_to_pdf, convert_document, convert_to_pdf et la famille v2.perceive.

from enconvert import BrowserCookie, HttpBasicAuth, PdfHeaderFooter, PdfMargins, PdfOptions

client.convert_url_to_pdf(
    "https://internal.example.com/report",
    pdf_options=PdfOptions(
        page_size="A4",
        orientation="landscape",
        margins=PdfMargins(top=10, bottom=10, left=15, right=15),
        scale=0.9,
        header=PdfHeaderFooter(content="Quarterly Report", height=15),
        footer=PdfHeaderFooter(content="Confidential", height=12),
    ),
    auth=HttpBasicAuth(username="user", password="pass"),
    cookies=[BrowserCookie(name="session", value="abc123", domain="internal.example.com")],
    save_to="report.pdf",
)

BrowserCookie prend name, value, et soit domain, soit url, plus les champs facultatifs path, expires, http_only, secure et same_site ("Strict", "Lax", "None"). Le SDK mappe http_only et same_site sur leurs clés camelCase de transport pour vous.

Gestion des erreurs#

Les erreurs sont des classes d'exception : attrapez-les donc avec except. Ordonnez les gestionnaires du spécifique au général : AuthenticationError, QuotaError et RateLimitError héritent tous de APIError, qui hérite de EnconvertError.

from enconvert import APIError, AuthenticationError, EnconvertError, QuotaError, RateLimitError

try:
    op = client.v2.perceive("https://example.com")
except AuthenticationError:
    print("Invalid or missing API key. Check ENCONVERT_API_KEY.")
except QuotaError as e:
    print(f"402 from the API: {e.message}")
except RateLimitError:
    print("Too many requests. Back off and retry.")
except APIError as e:
    print(f"API error [{e.status_code}]: {e.message}")
except EnconvertError as e:
    print(f"Rejected before the request was sent: {e}")

APIError porte status_code et message, et son str() se lit [404] Not found. Les levées côté client que vous pouvez rencontrer : une api_key vide, une extension de fichier non prise en charge, une paire de conversion non implémentée, un appel distill avec les deux ou aucun de urls et discover_from, une incohérence entre le mode et les arguments d'ingest, une charge utile update_watcher vide, et une liste de sorties perceive_direct qui ne se résout pas à exactement un artefact. La table complète des messages se trouve dans Codes d'erreur.

Récupération après timeout#

Les conversions longues d'URL et de documents peuvent survivre à un timeout du reverse proxy même quand le serveur termine la tâche. Le SDK Python récupère de façon transparente :

1. Avant chaque conversion de fichier unique ou d'URL unique, le SDK génère une chaîne hexadécimale UUID4 et l'envoie comme job_id.
2. Si cette requête revient en 5xx, le SDK bascule sur l'interrogation de GET /v1/convert/status/{job_id} toutes les 3 secondes. Un 404 à cet endroit signifie que la ligne de la tâche n'est pas encore écrite, donc l'interrogation continue.
3. Sur success le SDK renvoie le résultat comme si de rien n'était ; sur failed il lève APIError(500, ...) avec le message d'erreur du serveur ; et passé l'échéance d'interrogation de 300 secondes, il lève APIError(504, "Conversion timed out").

Vous n'écrivez aucun code pour cela. Quand une réponse arrive par le chemin de récupération, ConversionResult.job_id est renseigné pour que vous puissiez la corréler dans vos logs.

Deux exceptions. convert_website_to_pdf et convert_website_to_screenshot se retirent de ce mécanisme, parce qu'une soumission de site n'a pas de ligne de tâche propre : une 5xx signifie donc que la soumission elle-même a échoué et remonte directement. Les endpoints V2 ne sont pas interrogés non plus ; utilisez leurs propres identifiants de tâche avec get_perceive_batch ou get_ingest_job.

Configuration#

client = Enconvert(
    api_key=os.environ["ENCONVERT_API_KEY"], timeout=300.0, base_url="https://api.enconvert.com"
)

Le client conserve une requests.Session : les connexions sont donc mutualisées entre les appels ; réutilisez un seul client au lieu d'en construire un par requête. Votre clé voyage dans l'en-tête X-API-Key, et les téléchargements save_to attaquent l'URL de stockage signée par un simple GET non authentifié écrit sur le disque par blocs de 64 Ko : la clé ne quitte donc jamais l'hôte de l'API.

Forme du résultat#

Les méthodes de conversion renvoient un ConversionResult figé :

@dataclass(frozen=True)
class ConversionResult:
    presigned_url: str
    object_key: str
    filename: str
    file_size: int | None = None
    conversion_time_seconds: float | None = None
    job_id: str | None = None

L'URL pré-signée est de courte durée de vie. Passez save_to, ou récupérez l'URL vous-même, et stockez les octets dans votre propre bucket quand vous avez besoin d'un accès durable.

Les URL d'artefacts V2 sont signées pour 15 minutes et resignées à chaque lecture de l'opération : appelez donc get_perceive_operation plutôt que de mettre une chaîne d'URL en cache.

Source et tickets#

• PyPI : enconvert
• GitHub : conversionapi/python-sdk
• Python : 3.9, 3.10, 3.11, 3.12, 3.13
• Licence : MIT
• Autres clients : Tous les SDK

Questions fréquentes#

Comment convertir des fichiers en Python ?#

Lancez pip install enconvert, construisez un client avec Enconvert(api_key=os.environ["ENCONVERT_API_KEY"]), et appelez une méthode typée comme convert_document, convert_image, convert_to_pdf ou convert_to_markdown. Passez save_to="out.pdf" et le SDK écrit le fichier terminé en flux directement sur le disque, au lieu de vous remettre une URL à aller chercher vous-même.

Comment convertir une URL en PDF en Python ?#

Appelez client.convert_url_to_pdf("https://example.com", save_to="page.pdf"). Définissez single_page=False plus pdf_options=PdfOptions(page_size="A4") pour une sortie paginée, et ajustez viewport_width, load_media ou enable_scroll quand une page a besoin d'un canevas plus large ou d'images chargées en différé.

Comment convertir du DOCX en PDF en Python ?#

Soit client.convert_document("report.docx", save_to="report.pdf"), puisque output_format vaut déjà "pdf" par défaut, soit client.convert_to_pdf("report.docx", save_to="report.pdf") quand vous voulez la détection automatique du format côté serveur. Le même appel gère XLSX, PPTX, ODT, ODS, ODP, OTS, Pages et Numbers.

Comment convertir du HEIC en WebP en Python ?#

client.convert_image("photo.heic", output_format="webp", save_to="photo.webp"). Le format d'entrée vient de l'extension du nom de fichier, et jpeg, png, svg, heic et webp se convertissent tous les uns vers les autres. Vous travaillez en mémoire plutôt que sur disque ? Enveloppez les octets dans FileData(data=blob, filename="photo.heic") pour que l'extension survive.

Comment récupérer une page web en Markdown propre avec Python ?#

Utilisez client.v2.perceive(url, outputs=["markdown"]) et lisez op.outputs["markdown"].url, ou client.v2.perceive_direct(url, outputs=["markdown"]) pour récupérer les octets dans le corps de la réponse. Ajoutez only_main_content=True pour écarter la navigation et les pieds de page. Pour une conversion simple, sans scoring ni extraction, convert_url_to_markdown est l'appel le plus léger.

Que signifie render_quality, et quand faut-il réessayer une page ?#

C'est un flottant de 0.0 à 1.0 sur chaque lecture V2 qui dit avec quelle honnêteté la page s'est rendue. Un écran de défi, un mur de cookies, une porte de connexion, une page d'erreur HTTP ou une coquille vide d'application monopage obtiennent un score bas et nomment ce qui s'est déclenché dans deductions, avec le détail dans warnings et le statut HTTP propre à la page dans status_code. Servez-vous-en comme d'une porte : traitez un score bas comme un signal pour réessayer avec cache_mode="refresh", un sélecteur wait_for que seul le vrai contenu satisfait, ou des cookies différents, plutôt que de donner le texte à votre modèle.

Comment transformer un site de documentation entier en chunks RAG avec Python ?#

Appelez client.v2.ingest(mode="sitemap", url="https://docs.example.com", max_pages=100, chunk=IngestChunkOptions(max_words=512, sentence_overlap=1)). La tâche est asynchrone : interrogez donc get_ingest_job(job_id) jusqu'à ce que le statut quitte queued, discovering et processing, ou passez webhook_url et attendez d'être appelé. Le JSONL terminé se trouve à output_url. Pour des documents locaux plutôt qu'un site, ingest_files exécute le même pipeline.

Le SDK Python prend-il en charge asyncio ?#

Pas nativement. Toutes les méthodes sont synchrones et construites sur requests. Dans une application asynchrone, enveloppez les appels dans await asyncio.to_thread(client.convert_to_pdf, "report.docx") ou confiez-les à un concurrent.futures.ThreadPoolExecutor pour que la boucle d'événements continue de tourner. Le client peut être partagé entre threads sans risque, car il détient une requests.Session mutualisée.

Comment le SDK survit-il à un timeout de proxy sur une conversion longue ?#

Chaque conversion de fichier unique et d'URL unique envoie un job_id généré. Si la requête renvoie une 5xx, le SDK interroge GET /v1/convert/status/{job_id} toutes les 3 secondes pendant un maximum de 300 secondes, renvoie normalement dès que la tâche rapporte success, lève APIError(500, ...) si elle rapporte failed, et lève APIError(504, "Conversion timed out") si l'échéance est dépassée. Les soumissions de lots de sites sautent ce chemin, puisqu'un échec à cet endroit signifie que la soumission elle-même n'a pas abouti.