Un'unica API, cinque modi per chiamarla#

EnConvert è un'unica API HTTP su https://api.enconvert.com. Il server MCP, la CLI, il node n8n e i dieci SDK sono client di quell'API, non prodotti separati. Raggiungono gli stessi endpoint con la stessa chiave.

REST è il substrato#

Ogni chiamata finisce nella stessa forma: una richiesta HTTPS verso https://api.enconvert.com con un header X-API-Key. Il gateway non sa quale client l'ha inviata, a parte la stringa User-Agent, e l'unico motivo per cui quella stringa esiste è l'attribuzione: ogni SDK invia enconvert-sdk/<version> (<language>) così il traffico può essere conteggiato per linguaggio.

Nessun client ha un endpoint tutto suo. Non esiste alcuna operazione API raggiungibile tramite la CLI o il server MCP che tu non possa eseguire con curl e le pagine di questo sito.

Il contrario va detto chiaramente, perché è qui che le persone restano sorprese: i client incapsulano REST a profondità diverse.

• La CLI è la più ampia. Ha verbi per le route di conversione e per perceive, discover, lookup, distill e ingest, più enconvert api come passthrough in stile gh che raggiunge tutto ciò per cui non ha ancora un verbo.
• Il server MCP registra 24 strumenti. Lascia deliberatamente fuori gli endpoint del signing secret dei webhook (GET /v2/ingest/webhook-secret e il suo corrispettivo di rotazione), perché un signing secret non dovrebbe essere leggibile da un modello.
• Il node n8n espone 6 risorse e 16 operazioni, modellate sui passaggi di un workflow anziché sulla copertura completa dell'API.
• Gli SDK coprono gli endpoint di conversione e gli endpoint web V2 in tutti e dieci i linguaggi.

Quando un client è più ristretto dell'API, scendi a REST per quella singola chiamata. Mescolare va bene. Chiamate SDK e chiamate HTTP scritte a mano possono condividere un progetto e una chiave senza alcuna gestione particolare.

Una sola chiave, ogni superficie#

Ogni superficie si autentica con la stessa chiave API privata (sk_...), inviata nell'header X-API-Key. Generane una nella dashboard e funziona in curl, in enconvert auth login, in una configurazione MCP, in una credenziale n8n e nel costruttore di un SDK. Ruotarla le ruota tutte.

L'unica cosa che cambia è dove viene conservata la chiave.

Anche l'utilizzo è condiviso. Un'unica quota mensile di ops copre ogni superficie, e un'operazione costa lo stesso sia che arrivi da un programma Go sia che arrivi da un terminale. Consulta Rate limit e quote.

Quando scegliere ciascuna#

Due di queste scelte sono di solito ovvie. Se a digitare è una persona, è la CLI; se a decidere è un modello, è MCP. La domanda REST o SDK è l'unica su cui valga la pena ragionare, e dipende da quanto codice di retry e di polling vuoi mantenere tu.

La stessa lettura, in tre modi#

Leggere https://example.com/pricing in Markdown è una sola richiesta POST /v2/perceive. Eccola come HTTP grezzo:

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "outputs": ["markdown"]
  }'

La CLI emette lo stesso POST /v2/perceive. Il comando da solo non invia outputs, quindi ottiene il valore predefinito del server: Markdown più il blocco strutturato inline:

enconvert perceive https://example.com/pricing

Con MCP la chiamata non la scrivi affatto. Chiedi all'assistente di leggere la pagina, lui sceglie lo strumento perceive_url, e gli argomenti che contano vengono fuori così:

{
  "name": "perceive_url",
  "arguments": {
    "url": "https://example.com/pricing",
    "outputs": ["markdown"]
  }
}

Dove andare adesso#

La configurazione si trova nelle guide alle integrazioni, una pagina per superficie:

• Integrazioni è l'hub, e copre anche i widget web incorporabili.
• Impostazione MCP installa @enconvert/mcp in Claude Code, Cursor, Windsurf e altri sei client con npx @enconvert/mcp setup.
• n8n installa il community node e ti accompagna tra le sei risorse.
• CLI copre l'installazione, enconvert auth login, i flag per lo scripting e i codici di uscita.
• SDK elenca tutti e dieci i pacchetti, con una pagina ciascuno.

Per l'API in sé, Endpoint è il riferimento e Autenticazione spiega i due tipi di chiave.

Domande frequenti#

Il server MCP è un'API diversa dall'API REST?#

No. @enconvert/mcp è un processo stdio locale che chiama gli stessi endpoint REST pubblici documentati su questo sito, usando la tua chiave API privata. Ogni strumento corrisponde a una richiesta /v1/convert/* o /v2/*, quindi attinge dalla stessa quota e restituisce gli stessi errori.

Mi servono API key separate per la CLI, per MCP e per la mia applicazione?#

No. Un'unica chiave privata (sk_...) le autentica tutte, e puoi riusare la stessa chiave su tutte le superfici. Chiavi separate restano comunque utili se vuoi revocare una superficie senza toccare le altre, per esempio una chiave di CI che puoi ruotare indipendentemente da quella del tuo portatile.

Posso usare una chiave pubblica pk_ con la CLI o con un SDK?#

No. Le chiavi pubbliche esistono per il codice del browser, dove generano un JWT a breve scadenza invece di essere inviate direttamente. La CLI, il server MCP, il node n8n e gli SDK si aspettano tutti una chiave privata sk_..., e la credenziale n8n rifiuta una chiave pk_ già in fase di validazione.

C'è qualcosa disponibile solo tramite gli SDK o solo tramite la CLI?#

Nessuna operazione API. Quello che gli SDK aggiungono è lato client: opzioni type-safe, download in streaming su disco e fallback automatico al polling di GET /v1/convert/status/{job_id} quando una conversione lunga supera il timeout del proxy. Tutto questo puoi scriverlo tu direttamente su REST grezzo.

Quale superficie dovrei usare dentro una pipeline di CI?#

La CLI, con ENCONVERT_API_KEY impostata dal secret store della tua CI e --no-input così nessun prompt può bloccare l'esecuzione. I suoi codici di uscita sono un contratto pubblicato e stabile, quindi una conversione fallita fa fallire lo step senza dover analizzare l'output.