Social-Media-API

Posten oder planen Sie ein Video auf Instagram, Facebook, TikTok und YouTube mit einem einzigen Aufruf. Nur mit Pedra Pro, ohne Credits.

Veröffentlichen Sie ein Video mit einem einzigen Aufruf auf Instagram, Facebook, TikTok und YouTube, sofort oder zu einem festen Zeitpunkt. Senden Sie die öffentliche URL einer MP4-Datei und pro Netzwerk einen Eintrag mit Text und Einstellungen. Pedra speichert das Video, veröffentlicht es in jedem Netzwerk und liefert Ihnen den Status jedes Beitrags.

Was Sie mit einem einzigen Aufruf bekommen:

• Ein Video, vier Netzwerke: Instagram (als Reel), eine Facebook-Seite, TikTok und YouTube, jeweils mit eigenem Text und eigenen Einstellungen.
• Sofort posten oder planen: Ohne scheduledAt geht das Video in etwa einer Minute raus, oder Sie wählen einen Zeitpunkt in den nächsten 180 Tagen.
• Ein Status pro Beitrag: Listen Sie Ihre Beiträge auf und sehen Sie, was veröffentlicht wurde, die ID des Beitrags im Netzwerk und warum etwas fehlgeschlagen ist. Geplante Beiträge können Sie vorher stornieren.
• Funktioniert aus dem Chat: Dieselben Endpunkte sind Tools im Remote-MCP-Server von Pedra, sodass ChatGPT und Claude Beiträge aus einer Unterhaltung heraus planen können.

Bevor Sie beginnen

• Nur mit Pedra Pro. Jeder Aufruf prüft, ob das Konto im Pro-Tarif ist. Andere Konten erhalten 403 pro_required. Ein geplanter Beitrag wird nur veröffentlicht, wenn das Konto zum geplanten Zeitpunkt noch Pro hat; sonst schlägt er mit einem Fehler fehl.
• Verbinden Sie die Konten in der App. Social-Media-Konten werden in Pedra unter Einstellungen › Socials verbunden, wo Sie sich bei jedem Netzwerk anmelden. Über die API geht das nicht. Ein Konto pro Netzwerk und Pedra-Nutzer.
• Unterstützte Netzwerke: Instagram (ein professionelles Konto, als Reel veröffentlicht), eine Facebook-Seite, TikTok und YouTube. Vorerst nur Videos.
• Keine Credits. Das Posten ist kostenlos. Das Limit liegt bei 25 Beiträgen pro Netzwerk in rollierenden 24 Stunden (429 daily_limit).

So funktioniert es

Drei Aufrufe decken die meisten Integrationen ab:

1. Prüfen: POST /api/social/accounts zeigt Ihnen, welche Netzwerke verbunden sind.
2. Posten: POST /api/social/posts mit der Video-URL und einem Eintrag pro Netzwerk. Sie erhalten einen Beitrag pro Netzwerk zurück, mit status: "pending".
3. Nachverfolgen: POST /api/social/posts/list zeigt den Status jedes Beitrags. Sobald er "posted" ist, enthält platformPostId die ID im Netzwerk.

Das Beispiel plant ein Hochformat-Video für Instagram, TikTok und YouTube Shorts, morgen um 10:00 Uhr Madrider Zeit.

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

Die SDKs für Python und Node haben noch keine Social-Methoden, deshalb nutzen die Beispiele direktes HTTP.

Verbundene Konten auflisten

Gibt jedes unterstützte Netzwerk zurück und ob es verbunden ist. account ist der Instagram- oder TikTok-Nutzername bzw. der Name der Facebook-Seite. YouTube gibt den Kanalnamen nicht weiter, dort ist er also immer null.

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

Antwort

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

Ein Video posten oder planen

Veröffentlicht ein Video in einem oder mehreren Netzwerken, sofort oder zu scheduledAt. Pedra kopiert das Video zuerst in den eigenen Speicher (max. 1 GB), Ihre URL muss also nur während dieses Aufrufs funktionieren. Eine Pedra-Video-URL (img.pedra.ai) wird direkt verwendet. Jedes Netzwerk darf einmal in posts vorkommen und muss verbunden sein, sonst erhalten Sie 400 not_connected.

Eintrag in posts

Ein Objekt pro Netzwerk in posts. network und caption funktionieren überall gleich; die übrigen Felder hängen vom Netzwerk ab und stehen unten.

Instagram

Wird als Reel im verbundenen professionellen Konto veröffentlicht. Nur caption, max. 2.200 Zeichen.

Facebook

Wird auf der verbundenen Facebook-Seite veröffentlicht.

TikTok

privacyLevel ist Pflicht und muss eine Option sein, die das Konto des Creators erlaubt. caption max. 2.200 Zeichen.

YouTube

title ist Pflicht. caption wird zur Videobeschreibung, max. 5.000 Zeichen. Kurze Hochformat-Videos zeigt YouTube als 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"
      }
    ]
  }'

Antwort

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

Beiträge auflisten

Gibt Ihre Beiträge zurück, sortiert nach scheduledAt, die neuesten zuerst. Filtern Sie nach Status, Netzwerk und Datum, um zu sehen, was veröffentlicht wurde und warum etwas fehlgeschlagen ist.

Status eines Beitrags

• pending: wartet auf den geplanten Zeitpunkt. Nur wartende Beiträge können storniert werden.
• processing: wird gerade veröffentlicht.
• posted: live im Netzwerk. postedAt und platformPostId sind gesetzt.
• failed: nicht veröffentlicht. error nennt den Grund.
• cancelled: vor der Veröffentlichung storniert.

Post-Objekt

Alle Endpunkte, die Beiträge zurückgeben, nutzen diese Form.

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

Antwort

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

Einen geplanten Beitrag stornieren

Storniert einen Beitrag, der noch nicht veröffentlicht wurde. Nur Beiträge mit pending lassen sich stornieren; alle anderen geben 409 not_cancellable zurück. Jedes Netzwerk hat einen eigenen Beitrag, das Stornieren eines Beitrags lässt die anderen aus demselben Aufruf also unberührt.

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

Antwort

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

Fehler

Fehler kommen als { "error": "...", "code": "..." } zurück. Verzweigen Sie anhand von code; error ist eine lesbare Meldung. Siehe Fehler und Limits für das allgemeine Modell.

• 400: invalid_video_url (keine öffentliche https-URL), video_unreachable (Pedra konnte es nicht herunterladen), not_a_video, video_too_large (über 1 GB), invalid_network, not_connected (verbinden Sie es unter Einstellungen › Socials), invalid_post (die Meldung nennt Netzwerk und Feld), invalid_scheduled_at (kein ISO 8601, in der Vergangenheit oder mehr als 180 Tage voraus), invalid_cover (coverOffsetMs ist keine ganze Zahl an Millisekunden zwischen 0 und 600000).
• 401 invalid_api_key: Der API-Schlüssel fehlt oder ist falsch.
• 403 pro_required: Das Konto hat kein Pedra Pro.
• 404 post_not_found: Kein Beitrag mit dieser postId in diesem Konto.
• 409 not_cancellable: Der Beitrag ist bereits veröffentlicht, fehlgeschlagen, in Bearbeitung oder storniert.
• 429 daily_limit: Für dieses Netzwerk gibt es in den letzten 24 Stunden schon 25 Beiträge.

Weiter

Erstellen Sie das Video zuerst mit der Video-API (die URL wird direkt verwendet), oder planen Sie Beiträge aus ChatGPT oder Claude mit dem MCP-Server.