Eine API, fünf Wege sie aufzurufen#

EnConvert ist eine einzige HTTP-API unter https://api.enconvert.com. Der MCP-Server, die CLI, der n8n Node und die zehn SDKs sind Clients dieser API, keine separaten Produkte. Sie sprechen dieselben Endpunkte mit demselben Key an.

REST ist der Unterbau#

Jeder Aufruf landet in derselben Form: eine HTTPS-Anfrage an https://api.enconvert.com mit einem X-API-Key-Header. Das Gateway kann außer am User-Agent-String nicht erkennen, welcher Client sie gesendet hat, und dieser String existiert einzig zur Zuordnung: Jedes SDK sendet enconvert-sdk/<version> (<language>), damit sich der Traffic pro Sprache zählen lässt.

Kein Client hat einen eigenen Endpunkt. Es gibt keine API-Operation, die über die CLI oder den MCP-Server erreichbar wäre und die du nicht mit curl und den Seiten dieser Site selbst absetzen könntest.

Die Umkehrung muss man deutlich sagen, denn hier werden Leute überrascht: Die Clients kapseln REST unterschiedlich tief.

Die CLI deckt am meisten ab. Sie hat Verben für die Konvertierungsrouten sowie für perceive, discover, lookup, distill und ingest, dazu enconvert api als Passthrough im gh-Stil, der alles erreicht, wofür sie noch kein Verb hat.
Der MCP-Server registriert 24 Tools. Er lässt die Endpunkte für das Webhook-Signing-Secret bewusst aus (GET /v2/ingest/webhook-secret und sein Rotate-Gegenstück), denn ein Signing-Secret sollte für ein Modell nicht lesbar sein.
Der n8n Node stellt 6 Ressourcen und 16 Operationen bereit, zugeschnitten auf Workflow-Schritte statt auf vollständige API-Abdeckung.
Die SDKs decken die Konvertierungs-Endpunkte und die V2-Web-Endpunkte in allen zehn Sprachen ab.

Ist ein Client enger als die API, geh für diesen einen Aufruf auf REST herunter. Mischen ist unproblematisch. SDK-Aufrufe und selbst gebaute HTTP-Aufrufe können sich ohne Sonderbehandlung ein Projekt und einen Key teilen.

Ein Key, alle Oberflächen#

Jede Oberfläche authentifiziert sich mit demselben privaten API-Key (sk_...), gesendet im X-API-Key-Header. Erzeuge einen im Dashboard, und er funktioniert in curl, in enconvert auth login, in einer MCP-Config, in einem n8n-Credential und in einem SDK-Konstruktor. Rotierst du ihn, rotierst du alle.

Was sich unterscheidet, ist nur, wo der Key liegt.

Oberfläche	Wo der Key liegt	Environment-Override
REST	Wo auch immer dein eigener Code Secrets ablegt	--
SDKs	An den Client-Konstruktor übergeben	--
CLI	`credentials.toml`, Dateimodus `0600`	`ENCONVERT_API_KEY`
MCP-Server	`~/.enconvert/config.json`, Dateimodus `600`	`ENCONVERT_API_KEY`
n8n Node	Das `enconvertApi`-Credential in n8n	--

Diese Oberflächen brauchen einen privaten Key. Die CLI, der MCP-Server, der n8n Node und die SDKs erwarten alle sk_.... Ein öffentlicher pk_-Key ist für Browser-Code gedacht, der daraus ein kurzlebiges JWT erzeugt, und das n8n-Credential lehnt pk_-Keys rundweg ab. Siehe Authentifizierung.

Auch die Nutzung ist geteilt. Ein monatliches Ops-Kontingent deckt alle Oberflächen ab, und eine Operation kostet gleich viel, ob sie aus einem Go-Programm oder aus einem Terminal kam. Siehe Rate-Limits und Kontingente.

Wann du was nimmst#

Oberfläche	Was es ist	Wann du dazu greifst
REST	Die API selbst: JSON- und Multipart-Bodys über HTTPS	Du schreibst Anwendungscode, willst keine Abhängigkeit, oder deine Sprache hat kein SDK
SDK	Typisierte Clients für zehn Sprachen	Du willst Autovervollständigung für jeden Parameter und eine Timeout-Recovery, die du nicht selbst schreiben musstest
CLI	Das `enconvert`-Binary, aus Homebrew, Scoop, einem Shell-Installer oder npm	Du schreibst ein Shell-Skript, führst einen einmaligen Job aus oder arbeitest in CI
MCP-Server	`@enconvert/mcp`, ein lokaler stdio-Server für KI-Assistenten	Ein Coding-Agent soll selbst entscheiden, wann er die API aufruft
n8n Node	`@enconvert/n8n-nodes-enconvert`, ein Community Node	Der Workflow liegt schon in n8n und du willst das Ergebnis als n8n Binary Data

Zwei dieser Entscheidungen sind meist offensichtlich. Tippt ein Mensch, ist es die CLI; entscheidet ein Modell, ist es MCP. Nur die Frage REST oder SDK lohnt das Nachdenken, und sie hängt daran, wie viel Retry- und Polling-Code du selbst pflegen willst.

Derselbe Abruf, auf drei Wegen#

https://example.com/pricing als Markdown einzulesen ist eine einzige POST /v2/perceive-Anfrage. So sieht sie als rohes HTTP aus:

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"]
  }'

Die CLI setzt dasselbe POST /v2/perceive ab. Der nackte Befehl sendet kein outputs und erhält damit den Server-Standard: Markdown plus den strukturierten Block inline:

enconvert perceive https://example.com/pricing

Über MCP schreibst du den Aufruf gar nicht. Du bittest den Assistenten, die Seite zu lesen, er wählt das Tool perceive_url, und die entscheidenden Argumente sehen so aus:

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

Gleiche Anfrage, gleiche Abrechnung. Alle drei rendern die Seite einmal und kosten eine Operation. Der MCP-Server macht obendrein eine Sache zusätzlich: Er holt das fertige Markdown-Artefakt und bettet den Text inline ins Tool-Ergebnis ein (bis etwa 256 KB), sodass der Assistent die Seite ohne zweiten Abruf lesen kann.

Wie es weitergeht#

Die Einrichtung steht in den Integrations-Leitfäden, eine Seite je Oberfläche:

Integrationen ist die Übersichtsseite und behandelt auch die einbettbaren Web-Widgets.
MCP-Einrichtung installiert @enconvert/mcp mit npx @enconvert/mcp setup in Claude Code, Cursor, Windsurf und sechs weitere Clients.
n8n installiert den Community Node und geht die sechs Ressourcen durch.
CLI behandelt Installation, enconvert auth login, die Scripting-Flags und die Exit-Codes.
SDKs listet alle zehn Pakete mit je einer eigenen Seite auf.

Für die API selbst sind Endpunkte die Referenz, und Authentifizierung erklärt die beiden Key-Typen.

Häufig gestellte Fragen#

Ist der MCP-Server eine andere API als die REST-API?#

Nein. @enconvert/mcp ist ein lokaler stdio-Prozess, der mit deinem privaten API-Key dieselben öffentlichen REST-Endpunkte aufruft, die auf dieser Site dokumentiert sind. Jedes Tool bildet auf eine /v1/convert/*- oder /v2/*-Anfrage ab, schöpft also aus demselben Kontingent und liefert dieselben Fehler.

Brauche ich separate API-Keys für CLI, MCP und meine Anwendung?#

Nein. Ein privater Key (sk_...) authentifiziert sie alle, und du kannst denselben Key über alle Oberflächen hinweg verwenden. Separate Keys sind trotzdem nützlich, wenn du eine Oberfläche sperren willst, ohne die anderen anzufassen, zum Beispiel einen CI-Key, den du unabhängig von deinem Laptop rotieren kannst.

Kann ich einen öffentlichen pk_-Key mit der CLI oder einem SDK verwenden?#

Nein. Öffentliche Keys gibt es für Browser-Code, wo sie ein kurzlebiges JWT erzeugen, statt direkt gesendet zu werden. Die CLI, der MCP-Server, der n8n Node und die SDKs erwarten alle einen privaten sk_...-Key, und das n8n-Credential lehnt einen pk_-Key schon bei der Validierung ab.

Gibt es etwas, das nur über die SDKs oder nur über die CLI verfügbar ist?#

Keine API-Operation. Was die SDKs hinzufügen, liegt auf der Client-Seite: typsichere Optionen, Streaming-Downloads auf die Festplatte und der automatische Rückfall auf Polling per GET /v1/convert/status/{job_id}, wenn eine lange Konvertierung das Proxy-Timeout überdauert. Das alles kannst du auch selbst gegen rohes REST schreiben.

Welche Oberfläche sollte ich in einer CI-Pipeline nutzen?#

Die CLI, mit ENCONVERT_API_KEY aus deinem CI-Secret-Store und --no-input, damit keine Eingabeaufforderung den Lauf blockieren kann. Ihre Exit-Codes sind ein stabiler, veröffentlichter Vertrag, ein fehlgeschlagener Konvertierungsvorgang lässt den Step also ohne jedes Parsen der Ausgabe fehlschlagen.

← Concepts Sync and Async Jobs →

API Documentation