API Documentation

Plugin Dify per pagine web e conversione di file#

Il plugin EnConvert per Dify aggiunge sei tool a qualsiasi agente o workflow: leggere una pagina web come markdown, cercare sul web, elencare gli URL di un sito, estrarre campi strutturati e convertire un file caricato in markdown o PDF. Ogni rendering di pagina porta con sé un punteggio render_quality da 0.0 a 1.0, così una pagina di challenge o il guscio vuoto di una single-page app arriva segnalata invece di essere trattata come contenuto reale.

Pacchetto: enconvert · Sorgente: enconvert/dify-enconvert · Dify minimo: 1.0.0 · Licenza: MIT

I sei tool#

Tool Endpoint Cosa fa
Perceive URL POST /v2/perceive Renderizza una singola pagina in markdown, HTML pulito, HTML grezzo, uno screenshot, un PDF, link, immagini o dati strutturati, con un punteggio render_quality. Costruito su Perceive.
Web Search POST /v2/lookup Ricerca su web, news, immagini, scholar, brevetti e mappe, con titolo, URL, snippet e posizione per ogni risultato. Costruito su Lookup.
Discover URLs POST /v2/discover Elenca gli URL di un sito tramite sitemap, crawl o entrambi, senza renderizzarli. Costruito su Discover.
Extract Structured POST /v2/distill Estrae campi con nome da una o più pagine, oppure da un sito di cui fa il crawl per te. Costruito su Distill.
Convert File to Markdown POST /v1/convert/anything-to-markdown Trasforma in markdown i file Word, PowerPoint, Excel, PDF, EPUB, RTF, HTML e di testo. Costruito su Anything to Markdown.
Convert File to PDF POST /v1/convert/anything-to-pdf Trasforma in PDF un documento, un foglio di calcolo, una presentazione, un'immagine, un file HTML o di testo. Costruito su Anything to PDF.

Tutto gira sulla stessa API REST documentata in questo sito, quindi la quota del tuo piano, i rate limit e le funzionalità valgono esattamente come ovunque altrove.

Installazione#

Il plugin si installa dalla sua release GitHub mentre la scheda sul Marketplace è in revisione.

  1. In Dify apri Plugins, in alto a destra.
  2. Clicca Install Plugin, poi From GitHub.
  3. Incolla l'URL del repository:
https://github.com/enconvert/dify-enconvert
  1. Seleziona la versione dal menu a tendina. Dify scarica da quella release l'asset .difypkg corrispondente.
  2. Controlla i permessi, poi clicca Install.

Il plugin chiede soltanto il permesso tool e dichiara l'accesso in uscita verso api.enconvert.com, www.enconvert.com e l'host di storage che serve i file convertiti.

Dify self-hosted verifica le firme dei plugin per impostazione predefinita. Solo i pacchetti del Marketplace portano una firma che Dify riconosce, quindi un'installazione da GitHub fallisce con plugin verification has been enabled, and the plugin you want to install has a bad signature. La soluzione è in Risoluzione dei problemi. Dify Cloud non è interessato.

Aggiungi la tua chiave API#

Il plugin richiede una sola credenziale: EnConvert API Key.

  1. Genera una chiave API privata nella dashboard. Le chiavi private iniziano con sk_.
  2. Apri il plugin EnConvert, clicca To authorize e incolla la chiave.
  3. Salva.

Il salvataggio chiama GET /v1/whoami, che accetta solo chiavi private, quindi una chiave pubblica pk_ viene rifiutata nel momento esatto in cui la incolli invece di far fallire più tardi l'esecuzione di un workflow. La chiave viaggia nell'header X-API-Key su ogni richiesta che il plugin effettua.

Le chiavi pubbliche non funzionano. Le chiavi che iniziano con pk_ sono pensate per i widget nel browser e vengono rifiutate da ogni tool di questo plugin. Trovi altri dettagli in Chiavi private.

Leggere una pagina#

Perceive URL prende l'URL dall'agente e due impostazioni dal form:

Parametro Impostato da Predefinito Scopo
URL L'agente -- L'URL assoluto da renderizzare
Outputs Il form markdown,structured Uno o più tra markdown, html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links, images, structured, separati da virgola
Only Main Content Il form Off Rimuove navigazione, header e footer, mantenendo l'articolo

L'API restituisce ogni artefatto come URL firmato che scade dopo 15 minuti, non come testo inline, e un agente non può aprire un URL. Per questo il plugin legge per te gli artefatti testuali: markdown, HTML pulito e HTML grezzo vengono scaricati e inseriti nel risultato del tool, fino a 256 KB ciascuno. Tutto ciò che è più grande, e tutto ciò che è binario, resta un link. L'output structured è l'eccezione e arriva inline al livello superiore della risposta.

Il punteggio render_quality#

Ogni risultato di Perceive porta con sé render_quality, un numero da 0.0 a 1.0. Zero significa che la pagina era bloccata o vuota, uno significa un rendering pulito. In entrambi i casi il contenuto torna comunque, segnalato, così una lettura errata non entra mai di nascosto in un riassunto o in un vector store.

Ramifica su questo valore con un nodo IF/ELSE prima del nodo LLM che consuma il markdown. In un agente il punteggio si trova nel risultato del tool che il modello legge, quindi basta una frase nel system prompt perché il modello diffidi di un valore basso.

Estrarre campi#

Extract Structured richiede uno schema ed esattamente una sorgente. Lo schema è un oggetto JSON in una di due forme. Una mappa piatta da nome del campo a descrizione in linguaggio naturale è quella veloce:

{"title": "the page title", "price": "the monthly price in USD"}

Uno schema JSON completo, {"type": "object", "properties": {...}}, è l'altra: vale la digitazione in più quando ti servono tipi o oggetti annidati garantiti.

Come sorgente passa URLs, un elenco separato da virgole con un tetto di 50, oppure Discover From URL, un singolo sito di cui l'API fa il crawl per te, governato da Discover Mode e Discover Max Pages. Passarli entrambi, o nessuno dei due, restituisce un messaggio che te lo dice.

I risultati arrivano come results[], una voce per URL, ciascuna con i propri dati e il proprio extraction_tier, che dice se la risposta l'ha prodotta un passaggio deterministico o un modello che ha letto la pagina.

Convertire file#

Convert File to Markdown e Convert File to PDF prendono un file di Dify, non un URL. Collega un file dall'input file di un nodo Start, oppure una variabile file di un nodo precedente. Il plugin carica i byte come multipart e restituisce un URL di download firmato per il risultato, valido per circa 15 minuti e da scaricare con una semplice GET senza chiave API.

L'estensione del nome del file caricato decide il formato di input. Dify porta con sé il nome originale, quindi di solito la cosa è invisibile, ma un file che arriva senza un'estensione utilizzabile ripiega sui propri byte: un PDF, un'immagine o un DOCX viene riconosciuto dalla firma, mentre un formato di testo come CSV o HTML non ne ha e viene rifiutato con un 400.

Costruire qualcosa con il plugin#

Un agente che fa ricerca#

Dai a un agente Web Search, Perceive URL e Discover URLs. La ricerca trova le pagine candidate, Perceive legge come markdown quelle promettenti e Discover mappa un sito quando l'agente ha bisogno di sapere cos'altro contiene senza renderizzare nulla.

Un workflow che trasforma un upload in una risposta#

Start (file input)  ->  Convert File to Markdown  ->  LLM  ->  Answer

L'estrazione documenti integrata in Dify copre i formati più comuni. Questo percorso aggiunge quelli che le mancano.

Risoluzione dei problemi#

plugin verification has been enabled, and the plugin you want to install has a bad signature. Un'istanza Dify self-hosted impone per impostazione predefinita la verifica della firma sui pacchetti dei plugin, e solo i pacchetti del Marketplace portano una firma che riconosce. Aggiungi FORCE_VERIFYING_SIGNATURE=false a docker/.env, poi riavvia:

cd docker
docker compose down
docker compose up -d

Quell'impostazione vale per ogni plugin non proveniente dal Marketplace su quell'istanza, quindi trattala come una decisione sull'istanza e non su una singola installazione. Dify Cloud non è interessato.

Nella finestra di installazione non compare nessuna versione. Dify elenca una release solo quando ha un asset .difypkg allegato. Apri l'ultima release e verifica che l'asset ci sia sotto Assets. Un menu a tendina vuoto significa nessun pacchetto, non il pacchetto sbagliato.

Il salvataggio della credenziale fallisce. La chiave è sbagliata, oppure è una chiave pubblica pk_. Genera una chiave privata nella dashboard. Il salvataggio chiama GET /v1/whoami, che accetta solo chiavi private.

Un tool segnala che l'operazione non è inclusa nel mio piano. Perceive, Web Search, Discover ed Extract Structured attingono al numero di operazioni mensili incluse nel tuo piano. Controlla il tuo utilizzo nella pagina dei prezzi.

Perceive restituisce un link dove ti aspettavi il markdown. Il markdown ha superato il limite di 256 KB per l'inline, quindi il plugin ti ha passato l'URL firmato. Scaricalo con una semplice GET senza chiave API. Only Main Content di solito riporta una pagina lunga sotto il limite.

Un tool di conversione dice che si aspettava un file caricato. Nel parametro File è stata collegata una stringa URL. Entrambi i tool di conversione prendono un file di Dify. Per convertire una pagina web usa Perceive URL con pdf o markdown sotto Outputs.

Domande frequenti#

Come installo il plugin EnConvert in Dify?#

Apri Plugins, clicca Install Plugin, poi From GitHub, e incolla https://github.com/enconvert/dify-enconvert. Scegli la versione dal menu a tendina, controlla i permessi e clicca Install. Dify scarica l'asset .difypkg direttamente da quella release GitHub, che è un percorso di installazione documentato e non richiede una scheda sul Marketplace.

Posso installarlo prima che la scheda sul Marketplace sia approvata?#

Sì. Installare da una release GitHub è una delle strade di pubblicazione previste da Dify e richiede più o meno lo stesso numero di clic del Marketplace. L'unica differenza è che un'istanza self-hosted con la verifica delle firme attiva rifiuta un pacchetto non proveniente dal Marketplace finché non imposti FORCE_VERIFYING_SIGNATURE=false in docker/.env.

Come leggo una pagina web come markdown in un agente Dify?#

Aggiungi Perceive URL come tool e lascia Outputs sul valore predefinito. L'agente passa l'URL e il plugin restituisce il markdown inline nel risultato del tool, fino a 256 KB, così il modello legge la pagina invece di un link che non può aprire. Attiva Only Main Content per eliminare navigazione e footer.

Ogni artefatto prodotto dall'API è un URL firmato valido 15 minuti. Il plugin scarica quelli testuali e li inserisce inline, fino a 256 KB. Una pagina più grande, o un output binario come uno screenshot o un PDF, resta un link, da scaricare con una semplice GET senza chiave API.

Come converto un DOCX caricato in PDF in un workflow Dify?#

Aggiungi un input file al nodo Start, poi collega quella variabile file a Convert File to PDF. Il tool carica i byte e restituisce un URL di download firmato per il PDF. L'estensione del nome file decide il formato di input, quindi mantieni il nome originale.

← ClawHub n8n →