API de redes sociales

Publica o programa un vídeo en Instagram, Facebook, TikTok y YouTube con una sola llamada. Solo Pedra Pro, sin coste en créditos.

Publica un vídeo en Instagram, Facebook, TikTok y YouTube con una sola llamada, ahora o a la hora que elijas. Envía la URL pública de un MP4 y una entrada por red con su texto y sus ajustes. Pedra guarda el vídeo, lo publica en cada red y te da el estado de cada publicación.

Lo que obtienes con una sola llamada:

• Un vídeo, cuatro redes: Instagram (como Reel), una página de Facebook, TikTok y YouTube, cada una con su propio texto y sus ajustes.
• Publica ahora o programa: si omites scheduledAt, el vídeo sale en más o menos un minuto; si no, elige cualquier hora en los próximos 180 días.
• Un estado por publicación: lista tus publicaciones para ver qué ha salido, el id de la publicación en la red y por qué ha fallado algo. Cancela una publicación programada antes de que salga.
• Funciona desde el chat: los mismos endpoints son herramientas del servidor MCP remoto de Pedra, así que ChatGPT y Claude pueden programar publicaciones desde una conversación.

Antes de empezar

• Solo Pedra Pro. Cada llamada comprueba que la cuenta esté en el plan Pro. Las demás cuentas reciben 403 pro_required. Una publicación programada solo se publica si la cuenta sigue en Pro cuando llega la hora; si no, la publicación falla con un error.
• Conecta las cuentas en la app. Las cuentas sociales se conectan en Pedra en Ajustes › Redes sociales, donde inicias sesión en cada red. La API no puede conectarlas. Una cuenta por red por usuario de Pedra.
• Redes compatibles: Instagram (una cuenta profesional, se publica como Reel), una página de Facebook, TikTok y YouTube. De momento, solo vídeo.
• Sin créditos. Publicar es gratis. El límite es de 25 publicaciones por red en cualquier periodo de 24 horas (429 daily_limit).

Cómo funciona

Tres llamadas cubren la mayoría de integraciones:

1. Comprueba: POST /api/social/accounts te dice qué redes están conectadas.
2. Publica: POST /api/social/posts con la URL del vídeo y una entrada por red. Recibes una publicación por red, con status: "pending".
3. Haz seguimiento: POST /api/social/posts/list muestra el estado de cada publicación. Cuando es "posted", platformPostId contiene el id en la red.

El ejemplo programa un vídeo vertical para Instagram, TikTok y YouTube Shorts, mañana a las 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 }'

Los SDK de Python y Node aún no tienen métodos sociales, así que los ejemplos usan HTTP directo.

Listar cuentas conectadas

Devuelve cada red compatible y si está conectada. account es el nombre de usuario de Instagram o TikTok, o el nombre de la página de Facebook. YouTube no comparte el nombre del canal, así que ahí siempre es null.

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

Respuesta

{
  "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 o programar un vídeo

Publica un vídeo en una o varias redes, ahora o en scheduledAt. Pedra copia primero el vídeo a su propio almacenamiento (máx. 1 GB), así que tu URL solo tiene que funcionar durante esta llamada. Una URL de vídeo de Pedra (img.pedra.ai) se usa tal cual. Cada red puede aparecer una vez en posts y tiene que estar conectada; si no, recibes 400 not_connected.

Entrada de posts

Un objeto por red en posts. network y caption funcionan igual en todas; los demás campos dependen de la red y se listan abajo.

Instagram

Se publica como Reel en la cuenta profesional conectada. Solo caption, máx. 2.200 caracteres.

Facebook

Se publica en la página de Facebook conectada.

TikTok

privacyLevel es obligatorio y tiene que ser uno que la cuenta del creador permita. caption máx. 2.200 caracteres.

YouTube

title es obligatorio. caption pasa a ser la descripción del vídeo, máx. 5.000 caracteres. YouTube muestra los vídeos verticales cortos como 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"
      }
    ]
  }'

Respuesta

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

Devuelve tus publicaciones, ordenadas por scheduledAt de la más nueva a la más antigua. Filtra por estado, red y fecha para ver qué ha salido y por qué algo ha fallado.

Estados de una publicación

• pending: esperando su hora. Solo se pueden cancelar las publicaciones pendientes.
• processing: se está publicando en este momento.
• posted: publicada en la red. postedAt y platformPostId tienen valor.
• failed: no se ha publicado. error dice por qué.
• cancelled: cancelada antes de salir.

Objeto post

Todos los endpoints que devuelven publicaciones usan esta 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
  }'

Respuesta

{
  "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 una publicación programada

Cancela una publicación que aún no ha salido. Solo se pueden cancelar las publicaciones pending; cualquier otra devuelve 409 not_cancellable. La publicación de cada red es independiente, así que cancelar una no afecta a las demás de la misma llamada.

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

Respuesta

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

Errores

Los errores llegan como { "error": "...", "code": "..." }. Usa code para decidir qué hacer; error es un mensaje legible. Mira Errores y límites para el modelo general.

• 400: invalid_video_url (no es una URL https pública), video_unreachable (Pedra no ha podido descargarlo), not_a_video, video_too_large (más de 1 GB), invalid_network, not_connected (conéctala en Ajustes › Redes sociales), invalid_post (el mensaje indica la red y el campo), invalid_scheduled_at (no es ISO 8601, está en el pasado o a más de 180 días), invalid_cover (coverOffsetMs no son milisegundos enteros entre 0 y 600000).
• 401 invalid_api_key: falta la clave API o es incorrecta.
• 403 pro_required: la cuenta no está en Pedra Pro.
• 404 post_not_found: no hay ninguna publicación con ese postId en esta cuenta.
• 409 not_cancellable: la publicación ya está publicada, ha fallado, se está procesando o ya se canceló.
• 429 daily_limit: esa red ya tiene 25 publicaciones en las últimas 24 horas.

Siguiente

Crea primero el vídeo con la API de vídeo (su URL se usa tal cual) o programa publicaciones desde ChatGPT o Claude con el servidor MCP.