Referência de Ferramentas MCP

Referência completa para todas as 25 ferramentas expostas pelo servidor MCP do Postzee. Essas ferramentas estão disponíveis para qualquer agente IA compatível com MCP (Claude Code, OpenClaw, Hermes Agent ou clientes MCP diretos).

Todas as ferramentas aceitam a chave de API embutida na sua URL MCP. Elas são escopadas a uma única organização. Custos de geração de IA são sempre retornados em créditos, nunca em dólares. ($1 USD = 1.000 créditos.)

Referência rápida

Categoria	Ferramentas
Contexto e Descoberta	`POSTZEE_GET_CONTEXT`, `POSTZEE_LIST_PLANS`, `POSTZEE_LIST_CREDIT_PACKAGES`
Modelos e Specs	`POSTZEE_LIST_MODELS_DETAILED`, `POSTZEE_LIST_PLATFORM_SPECS`, `POSTZEE_GET_BEST_POSTING_TIMES`
Custo e Validação	`POSTZEE_ESTIMATE_GENERATION_COST`, `POSTZEE_VALIDATE_GENERATION`
Canais e Créditos	`POSTZEE_LIST_CHANNELS`, `POSTZEE_GET_CREDITS`
Memória de Mídia	`POSTZEE_LIST_MEDIA`, `POSTZEE_UPLOAD_MEDIA`
Otimização de Prompt	`POSTZEE_ENHANCE_PROMPT`
Geração	`POSTZEE_GENERATE_IMAGE`, `POSTZEE_GENERATE_VIDEO`, `POSTZEE_CHECK_JOB`
Imagens e Carrosséis	`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`
Postagem	`POSTZEE_CREATE_POST`, `POSTZEE_GET_POST`
Legacy (deprecadas)	`POSTZEE_LIST_IMAGE_MODELS`, `POSTZEE_LIST_VIDEO_MODELS`

Contexto e Descoberta

POSTZEE_GET_CONTEXT

Agregação de contexto em uma única chamada. Recomendada como primeira chamada de toda sessão. Retorna plano, créditos, storage, canais, features e versão da skill em um round-trip. Parâmetros: Nenhum Retorna:

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

As flags features.* refletem o que o MCP consegue executar agora — agentes só devem sugerir features cuja flag correspondente seja true.

POSTZEE_LIST_PLANS

Lista os 5 níveis de assinatura com pricing e limites. Parâmetros: Nenhum Retorna:

[
  {
    "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 pacotes de créditos one-time (eternos — nunca expiram). Parâmetros: Nenhum Retorna:

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

POSTZEE_LIST_MODELS_DETAILED

Matriz de capacidades para todos os modelos de imagem e vídeo disponíveis — durações, resoluções, capacidades de áudio, parâmetros customizados aceitos, e tier de custo relativo. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Não	`"image"`, `"video"`, ou `"all"` (default)
`includeHeygen`	boolean	Não	Inclui a entrada sintética HeyGen. Default: `true`
`family`	string	Não	Filtra por uma única família (ex.: `"ideogram-v3"`, `"sora-2"`, `"veo3.1"`)
`agenticDefault`	boolean	Não	Quando `true`, retorna apenas as entradas marcadas como recomendação para automação

Retorna (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 é um de very-low, low, mid, high, premium — o custo absoluto em créditos não é exposto intencionalmente; use POSTZEE_ESTIMATE_GENERATION_COST em vez disso. A entrada sintética heygen-avatar-video tem costTier: "external" e um billingNote indicando que o HeyGen cobra na conta HeyGen do usuário, não em créditos Postzee.

POSTZEE_LIST_PLATFORM_SPECS

Specs por plataforma (aspect ratios, máximo de slides para carrosséis, limites de caracteres em legendas, recomendações de hashtag). Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`platforms`	string[]	Não	Filtra para plataformas específicas (ex.: `["instagram", "tiktok"]`). Omitir para todas.

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

POSTZEE_GET_BEST_POSTING_TIMES

Janelas heurísticas dos melhores horários de postagem por canal, retornadas no fuso horário da organização. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`channelIds`	string[]	Não	Filtra para canais específicos. Omitir para todos os canais ativos.

Retorna:

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

Canais com status disabled ou requiresReauth são filtrados — recomendações só aparecem para canais que de fato podem postar.

Custo e Validação

POSTZEE_ESTIMATE_GENERATION_COST

Fonte única de verdade para estimativas de custo. Sempre retorna créditos, nunca dólares. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Sim	`"image"` ou `"video"`
`model`	string	Sim	ID do modelo de `POSTZEE_LIST_MODELS_DETAILED`
`duration`	number	Não	Segundos (vídeo, para modelos com pricing por segundo)
`resolution`	string	Não	`"480p"`, `"540p"`, `"720p"`, `"1080p"`, `"4k"`
`quality`	string	Não	Sora 2 Pro: `"standard"` (720p) ou `"high"` (1080p)
`generateAudio`	boolean	Não	Afeta custo em Veo, Pixverse, Wan 2.5
`voiceControl`	boolean	Não	Kling 2.6/3.0 Pro
`aspectRatio`	string	Não	Informativo

Retorna:

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

Validação pré-execução — captura erros de parâmetros, créditos insuficientes, problemas de storage e bloqueios de plano antes de queimar créditos. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Sim	`"image"` ou `"video"`
`model`	string	Sim	ID do modelo
`duration`	number	Não	Segundos
`aspectRatio`	string	Não	ex.: `"4:5"`
`resolution`	string	Não	Resolução de saída
`quality`	string	Não	Sora Pro `"standard"` / `"high"`
`generateAudio`	boolean	Não
`voiceControl`	boolean	Não
`imageUrl`	string	Não	Obrigatório para modelos image-to-video
`slideCount`	number	Não	Multiplicador de batch (ex.: N variações do mesmo prompt). Não use para carrosséis — esses passam por `POSTZEE_RENDER_CAROUSEL` com modelo de custo próprio.

Retorna:

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

Quando valid: false, o array errors[] contém problemas legíveis — ex.: duração não está no conjunto permitido pelo modelo, falta imageUrl para modelo i2v, storage em 100%, ou modelo registrado mas não disponível ainda via MCP.

Canais e Créditos

POSTZEE_LIST_CHANNELS

Lista canais de redes sociais conectados com flags de ação explícitas. Parâmetros: Nenhum Retorna:

[
  {
    "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 é um de "none" (pronto para postar), "reconnect" (token expirado — usuário reconecta), ou "reenable" (admin/billing — usuário reativa, não o mesmo que reconectar). statusMessage é uma explicação legível quando o canal requer ação (ex: "Token do canal expirado. Reconecte para continuar postando."). É null quando actionRequired é "none".

POSTZEE_GET_CREDITS

Saldo de créditos leve. Subset de POSTZEE_GET_CONTEXT.credits — prefira o último para código novo. Parâmetros: Nenhum Retorna:

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

Todos os valores em créditos ($1 USD = 1.000 créditos).

Memória de Mídia

As duas ferramentas abaixo permitem que o agente recupere e reutilize ativos de mídia — gerados por IA ou enviados pelo usuário — entre turnos e entre sessões, sem precisar pedir URLs ao usuário novamente.

POSTZEE_LIST_MEDIA

Lista de mídia recente, escopada à organização. Retorna os itens mais novos primeiro. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Não	`"image"`, `"video"` ou `"all"` (padrão)
`source`	string	Não	`"generated"` (criado por IA), `"uploaded"` (importado via `POSTZEE_UPLOAD_MEDIA`) ou `"all"` (padrão)
`search`	string	Não	Busca case-insensitive no prompt original (mídia IA) e no nome do arquivo
`since`	string	Não	Data ISO — retorna apenas mídia criada após esse instante
`limit`	number	Não	Padrão 20, máximo 100

Retorna (por item):

{
  "mediaId": "uuid",
  "url": "https://cdn.postzee.app/abc.jpg",
  "name": "abc.jpg",
  "type": "image",
  "source": "generated",
  "prompt": "cachorro na praia ao pôr do sol",
  "modelUsed": "ideogram-v3-turbo",
  "createdAt": "2026-05-07T14:23:00Z",
  "sizeBytes": 245678,
  "dimensions": { "width": 1024, "height": 1280 }
}

Retorna (falha):

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

Mídias com soft-delete são excluídas automaticamente. Mídia em uso como foto de perfil também é excluída.

POSTZEE_UPLOAD_MEDIA

Importa uma URL pública para o storage do Postzee. Retorna um mediaId estável e URL na CDN para reuso em chamadas GENERATE_*, CREATE_POST e LIST_MEDIA. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL pública `http://` ou `https://`. Deve ser acessível sem autenticação.
`description`	string	Não	Rótulo curto guardado junto à mídia (ajuda o agente a manter seu manifest)

Retorna (sucesso):

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

Retorna (falha):

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

Ordem de validação (cada passo rejeita antes do próximo):

URL é parseável e usa http/https
Hostname não é localhost / IP privado / endpoint de cloud-metadata (defesa SSRF)
Sondagem HEAD bem-sucedida (ou GET ranged como fallback)
Content-Type bate com a allowlist configurada (padrão: image/jpeg, image/png, image/webp, image/gif / video/mp4, video/quicktime, video/webm)
Tamanho dentro do cap por tipo (padrão: 25 MB imagem, 500 MB vídeo)
Quota de storage da organização tem espaço

Limites padrão (configuráveis via SystemConfig):

Tipo	Tamanho máximo	Formatos aceitos
Imagem	25 MB	JPG, PNG, WebP, GIF
Vídeo	500 MB	MP4, MOV, WebM

Limites e formatos aceitos podem ser ajustados em runtime alterando as chaves UPLOAD_* no SystemConfig. Tanto esta ferramenta MCP quanto os endpoints REST de upload compartilham a mesma fonte de verdade — altera uma vez, vale para todos em ~5 minutos (TTL do cache).

Por privacidade e segurança, a ferramenta nunca aceita headers de autenticação ou tokens. URLs que requerem Bot Token (ex.: URLs getFile do Telegram) precisam ser re-hospedadas pelo cliente de chat em uma URL pública primeiro. Para uploads em base64 / arquivos diretos, use o endpoint REST existente /media/upload-server — a ferramenta MCP só lida com importações via URL.

Após importação bem-sucedida, a mídia aparece em POSTZEE_LIST_MEDIA com source: "uploaded".

Otimização de Prompt

POSTZEE_ENHANCE_PROMPT

Otimiza o prompt do usuário para melhores resultados de geração de IA. Grátis — sem custo de créditos. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`prompt`	string	Sim	O prompt do usuário a ser otimizado
`mediaType`	string	Sim	`"image"` ou `"video"`
`model`	string	Não	ID do modelo alvo (para otimização específica do modelo)
`language`	string	Não	Código do idioma de saída (ex: `"pt"`, `"es"`, `"fr"`, `"de"`). Se omitido, usa o idioma do proprietário da conta ou padrão inglês.

Retorna:

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

Geração

POSTZEE_GENERATE_IMAGE

Gera uma imagem IA a partir de um prompt. Operação assíncrona — retorna um job id para fazer poll com POSTZEE_CHECK_JOB. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`prompt`	string	Sim	Descrição detalhada da imagem
`model`	string	Sim	ID do modelo de `POSTZEE_LIST_MODELS_DETAILED` (type `"image"`)
`aspectRatio`	string	Não	ex.: `"1:1"`, `"4:5"`, `"9:16"`, `"16:9"`. Default: `"1:1"`
`imageUrls`	string[]	Não	URLs de imagens de referência para image-to-image
`quality`	string	Não	GPT Image 2: `"low"`, `"medium"` ou `"high"`. Default: `"high"`
`style`	string	Não	Recraft V3/V4: `"realistic_image"`, `"digital_illustration"`, `"vector_illustration"`
`renderingSpeed`	string	Não	Tier do Ideogram V3: `"turbo"`, `"balanced"` ou `"quality"`
`negativePrompt`	string	Não	Coisas a excluir da imagem
`seed`	number	Não	Seed determinística opcional

Retorna (sucesso):

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

Retorna (falha):

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

POSTZEE_GENERATE_VIDEO

Gera um vídeo IA a partir de um prompt ou imagem de referência. Operação assíncrona. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`prompt`	string	Sim	Descrição detalhada do vídeo
`model`	string	Sim	ID do modelo de `POSTZEE_LIST_MODELS_DETAILED` (type `"video"`)
`duration`	number	Não	Segundos. Valores permitidos variam por modelo — consulte `model.durations`
`aspectRatio`	string	Não	`"16:9"` ou `"9:16"`. Default: `"16:9"`
`imageUrl`	string	Não	URL de imagem de referência para modelos image-to-video
`endImageUrl`	string	Não	URL do frame final para interpolação first-last-frame (ex.: `wan-flf2v`)
`resolution`	string	Não	`"480p"`, `"540p"`, `"720p"`, `"1080p"`, `"4k"` (depende do modelo)
`quality`	string	Não	Apenas Sora 2 Pro: `"standard"` (720p) ou `"high"` (1080p)
`generateAudio`	boolean	Não	Gera áudio ambiente (Veo 3.1, Pixverse, Wan 2.5). Afeta créditos.
`voiceControl`	boolean	Não	Controle de voz (Kling 2.6/3.0 Pro). Afeta créditos.
`negativePrompt`	string	Não	Coisas a evitar no vídeo
`seed`	number	Não	Seed determinística opcional

Retorna: mesma estrutura de POSTZEE_GENERATE_IMAGE.

Os IDs específicos de tier retornados por POSTZEE_LIST_MODELS_DETAILED (ex.: ideogram-v3-turbo, gpt-image-2-high, sora-2-t2v-pro-1080p, recraft-v4-vector) podem ser passados diretamente em model. O MCP traduz para o payload correto do backend automaticamente — não é necessário um parâmetro tier ou quality separado para a seleção de tier.

Alguns IDs de modelo no catálogo ainda não estão disponíveis via MCP e serão rejeitados de antemão (variantes Sora 2 storyboard, alguns paths Veo 3.1). A resposta de erro inclui um array suggestions[] com até três alternativas próximas — escolha uma delas.

POSTZEE_CHECK_JOB

Faz poll do status de um job assíncrono de geração de imagem ou vídeo. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`jobId`	string	Sim	Job id de `POSTZEE_GENERATE_*`

Retorna (processando):

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

Retorna (sucesso):

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

Retorna (falha):

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

Retorna (não encontrado):

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

Imagens e Carrosséis

O pipeline de imagem e carrossel deixa o agente compor slides editoriais com tipografia pixel-perfect, fontes consistentes e zero alucinação de palavras. O agente envia o(s) slide(s) composto(s); o Postzee renderiza e devolve a mídia final pronta pra publicar. Quatro tools cobrem o ciclo: um render de imagem única para posts editoriais avulsos com tipografia caprichada, um render completo de carrossel para o batch inicial, substituição cirúrgica para correções e append incremental para autoria iterativa.

POSTZEE_RENDER_IMAGE

Renderiza UM documento HTML para um Media PNG único. A contraparte single-image do POSTZEE_RENDER_CAROUSEL, pra posts editoriais avulsos (single images text-heavy, capas estilo magazine, hero quote cards) onde o valor está no layout + tipografia em vez de numa sequência deslizável. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`html`	string	Sim	Documento `<!doctype html>` completo do slide. Referencie imagens pela URL Postzee CDN (retornada por `POSTZEE_GENERATE_IMAGE` ou `POSTZEE_UPLOAD_MEDIA`). Apenas composição estática — sem scripts interativos.
`width`	number	Não	Largura de saída em px (256-2160). Default `1080`.
`height`	number	Não	Altura de saída em px (256-2160). Default `1350` (4:5 — otimizado pro feed do Instagram).
`name`	string	Não	Título opcional mostrado na gallery.

Mesmos limites hard do POSTZEE_RENDER_CAROUSEL: 7 MB máximo por slide, 256-2160 px por dimensão, timeout de 45 s. Retorna (sucesso):

{
  "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 fica exposto pra callers avançados mas o uso típico é passar o mediaUrl direto pro POSTZEE_CREATE_POST como um array mediaUrls de elemento único. Retorna (falha):

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

Mesma idempotency cache do carousel render: payloads idênticos dentro de uma janela de 1 hora retornam o mediaId cached em vez de re-renderizar.

POSTZEE_RENDER_CAROUSEL

Renderiza N slides HTML para PNG e os agrupa atomicamente como um MediaGroup de carrossel. Síncrona — bloqueia até todos os slides finalizarem. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`slides`	array	Sim	1-15 objetos slide em ordem de exibição. Cada um: `{ html: string, width?: number, height?: number }`. O índice do array vira a ordem do slide.
`aspectRatio`	string	Não	Tamanho default quando width/height são omitidos: `"1:1"` (1080×1080), `"4:5"` (1080×1350), `"9:16"` (1080×1920). Default `"1:1"`.
`name`	string	Não	Título opcional exibido na galeria.

Limites server-side:

Máximo 15 slides por chamada
Mínimo 256 / máximo 2160 px por dimensão
7 MB máximos de HTML por slide
50 MB máximos de payload total por chamada (soma de todos os slides)
45 s de timeout por slide

Guardrails por plataforma na publicação. O render aceita até 15 slides, mas a publicação é limitada pelo teto nativo de cada rede social (Instagram/Facebook ≤ 10, LinkedIn ≤ 20, TikTok ≤ 35, Threads/Reddit ≤ 20, Pinterest ≤ 5, X ≤ 4, Bluesky/Mastodon ≤ 4, Telegram/VK ≤ 10). Quando POSTZEE_CREATE_POST é chamado com mediaUrls excedendo o limite da rede destino, o Postzee rejeita o post antes de chamar a API da plataforma, com mensagem traduzida para o idioma do usuário. Use POSTZEE_LIST_PLATFORM_SPECS para a tabela viva. Modelo de falha tolerante a parcial. Se um slide falhar ou o dispatcher timeout antes de todos os slides assentarem, o grupo é preservado com renderStatus: "partial" no aiMetadata (em vez de ser revertido). Refaça os slides faltantes via POSTZEE_REPLACE_CAROUSEL_SLIDE ou POSTZEE_APPEND_CAROUSEL_SLIDE. Slides que renderizaram nunca são destruídos — o usuário mantém o trabalho mesmo em falha parcial. Ordem é estrutural, não temporal. O índice do array = orderInGroup, atribuído ANTES de qualquer worker rodar. Slides podem renderizar em paralelo, mas a ordem é preservada deterministicamente. Modelo de segurança. As composições de slide são renderizadas como conteúdo estático — scripts interativos são inertes. As requisições de rede para os assets referenciados são restritas a hosts públicos (endereços privados/internos são bloqueados). Retorna:

{
  "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 já vem em ordem de exibição — passe direto para POSTZEE_CREATE_POST. Resposta de falha:

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

POSTZEE_REPLACE_CAROUSEL_SLIDE

Substitui cirurgicamente UM slide de um carrossel existente sem tocar nos outros. Use quando o usuário pede “muda o slide N” — economiza tempo e créditos, e preserva a identidade dos demais slides (URLs e IDs intactos). Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`mediaGroupId`	string	Sim	O id retornado por `POSTZEE_RENDER_CAROUSEL`.
`orderInGroup`	number	Sim	Índice base-zero do slide a substituir. Slide 4 → `3`. Deve apontar pra slide ativo (não soft-deleted).
`slide`	object	Sim	`{ html, width?, height? }` — mesma estrutura de uma entrada de `RENDER_CAROUSEL.slides`.

O slide substituído é soft-deleted depois que o novo render é uploadado com sucesso; o novo slide assume o mesmo orderInGroup. Se orderInGroup === 0, o thumbnail de capa do carrossel é atualizado automaticamente. Retorna:

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

Adiciona UM novo slide ao final de um carrossel existente. Use para autoria iterativa — quando o usuário quer construir o carrossel slide a slide (“mostra o slide 1… agora o slide 2…”), isso mantém cada novo slide caindo no MESMO MediaGroup em vez de produzir N grupos de slide único órfãos na galeria. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`mediaGroupId`	string	Sim	O id do carrossel que você está expandindo. Retornado por `POSTZEE_RENDER_CAROUSEL` (primeiro slide) ou por uma chamada anterior de `APPEND_CAROUSEL_SLIDE`.
`slide`	object	Sim	`{ html, width?, height? }` — mesma estrutura de uma entrada de `RENDER_CAROUSEL.slides`.

O novo slide é adicionado no próximo orderInGroup disponível (gap-safe — se slides intermediários foram deletados, isso pega max(orderInGroup) + 1, nunca reaproveita slot livre). Thumbnail de capa não é alterado. Padrão de autoria iterativa. Primeiro slide ainda deve ir por POSTZEE_RENDER_CAROUSEL (é o que cria o MediaGroup). Cada slide subsequente vai por APPEND_CAROUSEL_SLIDE com o mesmo mediaGroupId. Chamar RENDER_CAROUSEL uma segunda vez para o mesmo carrossel lógico produz um novo grupo e quebra o fluxo iterativo — não faça. Retorna:

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

Não há primitiva de inserir-no-meio, reordenar ou remover na v1. APPEND_CAROUSEL_SLIDE só adiciona ao FINAL. Se o usuário pedir pra inserir em posição específica, trocar dois slides ou remover um, refaça o carrossel inteiro com POSTZEE_RENDER_CAROUSEL a partir de um novo roteiro.

HeyGen

Ferramentas HeyGen exigem uma chave de API HeyGen configurada na sua conta Postzee. Configure em Settings → integração HeyGen. Geração de vídeo HeyGen cobra na conta HeyGen do usuário, não em créditos Postzee.

POSTZEE_LIST_HEYGEN_AVATARS

Lista avatares HeyGen disponíveis (filtre por gênero, idade, estilo etc. no lado do cliente). Parâmetros: Nenhum Retorna: Array de avatares da sua conta HeyGen.

POSTZEE_LIST_HEYGEN_VOICES

Lista vozes HeyGen disponíveis. Parâmetros: Nenhum Retorna: Array de vozes da sua conta HeyGen, com info de idioma e gênero.

POSTZEE_GENERATE_HEYGEN_VIDEO

Cria um vídeo de avatar com HeyGen. Operação assíncrona — faça poll com POSTZEE_CHECK_JOB. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`script`	string	Sim	Texto para o avatar falar (20-1500 caracteres)
`avatarId`	string	Sim	De `POSTZEE_LIST_HEYGEN_AVATARS`
`voiceId`	string	Sim	De `POSTZEE_LIST_HEYGEN_VOICES`
`aspectRatio`	string	Não	`"16:9"` ou `"9:16"`. Default: `"16:9"`

Retorna: mesma estrutura de POSTZEE_GENERATE_IMAGE — jobId + status: "processing". A resposta também avisa que créditos HeyGen (não Postzee) serão consumidos.

Postagem

POSTZEE_CREATE_POST

Cria, agenda ou publica um post em um canal de rede social. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Sim	`"now"` (publica imediatamente), `"draft"` ou `"schedule"`
`date`	string	Apenas schedule	UTC datetime (ex.: `"2026-04-24T15:00:00Z"`) — obrigatório quando `type` é `"schedule"`
`channelId`	string	Sim	ID do canal de `POSTZEE_LIST_CHANNELS`
`text`	string	Sim	Conteúdo do post
`mediaUrls`	string[]	Não	URLs das mídias (em ordem de exibição — ordem do array = ordem dos slides em carrosséis)
`settings`	object	Não	Configurações de publicação por plataforma. Envie um objeto flat com apenas os campos relevantes pra rede do canal alvo — ex.: `{ "post_type": "story" }` pro Instagram, `{ "privacy_level": "PUBLIC_TO_EVERYONE", "duet": true }` pro TikTok. O MCP roteia as settings pro validador certo baseado no canal. Veja configurações de plataforma pra referência completa.

Retorna (sucesso):

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

A publicação é assíncrona: POSTZEE_CREATE_POST retorna um postId imediatamente, mas o post ainda não está no ar. Faça poll de POSTZEE_GET_POST com esse postId até state ser "PUBLISHED" para obter o ID do post na plataforma (releaseId) e o permalink (releaseURL). Retorna (falha):

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

Códigos de error possíveis:

Código	Significado
`subscription_required`	O plano atual não permite publicar ou o limite mensal de posts foi atingido. `upgradeUrl` é incluído.
`date_required`	`type: "schedule"` foi enviado sem `date`.
`invalid_date`	A string `date` não é um timestamp UTC ISO válido.
`organization_not_found`	A chave MCP resolveu para uma organização que não existe (raro).
`post_failed`	Erro de provider/rede durante a publicação. Tente uma vez de novo; se persistir, surface a `message`.

POSTZEE_GET_POST

Obtém o status de publicação de um único post — faça poll desta ferramenta após POSTZEE_CREATE_POST para obter o ID do post na plataforma e o permalink assim que o post entrar no ar. Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`postId`	string	Sim	O id do post retornado por `POSTZEE_CREATE_POST`

Retorna (sucesso):

{
  "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	Descrição
`state`	`QUEUE` (aguardando), `PUBLISHED`, `ERROR` ou `DRAFT`
`published`	`true` quando `state` é `PUBLISHED`
`releaseId`	O ID nativo do post na plataforma (ex.: o ID da mídia no Instagram). `null` até ser publicado
`releaseURL`	O permalink público do post. `null` até ser publicado

Enquanto o post ainda está sendo publicado, state é "QUEUE" e releaseId/releaseURL são null — continue fazendo poll até state ser "PUBLISHED" (ou "ERROR" se a publicação falhar). Retorna (falha):

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

Ferramentas legacy (deprecadas)

As ferramentas a seguir ainda funcionam mas foram superadas:

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

Serão mantidas por pelo menos 90 dias para retrocompatibilidade, depois removidas em uma futura versão major.

Padrão de workflow assíncrono

Geração de imagem, vídeo e HeyGen são assíncronas. O workflow recomendado:

Valide primeiro — POSTZEE_VALIDATE_GENERATION para capturar erros de parâmetros e créditos insuficientes sem queimar créditos
Estime o custo — POSTZEE_ESTIMATE_GENERATION_COST se você precisar do número exato para mostrar ao usuário
Otimize o prompt — POSTZEE_ENHANCE_PROMPT (grátis)
Gere — POSTZEE_GENERATE_IMAGE / POSTZEE_GENERATE_VIDEO / POSTZEE_GENERATE_HEYGEN_VIDEO → retorna jobId
Faça poll — POSTZEE_CHECK_JOB a cada poucos segundos. Latências típicas: 10-60s para imagens, 30-180s para vídeos, até 5min para HeyGen
Em caso de sucesso — use mediaUrl em POSTZEE_CREATE_POST

Formato de erro padrão

Todas as ferramentas write/generate retornam:

{
  "success": true | false,
  "error": "<machine_code>",
  "message": "<human readable>",
  "...": "campos específicos da ferramenta em sucesso"
}

Faça branch no error machine code para lógica; use message para narrar ao usuário (traduzido para o idioma dele).

Limites de taxa

Endpoint	Limite
HTTP POST	60 requests/minuto
Conexão SSE (legacy)	30 requests/minuto
Geração IA (`GENERATE_*`)	10 requests/minuto

Claude Code

Conecte o Postzee ao Claude Code.

OpenClaw

Conecte o Postzee ao OpenClaw.

Hermes Agent

Conecte o Postzee ao Hermes Agent.

Visão Geral do MCP

Volte para a visão geral do MCP.

​Referência rápida

​Contexto e Descoberta

​POSTZEE_GET_CONTEXT

​POSTZEE_LIST_PLANS

​POSTZEE_LIST_CREDIT_PACKAGES

​Modelos e Specs

​POSTZEE_LIST_MODELS_DETAILED

​POSTZEE_LIST_PLATFORM_SPECS

​POSTZEE_GET_BEST_POSTING_TIMES

​Custo e Validação

​POSTZEE_ESTIMATE_GENERATION_COST

​POSTZEE_VALIDATE_GENERATION

​Canais e Créditos

​POSTZEE_LIST_CHANNELS

​POSTZEE_GET_CREDITS

​Memória de Mídia

​POSTZEE_LIST_MEDIA

​POSTZEE_UPLOAD_MEDIA

​Otimização de Prompt

​POSTZEE_ENHANCE_PROMPT

​Geração

​POSTZEE_GENERATE_IMAGE

​POSTZEE_GENERATE_VIDEO

​POSTZEE_CHECK_JOB

​Imagens e Carrosséis

​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

​Postagem

​POSTZEE_CREATE_POST

​POSTZEE_GET_POST

​Ferramentas legacy (deprecadas)

​Padrão de workflow assíncrono

​Formato de erro padrão

​Limites de taxa

Claude Code

OpenClaw

Hermes Agent

Visão Geral do MCP

Referência rápida

Contexto e Descoberta

POSTZEE_GET_CONTEXT

POSTZEE_LIST_PLANS

POSTZEE_LIST_CREDIT_PACKAGES

Modelos e Specs

POSTZEE_LIST_MODELS_DETAILED

POSTZEE_LIST_PLATFORM_SPECS

POSTZEE_GET_BEST_POSTING_TIMES

Custo e Validação

POSTZEE_ESTIMATE_GENERATION_COST

POSTZEE_VALIDATE_GENERATION

Canais e Créditos

POSTZEE_LIST_CHANNELS

POSTZEE_GET_CREDITS

Memória de Mídia

POSTZEE_LIST_MEDIA

POSTZEE_UPLOAD_MEDIA

Otimização de Prompt

POSTZEE_ENHANCE_PROMPT

Geração

POSTZEE_GENERATE_IMAGE

POSTZEE_GENERATE_VIDEO

POSTZEE_CHECK_JOB

Imagens e Carrosséis

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

Postagem

POSTZEE_CREATE_POST

POSTZEE_GET_POST

Ferramentas legacy (deprecadas)

Padrão de workflow assíncrono

Formato de erro padrão

Limites de taxa