Orshot-HQ/orshot-openclaw

Agendador de Mídias Sociais Orshot: renderizar, publicar, agendar, aprender

O Orshot renderiza uma imagem, carrossel ou vídeo a partir de um template e publica em mais de 13 plataformas em uma única requisição. Ele também gerencia rascunhos, agendamentos, edições e relatórios de análise, permitindo que um agente execute um calendário de conteúdo completo sem uma segunda ferramenta. Postagens também podem anexar qualquer URL de mídia pública, funcionando com imagens criadas em outro lugar.

Plataformas: X (Twitter), Instagram, Facebook, LinkedIn (perfil e página), TikTok, YouTube, Pinterest, Reddit, Bluesky, Threads, Telegram, Snapchat, Google Business.

Passo 1: conectar o servidor MCP do Orshot

Nada funciona antes disso. A rota MCP não precisa de chave para colar, mostra cada postagem como um cartão visual e é a que deve ser usada a partir de um agente.

openclaw mcp add orshot --url https://mcp.orshot.com/mcp --transport streamable-http --auth oauth
openclaw mcp login orshot

Claude Code: claude mcp add --transport http orshot https://mcp.orshot.com/mcp. Outros clientes MCP usam a mesma URL.

Apenas para jobs headless (cron, n8n, script de servidor): export ORSHOT_API_KEY=... e chame REST com Authorization: Bearer $ORSHOT_API_KEY.

Passo 2: verificar as contas conectadas

orshot_list_social_accounts            # MCP
GET /v1/social/accounts?include_health=true   # REST
# [{ "id": 1, "platform": "linkedin", "account_name": "Acme", "account_username": "acme", "health": { "status": "ok" } }]

Uma lista com contas significa que você pode publicar. Anote o id numérico de cada uma e qualquer flag health que indique reconexão.

Uma lista vazia significa que um humano ainda precisa conectar as contas. A API não pode conectar uma conta. Envie o usuário para o painel do Orshot: Workspace > Socials > Accounts (https://orshot.com/dashboard, depois a seção Socials do workspace), onde cada plataforma conecta com seu próprio login OAuth. Publicação social é um add-on em planos pagos, $12 por conta conectada por mês, sem créditos extras por postagem; o plano gratuito não pode conectar contas. Planos e o add-on estão em https://orshot.com/pricing. Diga isso uma vez, claramente, e aguarde o usuário voltar; a próxima chamada orshot_list_social_accounts mostrará a nova conta.

Fluxo de trabalho principal

1. Conectar e listar contas (acima).
2. Decidir a mídia. Renderizar a partir de um template (templateId + modifications) ou usar uma media_url existente.
3. Rascunho primeiro. Criar a postagem com status: "draft" a menos que o usuário tenha dito claramente para publicar agora.
4. Mostrar ao usuário a prévia, legenda, contas e horário. Pelo MCP, orshot_get_social_post renderiza um cartão visual.
5. Editar o que ele mudar (orshot_update_social_post), depois publicar (orshot_publish_social_draft) ou agendar (status: "scheduled" + scheduled_for).
6. Verificar status após uma plataforma assíncrona (Instagram, TikTok) terminar: processing vira published ou failed.
7. Ler análises um dia depois, e os insights de melhor horário antes do próximo agendamento.

Mapa de ferramentas MCP

Job	Ferramenta
listar contas	orshot_list_social_accounts
renderizar + publicar em uma chamada	orshot_render_template com publish
publicar URL de mídia	orshot_publish_social_post
listar / ler postagens	orshot_list_social_posts, orshot_get_social_post (cartão visual)
editar / enviar / descartar	orshot_update_social_post, orshot_publish_social_draft, orshot_discard_social_post
análises	orshot_get_social_analytics, orshot_get_social_analytics_daily, orshot_get_social_followers, orshot_get_social_post_analytics
melhor horário para publicar	orshot_get_best_time_to_post

O servidor MCP padrão usa status: "draft" a menos que haja uma autorização explícita. Mantenha assim.

Chamadas essenciais

Renderizar e publicar (ou rascunho, ou agendar) em uma chamada

Pelo MCP, isso é orshot_render_template com o mesmo objeto publish.

await fetch("https://api.orshot.com/v1/studio/render", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({
    templateId: 123,
    modifications: { headline: "Dia do lançamento", stat: "2.000 renderizações" },
    response: { type: "url", format: "png" },
    publish: {
      accounts: [1, 3],
      content: "Legenda de até 5000 caracteres",
      status: "scheduled",               // published | draft | scheduled
      scheduled_for: "2026-11-01T14:00:00Z",
      timezone: "America/New_York",
      platformOptions: {
        "3": { firstComment: "https://orshot.com", disableLinkPreview: true }, // LinkedIn
      },
    },
  }),
});

Templates com várias páginas publicam como carrossel nas plataformas que suportam. A resposta tem data.content (a renderização) e publish[] com uma entrada por conta.

Publicar mídia que você já tem

orshot_publish_social_post, ou:

curl -s -X POST https://api.orshot.com/v1/social/publish \
  -H "Authorization: Bearer $ORSHOT_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "accounts": [2],
    "content": "Seis coisas que ninguém te conta",
    "media_urls": ["https://.../1.png", "https://.../2.png", "https://.../3.png"],
    "status": "draft",
    "tiktokSettings": { "autoAddMusic": true }
  }'

Campo	Notas
accounts	obrigatório, ids numéricos
content	legenda, máximo 5000 caracteres
media_url / media_urls	uma ou várias URLs públicas; várias = carrossel
status	published (padrão no REST), draft, scheduled
scheduled_for	ISO 8601, pelo menos 60 s à frente, apenas com scheduled
timezone	nome IANA
platformOptions	por id da conta: LinkedIn firstComment, disableLinkPreview; Pinterest title, link
tiktokSettings.autoAddMusic	nível raiz, carrosséis de fotos no TikTok

Resposta: { post_id, status, platforms: [{ account_id, platform, status, url, error, action }] }. status pode ser published, scheduled, drafted, partial, processing ou failed. action: "reconnect" significa que o humano deve reconectar essa conta no painel.

Gerenciar postagens retidas

GET    /v1/social/posts?status=draft&limit=25        # também scheduled | published | processing | partial | failed, platform=, account_id=, cursor=
GET    /v1/social/posts/:id
PATCH  /v1/social/posts/:id                          # content, media_urls, accounts, status (draft|scheduled), scheduled_for, timezone, platformOptions
POST   /v1/social/posts/:id/publish                  # enviar uma postagem retida agora
POST   /v1/social/posts/:id/sync                     # atualizar status do provedor
DELETE /v1/social/posts/:id                          # descartar; recusado se alguma conta já foi ao ar

is_editable e is_discardable em cada postagem informam o que ainda é permitido. Editar nunca re-renderiza e não custa nada.

Análises

GET /v1/social/analytics?platform=linkedin&source=orshot      # por postagem: impressões, engajamento, cliques, taxa; seguidores por conta
GET /v1/social/analytics/daily?from=2026-10-01&to=2026-10-21  # dia a dia
GET /v1/social/analytics/accounts?from=2026-09-01             # histórico de seguidores e crescimento por conta
GET /v1/social/analytics/insights?platform=instagram          # melhores slots de dia e hora (UTC), frequência vs engajamento, declínio

source é all, orshot ou external (postagens sincronizadas da plataforma, para que o histórico exista desde o dia um). refresh=1 ignora o cache. Limite: 10 requisições de análise por minuto. Insights precisam de histórico de postagens, então uma conta nova retorna slots vazios.

Padrões comuns

Padrão 1: calendário semanal de conteúdo como rascunhos

Renderize sete postagens a partir de um template com diferentes modifications, crie cada uma com status: "draft", liste-as para o usuário com orshot_list_social_posts, publique ou agende as aprovadas. Uma atualização por mudança de legenda ou horário.

Padrão 2: agendar no melhor horário para publicar

orshot_get_best_time_to_post para a plataforma, pegue o melhor slot (UTC), converta para o fuso horário do usuário, passe como scheduled_for. Se os slots estiverem vazios, peça ao usuário um horário em vez de inventar um.

Padrão 3: cross-post, todas as plataformas, extras específicos por plataforma

Um array accounts com todos os ids. Coloque o link em platformOptions[<id do linkedin>].firstComment, um title e link para o Pinterest, e tiktokSettings.autoAddMusic para postagens de fotos no TikTok. Mantenha content abaixo do limite mais curto das plataformas que você está segmentando (o X é o mais restrito).

Padrão 4: carrossel a partir de um template de várias páginas

Renderize um template de 5 a 10 páginas com chaves pageN@ e adicione publish. O Orshot envia cada página e publica um carrossel no Instagram, LinkedIn, TikTok (modo foto), Threads e Bluesky. A skill orshot-carousel tem a fórmula de 6 slides.

Padrão 5: aprender com os resultados

Diariamente: orshot_get_social_analytics com source: "orshot", ordene por engajamento, mantenha os estilos de gancho do quartil superior, descarte o quartil inferior, escreva os rascunhos da próxima semana. Registre o que mudou para que o usuário possa ler o histórico.

Padrão 6: recuperar uma falha

partial ou failed com action: "reconnect": informe ao usuário qual conta reconectar no painel (Workspace > Socials > Accounts), mantenha a postagem como rascunho, tente novamente com orshot_publish_social_draft após a confirmação. Qualquer outro error: mostre-o textualmente; não tente novamente cegamente.

Regras de segurança

• Nunca publique sem uma autorização explícita para aquela postagem. "Preparar", "rascunho", "mostre-me" significam status: "draft".
• Repita exatamente as contas (plataforma e nome de usuário), a legenda e o horário antes de enviar.
• Não descarte postagens que o usuário não pediu para descartar.
• Mencione o add-on de $12 por conta uma vez antes de sugerir que o usuário conecte mais contas.
• No REST, mantenha a chave da API no ambiente. Nunca a exiba.

Equívocos comuns

1. Ids de conta são numéricos e por conta. Duas contas do LinkedIn têm dois ids. Publique por id, nunca pelo nome da plataforma.
2. PDF não pode ser postado em lugar nenhum. Renderize png, jpg ou webp (ou mp4 para plataformas de vídeo).
3. TikTok e YouTube aceitam vídeo, não imagens únicas. O TikTok aceita carrosséis de fotos (várias imagens). O Google Business aceita apenas imagens.
4. scheduled_for com menos de 60 segundos de antecedência é rejeitado, e é inválido com draft ou published.
5. Instagram e TikTok publicam de forma assíncrona. processing não é uma falha. Sincronize ou releia a postagem antes de relatar.
6. Uma publicação com falha nunca falha a renderização. Leia publish[] mesmo quando a renderização foi bem-sucedida.
7. URLs de mídia devem ser públicas. URLs de renderização do Orshot são. URLs assinadas ou localhost não são.
8. Legendas com mais de 5000 caracteres são rejeitadas. Os limites das plataformas são menores; o X é o mais curto.
9. As análises são limitadas a 10 requisições por minuto em todos os endpoints de análise.
10. Workspaces do plano gratuito não podem conectar contas. Um 403 em /social/* com uma mensagem de plano é um estado de faturamento, não um bug de autenticação. Aponte para https://orshot.com/pricing.

Referência rápida

openclaw mcp add orshot --url https://mcp.orshot.com/mcp --transport streamable-http --auth oauth && openclaw mcp login orshot

GET    /v1/social/accounts?include_health=true   # orshot_list_social_accounts
POST   /v1/studio/render            # + publish: { accounts, content, status, scheduled_for, timezone, platformOptions, tiktokSettings }   orshot_render_template
POST   /v1/social/publish           # { accounts, content, media_url | media_urls, status, scheduled_for, timezone, platformOptions, tiktokSettings }   orshot_publish_social_post
GET    /v1/social/posts?status=draft             # orshot_list_social_posts
GET    /v1/social/posts/:id                      # orshot_get_social_post
PATCH  /v1/social/posts/:id                      # orshot_update_social_post
POST   /v1/social/posts/:id/publish              # orshot_publish_social_draft
POST   /v1/social/posts/:id/sync
DELETE /v1/social/posts/:id                      # orshot_discard_social_post
GET    /v1/social/analytics                      # orshot_get_social_analytics
GET    /v1/social/analytics/daily?from=&to=      # orshot_get_social_analytics_daily
GET    /v1/social/analytics/accounts?from=       # orshot_get_social_followers
GET    /v1/social/analytics/insights?platform=   # orshot_get_best_time_to_post

Documentação: https://orshot.com/docs/publish/introduction.md, https://orshot.com/docs/api-reference/social-publish.md, https://orshot.com/docs/api-reference/social-posts-list.md. Detalhes de renderização estão na skill orshot.