SDK Python per la conversione file#

enconvert è il client Python ufficiale per l'API EnConvert: un solo pip install, una sola chiave API e metodi tipizzati per convertire file e per leggere il web live. Gira su Python 3.9 o successivo con un'unica dipendenza runtime, requests, e include type hint inline più un marcatore py.typed, così mypy e Pyright vedono tutto. Il client ha due superfici. Nove metodi di conversione coprono 43 coppie {input}-to-{output} più URL in PDF, screenshot e Markdown, supportati da tre helper di polling dello stato. Il namespace client.v2 aggiunge la web intelligence: perceive, discover, lookup, distill, ingest e watch.

Installazione#

pip install enconvert

uv add enconvert e poetry add enconvert funzionano allo stesso modo. requests è l'unica dipendenza runtime, e gli stub di tipo viaggiano dentro la wheel, quindi non c'è nessun pacchetto types- da inseguire.

Guida rapida#

Leggi una pagina come dovrebbe farlo il tuo agente, con un punteggio di qualità allegato, poi converti un file locale con lo stesso 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)

Ogni metodo è sincrono e bloccante. L'SDK è solo lato server: si autentica con una chiave API privata, quindi non distribuirlo mai dentro un client desktop, mobile o browser. Prendi una chiave dalla tua dashboard e consulta Autenticazione per capire come sono definiti gli ambiti delle chiavi.

Cosa espone il client#

Enconvert è tutta la superficie pubblica. I metodi di conversione pendono direttamente dal client; tutto ciò che riguarda il web vive sotto client.v2.

Ogni argomento dopo il primo posizionale è solo per parola chiave, in snake_case e facoltativo, se non indicato diversamente in una tabella. I risultati sono dataclass congelate, quindi costruisci una nuova istanza invece di mutarne una. Le forme REST sono nella panoramica degli endpoint.

Conversione file#

Ogni metodo di conversione accetta save_to (uno str o un os.PathLike; il risultato viene scritto lì in streaming e le directory superiori vengono create) e output_filename (per sovrascrivere il nome generato). Entrambi sono omessi dalle tabelle qui sotto.

convert_url_to_pdf#

Esegue il rendering in PDF di qualsiasi URL raggiungibile.

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 ed enable_scroll valgono entrambi True per impostazione predefinita: il primo attende immagini e video, il secondo scorre dall'alto in basso così i lazy loader scattano. Altre tre opzioni raggiungono pagine dietro un accesso protetto: auth (HttpBasicAuth), cookies (list[BrowserCookie]) e headers (dict[str, str]).

convert_url_to_screenshot#

Cattura un PNG di qualsiasi URL.

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

Accetta le stesse opzioni di viewport, media, scroll, nome file e accesso al browser di convert_url_to_pdf, esclusi single_page e pdf_options.

convert_url_to_markdown#

Estrae Markdown GitHub-Flavored pulito da un URL. Navigazione, piè di pagina, pubblicità e script vengono rimossi, il corpo principale dell'articolo viene mantenuto e viene anteposto un frontmatter YAML con titolo, descrizione, url, link e immagini.

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

Stesso insieme di opzioni di convert_url_to_screenshot. Quando sulla stessa lettura vuoi anche un punteggio di qualità, i metadati della pagina o l'estrazione strutturata, usa invece v2.perceive.

convert_image#

Converte tra jpeg, png, svg, heic e webp, oppure rasterizza un PDF in JPEG. Il formato di input viene ricavato dall'estensione del nome file.

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 è obbligatorio e deve essere uno tra jpeg, png, svg, heic o webp; gli alias jpg, yml, htm e md vengono normalizzati per te. file accetta una stringa di percorso, un os.PathLike, bytes grezzi o un wrapper FileData(data, filename). I bytes grezzi non portano alcun nome file e vengono caricati come upload.bin, quindi preferisci FileData ogni volta che l'estensione conta.

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#

Converte documenti e formati dati. output_format vale "pdf" per impostazione predefinita, e pdf_options viene rispettato quando l'output è 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"
)

Input supportati: .doc, .docx, .xls, .xlsx, .ppt, .pptx, .html, .htm, .odt, .ods, .odp, .ots, .pages, .numbers, .md, .markdown, .csv, .json, .xml, .yaml, .yml, .toml.

EPUB non ha una coppia documenti dedicata. Passa i .epub attraverso convert_to_pdf o convert_to_markdown.

convert_to_markdown#

Rileva automaticamente lato server un documento caricato e restituisce Markdown pulito. È il mattone di base per l'ingestione RAG di un singolo file.

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

Input accettati: PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT e MD, più i formati office legacy e ODF. Le immagini non sono supportate qui, e l'endpoint non accetta opzioni PDF. Per un sito intero invece che per un singolo file, usa v2.ingest.

convert_to_pdf#

Rileva automaticamente lato server un file caricato e restituisce 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")

Input accettati: office, ODF, Pages, Numbers, RTF, CSV, HTML, Markdown, testo semplice, immagini raster, SVG, EPUB e un PDF esistente in passthrough. Dato che un input .pdf viene restituito così com'è, questo metodo funziona anche come normalizzatore in scala di grigi.

convert_website_to_pdf e convert_website_to_screenshot#

Individua ogni pagina di un sito, converte ciascuna in background e raccoglie tutto in un unico ZIP. Entrambi sono asincroni per progetto e restituiscono subito 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)

Anche le opzioni di rendering per singola pagina si applicano a ogni URL individuato: viewport_width, viewport_height, load_media, enable_scroll, auth, cookies e headers. Tutto ciò che lasci non impostato mantiene il valore predefinito del gateway.

wait_for_batch accetta interval_seconds (default 5.0), timeout_seconds (default 1800.0) e save_to. Solleva APIError(504, ...) se il batch è ancora in elaborazione quando la scadenza viene superata.

Coppie di conversione supportate#

L'SDK porta con sé una copia della mappa di conversione del gateway e rifiuta in locale una coppia non implementata, prima di qualsiasi round-trip di rete, indicando nel messaggio gli output validi per quell'input.

In totale fanno 43 coppie implementate. Controllale a livello di codice:

from enconvert import IMPLEMENTED_CONVERSIONS, valid_outputs_for

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

Il riferimento completo dei parametri vive in Parametri e opzioni.

Web intelligence (V2)#

Ogni lettura V2 porta con sé render_quality, un float da 0.0 a 1.0 che dice quanto onestamente si è renderizzata la pagina. Una schermata di sfida, un muro dei cookie, un accesso protetto da login, una pagina di errore HTTP o uno shell SPA vuoto tornano con un punteggio basso, una mappa deductions che nomina cosa è scattato e un elenco warnings. Il contenuto viene comunque restituito, solo segnalato, così una lettura sbagliata non entra mai di nascosto nel contesto del tuo agente. Tratta il punteggio come un filtro e controllalo prima di usare il testo. PerceiveResult, PerceiveDirectResult, DistillItem, LookupItem.perceive e WatcherSnapshot lo espongono tutti. I concetti sono nella panoramica V2.

Perceive#

Esegue il rendering di un URL in artefatti pronti per gli agenti. È sincrono: la chiamata restituisce l'operazione completata con gli URL firmati degli artefatti.

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

print(op.render_quality)            # da 0.0 a 1.0
print(op.status_code)               # stato HTTP della pagina stessa
print(op.deductions)                # ad es. {"login_wall": 0.65}
print(op.outputs["markdown"].url)   # URL firmato, 15 minuti
print(op.structured)

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

Sono accettati anche: schema (dict, uno schema di estrazione libero passato invariato), js_code (str, eseguito nella pagina prima della cattura), wait_timeout_ms (int), headers (dict[str, str]), cookies (list[BrowserCookie]), auth (HttpBasicAuth), proxy_url (str), geolocation (dict), action_chain (list[dict] di passaggi scriptati di click, digitazione e scroll), pdf_options (PdfOptions, applicato all'output pdf), mobile (bool) e respect_robots (bool). perceive_batch accetta esattamente lo stesso insieme a parte direct_download.

Gli URL degli artefatti vengono rifirmati a ogni lettura, quindi chiama client.v2.get_perceive_operation(op.operation_id) per averne uno fresco invece di mettere in cache la stringa.

Byte grezzi, senza giro di andata e ritorno sull'URL firmato. perceive_direct forza direct_download a on e ti consegna l'artefatto stesso, con i metadati letti dagli header della risposta.

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 richiede esattamente un output che produca un artefatto tra markdown, html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links e images. structured può viaggiare insieme ma resta inline lato server; passa qualsiasi altra cosa e l'SDK solleva EnconvertError prima di inviare la richiesta. Su download_perceive_artifact, output si può omettere quando l'operazione ha prodotto esattamente un artefatto, e un artefatto oltre la sua finestra di conservazione risponde 410.

Batch. Fino a 1000 URL condividono un unico blocco di opzioni. I batch piccoli si completano inline; quelli più grandi tornano con stato "queued", quindi interroga l'id del job.

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 è "manifest" (predefinito) o "zip"; quando è "zip", l'archivio finito si trova su done.zip.url. I dettagli sono in Perceive.

Discover#

Elenca gli URL di un sito senza alcun rendering del browser, il che ne fa il primo passo economico prima di percepire qualsiasi cosa.

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

include_patterns ed exclude_patterns (entrambi list[str]) filtrano l'insieme dei risultati. DiscoverResult.sources contiene i conteggi grezzi per sorgente prima della deduplicazione, ad esempio {"sitemap": 42, "crawl": 30}. Altro in Discover.

Lookup#

Esegue una ricerca web categorizzata, con la possibilità di renderizzare i primi risultati nella stessa chiamata.

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)

Sono accettati anche: country (str), locale (str), location (str) per query sensibili alla geolocalizzazione e autocorrect (bool). LookupResult porta con sé answer_box, knowledge_graph, perceive_operation_ids e perceive_top, dove quest'ultimo riporta quanti risultati sono stati effettivamente renderizzati, che possono essere meno di quanti ne avevi chiesti. Riferimento in Lookup.

Distill#

Estrazione strutturata guidata da uno schema su una o più pagine. Fornisci esattamente uno tra urls e discover_from; schema è sempre obbligatorio. Entrambe le regole vengono applicate lato client e sollevano EnconvertError prima che parta una richiesta.

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)

Il css_schema facoltativo gira per primo e risponde a tutto ciò che i selettori riescono a raggiungere. Solo i campi che mancano vengono escalati al tier del modello linguistico, ed extraction_tier su ciascun elemento riporta quale percorso è stato usato: css, llm, mixed o none.

Scoprire e distillare in un'unica chiamata:

from enconvert import DistillDiscoverFrom

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

Sono accettati anche: wait_for (str), wait_timeout_ms (int), headers (dict[str, str]), cookies (list[BrowserCookie]) e respect_robots (bool). CssField supporta i tipi text, attribute, html, regex, nested, list e nested_list, con attribute, pattern, default, transform (lowercase, uppercase, strip) facoltativi e fields annidati fino a cinque livelli di profondità. Vedi Distill.

Ingest#

Trasforma un sito intero, un elenco esplicito di URL o una pila di documenti caricati in JSONL suddiviso in chunk e pronto per RAG. Ingest è sempre asincrono.

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)

I file caricati percorrono lo stesso ciclo di vita del job sotto la modalità files. Sono accettati PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT e MD, più i formati office legacy e ODF, e ogni voce può essere un percorso, un os.PathLike, bytes grezzi o un FileData.

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

Sono accettate anche le opzioni di modellazione del crawl e di rendering: max_depth, same_domain_only, include_patterns, exclude_patterns, respect_robots, wait_for e wait_timeout_ms. ingest_files accetta solo chunk e 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 è idempotente; annullare un job già in stato terminale lo restituisce invariato. retry_ingest_webhook risponde 409 quando il job non è completato e 400 quando non era configurato alcun webhook. rotate_webhook_secret invalida immediatamente il segreto precedente. Approfondimento in Ingest.

Watch#

Riesegue il rendering di un URL a cadenza fissa e ti avvisa quando cambia.

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 richiede almeno un campo e altrimenti solleva EnconvertError; status accetta "active" o "paused", e un webhook_url vuoto azzera il webhook. delete_watcher è una eliminazione soft e idempotente che restituisce il watcher marcato come eliminato con stato "deleted", dopodiché il watcher risulta 404.

Il motore di diff e i payload di notifica sono documentati in Watch.

Opzioni PDF#

PdfOptions è una dataclass congelata condivisa da convert_url_to_pdf, convert_website_to_pdf, convert_document, convert_to_pdf e dalla famiglia 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 accetta name, value e o domain o url, più path, expires, http_only, secure e same_site ("Strict", "Lax", "None") facoltativi. L'SDK mappa http_only e same_site sulle rispettive chiavi wire in camelCase al posto tuo.

Gestione degli errori#

Gli errori sono classi di eccezione, quindi intercettali con except. Ordina i gestori dal più specifico al più generale: AuthenticationError, QuotaError e RateLimitError sono tutte sottoclassi di APIError, che a sua volta è sottoclasse di 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 porta con sé status_code e message, e il suo str() si legge come [404] Not found. Errori lato client in cui puoi incappare: una api_key vuota, un'estensione di file non supportata, una coppia di conversione non implementata, una chiamata distill con entrambi o nessuno tra urls e discover_from, una mancata corrispondenza tra modalità e argomenti di ingest, un payload update_watcher vuoto e un elenco di output di perceive_direct che non si risolve in esattamente un artefatto. La mappa completa dei messaggi è in Codici di errore.

Recupero dei timeout#

Le conversioni lunghe di URL e documenti possono sopravvivere più a lungo del timeout di un reverse-proxy anche quando il server porta a termine il job. L'SDK Python recupera in modo trasparente:

1. Prima di ogni conversione di un singolo file o di un singolo URL, l'SDK genera una stringa esadecimale UUID4 e la invia come job_id.
2. Se quella richiesta torna con un 5xx, l'SDK passa al polling di GET /v1/convert/status/{job_id} ogni 3 secondi. Un 404 lì significa che la riga del job non è ancora stata scritta, quindi il polling continua.
3. Su success l'SDK restituisce il risultato come se nulla fosse; su failed solleva APIError(500, ...) con il messaggio di errore del server; e oltre la scadenza di polling di 300 secondi solleva APIError(504, "Conversion timed out").

Per tutto questo non scrivi codice. Quando una risposta arriva attraverso il percorso di recupero, ConversionResult.job_id viene valorizzato, così puoi correlarla nei tuoi log.

Due eccezioni. convert_website_to_pdf e convert_website_to_screenshot non partecipano, perché l'invio di un intero sito non ha una riga di job per singola pagina, quindi un 5xx lì significa che è fallito l'invio stesso e l'errore emerge direttamente. Nemmeno gli endpoint V2 vengono interrogati con polling: usa i loro id di job con get_perceive_batch o get_ingest_job.

Configurazione#

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

Il client mantiene una requests.Session, quindi le connessioni vengono riusate tra le chiamate; riusa un solo client invece di crearne uno per richiesta. La tua chiave viaggia come header X-API-Key, e i download con save_to colpiscono l'URL firmato dello storage come una semplice GET non autenticata scritta su disco in streaming a blocchi da 64 KB, così la chiave non lascia mai l'host dell'API.

Forma del risultato#

I metodi di conversione restituiscono un ConversionResult congelato:

@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 pre-firmato è di breve durata. Passa save_to, oppure recupera tu stesso l'URL, e archivia i byte nel tuo bucket quando ti serve un accesso duraturo.

Gli URL degli artefatti V2 sono firmati per 15 minuti e rifirmati ogni volta che leggi l'operazione, quindi chiama get_perceive_operation invece di mettere in cache una stringa di URL.

Sorgente e segnalazioni#

• PyPI: enconvert
• GitHub: conversionapi/python-sdk
• Python: 3.9, 3.10, 3.11, 3.12, 3.13
• Licenza: MIT
• Altri client: Tutti gli SDK

Domande frequenti#

Come converto file in Python?#

Esegui pip install enconvert, costruisci un client con Enconvert(api_key=os.environ["ENCONVERT_API_KEY"]) e chiama un metodo tipizzato come convert_document, convert_image, convert_to_pdf o convert_to_markdown. Passa save_to="out.pdf" e l'SDK scrive il file finito direttamente su disco in streaming, invece di consegnarti un URL da recuperare da solo.

Come converto un URL in PDF con Python?#

Chiama client.convert_url_to_pdf("https://example.com", save_to="page.pdf"). Imposta single_page=False più pdf_options=PdfOptions(page_size="A4") per un output impaginato, e regola viewport_width, load_media o enable_scroll quando una pagina ha bisogno di un canvas più largo o di immagini caricate in lazy loading.

Come converto DOCX in PDF con Python?#

O client.convert_document("report.docx", save_to="report.pdf"), dato che output_format vale già "pdf" per impostazione predefinita, oppure client.convert_to_pdf("report.docx", save_to="report.pdf") quando vuoi il rilevamento automatico del formato lato server. La stessa chiamata gestisce XLSX, PPTX, ODT, ODS, ODP, OTS, Pages e Numbers.

Come converto HEIC in WebP con Python?#

client.convert_image("photo.heic", output_format="webp", save_to="photo.webp"). Il formato di input viene ricavato dall'estensione del nome file, e jpeg, png, svg, heic e webp si convertono tutti l'uno nell'altro. Stai lavorando in memoria invece che su disco? Avvolgi i byte in FileData(data=blob, filename="photo.heic") così l'estensione sopravvive.

Come estraggo una pagina web in Markdown pulito con Python?#

Usa client.v2.perceive(url, outputs=["markdown"]) e leggi op.outputs["markdown"].url, oppure client.v2.perceive_direct(url, outputs=["markdown"]) per ottenere i byte nel corpo della risposta. Aggiungi only_main_content=True per eliminare navigazione e piè di pagina. Per una conversione semplice senza punteggio né estrazione, convert_url_to_markdown è la chiamata più leggera.

Cosa significa render_quality e quando conviene riprovare una pagina?#

È un float da 0.0 a 1.0 su ogni lettura V2 che dice quanto onestamente si è renderizzata la pagina. Una schermata di sfida, un muro dei cookie, un accesso protetto da login, una pagina di errore HTTP o uno shell SPA vuoto ottengono un punteggio basso e indicano cosa è scattato in deductions, con il dettaglio in warnings e lo stato HTTP della pagina stessa in status_code. Usalo come filtro: tratta un punteggio basso come il segnale per riprovare con cache_mode="refresh", con un selettore wait_for che solo il contenuto reale soddisfa, oppure con cookies diversi, invece di dare quel testo in pasto al tuo modello.

Come trasformo un intero sito di documentazione in chunk RAG con Python?#

Chiama client.v2.ingest(mode="sitemap", url="https://docs.example.com", max_pages=100, chunk=IngestChunkOptions(max_words=512, sentence_overlap=1)). Il job è asincrono, quindi o interroghi get_ingest_job(job_id) finché lo stato non esce da queued, discovering e processing, oppure passi webhook_url e aspetti di essere chiamato. Il JSONL finito si trova su output_url. Per documenti locali invece che per un sito, ingest_files esegue la stessa pipeline.

L'SDK Python supporta asyncio?#

Non in modo nativo. Ogni metodo è sincrono e costruito su requests. Dentro un'applicazione asincrona, avvolgi le chiamate in await asyncio.to_thread(client.convert_to_pdf, "report.docx") oppure passale a un concurrent.futures.ThreadPoolExecutor così l'event loop continua a girare. Il client si può condividere tra thread in sicurezza perché mantiene una requests.Session con pool di connessioni.

Come sopravvive l'SDK a un timeout del proxy su una conversione lunga?#

Ogni conversione di un singolo file o di un singolo URL invia un job_id generato. Se la richiesta restituisce 5xx, l'SDK interroga GET /v1/convert/status/{job_id} ogni 3 secondi per un massimo di 300 secondi, restituisce normalmente una volta che il job riporta success, solleva APIError(500, ...) se riporta failed e solleva APIError(504, "Conversion timed out") se la scadenza viene superata. Gli invii di batch di interi siti saltano questo percorso, dato che un errore lì significa che l'invio stesso non è andato a buon fine.