Referencia de Herramientas MCP

Referencia completa de las 25 herramientas expuestas por el servidor MCP de Postzee. Estas herramientas están disponibles para cualquier agente de IA compatible con MCP (Claude Code, OpenClaw, Hermes Agent o clientes MCP directos).

Todas las herramientas aceptan la clave de API embebida en tu URL MCP. Están limitadas a una sola organización. Los costos de generación de IA siempre se devuelven en créditos, nunca en dólares. ($1 USD = 1.000 créditos.)

Referencia rápida

Categoría	Herramientas
Contexto y Descubrimiento	`POSTZEE_GET_CONTEXT`, `POSTZEE_LIST_PLANS`, `POSTZEE_LIST_CREDIT_PACKAGES`
Modelos y Specs	`POSTZEE_LIST_MODELS_DETAILED`, `POSTZEE_LIST_PLATFORM_SPECS`, `POSTZEE_GET_BEST_POSTING_TIMES`
Costo y Validación	`POSTZEE_ESTIMATE_GENERATION_COST`, `POSTZEE_VALIDATE_GENERATION`
Canales y Créditos	`POSTZEE_LIST_CHANNELS`, `POSTZEE_GET_CREDITS`
Memoria de Medios	`POSTZEE_LIST_MEDIA`, `POSTZEE_UPLOAD_MEDIA`
Optimización de Prompt	`POSTZEE_ENHANCE_PROMPT`
Generación	`POSTZEE_GENERATE_IMAGE`, `POSTZEE_GENERATE_VIDEO`, `POSTZEE_CHECK_JOB`
Imágenes y Carruseles	`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`
Publicación	`POSTZEE_CREATE_POST`, `POSTZEE_GET_POST`
Legacy (deprecadas)	`POSTZEE_LIST_IMAGE_MODELS`, `POSTZEE_LIST_VIDEO_MODELS`

Contexto y Descubrimiento

POSTZEE_GET_CONTEXT

Agregación de contexto en una sola llamada. Recomendada como primera llamada de cada sesión. Devuelve plan, créditos, almacenamiento, canales, features y versión de la skill en un round-trip. Parámetros: Ninguno Devuelve:

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

Las flags features.* reflejan lo que el MCP puede ejecutar ahora mismo — los agentes solo deben sugerir features cuya flag correspondiente sea true.

POSTZEE_LIST_PLANS

Lista los 5 niveles de suscripción con precios y límites. Parámetros: Ninguno Devuelve:

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

Lista paquetes de créditos one-time (eternos — nunca expiran). Parámetros: Ninguno Devuelve:

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

Modelos y Specs

POSTZEE_LIST_MODELS_DETAILED

Matriz de capacidades para todos los modelos de imagen y video disponibles — duraciones, resoluciones, capacidades de audio, parámetros customizados aceptados, y tier de costo relativo. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`type`	string	No	`"image"`, `"video"`, o `"all"` (default)
`includeHeygen`	boolean	No	Incluye la entrada sintética HeyGen. Default: `true`
`family`	string	No	Filtra a una sola familia (ej.: `"ideogram-v3"`, `"sora-2"`, `"veo3.1"`)
`agenticDefault`	boolean	No	Cuando es `true`, devuelve solo las entradas marcadas como elección recomendada para automatización

Devuelve (por modelo):

{
  "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 es uno de very-low, low, mid, high, premium — el costo absoluto en créditos no se expone intencionalmente; usa POSTZEE_ESTIMATE_GENERATION_COST en su lugar. La entrada sintética heygen-avatar-video tiene costTier: "external" y un billingNote indicando que HeyGen factura en la cuenta HeyGen del usuario, no en créditos Postzee.

POSTZEE_LIST_PLATFORM_SPECS

Specs por plataforma (aspect ratios, máximo de slides para carruseles, límites de caracteres en captions, recomendaciones de hashtags). Parámetros:

Parámetro	Tipo	Requerido	Descripción
`platforms`	string[]	No	Filtra a plataformas específicas (ej.: `["instagram", "tiktok"]`). Omitir para todas.

Plataformas cubiertas: instagram, facebook, linkedin, x, tiktok, youtube, pinterest, threads, bluesky, reddit.

POSTZEE_GET_BEST_POSTING_TIMES

Ventanas heurísticas de los mejores horarios de publicación por canal, devueltas en la zona horaria de la organización. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`channelIds`	string[]	No	Filtra a canales específicos. Omitir para todos los canales activos.

Devuelve:

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

Los canales con estado disabled o requiresReauth se filtran — las recomendaciones solo aparecen para canales que efectivamente pueden publicar.

Costo y Validación

POSTZEE_ESTIMATE_GENERATION_COST

Fuente única de verdad para estimaciones de costo. Siempre devuelve créditos, nunca dólares. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`type`	string	Sí	`"image"` o `"video"`
`model`	string	Sí	ID del modelo de `POSTZEE_LIST_MODELS_DETAILED`
`duration`	number	No	Segundos (video, para modelos con pricing por segundo)
`resolution`	string	No	`"480p"`, `"540p"`, `"720p"`, `"1080p"`, `"4k"`
`quality`	string	No	Sora 2 Pro: `"standard"` (720p) o `"high"` (1080p)
`generateAudio`	boolean	No	Afecta costo en Veo, Pixverse, Wan 2.5
`voiceControl`	boolean	No	Kling 2.6/3.0 Pro
`aspectRatio`	string	No	Informativo

Devuelve:

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

Validación pre-ejecución — captura errores de parámetros, créditos insuficientes, problemas de almacenamiento y bloqueos de plan antes de quemar créditos. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`type`	string	Sí	`"image"` o `"video"`
`model`	string	Sí	ID del modelo
`duration`	number	No	Segundos
`aspectRatio`	string	No	ej.: `"4:5"`
`resolution`	string	No	Resolución de salida
`quality`	string	No	Sora Pro `"standard"` / `"high"`
`generateAudio`	boolean	No
`voiceControl`	boolean	No
`imageUrl`	string	No	Requerido para modelos image-to-video
`slideCount`	number	No	Multiplicador de batch (ej. N variaciones del mismo prompt). No para carruseles — esos pasan por `POSTZEE_RENDER_CAROUSEL` con su propio modelo de costo.

Devuelve:

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

Cuando valid: false, el array errors[] contiene problemas legibles — ej.: la duración no está en el conjunto permitido por el modelo, falta imageUrl para modelo i2v, almacenamiento al 100%, o modelo registrado pero aún no disponible vía MCP.

Canales y Créditos

POSTZEE_LIST_CHANNELS

Lista canales de redes sociales conectados con flags de acción explícitas. Parámetros: Ninguno Devuelve:

[
  {
    "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 es uno de "none" (listo para publicar), "reconnect" (token expirado — el usuario reconecta), o "reenable" (admin/billing — el usuario reactiva, no lo mismo que reconectar). statusMessage es una explicacion legible cuando el canal requiere accion (ej: "Token del canal expirado. Reconecte para seguir publicando."). Es null cuando actionRequired es "none".

POSTZEE_GET_CREDITS

Saldo de créditos ligero. Subset de POSTZEE_GET_CONTEXT.credits — prefiere este último para código nuevo. Parámetros: Ninguno Devuelve:

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

Todos los valores en créditos ($1 USD = 1.000 créditos).

Memoria de Medios

Las dos herramientas siguientes permiten que el agente recupere y reutilice activos de medios — generados por IA o subidos por el usuario — entre turnos y entre sesiones, sin pedir URLs al usuario nuevamente.

POSTZEE_LIST_MEDIA

Lista de medios recientes, con alcance a la organización. Devuelve los más nuevos primero. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`type`	string	No	`"image"`, `"video"` o `"all"` (predeterminado)
`source`	string	No	`"generated"` (creado por IA), `"uploaded"` (importado vía `POSTZEE_UPLOAD_MEDIA`) o `"all"` (predeterminado)
`search`	string	No	Búsqueda case-insensitive en el prompt original (medios IA) y nombre de archivo
`since`	string	No	Fecha ISO — devuelve solo medios creados después de ese instante
`limit`	number	No	Predeterminado 20, máximo 100

Devuelve (por ítem):

{
  "mediaId": "uuid",
  "url": "https://cdn.postzee.app/abc.jpg",
  "name": "abc.jpg",
  "type": "image",
  "source": "generated",
  "prompt": "perro en la playa al atardecer",
  "modelUsed": "ideogram-v3-turbo",
  "createdAt": "2026-05-07T14:23:00Z",
  "sizeBytes": 245678,
  "dimensions": { "width": 1024, "height": 1280 }
}

Devuelve (falla):

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

Los medios con soft-delete se excluyen automáticamente. Los medios en uso como foto de perfil también se excluyen.

POSTZEE_UPLOAD_MEDIA

Importa una URL pública al storage de Postzee. Devuelve un mediaId estable y URL en CDN para reuso en llamadas GENERATE_*, CREATE_POST y LIST_MEDIA. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`url`	string	Sí	URL pública `http://` o `https://`. Debe ser accesible sin autenticación.
`description`	string	No	Etiqueta corta guardada junto al medio (ayuda al agente a mantener su manifest)

Devuelve (éxito):

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

Devuelve (falla):

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

Orden de validación (cada paso rechaza antes del siguiente):

URL es parseable y usa http/https
Hostname no es localhost / IP privada / endpoint de cloud-metadata (defensa SSRF)
Sondeo HEAD exitoso (o GET ranged como fallback)
Content-Type coincide con la allowlist configurada (predeterminado: image/jpeg, image/png, image/webp, image/gif / video/mp4, video/quicktime, video/webm)
Tamaño dentro del cap por tipo (predeterminado: 25 MB imagen, 500 MB video)
La cuota de storage de la organización tiene espacio

Límites predeterminados (configurables vía SystemConfig):

Tipo	Tamaño máximo	Formatos aceptados
Imagen	25 MB	JPG, PNG, WebP, GIF
Video	500 MB	MP4, MOV, WebM

Los límites y formatos aceptados pueden ajustarse en runtime modificando las llaves UPLOAD_* en SystemConfig. Tanto esta herramienta MCP como los endpoints REST de upload comparten la misma fuente de verdad — cambias una vez, aplica a todos en ~5 minutos (TTL del cache).

Por privacidad y seguridad, la herramienta nunca acepta headers de autenticación ni tokens. URLs que requieren Bot Token (ej.: URLs getFile de Telegram) deben ser re-alojadas por el cliente de chat en una URL pública primero. Para uploads en base64 / archivos directos, usa el endpoint REST existente /media/upload-server — la herramienta MCP solo maneja importaciones vía URL.

Tras una importación exitosa, el medio aparece en POSTZEE_LIST_MEDIA con source: "uploaded".

Optimización de Prompt

POSTZEE_ENHANCE_PROMPT

Optimiza el prompt del usuario para mejores resultados de generación de IA. Gratis — sin costo de créditos. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`prompt`	string	Sí	El prompt del usuario a optimizar
`mediaType`	string	Sí	`"image"` o `"video"`
`model`	string	No	ID del modelo objetivo (para optimización específica del modelo)
`language`	string	No	Codigo del idioma de salida (ej: `"pt"`, `"es"`, `"fr"`, `"de"`). Si se omite, usa el idioma del propietario de la cuenta o ingles por defecto.

Devuelve:

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

Generación

POSTZEE_GENERATE_IMAGE

Genera una imagen IA a partir de un prompt. Operación asíncrona — devuelve un job id para hacer poll con POSTZEE_CHECK_JOB. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`prompt`	string	Sí	Descripción detallada de la imagen
`model`	string	Sí	ID del modelo de `POSTZEE_LIST_MODELS_DETAILED` (type `"image"`)
`aspectRatio`	string	No	ej.: `"1:1"`, `"4:5"`, `"9:16"`, `"16:9"`. Default: `"1:1"`
`imageUrls`	string[]	No	URLs de imágenes de referencia para image-to-image
`quality`	string	No	GPT Image 2: `"low"`, `"medium"` o `"high"`. Default: `"high"`
`style`	string	No	Recraft V3/V4: `"realistic_image"`, `"digital_illustration"`, `"vector_illustration"`
`renderingSpeed`	string	No	Tier de Ideogram V3: `"turbo"`, `"balanced"` o `"quality"`
`negativePrompt`	string	No	Cosas a excluir de la imagen
`seed`	number	No	Seed determinística opcional

Devuelve (éxito):

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

Devuelve (falla):

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

POSTZEE_GENERATE_VIDEO

Genera un video IA a partir de un prompt o imagen de referencia. Operación asíncrona. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`prompt`	string	Sí	Descripción detallada del video
`model`	string	Sí	ID del modelo de `POSTZEE_LIST_MODELS_DETAILED` (type `"video"`)
`duration`	number	No	Segundos. Valores permitidos varían por modelo — consulta `model.durations`
`aspectRatio`	string	No	`"16:9"` o `"9:16"`. Default: `"16:9"`
`imageUrl`	string	No	URL de imagen de referencia para modelos image-to-video
`endImageUrl`	string	No	URL del frame final para interpolación first-last-frame (ej.: `wan-flf2v`)
`resolution`	string	No	`"480p"`, `"540p"`, `"720p"`, `"1080p"`, `"4k"` (depende del modelo)
`quality`	string	No	Solo Sora 2 Pro: `"standard"` (720p) o `"high"` (1080p)
`generateAudio`	boolean	No	Genera audio ambiente (Veo 3.1, Pixverse, Wan 2.5). Afecta créditos.
`voiceControl`	boolean	No	Control de voz (Kling 2.6/3.0 Pro). Afecta créditos.
`negativePrompt`	string	No	Cosas a evitar en el video
`seed`	number	No	Seed determinística opcional

Devuelve: misma estructura que POSTZEE_GENERATE_IMAGE.

Los IDs específicos de tier devueltos por POSTZEE_LIST_MODELS_DETAILED (ej.: ideogram-v3-turbo, gpt-image-2-high, sora-2-t2v-pro-1080p, recraft-v4-vector) pueden pasarse directamente en model. El MCP traduce al payload correcto del backend automáticamente — no se requiere un parámetro tier o quality separado para la selección de tier.

Algunos IDs de modelo en el catálogo todavía no están disponibles vía MCP y serán rechazados por adelantado (variantes Sora 2 storyboard, algunos paths Veo 3.1). La respuesta de error incluye un array suggestions[] con hasta tres alternativas cercanas — elige una de ellas.

POSTZEE_CHECK_JOB

Hace poll del estado de un job asíncrono de generación de imagen o video. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`jobId`	string	Sí	Job id de `POSTZEE_GENERATE_*`

Devuelve (procesando):

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

Devuelve (éxito):

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

Devuelve (falla):

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

Devuelve (no encontrado):

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

Imágenes y Carruseles

El pipeline de imagen y carrusel deja que el agente componga slides editoriales con tipografía pixel-perfect, fuentes consistentes y cero alucinación de palabras. El agente envía el/los slide(s) compuesto(s); Postzee renderiza y devuelve el medio final listo para publicar. Cuatro tools cubren el ciclo: un render de imagen única para posts editoriales sueltos con tipografía cuidada, un render completo de carrusel para el batch inicial, reemplazo quirúrgico para correcciones y append incremental para autoría iterativa.

POSTZEE_RENDER_IMAGE

Renderiza UN documento HTML a un único Media PNG. La contraparte single-image de POSTZEE_RENDER_CAROUSEL, para posts editoriales sueltos (imágenes con mucho texto, portadas estilo magazine, hero quote cards) donde el valor está en el layout + tipografía en lugar de en una secuencia deslizable. Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`html`	string	Sí	Documento `<!doctype html>` completo del slide. Referencia imágenes por su URL Postzee CDN (devuelta por `POSTZEE_GENERATE_IMAGE` o `POSTZEE_UPLOAD_MEDIA`). Solo composición estática — sin scripts interactivos.
`width`	number	No	Ancho de salida en px (256-2160). Default `1080`.
`height`	number	No	Alto de salida en px (256-2160). Default `1350` (4:5 — optimizado para el feed de Instagram).
`name`	string	No	Título opcional mostrado en la gallery.

Mismos límites duros de POSTZEE_RENDER_CAROUSEL: 7 MB máximo por slide, 256-2160 px por dimensión, 45 s de timeout. Retorna (éxito):

{
  "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 queda expuesto para callers avanzados pero el uso típico es pasar el mediaUrl directo a POSTZEE_CREATE_POST como un array mediaUrls de un solo elemento. Retorna (falla):

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

Misma idempotency cache que el carousel render: payloads idénticos dentro de una ventana de 1 hora devuelven el mediaId cacheado en lugar de re-renderizar.

POSTZEE_RENDER_CAROUSEL

Renderiza N slides HTML a PNG y los agrupa atómicamente como un MediaGroup de carrusel. Síncrono — bloquea hasta que todos los slides terminen. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`slides`	array	Sí	1-15 objetos slide en orden de visualización. Cada uno: `{ html: string, width?: number, height?: number }`. El índice del array se convierte en el orden del slide.
`aspectRatio`	string	No	Tamaño default cuando width/height son omitidos: `"1:1"` (1080×1080), `"4:5"` (1080×1350), `"9:16"` (1080×1920). Default `"1:1"`.
`name`	string	No	Título opcional mostrado en la galería.

Límites server-side:

Máximo 15 slides por llamada
Mínimo 256 / máximo 2160 px por dimensión
7 MB máximo de HTML por slide
50 MB máximo de payload total por llamada (suma de todos los slides)
45 s de timeout por slide

Guardrails por plataforma en la publicación. El render acepta hasta 15 slides, pero la publicación está limitada por el tope nativo de cada red social (Instagram/Facebook ≤ 10, LinkedIn ≤ 20, TikTok ≤ 35, Threads/Reddit ≤ 20, Pinterest ≤ 5, X ≤ 4, Bluesky/Mastodon ≤ 4, Telegram/VK ≤ 10). Cuando se llama a POSTZEE_CREATE_POST con mediaUrls excediendo el límite de la red destino, Postzee rechaza la publicación antes de llamar a la API de la plataforma, con mensaje traducido al idioma del usuario. Usa POSTZEE_LIST_PLATFORM_SPECS para la tabla viva. Modelo de falla tolerante a parcial. Si un slide falla o el dispatcher hace timeout antes que todos los slides se asienten, el grupo se preserva con renderStatus: "partial" en aiMetadata (en lugar de revertirse). Reintenta los slides faltantes via POSTZEE_REPLACE_CAROUSEL_SLIDE o POSTZEE_APPEND_CAROUSEL_SLIDE. Los slides que SÍ renderizaron nunca son destruidos — el usuario conserva su trabajo incluso en falla parcial. El orden es estructural, no temporal. El índice del array = orderInGroup, asignado ANTES de que cualquier worker corra. Los slides pueden renderizar en paralelo, pero el orden se preserva determinísticamente. Modelo de seguridad. Las composiciones de slide se renderizan como contenido estático — los scripts interactivos son inertes. Las requests de red para los assets referenciados están restringidas a hosts públicos (direcciones privadas/internas están bloqueadas). Devuelve:

{
  "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 ya viene en orden de visualización — pásalo directo a POSTZEE_CREATE_POST. Respuesta de falla:

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

POSTZEE_REPLACE_CAROUSEL_SLIDE

Reemplaza quirúrgicamente UN slide de un carrusel existente sin tocar los demás. Úsalo cuando el usuario diga “cambia el slide N” — ahorra tiempo y créditos, y preserva la identidad de los demás slides (URLs e IDs intactos). Parámetros:

Parámetro	Tipo	Requerido	Descripción
`mediaGroupId`	string	Sí	El id devuelto por `POSTZEE_RENDER_CAROUSEL`.
`orderInGroup`	number	Sí	Índice base-cero del slide a reemplazar. Slide 4 → `3`. Debe apuntar a un slide activo (no soft-deleted).
`slide`	object	Sí	`{ html, width?, height? }` — misma estructura que una entrada de `RENDER_CAROUSEL.slides`.

El slide reemplazado se soft-deleta después que el nuevo render se sube exitosamente; el nuevo slide toma el mismo orderInGroup. Si orderInGroup === 0, el thumbnail de portada del carrusel se actualiza automáticamente. Devuelve:

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

Añade UN nuevo slide al final de un carrusel existente. Úsalo para autoría iterativa — cuando el usuario quiere construir el carrusel slide por slide (“muéstrame el slide 1… ahora el slide 2…”), esto hace que cada nuevo slide caiga en el MISMO MediaGroup en lugar de producir N grupos de slide único huérfanos en la galería. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`mediaGroupId`	string	Sí	El id del carrusel que estás expandiendo. Devuelto por `POSTZEE_RENDER_CAROUSEL` (primer slide) o por una llamada anterior de `APPEND_CAROUSEL_SLIDE`.
`slide`	object	Sí	`{ html, width?, height? }` — misma estructura que una entrada de `RENDER_CAROUSEL.slides`.

El nuevo slide se añade en el siguiente orderInGroup disponible (gap-safe — si slides intermedios fueron eliminados, toma max(orderInGroup) + 1, nunca reutiliza un slot libre). El thumbnail de portada no cambia. Patrón de autoría iterativa. El primer slide debe ir por POSTZEE_RENDER_CAROUSEL (es lo que crea el MediaGroup). Cada slide subsecuente va por APPEND_CAROUSEL_SLIDE con el mismo mediaGroupId. Llamar RENDER_CAROUSEL por segunda vez para el mismo carrusel lógico produce un nuevo grupo y rompe el flujo iterativo — no lo hagas. Devuelve:

{
  "success": true,
  "mediaGroupId": "uuid",
  "appendedOrderInGroup": 7,
  "newMediaId": "...",
  "newMediaUrl": "https://cdn.postzee.app/.../slide-7-{ts}.png",
  "totalSlides": 8,
  "slides": [ /* ... lista ordenada completa incluyendo el nuevo ... */ ],
  "mediaUrls": [ /* ... lista ordenada completa ... */ ]
}

No hay primitiva de insertar-en-medio, reordenar o eliminar en v1. APPEND_CAROUSEL_SLIDE solo añade al FINAL. Si el usuario pide insertar en posición específica, intercambiar dos slides o eliminar uno, recompón el carrusel completo con POSTZEE_RENDER_CAROUSEL desde un nuevo guion.

HeyGen

Las herramientas HeyGen requieren una clave de API HeyGen configurada en tu cuenta Postzee. Conéctala en Settings → integración HeyGen. La generación de video HeyGen factura en la cuenta HeyGen del usuario, no en créditos Postzee.

POSTZEE_LIST_HEYGEN_AVATARS

Lista avatares HeyGen disponibles (filtra por género, edad, estilo, etc. del lado del cliente). Parámetros: Ninguno Devuelve: Array de avatares de tu cuenta HeyGen.

POSTZEE_LIST_HEYGEN_VOICES

Lista voces HeyGen disponibles. Parámetros: Ninguno Devuelve: Array de voces de tu cuenta HeyGen, con info de idioma y género.

POSTZEE_GENERATE_HEYGEN_VIDEO

Crea un video de avatar con HeyGen. Operación asíncrona — haz poll con POSTZEE_CHECK_JOB. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`script`	string	Sí	Texto para que el avatar hable (20-1500 caracteres)
`avatarId`	string	Sí	De `POSTZEE_LIST_HEYGEN_AVATARS`
`voiceId`	string	Sí	De `POSTZEE_LIST_HEYGEN_VOICES`
`aspectRatio`	string	No	`"16:9"` o `"9:16"`. Default: `"16:9"`

Devuelve: misma estructura que POSTZEE_GENERATE_IMAGE — jobId + status: "processing". La respuesta también avisa que se consumirán créditos HeyGen (no Postzee).

Publicación

POSTZEE_CREATE_POST

Crea, programa o publica un post en un canal de redes sociales. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`type`	string	Sí	`"now"` (publica inmediatamente), `"draft"` o `"schedule"`
`date`	string	Solo schedule	UTC datetime (ej.: `"2026-04-24T15:00:00Z"`) — requerido cuando `type` es `"schedule"`
`channelId`	string	Sí	ID del canal de `POSTZEE_LIST_CHANNELS`
`text`	string	Sí	Contenido del post
`mediaUrls`	string[]	No	URLs de medios (en orden de visualización — orden del array = orden de slides en carruseles)
`settings`	object	No	Configuración de publicación por plataforma. Envía un objeto plano con solo los campos relevantes a la red del canal destino — ej.: `{ "post_type": "story" }` para Instagram, `{ "privacy_level": "PUBLIC_TO_EVERYONE", "duet": true }` para TikTok. El MCP enruta los settings al validador correcto basándose en el canal. Ver configuraciones de plataforma para la referencia completa.

Devuelve (éxito):

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

La publicación es asíncrona: POSTZEE_CREATE_POST devuelve un postId de inmediato, pero el post aún no está en vivo. Haz polling de POSTZEE_GET_POST con ese postId hasta que state sea "PUBLISHED" para obtener el id del post en la plataforma (releaseId) y el enlace permanente (releaseURL). Devuelve (falla):

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

Códigos de error posibles:

Código	Significado
`subscription_required`	El plan actual no permite publicar o se alcanzó el límite mensual de posts. Se incluye `upgradeUrl`.
`date_required`	`type: "schedule"` se envió sin `date`.
`invalid_date`	El string `date` no es un timestamp UTC ISO válido.
`organization_not_found`	La clave MCP resolvió a una organización que no existe (raro).
`post_failed`	Error de provider/red durante la publicación. Reintenta una vez; si persiste, surface el `message`.

POSTZEE_GET_POST

Obtiene el estado de publicación de un solo post — haz polling de esta herramienta después de POSTZEE_CREATE_POST para obtener el id del post en la plataforma y el enlace permanente una vez que el post esté en vivo. Parámetros:

Parámetro	Tipo	Requerido	Descripción
`postId`	string	Sí	El id del post devuelto por `POSTZEE_CREATE_POST`

Devuelve (éxito):

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

Campo	Descripción
`state`	`QUEUE` (esperando), `PUBLISHED`, `ERROR` o `DRAFT`
`published`	`true` cuando `state` es `PUBLISHED`
`releaseId`	El id nativo del post en la plataforma (ej., el id del medio en Instagram). `null` hasta que se publique
`releaseURL`	El enlace público permanente al post. `null` hasta que se publique

Mientras el post se está publicando, state es "QUEUE" y releaseId/releaseURL son null — sigue haciendo polling hasta que state sea "PUBLISHED" (o "ERROR" si la publicación falló). Devuelve (falla):

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

Herramientas legacy (deprecadas)

Las herramientas siguientes todavía funcionan pero están superadas:

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

Se mantendrán por al menos 90 días para retrocompatibilidad, luego se removerán en una futura versión major.

Patrón de workflow asíncrono

La generación de imagen, video y HeyGen es asíncrona. El workflow recomendado:

Valida primero — POSTZEE_VALIDATE_GENERATION para capturar errores de parámetros y créditos insuficientes sin quemar créditos
Estima el costo — POSTZEE_ESTIMATE_GENERATION_COST si necesitas el número exacto para mostrar al usuario
Optimiza el prompt — POSTZEE_ENHANCE_PROMPT (gratis)
Genera — POSTZEE_GENERATE_IMAGE / POSTZEE_GENERATE_VIDEO / POSTZEE_GENERATE_HEYGEN_VIDEO → devuelve jobId
Haz poll — POSTZEE_CHECK_JOB cada pocos segundos. Latencias típicas: 10-60s para imágenes, 30-180s para videos, hasta 5min para HeyGen
En caso de éxito — usa mediaUrl en POSTZEE_CREATE_POST

Formato de error estándar

Todas las herramientas write/generate devuelven:

{
  "success": true | false,
  "error": "<machine_code>",
  "message": "<human readable>",
  "...": "campos específicos de la herramienta en éxito"
}

Haz branch en el error machine code para lógica; usa message para narrar al usuario (traducido a su idioma).

Límites de tasa

Endpoint	Límite
HTTP POST	60 requests/minuto
Conexión SSE (legacy)	30 requests/minuto
Generación IA (`GENERATE_*`)	10 requests/minuto

Claude Code

Conecta Postzee a Claude Code.

OpenClaw

Conecta Postzee a OpenClaw.

Hermes Agent

Conecta Postzee a Hermes Agent.

Resumen del MCP

Vuelve al resumen del MCP.

​Referencia rápida

​Contexto y Descubrimiento

​POSTZEE_GET_CONTEXT

​POSTZEE_LIST_PLANS

​POSTZEE_LIST_CREDIT_PACKAGES

​Modelos y Specs

​POSTZEE_LIST_MODELS_DETAILED

​POSTZEE_LIST_PLATFORM_SPECS

​POSTZEE_GET_BEST_POSTING_TIMES

​Costo y Validación

​POSTZEE_ESTIMATE_GENERATION_COST

​POSTZEE_VALIDATE_GENERATION

​Canales y Créditos

​POSTZEE_LIST_CHANNELS

​POSTZEE_GET_CREDITS

​Memoria de Medios

​POSTZEE_LIST_MEDIA

​POSTZEE_UPLOAD_MEDIA

​Optimización de Prompt

​POSTZEE_ENHANCE_PROMPT

​Generación

​POSTZEE_GENERATE_IMAGE

​POSTZEE_GENERATE_VIDEO

​POSTZEE_CHECK_JOB

​Imágenes y Carruseles

​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

​Publicación

​POSTZEE_CREATE_POST

​POSTZEE_GET_POST

​Herramientas legacy (deprecadas)

​Patrón de workflow asíncrono

​Formato de error estándar

​Límites de tasa

Claude Code

OpenClaw

Hermes Agent

Resumen del MCP

Referencia rápida

Contexto y Descubrimiento

POSTZEE_GET_CONTEXT

POSTZEE_LIST_PLANS

POSTZEE_LIST_CREDIT_PACKAGES

Modelos y Specs

POSTZEE_LIST_MODELS_DETAILED

POSTZEE_LIST_PLATFORM_SPECS

POSTZEE_GET_BEST_POSTING_TIMES

Costo y Validación

POSTZEE_ESTIMATE_GENERATION_COST

POSTZEE_VALIDATE_GENERATION

Canales y Créditos

POSTZEE_LIST_CHANNELS

POSTZEE_GET_CREDITS

Memoria de Medios

POSTZEE_LIST_MEDIA

POSTZEE_UPLOAD_MEDIA

Optimización de Prompt

POSTZEE_ENHANCE_PROMPT

Generación

POSTZEE_GENERATE_IMAGE

POSTZEE_GENERATE_VIDEO

POSTZEE_CHECK_JOB

Imágenes y Carruseles

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

Publicación

POSTZEE_CREATE_POST

POSTZEE_GET_POST

Herramientas legacy (deprecadas)

Patrón de workflow asíncrono

Formato de error estándar

Límites de tasa