MCP Tools-Referenz - Postzee Docs

Vollstaendige Referenz fuer alle 25 Tools, die von Postzees MCP-Server bereitgestellt werden. Diese Tools stehen jedem MCP-kompatiblen KI-Agenten zur Verfuegung (Claude Code, OpenClaw, Hermes Agent oder direkte MCP-Clients).

Alle Tools akzeptieren den API-Key, der in Ihrer MCP-URL eingebettet ist. Sie sind auf eine einzelne Organisation beschraenkt. Kosten fuer KI-Generierung werden immer in Credits zurueckgegeben, niemals in Dollar. ($1 USD = 1.000 Credits.)

Schnellreferenz

Kategorie	Tools
Kontext und Discovery	`POSTZEE_GET_CONTEXT`, `POSTZEE_LIST_PLANS`, `POSTZEE_LIST_CREDIT_PACKAGES`
Modelle und Specs	`POSTZEE_LIST_MODELS_DETAILED`, `POSTZEE_LIST_PLATFORM_SPECS`, `POSTZEE_GET_BEST_POSTING_TIMES`
Kosten und Validierung	`POSTZEE_ESTIMATE_GENERATION_COST`, `POSTZEE_VALIDATE_GENERATION`
Kanaele und Credits	`POSTZEE_LIST_CHANNELS`, `POSTZEE_GET_CREDITS`
Medien-Speicher	`POSTZEE_LIST_MEDIA`, `POSTZEE_UPLOAD_MEDIA`
Prompt-Optimierung	`POSTZEE_ENHANCE_PROMPT`
Generierung	`POSTZEE_GENERATE_IMAGE`, `POSTZEE_GENERATE_VIDEO`, `POSTZEE_CHECK_JOB`
Bilder und Karussells	`POSTZEE_RENDER_IMAGE`, `POSTZEE_RENDER_CAROUSEL`, `POSTZEE_REPLACE_CAROUSEL_SLIDE`, `POSTZEE_APPEND_CAROUSEL_SLIDE`
HeyGen	`POSTZEE_LIST_HEYGEN_AVATARS`, `POSTZEE_LIST_HEYGEN_VOICES`, `POSTZEE_GENERATE_HEYGEN_VIDEO`
Veroeffentlichung	`POSTZEE_CREATE_POST`, `POSTZEE_GET_POST`
Legacy (veraltet)	`POSTZEE_LIST_IMAGE_MODELS`, `POSTZEE_LIST_VIDEO_MODELS`

Kontext und Discovery

POSTZEE_GET_CONTEXT

Kontext-Aggregation in einem einzigen Aufruf. Empfohlen als erster Aufruf jeder Session. Gibt Plan, Credits, Speicher, Kanaele, Features und Skill-Version in einem Round-Trip zurueck. Parameter: Keine Gibt zurueck:

{
  "skill": {
    "currentVersion": "4.0.0",
    "repoUrl": "https://github.com/Zee-Labs/postzee-skill",
    "downloadUrl": "https://github.com/Zee-Labs/postzee-skill/releases/latest/download/postzee-skill.zip",
    "releaseNotesUrl": "https://github.com/Zee-Labs/postzee-skill/releases/latest"
  },
  "plan": {
    "tier": "FREE | STANDARD | TEAM | PRO | ULTIMATE",
    "isLifetime": false,
    "period": "MONTHLY | YEARLY | null",
    "cancelAt": "string | null",
    "canPost": true,
    "canConnectChannels": true,
    "canUseAi": true,
    "channelsLimit": 5,
    "postsPerMonth": 400,
    "postsRemaining": 380,
    "monthlyCredits": 2000,
    "storageLimitGB": 15,
    "monthPriceUSD": 27,
    "yearPriceUSD": 252
  },
  "credits": {
    "available": 4500,
    "monthly": 2000,
    "purchased": 2500,
    "used": 0,
    "lastResetAt": "2026-04-15T10:00:00Z",
    "nextResetAt": "2026-05-15T10:00:00Z"
  },
  "storage": { "usedGB": 1.2, "limitGB": 15, "percentUsed": 8 },
  "channels": {
    "connected": 5,
    "active": 4,
    "requiresReauth": 1,
    "disabled": 0,
    "withIssues": 1
  },
  "organization": { "id": "...", "timezone": "Europe/Berlin" },
  "features": {
    "img2vid": true,
    "veoR2V": false,
    "soraStoryboard": false,
    "sora1080p": true,
    "audioControl": true,
    "firstLastFrame": true,
    "firstLastFrameProvider": "wan-flf2v",
    "heygen": true
  }
}

Die features.*-Flags spiegeln wider, was das MCP gerade jetzt ausfuehren kann — Agenten sollten nur Features vorschlagen, deren entsprechende Flag true ist.

POSTZEE_LIST_PLANS

Listet die 5 Abonnement-Stufen mit Preisen und Limits auf. Parameter: Keine Gibt zurueck:

[
  {
    "tier": "STANDARD",
    "monthPriceUSD": 27,
    "yearPriceUSD": 252,
    "yearMonthlyDisplayUSD": 21,
    "channelsLimit": 5,
    "postsPerMonth": 400,
    "postsUnlimited": false,
    "monthlyCredits": 2000,
    "storageLimitGB": 15,
    "canPost": true,
    "canUseAi": true,
    "teamMembers": false,
    "publicApi": true,
    "webhooks": 2
  }
]

POSTZEE_LIST_CREDIT_PACKAGES

Listet One-Time-Credit-Pakete (ewig — laufen nie ab). Parameter: Keine Gibt zurueck:

[
  { "id": "starter", "name": "Starter", "priceUSD": 2, "credits": 2000, "popular": false },
  { "id": "basic", "name": "Basic", "priceUSD": 10, "credits": 10000, "popular": false },
  { "id": "standard", "name": "Standard", "priceUSD": 25, "credits": 25000, "popular": true },
  { "id": "pro", "name": "Pro", "priceUSD": 50, "credits": 50000, "popular": false },
  { "id": "enterprise", "name": "Enterprise", "priceUSD": 100, "credits": 100000, "popular": false }
]

Modelle und Specs

POSTZEE_LIST_MODELS_DETAILED

Capability-Matrix fuer alle verfuegbaren Bild- und Video-Modelle — Dauern, Aufloesungen, Audio-Faehigkeiten, akzeptierte Custom-Parameter und relativer Cost-Tier. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`type`	string	Nein	`"image"`, `"video"` oder `"all"` (default)
`includeHeygen`	boolean	Nein	Inkludiert den synthetischen HeyGen-Eintrag. Default: `true`
`family`	string	Nein	Filtert auf eine einzelne Familie (z. B. `"ideogram-v3"`, `"sora-2"`, `"veo3.1"`)
`agenticDefault`	boolean	Nein	Bei `true` werden nur Eintraege zurueckgegeben, die als empfohlene Wahl fuer Automatisierung markiert sind

Gibt zurueck (pro Modell):

{
  "modelId": "sora-2-t2v-pro-1080p",
  "displayName": "Sora 2 Pro 1080p (Text-to-Video)",
  "type": "video",
  "family": "sora-2-pro",
  "tierWithinFamily": "premium",
  "audio": "speech-lipsync",
  "supportsImg2Img": false,
  "supportsImg2Vid": false,
  "supportsVector": false,
  "durations": [10, 15],
  "resolutions": ["1080p"],
  "aspectRatios": ["16:9", "9:16"],
  "recommendedAspectsByPlatform": {
    "instagram_reels": "9:16",
    "tiktok_feed": "9:16",
    "youtube_feed": "16:9"
  },
  "customParamsAccepted": {
    "duration": { "type": "enum", "enum": [10, 15], "description": "..." }
  },
  "costTier": "premium",
  "popular": false,
  "agenticDefault": false,
  "agenticDefaultFree": false,
  "bestFor": ["highest cinematic quality", "1080p Pro", "final publication"],
  "notRecommendedFor": ["high-volume automation"]
}

costTier ist einer von very-low, low, mid, high, premium — die absoluten Credit-Kosten werden absichtlich nicht offengelegt; verwenden Sie stattdessen POSTZEE_ESTIMATE_GENERATION_COST. Der synthetische heygen-avatar-video-Eintrag hat costTier: "external" und einen billingNote, der angibt, dass HeyGen ueber das HeyGen-Konto des Benutzers abrechnet, nicht ueber Postzee-Credits.

POSTZEE_LIST_PLATFORM_SPECS

Specs pro Plattform (Aspect Ratios, max. Slides fuer Carousels, Zeichenlimits fuer Captions, Hashtag-Empfehlungen). Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`platforms`	string[]	Nein	Filtert auf bestimmte Plattformen (z. B. `["instagram", "tiktok"]`). Weglassen fuer alle.

Abgedeckte Plattformen: instagram, facebook, linkedin, x, tiktok, youtube, pinterest, threads, bluesky, reddit.

POSTZEE_GET_BEST_POSTING_TIMES

Heuristische Best-Posting-Time-Fenster pro Kanal, in der Zeitzone der Organisation zurueckgegeben. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`channelIds`	string[]	Nein	Filtert auf bestimmte Kanaele. Weglassen fuer alle aktiven Kanaele.

Gibt zurueck:

[
  {
    "channelId": "...",
    "platform": "instagram",
    "name": "My Instagram",
    "timezone": "Europe/Berlin",
    "bestTimes": [
      { "time": "11:00", "timezone": "Europe/Berlin", "nextDateLocal": "2026-05-06", "score": 90, "reason": "Lunchtime peak", "source": "heuristic" },
      { "time": "19:00", "timezone": "Europe/Berlin", "nextDateLocal": "2026-05-06", "score": 95, "reason": "Evening prime", "source": "heuristic" }
    ]
  }
]

Kanaele mit Status disabled oder requiresReauth werden gefiltert — Empfehlungen erscheinen nur fuer Kanaele, die tatsaechlich posten koennen.

Kosten und Validierung

POSTZEE_ESTIMATE_GENERATION_COST

Single Source of Truth fuer Kostenschaetzungen. Gibt immer Credits zurueck, niemals Dollar. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`type`	string	Ja	`"image"` oder `"video"`
`model`	string	Ja	Model-ID aus `POSTZEE_LIST_MODELS_DETAILED`
`duration`	number	Nein	Sekunden (Video, fuer Modelle mit Pro-Sekunde-Pricing)
`resolution`	string	Nein	`"480p"`, `"540p"`, `"720p"`, `"1080p"`, `"4k"`
`quality`	string	Nein	Sora 2 Pro: `"standard"` (720p) oder `"high"` (1080p)
`generateAudio`	boolean	Nein	Beeinflusst Kosten bei Veo, Pixverse, Wan 2.5
`voiceControl`	boolean	Nein	Kling 2.6/3.0 Pro
`aspectRatio`	string	Nein	Informativ

Gibt zurueck:

{
  "modelId": "sora-2-t2v-pro",
  "displayName": "Sora 2 Pro Text-to-Video",
  "estimatedCredits": 5000,
  "currentBalance": 4500,
  "willExceedBalance": true,
  "creditsAfter": 0,
  "shortfall": 500,
  "warnings": []
}

POSTZEE_VALIDATE_GENERATION

Pre-Flight-Validierung — faengt Parameterfehler, unzureichende Credits, Speicherprobleme und Plan-Blockaden ab, bevor Credits verbrannt werden. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`type`	string	Ja	`"image"` oder `"video"`
`model`	string	Ja	Model-ID
`duration`	number	Nein	Sekunden
`aspectRatio`	string	Nein	z. B. `"4:5"`
`resolution`	string	Nein	Ausgabe-Aufloesung
`quality`	string	Nein	Sora Pro `"standard"` / `"high"`
`generateAudio`	boolean	Nein
`voiceControl`	boolean	Nein
`imageUrl`	string	Nein	Erforderlich fuer image-to-video-Modelle
`slideCount`	number	Nein	Batch-Multiplikator (z.B. N Variationen desselben Prompts). Nicht fuer Karussells — diese laufen ueber `POSTZEE_RENDER_CAROUSEL` mit eigenem Kostenmodell.

Gibt zurueck:

{
  "valid": true,
  "errors": [],
  "warnings": ["Storage at 85% — approaching limit."],
  "estimatedCreditsPerItem": 160,
  "totalEstimatedCredits": 1600,
  "slideCount": 10,
  "currentBalance": 4500,
  "willExceedBalance": false,
  "shortfall": 0
}

Wenn valid: false, enthaelt das Array errors[] lesbare Probleme — z. B. Dauer ist nicht im erlaubten Set des Modells, fehlende imageUrl fuer i2v-Modell, Speicher bei 100%, oder Modell ist registriert, aber noch nicht ueber MCP fahrbar.

Kanaele und Credits

POSTZEE_LIST_CHANNELS

Listet verbundene Social-Media-Kanaele mit expliziten Action-Flags auf. Parameter: Keine Gibt zurueck:

[
  {
    "id": "channel-uuid",
    "name": "My Instagram",
    "platform": "instagram",
    "picture": "https://...",
    "profile": "https://...",
    "disabled": false,
    "requiresReauth": false,
    "canPostNow": true,
    "actionRequired": "none",
    "actionUrl": null,
    "actionMessage": null,
    "status": "active",
    "statusMessage": null
  }
]

actionRequired ist einer von "none" (bereit zu posten), "reconnect" (Token abgelaufen — der Benutzer verbindet neu) oder "reenable" (Admin/Billing — der Benutzer reaktiviert, nicht dasselbe wie reconnect). statusMessage ist eine lesbare Erklarung, wenn der Kanal eine Aktion erfordert (z.B. "Kanal-Token abgelaufen. Verbinden Sie erneut, um weiter zu posten."). Es ist null, wenn actionRequired "none" ist.

POSTZEE_GET_CREDITS

Leichtes Credit-Saldo. Subset von POSTZEE_GET_CONTEXT.credits — bevorzugen Sie letzteres fuer neuen Code. Parameter: Keine Gibt zurueck:

{
  "available": 4500,
  "monthly": 2000,
  "used": 0,
  "purchased": 2500
}

Alle Werte in Credits ($1 USD = 1.000 Credits).

Medien-Speicher

Die folgenden zwei Tools erlauben einem Agenten, Medien-Assets — sowohl KI-generierte als auch vom Nutzer hochgeladene — ueber Turns und Sessions hinweg abzurufen und wiederzuverwenden, ohne den Nutzer erneut nach URLs fragen zu muessen.

POSTZEE_LIST_MEDIA

Liste der zuletzt erstellten Medien, beschraenkt auf die Organisation. Neueste zuerst. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`type`	string	Nein	`"image"`, `"video"` oder `"all"` (Standard)
`source`	string	Nein	`"generated"` (von KI erstellt), `"uploaded"` (importiert via `POSTZEE_UPLOAD_MEDIA`) oder `"all"` (Standard)
`search`	string	Nein	Case-insensitive Suche im Original-Prompt (KI-Medien) und Dateiname
`since`	string	Nein	ISO-Datum — gibt nur Medien zurueck, die nach diesem Zeitpunkt erstellt wurden
`limit`	number	Nein	Standard 20, Maximum 100

Gibt zurueck (pro Eintrag):

{
  "mediaId": "uuid",
  "url": "https://cdn.postzee.app/abc.jpg",
  "name": "abc.jpg",
  "type": "image",
  "source": "generated",
  "prompt": "Hund am Strand bei Sonnenuntergang",
  "modelUsed": "ideogram-v3-turbo",
  "createdAt": "2026-05-07T14:23:00Z",
  "sizeBytes": 245678,
  "dimensions": { "width": 1024, "height": 1280 }
}

Gibt zurueck (Fehler):

{ "error": "list_media_failed", "message": "..." }

Soft-geloeschte Medien werden automatisch ausgeschlossen. Medien, die als Profilbild verwendet werden, werden ebenfalls ausgeschlossen.

POSTZEE_UPLOAD_MEDIA

Importiert eine oeffentliche URL in Postzees Speicher. Gibt eine stabile mediaId und CDN-URL zurueck, die in GENERATE_*, CREATE_POST und LIST_MEDIA wiederverwendet werden kann. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`url`	string	Ja	Oeffentliche `http://` oder `https://` URL. Muss ohne Authentifizierung erreichbar sein.
`description`	string	Nein	Kurzes Label, das mit dem Medium gespeichert wird (hilft dem Agenten, sein Manifest zu pflegen)

Gibt zurueck (Erfolg):

{
  "success": true,
  "mediaId": "uuid",
  "url": "https://cdn.postzee.app/uploads/xyz.jpg",
  "type": "image",
  "sizeBytes": 524288,
  "dimensions": { "width": 1080, "height": 1920 }
}

Gibt zurueck (Fehler):

{
  "success": false,
  "error": "blocked_url | unsupported_type | size_limit_exceeded | fetch_failed | storage_full | upload_failed | save_failed",
  "message": "..."
}

Validierungs-Reihenfolge (jeder Schritt lehnt vor dem naechsten ab):

URL ist parsebar und nutzt http/https
Hostname ist nicht localhost / private IP / Cloud-Metadata-Endpoint (SSRF-Schutz)
HEAD-Probe erfolgreich (oder Range-GET als Fallback)
Content-Type entspricht der konfigurierten Allowlist (Standard: image/jpeg, image/png, image/webp, image/gif / video/mp4, video/quicktime, video/webm)
Groesse innerhalb des typ-spezifischen Limits (Standard: 25 MB Bild, 500 MB Video)
Speicher-Quota der Organisation hat Platz

Standard-Limits (konfigurierbar via SystemConfig):

Typ	Max-Groesse	Akzeptierte Formate
Bild	25 MB	JPG, PNG, WebP, GIF
Video	500 MB	MP4, MOV, WebM

Limits und akzeptierte Formate koennen zur Laufzeit angepasst werden, indem die UPLOAD_*-Schluessel im SystemConfig geaendert werden. Sowohl dieses MCP-Tool als auch die REST-Upload-Endpoints teilen sich dieselbe Quelle — einmal aendern, gilt ueberall innerhalb von ~5 Minuten (Cache-TTL).

Aus Datenschutz- und Sicherheitsgruenden akzeptiert das Tool niemals Authentifizierungs-Header oder Tokens. URLs, die einen Bot-Token erfordern (z. B. Telegram getFile-URLs), muessen vom Chat-Client zuerst auf eine oeffentliche URL umgehostet werden. Fuer Base64-/Direkt-Datei-Uploads nutzen Sie den bestehenden REST-Endpoint /media/upload-server — das MCP-Tool verwaltet nur URL-Importe.

Nach erfolgreichem Import erscheint das Medium in POSTZEE_LIST_MEDIA mit source: "uploaded".

Prompt-Optimierung

POSTZEE_ENHANCE_PROMPT

Optimiert den Benutzer-Prompt fuer bessere KI-Generierungsergebnisse. Kostenlos — keine Credit-Kosten. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`prompt`	string	Ja	Der zu optimierende Benutzer-Prompt
`mediaType`	string	Ja	`"image"` oder `"video"`
`model`	string	Nein	Ziel-Model-ID (fuer modellspezifische Optimierung)
`language`	string	Nein	Ausgabesprache-Code (z.B. `"pt"`, `"es"`, `"fr"`, `"de"`). Falls weggelassen, wird die Sprache des Kontoinhabers oder Englisch als Standard verwendet.

Gibt zurueck:

{ "success": true, "enhancedPrompt": "A young woman in a tailored trench coat walks through..." }

Generierung

POSTZEE_GENERATE_IMAGE

Generiert ein KI-Bild aus einem Prompt. Asynchrone Operation — gibt eine Job-ID zurueck, die mit POSTZEE_CHECK_JOB gepollt werden muss. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`prompt`	string	Ja	Detaillierte Bildbeschreibung
`model`	string	Ja	Model-ID aus `POSTZEE_LIST_MODELS_DETAILED` (type `"image"`)
`aspectRatio`	string	Nein	z. B. `"1:1"`, `"4:5"`, `"9:16"`, `"16:9"`. Default: `"1:1"`
`imageUrls`	string[]	Nein	Referenz-Bild-URLs fuer image-to-image
`quality`	string	Nein	GPT Image 2: `"low"`, `"medium"` oder `"high"`. Default: `"high"`
`style`	string	Nein	Recraft V3/V4: `"realistic_image"`, `"digital_illustration"`, `"vector_illustration"`
`renderingSpeed`	string	Nein	Ideogram-V3-Tier: `"turbo"`, `"balanced"` oder `"quality"`
`negativePrompt`	string	Nein	Dinge, die aus dem Bild ausgeschlossen werden sollen
`seed`	number	Nein	Optionaler deterministischer Seed

Gibt zurueck (Erfolg):

{ "success": true, "jobId": "job-uuid", "status": "processing", "message": "Image generation started..." }

Gibt zurueck (Fehler):

{ "success": false, "error": "unsupported_model | unknown_model | wrong_type | organization_not_found | generation_failed", "message": "...", "suggestions": [{ "modelId": "...", "reason": "..." }] }

POSTZEE_GENERATE_VIDEO

Generiert ein KI-Video aus einem Prompt oder Referenzbild. Asynchrone Operation. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`prompt`	string	Ja	Detaillierte Videobeschreibung
`model`	string	Ja	Model-ID aus `POSTZEE_LIST_MODELS_DETAILED` (type `"video"`)
`duration`	number	Nein	Sekunden. Erlaubte Werte variieren pro Modell — siehe `model.durations`
`aspectRatio`	string	Nein	`"16:9"` oder `"9:16"`. Default: `"16:9"`
`imageUrl`	string	Nein	Referenz-Bild-URL fuer image-to-video-Modelle
`endImageUrl`	string	Nein	URL des End-Frames fuer First-Last-Frame-Interpolation (z. B. `wan-flf2v`)
`resolution`	string	Nein	`"480p"`, `"540p"`, `"720p"`, `"1080p"`, `"4k"` (modellabhaengig)
`quality`	string	Nein	Nur Sora 2 Pro: `"standard"` (720p) oder `"high"` (1080p)
`generateAudio`	boolean	Nein	Generiert Umgebungsgeraeusche (Veo 3.1, Pixverse, Wan 2.5). Beeinflusst Credits.
`voiceControl`	boolean	Nein	Stimmkontrolle (Kling 2.6/3.0 Pro). Beeinflusst Credits.
`negativePrompt`	string	Nein	Dinge, die im Video vermieden werden sollen
`seed`	number	Nein	Optionaler deterministischer Seed

Gibt zurueck: gleiche Struktur wie POSTZEE_GENERATE_IMAGE.

Die tier-spezifischen Model-IDs, die von POSTZEE_LIST_MODELS_DETAILED zurueckgegeben werden (z. B. ideogram-v3-turbo, gpt-image-2-high, sora-2-t2v-pro-1080p, recraft-v4-vector), koennen direkt an model uebergeben werden. Der MCP uebersetzt sie automatisch in den richtigen Backend-Payload — ein separater Parameter tier oder quality ist fuer die Tier-Auswahl nicht erforderlich.

Einige Model-IDs im Katalog sind noch nicht ueber MCP fahrbar und werden im Voraus abgelehnt (Sora 2 storyboard-Varianten, einige Veo 3.1-Pfade). Die Fehlerantwort enthaelt ein Array suggestions[] mit bis zu drei naheliegenden Alternativen — waehlen Sie eine davon.

POSTZEE_CHECK_JOB

Pollt den Status eines asynchronen Bild- oder Video-Generierungsjobs. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`jobId`	string	Ja	Job-ID aus `POSTZEE_GENERATE_*`

Gibt zurueck (in Bearbeitung):

{ "jobId": "...", "status": "processing", "progress": 45 }

Gibt zurueck (Erfolg):

{ "jobId": "...", "status": "success", "progress": 100, "mediaUrl": "https://cdn.postzee.app/...", "mediaId": "media-uuid" }

Gibt zurueck (Fehler):

{ "jobId": "...", "status": "failed", "error": "Generation failed: ..." }

Gibt zurueck (nicht gefunden):

{ "jobId": "...", "status": "not_found" }

Bilder und Karussells

Die Bild- und Karussell-Pipeline laesst den Agent redaktionelle Slides mit pixelgenauer Typografie, konsistenten Schriften und keine halluzinierten Woerter komponieren. Der Agent reicht den/die komponierten Slide(s) ein; Postzee rendert und gibt das fertige Medium veroeffentlichungsbereit zurueck. Vier Tools decken den Lebenszyklus ab: ein Einzelbild-Render fuer eigenstaendige redaktionelle Posts mit gepflegter Typografie, ein vollstaendiges Karussell-Render fuer den initialen Batch, chirurgischer Slide-Austausch fuer Korrekturen und inkrementeller Append fuer iteratives Authoring.

POSTZEE_RENDER_IMAGE

Rendert EIN HTML-Dokument zu einem einzelnen Media-PNG. Das Single-Image-Gegenstueck zu POSTZEE_RENDER_CAROUSEL, fuer eigenstaendige redaktionelle Posts (textreiche Einzelbilder, Magazin-Style-Cover, Hero-Quote-Cards), bei denen der Wert im Layout + der Typografie liegt statt in einer swipebaren Sequenz. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`html`	string	Ja	Vollstaendiges `<!doctype html>`-Dokument fuer die Folie. Bilder per Postzee-CDN-URL referenzieren (zurueckgegeben von `POSTZEE_GENERATE_IMAGE` oder `POSTZEE_UPLOAD_MEDIA`). Nur statische Komposition — keine interaktiven Scripts.
`width`	number	Nein	Ausgabebreite in px (256-2160). Default `1080`.
`height`	number	Nein	Ausgabehoehe in px (256-2160). Default `1350` (4:5 — optimiert fuer Instagram-Feed).
`name`	string	Nein	Optionaler Titel in der Galerie.

Gleiche harte Limits wie POSTZEE_RENDER_CAROUSEL: 7 MB max Payload pro Slide, 256-2160 px pro Dimension, 45 s Render-Timeout. Gibt zurueck (Erfolg):

{
  "success": true,
  "mediaId": "media-uuid",
  "mediaUrl": "https://cdn.postzee.app/...",
  "width": 1080,
  "height": 1350,
  "mediaGroupId": "group-uuid",
  "message": "Image rendered successfully (1080×1350). Use 'mediaUrl' when calling POSTZEE_CREATE_POST."
}

mediaGroupId ist fuer fortgeschrittene Caller verfuegbar, aber die typische Verwendung ist, die mediaUrl direkt an POSTZEE_CREATE_POST als Einzelelement-mediaUrls-Array zu uebergeben. Gibt zurueck (Fehler):

{ "success": false, "error": "render_failed", "message": "..." }

Gleicher Idempotency-Cache wie das Karussell-Render: identische Payloads innerhalb eines 1-Stunden-Fensters geben die gecachte mediaId zurueck statt neu zu rendern.

POSTZEE_RENDER_CAROUSEL

Rendert N HTML-Slides zu PNG und gruppiert sie atomar als ein MediaGroup-Karussell. Synchron — blockiert, bis alle Slides fertig sind. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`slides`	array	Ja	1-15 Slide-Objekte in Anzeigereihenfolge. Jedes: `{ html: string, width?: number, height?: number }`. Der Array-Index wird zur Slide-Reihenfolge.
`aspectRatio`	string	Nein	Standard-Canvas-Groesse, wenn width/height weggelassen werden: `"1:1"` (1080×1080), `"4:5"` (1080×1350), `"9:16"` (1080×1920). Default `"1:1"`.
`name`	string	Nein	Optionaler Titel, der in der Galerie angezeigt wird.

Server-side enforcierte Limits:

Maximal 15 Slides pro Aufruf
Minimum 256 / Maximum 2160 px pro Dimension
7 MB max HTML pro Slide
50 MB max Gesamt-Payload pro Aufruf (Summe aller Slides)
45 s Timeout pro Slide

Plattformbewusste Publish-Guards. Das Rendering akzeptiert bis zu 15 Slides, aber das Publishing ist an das native Limit jedes sozialen Netzwerks gebunden (Instagram/Facebook ≤ 10, LinkedIn ≤ 20, TikTok ≤ 35, Threads/Reddit ≤ 20, Pinterest ≤ 5, X ≤ 4, Bluesky/Mastodon ≤ 4, Telegram/VK ≤ 10). Wenn POSTZEE_CREATE_POST mit mediaUrls aufgerufen wird, die das Limit des Ziel-Netzwerks ueberschreiten, lehnt Postzee den Beitrag ab, bevor die Plattform-API aufgerufen wird — mit einer in die Sprache des Nutzers uebersetzten Fehlermeldung. Rufe POSTZEE_LIST_PLATFORM_SPECS fuer die aktuelle Tabelle ab. Partial-tolerantes Fehlermodell. Wenn ein Slide fehlschlaegt oder der Dispatcher Timeout hat, bevor alle Slides sich setzen, wird die Gruppe mit renderStatus: "partial" in aiMetadata erhalten (statt zurueckgerollt). Wiederhole fehlende Slides via POSTZEE_REPLACE_CAROUSEL_SLIDE oder POSTZEE_APPEND_CAROUSEL_SLIDE. Slides, die GERENDERT haben, werden nie zerstoert — der Nutzer behaelt seine Arbeit auch bei Teil-Fehlschlag. Reihenfolge ist strukturell, nicht zeitlich. Der Array-Index = orderInGroup, zugewiesen BEVOR irgendein Worker laeuft. Slides koennen parallel rendern, aber die Reihenfolge wird deterministisch erhalten. Sicherheitsmodell. Slide-Kompositionen werden als statischer Inhalt gerendert — interaktive Scripts sind inert. Netzwerk-Anfragen fuer referenzierte Assets sind auf oeffentliche Hosts beschraenkt (private/interne Adressen werden blockiert). Gibt zurueck:

{
  "success": true,
  "mediaGroupId": "uuid",
  "totalSlides": 10,
  "aspectRatio": "4:5",
  "slides": [
    { "mediaId": "...", "url": "https://cdn.postzee.app/.../slide-0.png", "orderInGroup": 0 },
    { "mediaId": "...", "url": "https://cdn.postzee.app/.../slide-1.png", "orderInGroup": 1 }
  ],
  "mediaUrls": [
    "https://cdn.postzee.app/.../slide-0.png",
    "https://cdn.postzee.app/.../slide-1.png"
  ]
}

mediaUrls ist bereits in Anzeigereihenfolge — direkt an POSTZEE_CREATE_POST weitergeben. Fehlschlag-Antwort:

{ "success": false, "error": "render_failed", "message": "Carousel rendering failed: ..." }

POSTZEE_REPLACE_CAROUSEL_SLIDE

Ersetzt chirurgisch EINE Folie eines existierenden Karussells, ohne die anderen anzufassen. Verwende es, wenn der Nutzer “aendere Folie N” sagt — spart Zeit und Credits und erhaelt die Identitaet der anderen Slides (URLs und IDs unveraendert). Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`mediaGroupId`	string	Ja	Die von `POSTZEE_RENDER_CAROUSEL` zurueckgegebene id.
`orderInGroup`	number	Ja	Null-basierter Index der zu ersetzenden Folie. Folie 4 → `3`. Muss auf einen aktiven (nicht soft-deleted) Slide zeigen.
`slide`	object	Ja	`{ html, width?, height? }` — gleiche Struktur wie ein Eintrag von `RENDER_CAROUSEL.slides`.

Der ersetzte Slide wird soft-deleted, nachdem das neue Render erfolgreich hochgeladen wurde; der neue Slide nimmt denselben orderInGroup. Wenn orderInGroup === 0, wird das Cover-Thumbnail des Karussells automatisch aktualisiert. Gibt zurueck:

{
  "success": true,
  "mediaGroupId": "uuid",
  "replacedOrderInGroup": 3,
  "newMediaId": "...",
  "newMediaUrl": "https://cdn.postzee.app/.../slide-3-{ts}.png",
  "totalSlides": 10,
  "slides": [ /* ... vollstaendige geordnete Liste ... */ ],
  "mediaUrls": [ /* ... vollstaendige geordnete Liste ... */ ],
  "message": "Slide 4 replaced. The other slides are unchanged. If you already attached the carousel to a draft post, refresh the attachments — the old slide URL is now soft-deleted."
}

POSTZEE_APPEND_CAROUSEL_SLIDE

Haengt EINEN neuen Slide an das Ende eines existierenden Karussells an. Verwende es fuer iteratives Authoring — wenn der Nutzer das Karussell Slide fuer Slide bauen will (“zeig mir Slide 1… jetzt Slide 2…”), sorgt das dafuer, dass jeder neue Slide in derselben MediaGroup landet, statt N einzelne verwaiste Slide-Gruppen in der Galerie zu produzieren. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`mediaGroupId`	string	Ja	Die id des Karussells, das du erweiterst. Zurueckgegeben von `POSTZEE_RENDER_CAROUSEL` (erster Slide) oder einem vorigen `APPEND_CAROUSEL_SLIDE`-Aufruf.
`slide`	object	Ja	`{ html, width?, height? }` — gleiche Struktur wie ein Eintrag von `RENDER_CAROUSEL.slides`.

Der neue Slide wird am naechsten verfuegbaren orderInGroup angehaengt (gap-safe — wenn Zwischen-Slides geloescht wurden, nimmt das max(orderInGroup) + 1, verwendet nie einen freien Slot wieder). Cover-Thumbnail bleibt unveraendert. Iteratives Authoring-Pattern. Der erste Slide sollte immer noch durch POSTZEE_RENDER_CAROUSEL gehen (das erstellt die MediaGroup). Jeder folgende Slide geht durch APPEND_CAROUSEL_SLIDE mit derselben mediaGroupId. RENDER_CAROUSEL ein zweites Mal fuer dasselbe logische Karussell aufzurufen, erzeugt eine neue Gruppe und bricht den iterativen Fluss — tu das nicht. Gibt zurueck:

{
  "success": true,
  "mediaGroupId": "uuid",
  "appendedOrderInGroup": 7,
  "newMediaId": "...",
  "newMediaUrl": "https://cdn.postzee.app/.../slide-7-{ts}.png",
  "totalSlides": 8,
  "slides": [ /* ... vollstaendige geordnete Liste inkl. neuem ... */ ],
  "mediaUrls": [ /* ... vollstaendige geordnete Liste ... */ ]
}

Es gibt in v1 keine Insert-in-der-Mitte / Reorder / Delete-Primitive. APPEND_CAROUSEL_SLIDE fuegt nur am ENDE hinzu. Wenn der Nutzer einfuegen an einer bestimmten Position, zwei Slides tauschen oder einen entfernen moechte, baue das gesamte Karussell mit POSTZEE_RENDER_CAROUSEL aus einem neuen Skript neu auf.

HeyGen

HeyGen-Tools erfordern einen in Ihrem Postzee-Konto konfigurierten HeyGen-API-Key. Verbinden Sie ihn unter Settings → HeyGen-Integration. HeyGen-Videogenerierung rechnet auf dem HeyGen-Konto des Benutzers ab, nicht auf Postzee-Credits.

POSTZEE_LIST_HEYGEN_AVATARS

Listet verfuegbare HeyGen-Avatare auf (filtern Sie nach Geschlecht, Alter, Stil usw. clientseitig). Parameter: Keine Gibt zurueck: Array von Avataren aus Ihrem HeyGen-Konto.

POSTZEE_LIST_HEYGEN_VOICES

Listet verfuegbare HeyGen-Stimmen auf. Parameter: Keine Gibt zurueck: Array von Stimmen aus Ihrem HeyGen-Konto, mit Sprach- und Geschlechtsinformationen.

POSTZEE_GENERATE_HEYGEN_VIDEO

Erstellt ein Avatar-Video mit HeyGen. Asynchrone Operation — pollen Sie mit POSTZEE_CHECK_JOB. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`script`	string	Ja	Text, den der Avatar sprechen soll (20-1500 Zeichen)
`avatarId`	string	Ja	Aus `POSTZEE_LIST_HEYGEN_AVATARS`
`voiceId`	string	Ja	Aus `POSTZEE_LIST_HEYGEN_VOICES`
`aspectRatio`	string	Nein	`"16:9"` oder `"9:16"`. Default: `"16:9"`

Gibt zurueck: gleiche Struktur wie POSTZEE_GENERATE_IMAGE — jobId + status: "processing". Die Antwort weist auch darauf hin, dass HeyGen-Credits (nicht Postzee) verbraucht werden.

Veroeffentlichung

POSTZEE_CREATE_POST

Erstellt, plant oder veroeffentlicht einen Post auf einem Social-Media-Kanal. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`type`	string	Ja	`"now"` (sofort veroeffentlichen), `"draft"` oder `"schedule"`
`date`	string	Nur Schedule	UTC-Datetime (z. B. `"2026-04-24T15:00:00Z"`) — erforderlich, wenn `type` `"schedule"` ist
`channelId`	string	Ja	Channel-ID aus `POSTZEE_LIST_CHANNELS`
`text`	string	Ja	Post-Inhalt
`mediaUrls`	string[]	Nein	Medien-URLs (in Anzeigereihenfolge — Array-Reihenfolge = Slide-Reihenfolge fuer Carousels)
`settings`	object	Nein	Plattform-spezifische Veroeffentlichungseinstellungen. Senden Sie ein flaches Objekt mit nur den fuer das Zielnetzwerk relevanten Feldern — z.B. `{ "post_type": "story" }` fuer Instagram, `{ "privacy_level": "PUBLIC_TO_EVERYONE", "duet": true }` fuer TikTok. Der MCP routet die Settings basierend auf dem Kanal zum richtigen Validator. Siehe Plattform-Einstellungen fuer die vollstaendige Referenz.

Gibt zurueck (Erfolg):

{ "success": true, "postId": "post-uuid", "message": "Post queued for immediate publishing successfully. Poll POSTZEE_GET_POST with this postId until state is \"PUBLISHED\"..." }

Die Veroeffentlichung ist asynchron: POSTZEE_CREATE_POST gibt sofort eine postId zurueck, der Post ist aber noch nicht live. Pollen Sie POSTZEE_GET_POST mit dieser postId, bis state den Wert "PUBLISHED" hat, um die Plattform-Post-ID (releaseId) und den Permalink (releaseURL) zu erhalten. Gibt zurueck (Fehler):

{ "success": false, "error": "<error_code>", "message": "...", "upgradeUrl": "https://dashboard.postzee.app/billing" }

Moegliche error-Codes:

Code	Bedeutung
`subscription_required`	Der aktuelle Plan erlaubt keine Veroeffentlichung oder das monatliche Post-Limit ist erreicht. `upgradeUrl` ist enthalten.
`date_required`	`type: "schedule"` wurde ohne `date` gesendet.
`invalid_date`	Der `date`-String ist kein gueltiges UTC-ISO-Timestamp.
`organization_not_found`	Der MCP-Key wurde zu einer nicht existierenden Organisation aufgeloest (selten).
`post_failed`	Provider-/Netzwerkfehler waehrend der Veroeffentlichung. Einmal wiederholen; bei Persistenz die `message` anzeigen.

POSTZEE_GET_POST

Ruft den Veroeffentlichungsstatus eines einzelnen Posts ab — pollen Sie dies nach POSTZEE_CREATE_POST, um die Plattform-Post-ID und den Permalink zu erhalten, sobald der Post live geht. Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`postId`	string	Ja	Die von `POSTZEE_CREATE_POST` zurueckgegebene Post-ID

Gibt zurueck (Erfolg):

{
  "success": true,
  "id": "post-uuid",
  "state": "PUBLISHED",
  "published": true,
  "releaseId": "17895695668004550",
  "releaseURL": "https://www.instagram.com/p/Cabc123/",
  "platform": "instagram",
  "channelId": "channel-uuid",
  "channelName": "My Instagram",
  "publishDate": "2026-04-29T15:00:00Z",
  "message": "Post is published. releaseId is the native platform post id; releaseURL is the public permalink."
}

Feld	Beschreibung
`state`	`QUEUE` (wartet), `PUBLISHED`, `ERROR` oder `DRAFT`
`published`	`true`, wenn `state` den Wert `PUBLISHED` hat
`releaseId`	Die native Plattform-Post-ID (z.B. die Instagram-Media-ID). `null` bis veroeffentlicht
`releaseURL`	Der oeffentliche Permalink zum Post. `null` bis veroeffentlicht

Solange der Post noch veroeffentlicht wird, ist state "QUEUE" und releaseId/releaseURL sind null — pollen Sie weiter, bis state "PUBLISHED" ist (oder "ERROR", falls die Veroeffentlichung fehlgeschlagen ist). Gibt zurueck (Fehler):

{ "success": false, "error": "post_not_found", "message": "Post <id> not found for this organization." }

Legacy-Tools (veraltet)

Die folgenden Tools funktionieren noch, sind aber abgeloest:

POSTZEE_LIST_IMAGE_MODELS → verwenden Sie POSTZEE_LIST_MODELS_DETAILED({ type: "image" })
POSTZEE_LIST_VIDEO_MODELS → verwenden Sie POSTZEE_LIST_MODELS_DETAILED({ type: "video" })

Sie werden mindestens 90 Tage lang fuer Rueckwaertskompatibilitaet beibehalten und in einer zukuenftigen Major-Version entfernt.

Asynchrones Workflow-Pattern

Bild-, Video- und HeyGen-Generierung ist asynchron. Der empfohlene Workflow:

Validieren Sie zuerst — POSTZEE_VALIDATE_GENERATION faengt Parameterfehler und unzureichende Credits ab, ohne Credits zu verbrennen
Schaetzen Sie die Kosten — POSTZEE_ESTIMATE_GENERATION_COST, falls Sie die genaue Zahl benoetigen, um sie dem Benutzer zu zeigen
Optimieren Sie den Prompt — POSTZEE_ENHANCE_PROMPT (kostenlos)
Generieren — POSTZEE_GENERATE_IMAGE / POSTZEE_GENERATE_VIDEO / POSTZEE_GENERATE_HEYGEN_VIDEO → gibt jobId zurueck
Pollen — POSTZEE_CHECK_JOB alle paar Sekunden. Typische Latenzen: 10-60s fuer Bilder, 30-180s fuer Videos, bis zu 5 Min fuer HeyGen
Bei Erfolg — verwenden Sie mediaUrl in POSTZEE_CREATE_POST

Standard-Fehlerformat

Alle write/generate-Tools geben zurueck:

{
  "success": true | false,
  "error": "<machine_code>",
  "message": "<human readable>",
  "...": "tool-spezifische Felder bei Erfolg"
}

Verzweigen Sie auf den error-Machine-Code fuer Logik; verwenden Sie message, um dem Benutzer (in seine Sprache uebersetzt) zu erzaehlen.

Rate-Limits

Endpoint	Limit
HTTP POST	60 Anfragen/Minute
SSE-Verbindung (legacy)	30 Anfragen/Minute
KI-Generierung (`GENERATE_*`)	10 Anfragen/Minute

Claude Code

Verbinden Sie Postzee mit Claude Code.

OpenClaw

Verbinden Sie Postzee mit OpenClaw.

Hermes Agent

Verbinden Sie Postzee mit Hermes Agent.

MCP-Uebersicht

Zurueck zur MCP-Uebersicht.

​Schnellreferenz

​Kontext und Discovery

​POSTZEE_GET_CONTEXT

​POSTZEE_LIST_PLANS

​POSTZEE_LIST_CREDIT_PACKAGES

​Modelle und Specs

​POSTZEE_LIST_MODELS_DETAILED

​POSTZEE_LIST_PLATFORM_SPECS

​POSTZEE_GET_BEST_POSTING_TIMES

​Kosten und Validierung

​POSTZEE_ESTIMATE_GENERATION_COST

​POSTZEE_VALIDATE_GENERATION

​Kanaele und Credits

​POSTZEE_LIST_CHANNELS

​POSTZEE_GET_CREDITS

​Medien-Speicher

​POSTZEE_LIST_MEDIA

​POSTZEE_UPLOAD_MEDIA

​Prompt-Optimierung

​POSTZEE_ENHANCE_PROMPT

​Generierung

​POSTZEE_GENERATE_IMAGE

​POSTZEE_GENERATE_VIDEO

​POSTZEE_CHECK_JOB

​Bilder und Karussells

​POSTZEE_RENDER_IMAGE

​POSTZEE_RENDER_CAROUSEL

​POSTZEE_REPLACE_CAROUSEL_SLIDE

​POSTZEE_APPEND_CAROUSEL_SLIDE

​HeyGen

​POSTZEE_LIST_HEYGEN_AVATARS

​POSTZEE_LIST_HEYGEN_VOICES

​POSTZEE_GENERATE_HEYGEN_VIDEO

​Veroeffentlichung

​POSTZEE_CREATE_POST

​POSTZEE_GET_POST

​Legacy-Tools (veraltet)

​Asynchrones Workflow-Pattern

​Standard-Fehlerformat

​Rate-Limits

Claude Code

OpenClaw

Hermes Agent

MCP-Uebersicht

Schnellreferenz

Kontext und Discovery

POSTZEE_GET_CONTEXT

POSTZEE_LIST_PLANS

POSTZEE_LIST_CREDIT_PACKAGES

Modelle und Specs

POSTZEE_LIST_MODELS_DETAILED

POSTZEE_LIST_PLATFORM_SPECS

POSTZEE_GET_BEST_POSTING_TIMES

Kosten und Validierung

POSTZEE_ESTIMATE_GENERATION_COST

POSTZEE_VALIDATE_GENERATION

Kanaele und Credits

POSTZEE_LIST_CHANNELS

POSTZEE_GET_CREDITS

Medien-Speicher

POSTZEE_LIST_MEDIA

POSTZEE_UPLOAD_MEDIA

Prompt-Optimierung

POSTZEE_ENHANCE_PROMPT

Generierung

POSTZEE_GENERATE_IMAGE

POSTZEE_GENERATE_VIDEO

POSTZEE_CHECK_JOB

Bilder und Karussells

POSTZEE_RENDER_IMAGE

POSTZEE_RENDER_CAROUSEL

POSTZEE_REPLACE_CAROUSEL_SLIDE

POSTZEE_APPEND_CAROUSEL_SLIDE

HeyGen

POSTZEE_LIST_HEYGEN_AVATARS

POSTZEE_LIST_HEYGEN_VOICES

POSTZEE_GENERATE_HEYGEN_VIDEO

Veroeffentlichung

POSTZEE_CREATE_POST

POSTZEE_GET_POST

Legacy-Tools (veraltet)

Asynchrones Workflow-Pattern

Standard-Fehlerformat

Rate-Limits