API Social

Pubblica o programma un video su Instagram, Facebook, TikTok e YouTube con una sola chiamata. Solo Pedra Pro, nessun credito addebitato.

Pubblica un video su Instagram, Facebook, TikTok e YouTube con una sola chiamata, subito o all'orario che scegli. Invia l'URL pubblico di un MP4 e una voce per ogni rete con la sua didascalia e le sue impostazioni. Pedra salva il video, lo pubblica su ogni rete e ti dà lo stato di ogni post.

Cosa ottieni con una sola chiamata:

• Un video, quattro reti: Instagram (come Reel), una Pagina Facebook, TikTok e YouTube, ognuna con la sua didascalia e le sue impostazioni.
• Pubblica subito o programma: se ometti scheduledAt il video esce in circa un minuto, altrimenti scegli un orario qualsiasi nei prossimi 180 giorni.
• Uno stato per ogni post: elenca i tuoi post per vedere cosa è uscito, l'id del post sulla rete e perché qualcosa non è andato. Annulla un post programmato prima che esca.
• Funziona dalla chat: gli stessi endpoint sono strumenti del server MCP remoto di Pedra, quindi ChatGPT e Claude possono programmare post da una conversazione.

Prima di iniziare

• Solo Pedra Pro. Ogni chiamata verifica che l'account sia sul piano Pro. Gli altri account ricevono 403 pro_required. Un post programmato viene pubblicato solo se all'orario previsto l'account è ancora Pro; altrimenti il post fallisce con un errore.
• Collega gli account nell'app. Gli account social si collegano in Pedra da Impostazioni › Social, dove accedi a ogni rete. L'API non può collegarli. Un account per rete per ogni utente Pedra.
• Reti supportate: Instagram (un account professionale, pubblicato come Reel), una Pagina Facebook, TikTok e YouTube. Per ora solo video.
• Nessun credito. Pubblicare è gratis. Il limite è di 25 post per rete nelle ultime 24 ore (429 daily_limit).

Come funziona

Tre chiamate coprono la maggior parte delle integrazioni:

1. Controlla: POST /api/social/accounts ti dice quali reti sono collegate.
2. Pubblica: POST /api/social/posts con l'URL del video e una voce per rete. Ricevi un post per ogni rete, con status: "pending".
3. Segui: POST /api/social/posts/list mostra lo stato di ogni post. Quando è "posted", platformPostId contiene l'id sulla rete.

L'esempio programma un video verticale su Instagram, TikTok e YouTube Shorts, domani alle 10:00 ora di 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 }'

Gli SDK Python e Node non hanno ancora metodi social, quindi gli esempi usano HTTP diretto.

Elencare gli account collegati

Restituisce ogni rete supportata e se è collegata. account è il nome utente Instagram o TikTok, o il nome della Pagina Facebook. YouTube non condivide il nome del canale, quindi lì è sempre null.

curl -X POST https://app.pedra.ai/api/social/accounts \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "YOUR_API_KEY" }'

Risposta

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

Pubblicare o programmare un video

Pubblica un video su una o più reti, subito o a scheduledAt. Pedra copia prima il video nel proprio spazio di archiviazione (max 1 GB), quindi il tuo URL deve funzionare solo durante questa chiamata. Un URL video di Pedra (img.pedra.ai) viene usato così com'è. Ogni rete può comparire una volta in posts e deve essere collegata, altrimenti ricevi 400 not_connected.

Voce di posts

Un oggetto per rete in posts. network e caption funzionano allo stesso modo ovunque; gli altri campi dipendono dalla rete e sono elencati sotto.

Instagram

Pubblicato come Reel sull'account professionale collegato. Solo caption, max 2.200 caratteri.

Facebook

Pubblicato sulla Pagina Facebook collegata.

TikTok

privacyLevel è obbligatorio e deve essere uno di quelli consentiti dall'account del creator. caption max 2.200 caratteri.

YouTube

title è obbligatorio. caption diventa la descrizione del video, max 5.000 caratteri. YouTube mostra i video verticali brevi come Shorts.

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"
      }
    ]
  }'

Risposta

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

Elencare i post

Restituisce i tuoi post, ordinati per scheduledAt dal più recente. Filtra per stato, rete e data per vedere cosa è uscito e perché qualcosa non è andato.

Stati di un post

• pending: in attesa del suo orario. Solo i post in attesa si possono annullare.
• processing: in pubblicazione in questo momento.
• posted: online sulla rete. postedAt e platformPostId sono valorizzati.
• failed: non pubblicato. error spiega perché.
• cancelled: annullato prima di uscire.

Oggetto post

Tutti gli endpoint che restituiscono post usano questa forma.

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
  }'

Risposta

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

Annullare un post programmato

Annulla un post non ancora uscito. Solo i post pending si possono annullare; gli altri restituiscono 409 not_cancellable. Il post di ogni rete è separato, quindi annullarne uno non tocca gli altri della stessa chiamata.

curl -X POST https://app.pedra.ai/api/social/posts/cancel \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "YOUR_API_KEY", "postId": "KBkxMfAPARdEG4gix" }'

Risposta

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

Errori

Gli errori arrivano come { "error": "...", "code": "..." }. Basa la logica su code; error è un messaggio leggibile. Vedi Errori e limiti per il modello generale.

• 400: invalid_video_url (non è un URL https pubblico), video_unreachable (Pedra non è riuscita a scaricarlo), not_a_video, video_too_large (oltre 1 GB), invalid_network, not_connected (collegala da Impostazioni › Social), invalid_post (il messaggio indica la rete e il campo), invalid_scheduled_at (non ISO 8601, nel passato o oltre 180 giorni), invalid_cover (coverOffsetMs non è un numero intero di millisecondi tra 0 e 600000).
• 401 invalid_api_key: la chiave API manca o è errata.
• 403 pro_required: l'account non è su Pedra Pro.
• 404 post_not_found: nessun post con quel postId su questo account.
• 409 not_cancellable: il post è già pubblicato, fallito, in elaborazione o annullato.
• 429 daily_limit: quella rete ha già 25 post nelle ultime 24 ore.

Successivo

Crea prima il video con l'API Video (il suo URL viene usato così com'è), o programma i post da ChatGPT o Claude con il server MCP.