API Réseaux sociaux

Publiez ou programmez une vidéo sur Instagram, Facebook, TikTok et YouTube en un seul appel. Pedra Pro uniquement, aucun crédit débité.

Publiez une vidéo sur Instagram, Facebook, TikTok et YouTube en un seul appel, tout de suite ou à l'heure de votre choix. Envoyez l'URL publique d'un MP4 et une entrée par réseau avec sa légende et ses réglages. Pedra stocke la vidéo, la publie sur chaque réseau et vous donne le statut de chaque publication.

Ce que vous obtenez en un seul appel :

• Une vidéo, quatre réseaux : Instagram (en Reel), une Page Facebook, TikTok et YouTube, chacun avec sa propre légende et ses réglages.
• Publiez maintenant ou programmez : sans scheduledAt, la vidéo part en une minute environ ; sinon, choisissez n'importe quelle heure dans les 180 prochains jours.
• Un statut par publication : listez vos publications pour voir ce qui est parti, l'id de la publication sur le réseau et pourquoi quelque chose a échoué. Annulez une publication programmée avant son départ.
• Fonctionne depuis le chat : les mêmes endpoints sont des outils du serveur MCP distant de Pedra, donc ChatGPT et Claude peuvent programmer des publications depuis une conversation.

Avant de commencer

• Pedra Pro uniquement. Chaque appel vérifie que le compte est sur le plan Pro. Les autres comptes reçoivent 403 pro_required. Une publication programmée n'est publiée que si le compte est toujours sur Pro à l'heure prévue ; sinon, elle échoue avec une erreur.
• Connectez les comptes dans l'app. Les comptes sociaux se connectent dans Pedra sous Paramètres › Réseaux sociaux, où vous vous identifiez sur chaque réseau. L'API ne peut pas les connecter. Un compte par réseau et par utilisateur Pedra.
• Réseaux pris en charge : Instagram (un compte professionnel, publié en Reel), une Page Facebook, TikTok et YouTube. Vidéo uniquement pour l'instant.
• Aucun crédit. Publier est gratuit. La limite est de 25 publications par réseau sur 24 heures glissantes (429 daily_limit).

Comment ça marche

Trois appels couvrent la plupart des intégrations :

1. Vérifiez : POST /api/social/accounts vous indique quels réseaux sont connectés.
2. Publiez : POST /api/social/posts avec l'URL de la vidéo et une entrée par réseau. Vous recevez une publication par réseau, avec status: "pending".
3. Suivez : POST /api/social/posts/list montre le statut de chaque publication. Une fois "posted", platformPostId contient l'id sur le réseau.

L'exemple programme une vidéo verticale sur Instagram, TikTok et YouTube Shorts, demain à 10 h, heure 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 }'

Les SDK Python et Node n'ont pas encore de méthodes sociales, donc les exemples utilisent du HTTP simple.

Lister les comptes connectés

Renvoie chaque réseau pris en charge et s'il est connecté. account est le nom d'utilisateur Instagram ou TikTok, ou le nom de la Page Facebook. YouTube ne partage pas le nom de la chaîne, donc il vaut toujours null.

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

Réponse

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

Publier ou programmer une vidéo

Publie une vidéo sur un ou plusieurs réseaux, maintenant ou à scheduledAt. Pedra copie d'abord la vidéo dans son propre stockage (max 1 Go), donc votre URL n'a besoin de fonctionner que pendant cet appel. Une URL de vidéo Pedra (img.pedra.ai) est utilisée telle quelle. Chaque réseau peut apparaître une fois dans posts et doit être connecté, sinon vous recevez 400 not_connected.

Entrée de posts

Un objet par réseau dans posts. network et caption fonctionnent partout de la même façon ; les autres champs dépendent du réseau et sont listés ci-dessous.

Instagram

Publié en Reel sur le compte professionnel connecté. Seulement caption, max 2 200 caractères.

Facebook

Publié sur la Page Facebook connectée.

TikTok

privacyLevel est obligatoire et doit être autorisé par le compte du créateur. caption max 2 200 caractères.

YouTube

title est obligatoire. caption devient la description de la vidéo, max 5 000 caractères. YouTube affiche les vidéos verticales courtes en 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"
      }
    ]
  }'

Réponse

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

Lister les publications

Renvoie vos publications, triées par scheduledAt, la plus récente en premier. Filtrez par statut, réseau et date pour voir ce qui est parti et pourquoi quelque chose a échoué.

Statuts d'une publication

• pending : en attente de son heure. Seules les publications en attente peuvent être annulées.
• processing : en cours de publication.
• posted : en ligne sur le réseau. postedAt et platformPostId sont renseignés.
• failed : non publiée. error indique pourquoi.
• cancelled : annulée avant son départ.

Objet post

Tous les endpoints qui renvoient des publications utilisent cette forme.

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

Réponse

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

Annuler une publication programmée

Annule une publication qui n'est pas encore partie. Seules les publications pending peuvent être annulées ; les autres renvoient 409 not_cancellable. Chaque réseau a sa propre publication, donc en annuler une ne touche pas les autres du même appel.

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

Réponse

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

Erreurs

Les erreurs arrivent sous la forme { "error": "...", "code": "..." }. Basez votre logique sur code ; error est un message lisible. Voir Erreurs et limites pour le modèle général.

• 400 : invalid_video_url (pas une URL https publique), video_unreachable (Pedra n'a pas pu la télécharger), not_a_video, video_too_large (plus de 1 Go), invalid_network, not_connected (connectez-le sous Paramètres › Réseaux sociaux), invalid_post (le message indique le réseau et le champ), invalid_scheduled_at (pas en ISO 8601, dans le passé ou à plus de 180 jours), invalid_cover (coverOffsetMs n'est pas un nombre entier de millisecondes entre 0 et 600000).
• 401 invalid_api_key : la clé API est absente ou invalide.
• 403 pro_required : le compte n'est pas sur Pedra Pro.
• 404 post_not_found : aucune publication avec ce postId sur ce compte.
• 409 not_cancellable : la publication est déjà publiée, en échec, en cours ou annulée.
• 429 daily_limit : ce réseau a déjà 25 publications sur les dernières 24 heures.

Suivant

Créez d'abord la vidéo avec l'API Vidéo (son URL est utilisée telle quelle), ou programmez des publications depuis ChatGPT ou Claude avec le serveur MCP.