Redes sociais

API de redes sociais

Publica ou agenda um vídeo no Instagram, Facebook, TikTok e YouTube com uma única chamada. Só Pedra Pro, sem custo em créditos.

Publica um vídeo no Instagram, Facebook, TikTok e YouTube com uma única chamada, já ou à hora que escolheres. Envia o URL público de um MP4 e uma entrada por rede com a legenda e as definições. A Pedra guarda o vídeo, publica-o em cada rede e dá-te o estado de cada publicação.

O que obténs com uma única chamada:

  • Um vídeo, quatro redes: Instagram (como Reel), uma Página do Facebook, TikTok e YouTube, cada uma com a sua legenda e as suas definições.
  • Publica já ou agenda: se omitires scheduledAt, o vídeo sai em cerca de um minuto; caso contrário, escolhe qualquer hora nos próximos 180 dias.
  • Um estado por publicação: lista as tuas publicações para ver o que saiu, o id da publicação na rede e porque é que algo falhou. Cancela uma publicação agendada antes de sair.
  • Funciona a partir do chat: os mesmos endpoints são ferramentas do servidor MCP remoto da Pedra, por isso o ChatGPT e o Claude podem agendar publicações a partir de uma conversa.

Antes de começar

  • Só Pedra Pro. Cada chamada verifica se a conta está no plano Pro. As outras contas recebem 403 pro_required. Uma publicação agendada só é publicada se a conta ainda estiver no Pro à hora marcada; caso contrário, falha com um erro.
  • Liga as contas na app. As contas sociais ligam-se na Pedra em Definições › Redes sociais, onde inicias sessão em cada rede. A API não as consegue ligar. Uma conta por rede por utilizador Pedra.
  • Redes suportadas: Instagram (uma conta profissional, publicado como Reel), uma Página do Facebook, TikTok e YouTube. Por agora, só vídeo.
  • Sem créditos. Publicar é grátis. O limite é de 25 publicações por rede em quaisquer 24 horas (429 daily_limit).

Como funciona

Três chamadas cobrem a maioria das integrações:

  1. Verifica: POST /api/social/accounts diz-te que redes estão ligadas.
  2. Publica: POST /api/social/posts com o URL do vídeo e uma entrada por rede. Recebes uma publicação por rede, com status: "pending".
  3. Acompanha: POST /api/social/posts/list mostra o estado de cada publicação. Quando é "posted", platformPostId tem o id na rede.

O exemplo agenda um vídeo vertical para Instagram, TikTok e YouTube Shorts, amanhã às 10:00, hora de Madrid.

# 1. Check which networks are connected
curl -X POST https://app.pedra.ai/api/social/accounts \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "YOUR_API_KEY" }'

# 2. Schedule the video for tomorrow at 10:00 Madrid time
curl -X POST https://app.pedra.ai/api/social/posts \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "videoUrl": "https://example.com/videos/calle-mayor-12.mp4",
    "scheduledAt": "2026-10-14T10:00:00+02:00",
    "timezone": "Europe/Madrid",
    "coverOffsetMs": 1000,
    "posts": [
      { "network": "instagram", "caption": "3-bed flat with a sunny terrace on Calle Mayor 12. Book a visit, link in bio." },
      { "network": "tiktok", "caption": "3-bed flat with a sunny terrace on Calle Mayor 12. Book a visit, link in bio.", "privacyLevel": "PUBLIC_TO_EVERYONE" },
      { "network": "youtube", "title": "Calle Mayor 12: 3-bed flat with terrace", "caption": "3-bed flat with a sunny terrace on Calle Mayor 12. Book a visit, link in bio." }
    ]
  }'

# 3. Later: check how it went
curl -X POST https://app.pedra.ai/api/social/posts/list \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "YOUR_API_KEY", "limit": 10 }'

Os SDK de Python e Node ainda não têm métodos sociais, por isso os exemplos usam HTTP direto.

Listar contas ligadas

POST/api/social/accounts

Devolve cada rede suportada e se está ligada. account é o nome de utilizador do Instagram ou TikTok, ou o nome da Página do Facebook. O YouTube não partilha o nome do canal, por isso aí é sempre null.

apiKeystringobrigatório
A tua chave API.
curl -X POST https://app.pedra.ai/api/social/accounts \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "YOUR_API_KEY" }'

Resposta

JSON
{
  "accounts": [
    { "network": "instagram", "connected": true, "account": "pedra_ai" },
    { "network": "facebook", "connected": true, "account": "Pedra AI" },
    { "network": "tiktok", "connected": false, "account": null },
    { "network": "youtube", "connected": true, "account": null }
  ]
}

Publicar ou agendar um vídeo

POST/api/social/posts

Publica um vídeo numa ou várias redes, já ou em scheduledAt. A Pedra copia primeiro o vídeo para o seu próprio armazenamento (máx. 1 GB), por isso o teu URL só tem de funcionar durante esta chamada. Um URL de vídeo da Pedra (img.pedra.ai) é usado tal como está. Cada rede pode aparecer uma vez em posts e tem de estar ligada; caso contrário, recebes 400 not_connected.

apiKeystringobrigatório
A tua chave API.
videoUrlstringobrigatório
URL https público de um MP4. A Pedra copia-o para o seu próprio armazenamento (máx. 1 GB). Um URL de vídeo da Pedra (img.pedra.ai) é usado tal como está.
scheduledAtstring
Quando publicar, como data e hora ISO 8601. Omite-o para publicar já (sai em cerca de um minuto). Não pode estar no passado nem a mais de 180 dias.
timezonestring
Fuso horário IANA, p. ex. Europe/Madrid. Só é guardado para mostrar; a hora vem de scheduledAt.
coverOffsetMsinteger
O fotograma de capa no Instagram e TikTok, em milissegundos desde o início do vídeo (de 0 a 600000). É ignorado no Facebook e YouTube.
postsarrayobrigatório
Uma entrada por rede, pelo menos uma. Cada rede no máximo uma vez.

Entrada de posts

Um objeto por rede em posts. network e caption funcionam igual em todas; os outros campos dependem da rede e estão listados abaixo.

networkstringobrigatório
A rede a que esta entrada se refere.
Values: instagram facebook tiktok youtube
captionstring
Texto da publicação. No YouTube é a descrição. Máx. 2.200 caracteres no Instagram e TikTok, 5.000 no YouTube.

Instagram

Publicado como Reel na conta profissional ligada. Só caption, máx. 2.200 caracteres.

Facebook

Publicado na Página do Facebook ligada.

videoTypestring
Publicá-lo como Reel ou como vídeo normal do feed.
Values: REEL FEED
Default: REEL
firstCommentstring
Publicado como primeiro comentário da Página, por exemplo um link. Máx. 8.000 caracteres.

TikTok

privacyLevel é obrigatório e tem de ser um que a conta do criador permita. caption máx. 2.200 caracteres.

privacyLevelstringobrigatório
Quem pode ver o vídeo. Tem de ser um que a conta do criador permita.
Values: PUBLIC_TO_EVERYONE MUTUAL_FOLLOW_FRIENDS FOLLOWER_OF_CREATOR SELF_ONLY
disableCommentboolean
Desativa os comentários.
disableDuetboolean
Desativa o Dueto.
disableStitchboolean
Desativa o Stitch.
brandOrganicToggleboolean
O vídeo promove a tua própria marca.
brandContentToggleboolean
Parceria paga. Não é permitida com SELF_ONLY.
aiGeneratedboolean
A etiqueta de conteúdo gerado por IA do TikTok. Põe false só para imagens reais.
Default: true

YouTube

title é obrigatório. caption passa a ser a descrição do vídeo, máx. 5.000 caracteres. O YouTube mostra os vídeos verticais curtos como Shorts.

titlestringobrigatório
Título do vídeo, máx. 100 caracteres. O título e a legenda não podem conter < nem >.
privacyStatusstring
Visibilidade do vídeo.
Values: public unlisted private
Default: public
categoryIdstring
Número de categoria do YouTube, como string (p. ex. "22").
curl -X POST https://app.pedra.ai/api/social/posts \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "videoUrl": "https://example.com/videos/calle-mayor-12.mp4",
    "scheduledAt": "2026-10-14T10:00:00+02:00",
    "timezone": "Europe/Madrid",
    "coverOffsetMs": 1000,
    "posts": [
      {
        "network": "instagram",
        "caption": "3-bed flat with a sunny terrace on Calle Mayor 12. Book a visit, link in bio."
      },
      {
        "network": "tiktok",
        "caption": "3-bed flat with a sunny terrace on Calle Mayor 12. Book a visit, link in bio.",
        "privacyLevel": "PUBLIC_TO_EVERYONE",
        "brandOrganicToggle": true
      },
      {
        "network": "youtube",
        "title": "Calle Mayor 12: 3-bed flat with terrace",
        "caption": "3-bed flat with a sunny terrace on Calle Mayor 12. Book a visit, link in bio.",
        "privacyStatus": "public",
        "categoryId": "22"
      }
    ]
  }'

Resposta

JSON
{
  "videoId": "cf568771-4d2a-4e8b-9c3f-1a7e5b2d8f60",
  "videoUrl": "https://img.pedra.ai/social-videos/cf568771-4d2a-4e8b-9c3f-1a7e5b2d8f60.mp4",
  "posts": [
    {
      "postId": "KBkxMfAPARdEG4gix",
      "network": "instagram",
      "status": "pending",
      "scheduledAt": "2026-10-14T08:00:00.000Z",
      "postedAt": null,
      "platformPostId": null,
      "videoId": "cf568771-4d2a-4e8b-9c3f-1a7e5b2d8f60",
      "error": null
    },
    {
      "postId": "q3TzR8wYbN5cLm2Hd",
      "network": "tiktok",
      "status": "pending",
      "scheduledAt": "2026-10-14T08:00:00.000Z",
      "postedAt": null,
      "platformPostId": null,
      "videoId": "cf568771-4d2a-4e8b-9c3f-1a7e5b2d8f60",
      "error": null
    },
    {
      "postId": "Xe7pGv2sJk9WfA4Ru",
      "network": "youtube",
      "status": "pending",
      "scheduledAt": "2026-10-14T08:00:00.000Z",
      "postedAt": null,
      "platformPostId": null,
      "videoId": "cf568771-4d2a-4e8b-9c3f-1a7e5b2d8f60",
      "error": null
    }
  ]
}

Listar publicações

POST/api/social/posts/list

Devolve as tuas publicações, ordenadas por scheduledAt, da mais recente para a mais antiga. Filtra por estado, rede e data para ver o que saiu e porque é que algo falhou.

apiKeystringobrigatório
A tua chave API.
statusstring
Só publicações com este estado.
Values: pending processing posted failed cancelled
networkstring
Só publicações nesta rede.
Values: instagram facebook tiktok youtube
fromstring
Só publicações com scheduledAt igual ou posterior a esta hora (ISO 8601).
tostring
Só publicações com scheduledAt igual ou anterior a esta hora (ISO 8601).
limitinteger
Quantas publicações devolver, de 1 a 100.
Default: 50

Estados de uma publicação

  • pending: à espera da sua hora. Só as publicações pendentes podem ser canceladas.
  • processing: a ser publicada neste momento.
  • posted: publicada na rede. postedAt e platformPostId têm valor.
  • failed: não foi publicada. error diz porquê.
  • cancelled: cancelada antes de sair.

Objeto post

Todos os endpoints que devolvem publicações usam esta forma.

postIdstring
O id da Pedra para a publicação.
networkstring
A rede.
Values: instagram facebook tiktok youtube
statusstring
Vê Estados de uma publicação, acima.
Values: pending processing posted failed cancelled
scheduledAtstring
Quando está marcada, em UTC.
postedAtstring | null
Quando saiu, ou null.
platformPostIdstring | null
O id na rede depois de publicada (p. ex. o id do vídeo do YouTube). Nas publicações privadas do TikTok, o publish id.
videoIdstring
O vídeo guardado, comum a todas as publicações da mesma chamada.
errorstring | null
Porque falhou, ou null.
firstCommentErrorstring
Só aparece se o primeiro comentário do Facebook falhou. A publicação saiu na mesma.
curl -X POST https://app.pedra.ai/api/social/posts/list \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "from": "2026-10-01T00:00:00Z",
    "limit": 20
  }'

Resposta

JSON
{
  "posts": [
    {
      "postId": "Xe7pGv2sJk9WfA4Ru",
      "network": "youtube",
      "status": "posted",
      "scheduledAt": "2026-10-14T08:00:00.000Z",
      "postedAt": "2026-10-14T08:00:41.000Z",
      "platformPostId": "k7Qm2LrT0aE",
      "videoId": "cf568771-4d2a-4e8b-9c3f-1a7e5b2d8f60",
      "error": null
    },
    {
      "postId": "q3TzR8wYbN5cLm2Hd",
      "network": "tiktok",
      "status": "failed",
      "scheduledAt": "2026-10-14T08:00:00.000Z",
      "postedAt": null,
      "platformPostId": null,
      "videoId": "cf568771-4d2a-4e8b-9c3f-1a7e5b2d8f60",
      "error": "TikTok rejected the post: the account was disconnected. Reconnect it under Settings > Socials."
    },
    {
      "postId": "Lw4nB8cVe2TyH6sPq",
      "network": "facebook",
      "status": "posted",
      "scheduledAt": "2026-10-10T16:30:00.000Z",
      "postedAt": "2026-10-10T16:30:52.000Z",
      "platformPostId": "1029384756102938",
      "videoId": "8b1d4e2f-7a3c-4f90-b5e6-2c9d0a1f3e47",
      "error": null,
      "firstCommentError": "Facebook didn't accept the comment."
    }
  ]
}

Cancelar uma publicação agendada

POST/api/social/posts/cancel

Cancela uma publicação que ainda não saiu. Só as publicações pending podem ser canceladas; as outras devolvem 409 not_cancellable. A publicação de cada rede é independente, por isso cancelar uma não afeta as outras da mesma chamada.

apiKeystringobrigatório
A tua chave API.
postIdstringobrigatório
O id da publicação (da chamada posts ou list).
curl -X POST https://app.pedra.ai/api/social/posts/cancel \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "YOUR_API_KEY", "postId": "KBkxMfAPARdEG4gix" }'

Resposta

JSON
{
  "post": {
    "postId": "KBkxMfAPARdEG4gix",
    "network": "instagram",
    "status": "cancelled",
    "scheduledAt": "2026-10-14T08:00:00.000Z",
    "postedAt": null,
    "platformPostId": null,
    "videoId": "cf568771-4d2a-4e8b-9c3f-1a7e5b2d8f60",
    "error": null
  }
}

Erros

Os erros chegam como { "error": "...", "code": "..." }. Usa code para decidir o que fazer; error é uma mensagem legível. Vê Erros e limites para o modelo geral.

  • 400: invalid_video_url (não é um URL https público), video_unreachable (a Pedra não o conseguiu descarregar), not_a_video, video_too_large (mais de 1 GB), invalid_network, not_connected (liga-a em Definições › Redes sociais), invalid_post (a mensagem indica a rede e o campo), invalid_scheduled_at (não é ISO 8601, está no passado ou a mais de 180 dias), invalid_cover (coverOffsetMs não são milissegundos inteiros entre 0 e 600000).
  • 401 invalid_api_key: a chave API falta ou está errada.
  • 403 pro_required: a conta não está no Pedra Pro.
  • 404 post_not_found: não há nenhuma publicação com esse postId nesta conta.
  • 409 not_cancellable: a publicação já foi publicada, falhou, está a ser processada ou foi cancelada.
  • 429 daily_limit: essa rede já tem 25 publicações nas últimas 24 horas.

Seguinte

Cria primeiro o vídeo com a API de vídeo (o URL é usado tal como está), ou agenda publicações a partir do ChatGPT ou do Claude com o servidor MCP.