Reference des outils MCP

Reference complete des 25 outils exposes par le serveur MCP de Postzee. Ces outils sont disponibles pour tout agent IA compatible MCP (Claude Code, OpenClaw, Hermes Agent ou clients MCP directs).

Tous les outils acceptent la cle API integree dans votre URL MCP. Ils sont limites a une seule organisation. Les couts de generation IA sont toujours retournes en credits, jamais en dollars. ($1 USD = 1 000 credits.)

Reference rapide

Categorie	Outils
Contexte et Decouverte	`POSTZEE_GET_CONTEXT`, `POSTZEE_LIST_PLANS`, `POSTZEE_LIST_CREDIT_PACKAGES`
Modeles et Specs	`POSTZEE_LIST_MODELS_DETAILED`, `POSTZEE_LIST_PLATFORM_SPECS`, `POSTZEE_GET_BEST_POSTING_TIMES`
Cout et Validation	`POSTZEE_ESTIMATE_GENERATION_COST`, `POSTZEE_VALIDATE_GENERATION`
Canaux et Credits	`POSTZEE_LIST_CHANNELS`, `POSTZEE_GET_CREDITS`
Memoire des Medias	`POSTZEE_LIST_MEDIA`, `POSTZEE_UPLOAD_MEDIA`
Optimisation de Prompt	`POSTZEE_ENHANCE_PROMPT`
Generation	`POSTZEE_GENERATE_IMAGE`, `POSTZEE_GENERATE_VIDEO`, `POSTZEE_CHECK_JOB`
Images et Carrousels	`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`
Publication	`POSTZEE_CREATE_POST`, `POSTZEE_GET_POST`
Legacy (depreciees)	`POSTZEE_LIST_IMAGE_MODELS`, `POSTZEE_LIST_VIDEO_MODELS`

Contexte et Decouverte

POSTZEE_GET_CONTEXT

Agregation de contexte en un seul appel. Recommande comme premier appel de chaque session. Retourne le forfait, les credits, le stockage, les canaux, les fonctionnalites et la version de la skill en un round-trip. Parametres : Aucun Retourne :

{
  "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/Paris" },
  "features": {
    "img2vid": true,
    "veoR2V": false,
    "soraStoryboard": false,
    "sora1080p": true,
    "audioControl": true,
    "firstLastFrame": true,
    "firstLastFrameProvider": "wan-flf2v",
    "heygen": true
  }
}

Les flags features.* refletent ce que le MCP peut executer maintenant — les agents ne doivent suggerer que les fonctionnalites dont la flag correspondante est true.

POSTZEE_LIST_PLANS

Liste les 5 niveaux d’abonnement avec prix et limites. Parametres : Aucun Retourne :

[
  {
    "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

Liste les packs de credits one-time (eternels — n’expirent jamais). Parametres : Aucun Retourne :

[
  { "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 }
]

Modeles et Specs

POSTZEE_LIST_MODELS_DETAILED

Matrice de capacites pour tous les modeles d’image et video disponibles — durees, resolutions, capacites audio, parametres customises acceptes, et tier de cout relatif. Parametres :

Parametre	Type	Requis	Description
`type`	string	Non	`"image"`, `"video"` ou `"all"` (default)
`includeHeygen`	boolean	Non	Inclut l’entree synthetique HeyGen. Default : `true`
`family`	string	Non	Filtre vers une seule famille (ex. : `"ideogram-v3"`, `"sora-2"`, `"veo3.1"`)
`agenticDefault`	boolean	Non	Quand `true`, ne retourne que les entrees marquees comme choix recommande pour l’automatisation

Retourne (par modele) :

{
  "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 est l’un de very-low, low, mid, high, premium — le cout absolu en credits n’est pas expose intentionnellement ; utilisez POSTZEE_ESTIMATE_GENERATION_COST a la place. L’entree synthetique heygen-avatar-video a costTier: "external" et un billingNote indiquant que HeyGen facture sur le compte HeyGen de l’utilisateur, pas sur les credits Postzee.

POSTZEE_LIST_PLATFORM_SPECS

Specs par plateforme (aspect ratios, max de slides pour carrousels, limites de caracteres pour legendes, recommandations de hashtags). Parametres :

Parametre	Type	Requis	Description
`platforms`	string[]	Non	Filtre vers des plateformes specifiques (ex. : `["instagram", "tiktok"]`). Omettre pour toutes.

Plateformes couvertes : instagram, facebook, linkedin, x, tiktok, youtube, pinterest, threads, bluesky, reddit.

POSTZEE_GET_BEST_POSTING_TIMES

Fenetres heuristiques des meilleurs horaires de publication par canal, retournees dans le fuseau horaire de l’organisation. Parametres :

Parametre	Type	Requis	Description
`channelIds`	string[]	Non	Filtre vers des canaux specifiques. Omettre pour tous les canaux actifs.

Retourne :

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

Les canaux avec le statut disabled ou requiresReauth sont filtres — les recommandations n’apparaissent que pour les canaux qui peuvent effectivement publier.

Cout et Validation

POSTZEE_ESTIMATE_GENERATION_COST

Source unique de verite pour les estimations de cout. Retourne toujours des credits, jamais des dollars. Parametres :

Parametre	Type	Requis	Description
`type`	string	Oui	`"image"` ou `"video"`
`model`	string	Oui	ID du modele depuis `POSTZEE_LIST_MODELS_DETAILED`
`duration`	number	Non	Secondes (video, pour modeles avec pricing par seconde)
`resolution`	string	Non	`"480p"`, `"540p"`, `"720p"`, `"1080p"`, `"4k"`
`quality`	string	Non	Sora 2 Pro : `"standard"` (720p) ou `"high"` (1080p)
`generateAudio`	boolean	Non	Affecte le cout sur Veo, Pixverse, Wan 2.5
`voiceControl`	boolean	Non	Kling 2.6/3.0 Pro
`aspectRatio`	string	Non	Informatif

Retourne :

{
  "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

Validation pre-execution — capture les erreurs de parametres, les credits insuffisants, les problemes de stockage et les blocages de forfait avant de bruler des credits. Parametres :

Parametre	Type	Requis	Description
`type`	string	Oui	`"image"` ou `"video"`
`model`	string	Oui	ID du modele
`duration`	number	Non	Secondes
`aspectRatio`	string	Non	ex. : `"4:5"`
`resolution`	string	Non	Resolution de sortie
`quality`	string	Non	Sora Pro `"standard"` / `"high"`
`generateAudio`	boolean	Non
`voiceControl`	boolean	Non
`imageUrl`	string	Non	Requis pour les modeles image-to-video
`slideCount`	number	Non	Multiplicateur de batch (ex. N variations du meme prompt). Pas pour les carrousels — ceux-ci passent par `POSTZEE_RENDER_CAROUSEL` avec son propre modele de cout.

Retourne :

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

Quand valid: false, le tableau errors[] contient des problemes lisibles — ex. : duree pas dans l’ensemble autorise par le modele, imageUrl manquant pour modele i2v, stockage a 100%, ou modele enregistre mais pas encore disponible via MCP.

Canaux et Credits

POSTZEE_LIST_CHANNELS

Liste les canaux de reseaux sociaux connectes avec des flags d’action explicites. Parametres : Aucun Retourne :

[
  {
    "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 est l’un de "none" (pret a publier), "reconnect" (token expire — l’utilisateur reconnecte) ou "reenable" (admin/billing — l’utilisateur reactive, pas la meme chose que reconnecter). statusMessage est une explication lisible quand le canal necessite une action (ex : "Token du canal expire. Reconnectez pour continuer a publier."). Il est null quand actionRequired est "none".

POSTZEE_GET_CREDITS

Solde de credits leger. Subset de POSTZEE_GET_CONTEXT.credits — preferez ce dernier pour le nouveau code. Parametres : Aucun Retourne :

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

Toutes les valeurs en credits ($1 USD = 1 000 credits).

Memoire des Medias

Les deux outils ci-dessous permettent a un agent de retrouver et reutiliser des actifs medias — generes par IA ou televerses par l’utilisateur — entre tours et entre sessions, sans redemander les URLs a l’utilisateur.

POSTZEE_LIST_MEDIA

Liste des medias recents, limitee a l’organisation. Renvoie les plus recents d’abord. Parametres :

Parametre	Type	Requis	Description
`type`	string	Non	`"image"`, `"video"` ou `"all"` (par defaut)
`source`	string	Non	`"generated"` (cree par IA), `"uploaded"` (importe via `POSTZEE_UPLOAD_MEDIA`) ou `"all"` (par defaut)
`search`	string	Non	Recherche insensible a la casse dans le prompt original (medias IA) et le nom de fichier
`since`	string	Non	Date ISO — ne renvoie que les medias crees apres cet instant
`limit`	number	Non	Par defaut 20, maximum 100

Renvoie (par element) :

{
  "mediaId": "uuid",
  "url": "https://cdn.postzee.app/abc.jpg",
  "name": "abc.jpg",
  "type": "image",
  "source": "generated",
  "prompt": "chien sur la plage au coucher du soleil",
  "modelUsed": "ideogram-v3-turbo",
  "createdAt": "2026-05-07T14:23:00Z",
  "sizeBytes": 245678,
  "dimensions": { "width": 1024, "height": 1280 }
}

Renvoie (echec) :

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

Les medias avec soft-delete sont exclus automatiquement. Les medias utilises comme photo de profil sont egalement exclus.

POSTZEE_UPLOAD_MEDIA

Importe une URL publique vers le storage Postzee. Renvoie un mediaId stable et une URL CDN reutilisable dans GENERATE_*, CREATE_POST et LIST_MEDIA. Parametres :

Parametre	Type	Requis	Description
`url`	string	Oui	URL publique `http://` ou `https://`. Doit etre accessible sans authentification.
`description`	string	Non	Etiquette courte enregistree avec le media (aide l’agent a tenir son manifest)

Renvoie (succes) :

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

Renvoie (echec) :

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

Ordre de validation (chaque etape rejette avant la suivante) :

URL parsable et utilisant http/https
Hostname non localhost / IP privee / endpoint cloud-metadata (defense SSRF)
Sondage HEAD reussi (ou GET ranged en fallback)
Content-Type correspond a l’allowlist configuree (par defaut : image/jpeg, image/png, image/webp, image/gif / video/mp4, video/quicktime, video/webm)
Taille dans le cap par type (par defaut : 25 MB image, 500 MB video)
Quota de storage de l’organisation a de la place

Limites par defaut (configurables via SystemConfig) :

Type	Taille max	Formats acceptes
Image	25 MB	JPG, PNG, WebP, GIF
Video	500 MB	MP4, MOV, WebM

Les limites et formats acceptes peuvent etre ajustes a l’execution en modifiant les cles UPLOAD_* dans SystemConfig. Cet outil MCP et les endpoints REST d’upload partagent la meme source de verite — modifie une fois, s’applique partout en ~5 minutes (TTL du cache).

Pour la confidentialite et la securite, l’outil n’accepte jamais d’en-tetes d’authentification ni de tokens. Les URLs qui requierent un Bot Token (ex. URLs getFile Telegram) doivent etre re-hebergees par le client de chat sur une URL publique au prealable. Pour les uploads en base64 / fichiers directs, utilisez l’endpoint REST existant /media/upload-server — l’outil MCP gere uniquement les imports via URL.

Apres un import reussi, le media apparait dans POSTZEE_LIST_MEDIA avec source: "uploaded".

Optimisation de Prompt

POSTZEE_ENHANCE_PROMPT

Optimise le prompt de l’utilisateur pour de meilleurs resultats de generation IA. Gratuit — pas de cout en credits. Parametres :

Parametre	Type	Requis	Description
`prompt`	string	Oui	Le prompt de l’utilisateur a optimiser
`mediaType`	string	Oui	`"image"` ou `"video"`
`model`	string	Non	ID du modele cible (pour optimisation specifique au modele)
`language`	string	Non	Code de langue de sortie (ex : `"pt"`, `"es"`, `"fr"`, `"de"`). Si omis, utilise la langue du proprietaire du compte ou anglais par defaut.

Retourne :

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

Generation

POSTZEE_GENERATE_IMAGE

Genere une image IA a partir d’un prompt. Operation asynchrone — retourne un job id a poll avec POSTZEE_CHECK_JOB. Parametres :

Parametre	Type	Requis	Description
`prompt`	string	Oui	Description detaillee de l’image
`model`	string	Oui	ID du modele depuis `POSTZEE_LIST_MODELS_DETAILED` (type `"image"`)
`aspectRatio`	string	Non	ex. : `"1:1"`, `"4:5"`, `"9:16"`, `"16:9"`. Default : `"1:1"`
`imageUrls`	string[]	Non	URLs d’images de reference pour image-to-image
`quality`	string	Non	GPT Image 2 : `"low"`, `"medium"` ou `"high"`. Default : `"high"`
`style`	string	Non	Recraft V3/V4 : `"realistic_image"`, `"digital_illustration"`, `"vector_illustration"`
`renderingSpeed`	string	Non	Tier Ideogram V3 : `"turbo"`, `"balanced"` ou `"quality"`
`negativePrompt`	string	Non	Choses a exclure de l’image
`seed`	number	Non	Seed deterministe optionnel

Retourne (succes) :

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

Retourne (echec) :

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

POSTZEE_GENERATE_VIDEO

Genere une video IA a partir d’un prompt ou d’une image de reference. Operation asynchrone. Parametres :

Parametre	Type	Requis	Description
`prompt`	string	Oui	Description detaillee de la video
`model`	string	Oui	ID du modele depuis `POSTZEE_LIST_MODELS_DETAILED` (type `"video"`)
`duration`	number	Non	Secondes. Valeurs autorisees varient par modele — consultez `model.durations`
`aspectRatio`	string	Non	`"16:9"` ou `"9:16"`. Default : `"16:9"`
`imageUrl`	string	Non	URL de l’image de reference pour modeles image-to-video
`endImageUrl`	string	Non	URL du frame final pour interpolation first-last-frame (ex. : `wan-flf2v`)
`resolution`	string	Non	`"480p"`, `"540p"`, `"720p"`, `"1080p"`, `"4k"` (depend du modele)
`quality`	string	Non	Sora 2 Pro uniquement : `"standard"` (720p) ou `"high"` (1080p)
`generateAudio`	boolean	Non	Genere de l’audio ambiant (Veo 3.1, Pixverse, Wan 2.5). Affecte les credits.
`voiceControl`	boolean	Non	Controle de voix (Kling 2.6/3.0 Pro). Affecte les credits.
`negativePrompt`	string	Non	Choses a eviter dans la video
`seed`	number	Non	Seed deterministe optionnel

Retourne : meme structure que POSTZEE_GENERATE_IMAGE.

Les IDs specifiques de tier retournes par POSTZEE_LIST_MODELS_DETAILED (ex. : ideogram-v3-turbo, gpt-image-2-high, sora-2-t2v-pro-1080p, recraft-v4-vector) peuvent etre passes directement dans model. Le MCP traduit vers la payload correcte du backend automatiquement — aucun parametre tier ou quality separe n’est requis pour la selection de tier.

Quelques IDs de modele dans le catalogue ne sont pas encore disponibles via MCP et seront rejetes en amont (variantes Sora 2 storyboard, certains paths Veo 3.1). La reponse d’erreur inclut un tableau suggestions[] avec jusqu’a trois alternatives proches — choisissez l’une d’elles.

POSTZEE_CHECK_JOB

Poll le statut d’un job asynchrone de generation d’image ou de video. Parametres :

Parametre	Type	Requis	Description
`jobId`	string	Oui	Job id depuis `POSTZEE_GENERATE_*`

Retourne (en cours) :

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

Retourne (succes) :

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

Retourne (echec) :

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

Retourne (introuvable) :

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

Images et Carrousels

Le pipeline d’image et carrousel laisse l’agent composer des slides editoriaux avec une typographie au pixel pres, des polices coherentes et zero hallucination de mots. L’agent soumet le(s) slide(s) compose(s) ; Postzee rend et renvoie le media final pret a publier. Quatre outils couvrent le cycle : un rendu d’image unique pour des posts editoriaux uniques avec typographie soignee, un rendu complet de carrousel pour le batch initial, remplacement chirurgical pour les corrections et append incremental pour l’authoring iteratif.

POSTZEE_RENDER_IMAGE

Rend UN document HTML en un Media PNG unique. La contrepartie single-image de POSTZEE_RENDER_CAROUSEL, pour les posts editoriaux uniques (images chargees en texte, couvertures style magazine, hero quote cards) ou la valeur reside dans le layout + la typographie plutot que dans une sequence swipeable. Parametres :

Parametre	Type	Requis	Description
`html`	string	Oui	Document `<!doctype html>` complet du slide. Referencez les images par leur URL Postzee CDN (renvoyee par `POSTZEE_GENERATE_IMAGE` ou `POSTZEE_UPLOAD_MEDIA`). Composition statique uniquement — pas de scripts interactifs.
`width`	number	Non	Largeur de sortie en px (256-2160). Default `1080`.
`height`	number	Non	Hauteur de sortie en px (256-2160). Default `1350` (4:5 — optimise pour le feed Instagram).
`name`	string	Non	Titre optionnel affiche dans la galerie.

Memes limites strictes que POSTZEE_RENDER_CAROUSEL : 7 MB max par slide, 256-2160 px par dimension, 45 s de timeout. Retourne (succes) :

{
  "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 est expose pour les callers avances mais l’usage typique est de passer le mediaUrl directement a POSTZEE_CREATE_POST comme un array mediaUrls a un seul element. Retourne (echec) :

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

Meme cache d’idempotency que le rendu de carrousel : des payloads identiques dans une fenetre d’1 heure retournent le mediaId mis en cache au lieu de re-rendre.

POSTZEE_RENDER_CAROUSEL

Rend N slides HTML en PNG et les regroupe atomiquement en un MediaGroup de carrousel. Synchrone — bloque jusqu’a ce que tous les slides soient termines. Parametres :

Parametre	Type	Requis	Description
`slides`	array	Oui	1-15 objets slide dans l’ordre d’affichage. Chacun : `{ html: string, width?: number, height?: number }`. L’index du tableau devient l’ordre du slide.
`aspectRatio`	string	Non	Taille par defaut quand width/height sont omis : `"1:1"` (1080×1080), `"4:5"` (1080×1350), `"9:16"` (1080×1920). Default `"1:1"`.
`name`	string	Non	Titre optionnel affiche dans la galerie.

Limites cote serveur :

Maximum 15 slides par appel
Minimum 256 / maximum 2160 px par dimension
7 MB maximum de HTML par slide
50 MB maximum de payload total par appel (somme de tous les slides)
45 s de timeout par slide

Garde-fous par plateforme a la publication. Le rendu accepte jusqu’a 15 slides, mais la publication est limitee par le plafond natif de chaque reseau social (Instagram/Facebook ≤ 10, LinkedIn ≤ 20, TikTok ≤ 35, Threads/Reddit ≤ 20, Pinterest ≤ 5, X ≤ 4, Bluesky/Mastodon ≤ 4, Telegram/VK ≤ 10). Quand POSTZEE_CREATE_POST est appele avec des mediaUrls depassant la limite du reseau cible, Postzee rejette la publication avant d’appeler l’API de la plateforme, avec un message traduit dans la langue de l’utilisateur. Utilisez POSTZEE_LIST_PLATFORM_SPECS pour la table en direct. Modele de defaillance tolerant aux partiels. Si un slide echoue ou si le dispatcher time out avant que tous les slides se stabilisent, le groupe est preserve avec renderStatus: "partial" dans aiMetadata (au lieu d’etre rollback). Reessayez les slides manquants via POSTZEE_REPLACE_CAROUSEL_SLIDE ou POSTZEE_APPEND_CAROUSEL_SLIDE. Les slides qui ONT rendu ne sont jamais detruits — l’utilisateur conserve son travail meme en cas de defaillance partielle. L’ordre est structurel, pas temporel. L’index du tableau = orderInGroup, assigne AVANT que tout worker tourne. Les slides peuvent rendre en parallele mais l’ordre est preserve de maniere deterministe. Modele de securite. Les compositions de slides sont rendues comme contenu statique — les scripts interactifs sont inertes. Les requetes reseau pour les assets referencees sont limitees aux hosts publics (les adresses privees/internes sont bloquees). Retourne :

{
  "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 est deja dans l’ordre d’affichage — passez-le directement a POSTZEE_CREATE_POST. Reponse d’echec :

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

POSTZEE_REPLACE_CAROUSEL_SLIDE

Remplace chirurgicalement UN slide d’un carrousel existant sans toucher les autres. A utiliser quand l’utilisateur dit “change le slide N” — economise du temps et des credits, et preserve l’identite des autres slides (URLs et IDs intacts). Parametres :

Parametre	Type	Requis	Description
`mediaGroupId`	string	Oui	L’id retourne par `POSTZEE_RENDER_CAROUSEL`.
`orderInGroup`	number	Oui	Index base zero du slide a remplacer. Slide 4 → `3`. Doit pointer vers un slide actif (non soft-deleted).
`slide`	object	Oui	`{ html, width?, height? }` — meme structure qu’une entree de `RENDER_CAROUSEL.slides`.

Le slide remplace est soft-delete apres que le nouveau rendu est uploade avec succes ; le nouveau slide prend le meme orderInGroup. Si orderInGroup === 0, le thumbnail de couverture du carrousel est mis a jour automatiquement. Retourne :

{
  "success": true,
  "mediaGroupId": "uuid",
  "replacedOrderInGroup": 3,
  "newMediaId": "...",
  "newMediaUrl": "https://cdn.postzee.app/.../slide-3-{ts}.png",
  "totalSlides": 10,
  "slides": [ /* ... liste ordonnee complete ... */ ],
  "mediaUrls": [ /* ... liste ordonnee complete ... */ ],
  "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

Ajoute UN nouveau slide a la fin d’un carrousel existant. A utiliser pour l’authoring iteratif — quand l’utilisateur veut construire le carrousel slide par slide (“montre-moi le slide 1… maintenant le slide 2…”), ceci fait que chaque nouveau slide atterrit dans le MEME MediaGroup au lieu de produire N groupes de slide unique orphelins dans la galerie. Parametres :

Parametre	Type	Requis	Description
`mediaGroupId`	string	Oui	L’id du carrousel que vous agrandissez. Retourne par `POSTZEE_RENDER_CAROUSEL` (premier slide) ou par un appel precedent de `APPEND_CAROUSEL_SLIDE`.
`slide`	object	Oui	`{ html, width?, height? }` — meme structure qu’une entree de `RENDER_CAROUSEL.slides`.

Le nouveau slide est ajoute au prochain orderInGroup disponible (gap-safe — si des slides intermediaires ont ete supprimes, on prend max(orderInGroup) + 1, jamais on ne reutilise un emplacement libre). Le thumbnail de couverture n’est pas modifie. Pattern d’authoring iteratif. Le premier slide doit toujours passer par POSTZEE_RENDER_CAROUSEL (c’est ce qui cree le MediaGroup). Chaque slide suivant passe par APPEND_CAROUSEL_SLIDE avec le meme mediaGroupId. Appeler RENDER_CAROUSEL une seconde fois pour le meme carrousel logique produit un nouveau groupe et casse le flux iteratif — ne le faites pas. Retourne :

{
  "success": true,
  "mediaGroupId": "uuid",
  "appendedOrderInGroup": 7,
  "newMediaId": "...",
  "newMediaUrl": "https://cdn.postzee.app/.../slide-7-{ts}.png",
  "totalSlides": 8,
  "slides": [ /* ... liste ordonnee complete incluant le nouveau ... */ ],
  "mediaUrls": [ /* ... liste ordonnee complete ... */ ]
}

Il n’y a pas de primitive d’insertion-au-milieu, de reordonnancement, ou de suppression en v1. APPEND_CAROUSEL_SLIDE n’ajoute qu’a la FIN. Si l’utilisateur demande d’inserer a une position specifique, d’echanger deux slides ou d’en supprimer un, recomposez tout le carrousel avec POSTZEE_RENDER_CAROUSEL a partir d’un nouveau scenario.

HeyGen

Les outils HeyGen requierent une cle API HeyGen configuree dans votre compte Postzee. Connectez-la dans Settings → integration HeyGen. La generation video HeyGen facture sur le compte HeyGen de l’utilisateur, pas sur les credits Postzee.

POSTZEE_LIST_HEYGEN_AVATARS

Liste les avatars HeyGen disponibles (filtrez par genre, age, style, etc. cote client). Parametres : Aucun Retourne : Tableau d’avatars de votre compte HeyGen.

POSTZEE_LIST_HEYGEN_VOICES

Liste les voix HeyGen disponibles. Parametres : Aucun Retourne : Tableau de voix de votre compte HeyGen, avec info de langue et de genre.

POSTZEE_GENERATE_HEYGEN_VIDEO

Cree une video d’avatar avec HeyGen. Operation asynchrone — pollez avec POSTZEE_CHECK_JOB. Parametres :

Parametre	Type	Requis	Description
`script`	string	Oui	Texte que l’avatar doit prononcer (20-1500 caracteres)
`avatarId`	string	Oui	Depuis `POSTZEE_LIST_HEYGEN_AVATARS`
`voiceId`	string	Oui	Depuis `POSTZEE_LIST_HEYGEN_VOICES`
`aspectRatio`	string	Non	`"16:9"` ou `"9:16"`. Default : `"16:9"`

Retourne : meme structure que POSTZEE_GENERATE_IMAGE — jobId + status: "processing". La reponse note egalement que des credits HeyGen (et non Postzee) seront consommes.

Publication

POSTZEE_CREATE_POST

Cree, programme ou publie un post sur un canal de reseaux sociaux. Parametres :

Parametre	Type	Requis	Description
`type`	string	Oui	`"now"` (publie immediatement), `"draft"` ou `"schedule"`
`date`	string	Schedule uniquement	UTC datetime (ex. : `"2026-04-24T15:00:00Z"`) — requis quand `type` est `"schedule"`
`channelId`	string	Oui	ID du canal depuis `POSTZEE_LIST_CHANNELS`
`text`	string	Oui	Contenu du post
`mediaUrls`	string[]	Non	URLs de medias (en ordre d’affichage — ordre du tableau = ordre des slides pour carrousels)
`settings`	object	Non	Configuration de publication par plateforme. Envoyez un objet plat avec uniquement les champs pertinents pour le reseau du canal cible — ex. : `{ "post_type": "story" }` pour Instagram, `{ "privacy_level": "PUBLIC_TO_EVERYONE", "duet": true }` pour TikTok. Le MCP route les settings vers le bon validateur en fonction du canal. Voir configurations de plateforme pour la reference complete.

Retourne (succes) :

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

La publication est asynchrone : POSTZEE_CREATE_POST retourne un postId immediatement, mais le post n’est pas encore en ligne. Interrogez POSTZEE_GET_POST avec ce postId jusqu’a ce que state vaille "PUBLISHED" pour obtenir l’ID du post sur la plateforme (releaseId) et le permalien (releaseURL). Retourne (echec) :

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

Codes d’error possibles :

Code	Signification
`subscription_required`	Le forfait actuel ne permet pas de publier ou la limite mensuelle de posts a ete atteinte. `upgradeUrl` est inclus.
`date_required`	`type: "schedule"` envoye sans `date`.
`invalid_date`	La string `date` n’est pas un timestamp UTC ISO valide.
`organization_not_found`	La cle MCP a resolu vers une organisation qui n’existe pas (rare).
`post_failed`	Erreur de provider/reseau pendant la publication. Reessayez une fois ; si ca persiste, surface le `message`.

POSTZEE_GET_POST

Recupere le statut de publication d’un seul post — interrogez-le apres POSTZEE_CREATE_POST pour obtenir l’ID du post sur la plateforme et le permalien une fois le post en ligne. Parametres :

Parametre	Type	Requis	Description
`postId`	string	Oui	L’ID du post retourne par `POSTZEE_CREATE_POST`

Retourne (succes) :

{
  "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."
}

Champ	Description
`state`	`QUEUE` (en attente), `PUBLISHED`, `ERROR` ou `DRAFT`
`published`	`true` lorsque `state` vaut `PUBLISHED`
`releaseId`	L’ID natif du post sur la plateforme (par ex. l’ID du media Instagram). `null` jusqu’a la publication
`releaseURL`	Le permalien public vers le post. `null` jusqu’a la publication

Tant que le post est encore en cours de publication, state vaut "QUEUE" et releaseId/releaseURL valent null — continuez d’interroger jusqu’a ce que state vaille "PUBLISHED" (ou "ERROR" si la publication a echoue). Retourne (echec) :

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

Outils legacy (depreciees)

Les outils suivants fonctionnent encore mais sont remplaces :

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

Ils seront maintenus pendant au moins 90 jours pour la retrocompatibilite, puis retires dans une future version majeure.

Pattern de workflow asynchrone

La generation d’image, de video et HeyGen est asynchrone. Le workflow recommande :

Validez d’abord — POSTZEE_VALIDATE_GENERATION pour capturer les erreurs de parametres et les credits insuffisants sans bruler de credits
Estimez le cout — POSTZEE_ESTIMATE_GENERATION_COST si vous avez besoin du nombre exact a montrer a l’utilisateur
Optimisez le prompt — POSTZEE_ENHANCE_PROMPT (gratuit)
Generez — POSTZEE_GENERATE_IMAGE / POSTZEE_GENERATE_VIDEO / POSTZEE_GENERATE_HEYGEN_VIDEO → retourne jobId
Pollez — POSTZEE_CHECK_JOB toutes les quelques secondes. Latences typiques : 10-60s pour les images, 30-180s pour les videos, jusqu’a 5min pour HeyGen
En cas de succes — utilisez mediaUrl dans POSTZEE_CREATE_POST

Format d’erreur standard

Tous les outils write/generate retournent :

{
  "success": true | false,
  "error": "<machine_code>",
  "message": "<human readable>",
  "...": "champs specifiques a l'outil en cas de succes"
}

Branchez sur le error machine code pour la logique ; utilisez message pour narrer a l’utilisateur (traduit dans sa langue).

Limites de taux

Endpoint	Limite
HTTP POST	60 requetes/minute
Connexion SSE (legacy)	30 requetes/minute
Generation IA (`GENERATE_*`)	10 requetes/minute

Claude Code

Connectez Postzee a Claude Code.

OpenClaw

Connectez Postzee a OpenClaw.

Hermes Agent

Connectez Postzee a Hermes Agent.

Apercu MCP

Retournez a l’apercu MCP.

​Reference rapide

​Contexte et Decouverte

​POSTZEE_GET_CONTEXT

​POSTZEE_LIST_PLANS

​POSTZEE_LIST_CREDIT_PACKAGES

​Modeles et Specs

​POSTZEE_LIST_MODELS_DETAILED

​POSTZEE_LIST_PLATFORM_SPECS

​POSTZEE_GET_BEST_POSTING_TIMES

​Cout et Validation

​POSTZEE_ESTIMATE_GENERATION_COST

​POSTZEE_VALIDATE_GENERATION

​Canaux et Credits

​POSTZEE_LIST_CHANNELS

​POSTZEE_GET_CREDITS

​Memoire des Medias

​POSTZEE_LIST_MEDIA

​POSTZEE_UPLOAD_MEDIA

​Optimisation de Prompt

​POSTZEE_ENHANCE_PROMPT

​Generation

​POSTZEE_GENERATE_IMAGE

​POSTZEE_GENERATE_VIDEO

​POSTZEE_CHECK_JOB

​Images et Carrousels

​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

​Publication

​POSTZEE_CREATE_POST

​POSTZEE_GET_POST

​Outils legacy (depreciees)

​Pattern de workflow asynchrone

​Format d’erreur standard

​Limites de taux

Claude Code

OpenClaw

Hermes Agent

Apercu MCP

Reference rapide

Contexte et Decouverte

POSTZEE_GET_CONTEXT

POSTZEE_LIST_PLANS

POSTZEE_LIST_CREDIT_PACKAGES

Modeles et Specs

POSTZEE_LIST_MODELS_DETAILED

POSTZEE_LIST_PLATFORM_SPECS

POSTZEE_GET_BEST_POSTING_TIMES

Cout et Validation

POSTZEE_ESTIMATE_GENERATION_COST

POSTZEE_VALIDATE_GENERATION

Canaux et Credits

POSTZEE_LIST_CHANNELS

POSTZEE_GET_CREDITS

Memoire des Medias

POSTZEE_LIST_MEDIA

POSTZEE_UPLOAD_MEDIA

Optimisation de Prompt

POSTZEE_ENHANCE_PROMPT

Generation

POSTZEE_GENERATE_IMAGE

POSTZEE_GENERATE_VIDEO

POSTZEE_CHECK_JOB

Images et Carrousels

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

Publication

POSTZEE_CREATE_POST

POSTZEE_GET_POST

Outils legacy (depreciees)

Pattern de workflow asynchrone

Format d’erreur standard

Limites de taux