Markdown-to-Image-API: PNG mit cURL, Node.js, Python und n8n erzeugen

Für ein einzelnes Bild reicht ein manueller Export. Wenn ein Produkt jedoch jeden KI-Bericht, Changelog, Support-Text oder Social-Post in eine einheitliche Grafik verwandeln soll, wird Handarbeit zum Engpass. Eine Markdown-to-Image-API verlagert das Rendering in den Code: Markdown senden, Format und Theme wählen, eine URL oder Binärdatei erhalten und das Ergebnis am gewünschten Ort speichern.

Dieser Leitfaden baut eine echte Integration mit der MarkdownToImage-API auf. Zuerst prüfen wir den Aufruf mit cURL, danach setzen wir denselben Ablauf in Node.js, Python und n8n um. Zum Schluss ergänzen wir die Schutzmaßnahmen, die in kurzen Quickstarts oft fehlen.

Endpoint und Limits wurden am 2. August 2026 anhand der offiziellen API-Dokumentation geprüft. Kontingente und Tarife können sich ändern; vor einer Kostenplanung solltest du die aktuelle Preisseite kontrollieren.

Melde dich bei MarkdownToImage an und erstelle im Bereich API Tokens einen Token. Behandle ihn wie ein Passwort: Er gehört weder in Quellcode und Markdown-Dateien noch in Screenshots, Browser-JavaScript oder exportierte Workflow-Dateien.

Für lokale Tests legst du ihn als Umgebungsvariable ab:

export MARKDOWN_TO_IMAGE_API_TOKEN="mti_your_token_here"

In Produktion solltest du den verschlüsselten Secret-Speicher deiner Hosting-Plattform verwenden. Taucht ein Token in einem öffentlichen Repository oder Log auf, widerrufe ihn und erstelle einen neuen, statt nur den alten Commit zu verstecken.

Die API hat ein separates Kontingent von 50 Anfragen mit Wasserzeichen pro Monat. Jedes Rendering ohne Wasserzeichen kostet einen API-Credit. Creator-Browser-Exporte und Batch-Läufe liefern keine API-Credits; plane beide getrennt.

Der Generierungs-Endpoint akzeptiert JSON und verwendet Bearer-Authentifizierung. Dieser Request erzeugt ein 1200 Pixel breites PNG im dunklen GitHub-Theme:

curl -X POST https://markdowntoimage.com/api/v1/images/generate \
  -H "Authorization: Bearer $MARKDOWN_TO_IMAGE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Weekly release\n\n- Faster exports\n- Clearer reports\n- One automated workflow",
    "format": "png",
    "width": 1200,
    "quality": 2,
    "theme": "github-dark",
    "mode": "url"
  }'

Eine erfolgreiche Antwort im URL-Modus enthält data.imageUrl. Die Adresse ist temporär: Sie im Browser zu öffnen bestätigt nur das Rendering, ersetzt aber keine dauerhafte Speicherung. Lade die Datei zeitnah herunter und übertrage sie in deinen eigenen Objektspeicher, dein CMS oder deine Mediathek.

Nur markdown ist verpflichtend. Für automatisierte Ausgaben solltest du die Einstellungen dennoch explizit setzen, damit das Ergebnis reproduzierbar bleibt.

JPEG passt zu fotografischem Material, wenn verlustbehaftete Kompression akzeptabel ist. PNG eignet sich für Code, Diagramme und scharfe UI-Elemente. WebP spart Bandbreite, sofern alle Empfänger es unterstützen. PDF wird zwar über denselben Endpoint erzeugt, ist aber eine Dokumentausgabe und keine normale Social-Grafik.

Das folgende Node.js-Skript ruft die API auf, prüft die HTTP-Antwort, lädt das temporäre Ergebnis herunter und schreibt eine echte Datei. Es nutzt das globale fetch aktueller Node.js-Versionen.

import { writeFile } from "node:fs/promises";

const token = process.env.MARKDOWN_TO_IMAGE_API_TOKEN;
if (!token) throw new Error("MARKDOWN_TO_IMAGE_API_TOKEN is required");

const response = await fetch("https://markdowntoimage.com/api/v1/images/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    markdown: "# Build report\n\n- Tests: **passed**\n- Deploy: **ready**",
    format: "png",
    width: 1200,
    quality: 2,
    theme: "github-dark",
    mode: "url",
  }),
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`Generation failed: ${response.status} ${await response.text()}`);
}

const result = await response.json();
const imageResponse = await fetch(result.data.imageUrl, {
  signal: AbortSignal.timeout(30_000),
});
if (!imageResponse.ok) {
  throw new Error(`Download failed: ${imageResponse.status}`);
}

await writeFile("build-report.png", Buffer.from(await imageResponse.arrayBuffer()));
console.log("Saved build-report.png");

In einem Webdienst sollte der Auftrag erst nach dem permanenten Upload als erfolgreich gelten. Nur die temporäre API-URL zu speichern, ohne die Datei zu kopieren, führt nach Ablauf der URL zu einem verzögerten Ausfall.

Im URL-Modus folgt Python demselben Muster mit zwei Requests: zuerst rendern, dann herunterladen. Explizite Timeouts verhindern, dass ein Worker unbegrenzt wartet.

import os
from pathlib import Path

import requests

token = os.environ["MARKDOWN_TO_IMAGE_API_TOKEN"]
payload = {
    "markdown": "# Build report\n\n- Tests: **passed**\n- Deploy: **ready**",
    "format": "png",
    "width": 1200,
    "quality": 2,
    "theme": "github-dark",
    "mode": "url",
}

response = requests.post(
    "https://markdowntoimage.com/api/v1/images/generate",
    headers={"Authorization": f"Bearer {token}"},
    json=payload,
    timeout=30,
)
response.raise_for_status()

image_url = response.json()["data"]["imageUrl"]
image_response = requests.get(image_url, timeout=30)
image_response.raise_for_status()
Path("build-report.png").write_bytes(image_response.content)
print("Saved build-report.png")

Bei wachsendem Volumen gehört diese Funktion in eine Job Queue statt in einen langen, nutzerseitigen Request. Die Queue begrenzt Parallelität und Wiederholungen und bietet einen Ort für die endgültige Speicher-URL.

Setze in n8n einen HTTP-Request-Node hinter den Node, der Markdown erzeugt oder lädt. Speichere den Token in n8n Credentials, nicht direkt im Workflow-JSON.

Wähle im HTTP-Request-Node Authentication → Generic Credential Type → Bearer Auth. Erstelle ein Credential und trage nur das rohe Token in das Feld Bearer Token ein. Speichere es und wähle es im Node aus. Füge kein zweites Bearer-Präfix hinzu und schreibe kein Geheimnis ins Workflow-JSON. Diese Schritte stehen in der n8n-Dokumentation zu HTTP-Request-Credentials.

Method: POST
URL: https://markdowntoimage.com/api/v1/images/generate
Authentication: Generic Credential Type
Generic Auth Type: Bearer Auth
Credential: Select the saved MarkdownToImage API credential
Send Body: JSON
Body:
{
  "markdown": "{{$json.content}}",
  "format": "png",
  "width": 1200,
  "quality": 2,
  "theme": "github-dark",
  "mode": "url"
}

Verbinde einen zweiten HTTP-Request-Node, der {{$json.data.imageUrl}} herunterlädt und Dateiausgabe aktiviert. Danach sendest du die Binärdatei an S3, Google Drive, Directus, WordPress, Slack oder das nächste Ziel. Definiere den Fehlerzweig ausdrücklich, damit Authentifizierungs- oder Quotenfehler keinen leeren Datensatz veröffentlichen.

Wähle den URL-Modus, wenn deine Automatisierungsplattform JSON gut verarbeitet und einen zweiten Download ausführen kann. Das ist bequem für Queues, Webhooks und No-Code-Workflows. Die zurückgegebene URL bleibt jedoch nur vorübergehend erhalten, laut aktueller Dokumentation 24 Stunden.

Wähle Binary, wenn eine Antwort direkt in den Speicher gestreamt werden soll. Damit entfällt der zweite HTTP-Aufruf, aber der Client muss Binärinhalt, Content-Type, Dateiendung, Speichergrenzen und die Bereinigung unvollständiger Uploads korrekt behandeln.

Speichere das endgültige Asset unabhängig vom Modus in einem Speicher unter deiner Kontrolle. Halte zusätzlich Format, Breite, Theme, Quell-ID, Erzeugungszeit und einen Hash des Markdowns fest. Das erleichtert Deduplizierung und Fehleranalyse.

Die API dokumentiert diese wichtigen Ergebnisse:

Wiederhole nur vorübergehende Fehler mit begrenztem exponentiellem Backoff und Jitter. Prüfe vorher, ob bereits eine Ausgabe für denselben Inhalts-Hash gespeichert wurde, und koordiniere parallele Worker. Das verringert Wiederholungen, garantiert aber keine serverseitige Idempotenz. Bei einem unklaren Timeout kann das erste Rendering schon erfolgreich gewesen sein, bevor das Ergebnis gespeichert wurde; ein Retry kann daher einen weiteren Credit verbrauchen. Protokolliere solche Jobs zur späteren Klärung statt eine exakt einmalige Abrechnung zu versprechen.

Protokolliere Statuscode, Provider-Fehlercode, Job-ID, Versuch und Latenz, aber niemals den vollständigen Authorization-Header.

Vor echtem Traffic sollten folgende Punkte erfüllt sein:

• API-Token liegt in einem verschlüsselten serverseitigen Secret-Speicher;
• Verbindungs- und Gesamt-Timeouts sind gesetzt;
• Wiederholungen sind begrenzt und nutzen exponentielles Backoff mit Jitter;
• Worker-Parallelität passt zu Quote und nachgelagertem Speicher;
• Markdown-Größe und Pflichtfelder werden vor dem API-Aufruf validiert;
• Format, Breite, Theme, Code-Stil und Schrift sind festgelegt;
• Ergebnisse im URL-Modus werden sofort dauerhaft gespeichert;
• Dateinamen sind sicher und deterministisch, nicht direkt aus Nutzereingaben übernommen;
• veröffentlichte Bilder erhalten Alt-Text und sinnvollen Kontext;
• Nutzung wird gemessen und vor Quotenende alarmiert;
• mehrsprachige Schriften, lange Codezeilen, Tabellen, Mermaid und KaTeX werden mit echten Inhalten getestet;
• geschäftskritische Veröffentlichungen haben einen manuellen Fallback.

Beginne mit einem kleinen, repräsentativen Testset. Zehn echte Markdown-Beispiele decken mehr Layoutprobleme auf als Hunderte „Hello World“-Aufrufe.

Nimm ein Markdown-Dokument, das dein Produkt bereits erzeugt, und führe das cURL-Beispiel damit aus. Prüfe Zeilenumbrüche in Code, Tabellen, Schriften und Bildgröße, bevor du den Workflow ausweitest.

Wenn das erste Rendering passt, öffne den MarkdownToImage-API-Leitfaden, erstelle einen serverseitigen Token und überführe das Node.js-, Python- oder n8n-Rezept in einen kleinen Produktionstest. Sicher startest du mit einem realen Inhaltstyp, einem festen visuellen Preset, dauerhaftem Speicher und beobachtbarer Fehlerbehandlung und skalierst erst danach anhand der Ergebnisse.

# Weekly release

- Faster exports
- Clearer reports
- One automated workflow

> Demo payload for an API integration.

Dies ist Beispielinhalt für markdown, kein echter Release-Bericht. Das Bild ist ein tatsächlicher Editor-Export derselben Quelle und zeigt keinen authentifizierten API-Aufruf. Behalte bei der Verwendung des Beispiels Endpoint, Bearer-Auth und Speicherung aus den Rezepten bei. Prüfe Abstände und Listenflucht und teste die eigene Integration separat.

API-Workflow einrichten.

• Konsistente Social-Media-Karten erstellen
• Browser-Batch und PDF-Automation