Video Requirements for Social Publishing API Workflows

Video publishing succeeds more consistently when media files match platform expectations before a request is sent. Wahdx Connection uses the same POST /api/content/post endpoint for video and photo carousel publishing; the backend determines the media type from the mediaItems file extensions and validates the payload for the selected platform.

Get Started Free View Docs Hub

Endpoint difference: video vs photo carousel

There is no separate video endpoint and no separate photo carousel endpoint for public publishing. Use POST /api/content/post for both. The difference is the request body: video uses exactly one video URL, while photo carousel uses multiple image URLs. The platform field must match the connected account platform.

// Video and photo carousel use the SAME endpoint:
// POST /api/content/post

const videoPayload = {
  "platform": "tiktok",
  "accountId": "CONNECTED_ACCOUNT_ID",
  "content": "Video caption",
  "mediaItems": [
    {
      "url": "https://your-domain.com/video.mp4"
    }
  ]
};

const photoCarouselPayload = {
  "platform": "tiktok",
  "accountId": "CONNECTED_ACCOUNT_ID",
  "photoTitle": "Carousel title",
  "content": "Carousel caption",
  "mediaItems": [
    {
      "url": "https://your-domain.com/photo-1.jpg"
    },
    {
      "url": "https://your-domain.com/photo-2.jpg"
    }
  ]
};

# Video and photo carousel use the SAME endpoint:
# POST /api/content/post

video_payload = {
    'platform': 'tiktok',
    'accountId': 'CONNECTED_ACCOUNT_ID',
    'content': 'Video caption',
    'mediaItems': [
        {
            'url': 'https://your-domain.com/video.mp4'
        }
    ]
}

photo_carousel_payload = {
    'platform': 'tiktok',
    'accountId': 'CONNECTED_ACCOUNT_ID',
    'photoTitle': 'Carousel title',
    'content': 'Carousel caption',
    'mediaItems': [
        {
            'url': 'https://your-domain.com/photo-1.jpg'
        },
        {
            'url': 'https://your-domain.com/photo-2.jpg'
        }
    ]
}

# Video request: exactly one video URL in mediaItems
curl -X POST "https://api.wahdx.com/api/content/post" \
  -H "X-API-Key: $WAHDX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "platform": "tiktok",
  "accountId": "CONNECTED_ACCOUNT_ID",
  "content": "Video caption",
  "mediaItems": [
    {
      "url": "https://your-domain.com/video.mp4"
    }
  ]
}'

# Photo carousel request: multiple image URLs in mediaItems
curl -X POST "https://api.wahdx.com/api/content/post" \
  -H "X-API-Key: $WAHDX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "platform": "tiktok",
  "accountId": "CONNECTED_ACCOUNT_ID",
  "photoTitle": "Carousel title",
  "content": "Carousel caption",
  "mediaItems": [
    {
      "url": "https://your-domain.com/photo-1.jpg"
    },
    {
      "url": "https://your-domain.com/photo-2.jpg"
    }
  ]
}'

Complete video samples for every platform

These examples use the same endpoint and show the required platform field for TikTok, Instagram, Facebook, and Threads. Keep X-API-Key server-side and replace each accountId with the connected account ID returned by your account listing flow.

const API_BASE_URL = 'https://api.wahdx.com';
const API_KEY = process.env.WAHDX_API_KEY;

const headers = {
  'X-API-Key': API_KEY,
  'Content-Type': 'application/json'
};

// TikTok video
await fetch(API_BASE_URL + '/api/content/post', {
  method: 'POST',
  headers,
  body: JSON.stringify(
    {
      "platform": "tiktok",
      "accountId": "TIKTOK_ACCOUNT_ID",
      "content": "TikTok video caption #launch",
      "mediaItems": [
        {
          "url": "https://your-domain.com/video-tiktok.mp4"
        }
      ],
      "tiktokSettings": {
        "privacy_level": "PUBLIC_TO_EVERYONE",
        "allow_comment": true,
        "allow_duet": true,
        "allow_stitch": true,
        "video_cover_timestamp_ms": 3000,
        "video_made_with_ai": false,
        "draft": false
      }
    }
  )
});

// Instagram video / Reel
await fetch(API_BASE_URL + '/api/content/post', {
  method: 'POST',
  headers,
  body: JSON.stringify(
    {
      "platform": "instagram",
      "accountId": "INSTAGRAM_ACCOUNT_ID",
      "content": "Instagram Reel caption #campaign",
      "mediaItems": [
        {
          "url": "https://your-domain.com/video-instagram.mp4"
        }
      ],
      "instagramSettings": {
        "share_to_feed": true
      }
    }
  )
});

// Facebook Page video
await fetch(API_BASE_URL + '/api/content/post', {
  method: 'POST',
  headers,
  body: JSON.stringify(
    {
      "platform": "facebook",
      "accountId": "FACEBOOK_PAGE_ACCOUNT_ID",
      "content": "Facebook Page video description",
      "mediaItems": [
        {
          "url": "https://your-domain.com/video-facebook.mp4"
        }
      ],
      "facebookSettings": {}
    }
  )
});

// Threads video
await fetch(API_BASE_URL + '/api/content/post', {
  method: 'POST',
  headers,
  body: JSON.stringify(
    {
      "platform": "threads",
      "accountId": "THREADS_ACCOUNT_ID",
      "content": "Threads video post text",
      "mediaItems": [
        {
          "url": "https://your-domain.com/video-threads.mp4"
        }
      ],
      "threadsSettings": {
        "who_can_reply": "everyone"
      }
    }
  )
});

import os
import requests

API_BASE_URL = 'https://api.wahdx.com'
API_KEY = os.environ['WAHDX_API_KEY']

headers = {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json',
}

# TikTok video
response = requests.post(
    API_BASE_URL + '/api/content/post',
    headers=headers,
    json={
    'platform': 'tiktok',
    'accountId': 'TIKTOK_ACCOUNT_ID',
    'content': 'TikTok video caption #launch',
    'mediaItems': [
        {
            'url': 'https://your-domain.com/video-tiktok.mp4'
        }
    ],
    'tiktokSettings': {
        'privacy_level': 'PUBLIC_TO_EVERYONE',
        'allow_comment': True,
        'allow_duet': True,
        'allow_stitch': True,
        'video_cover_timestamp_ms': 3000,
        'video_made_with_ai': False,
        'draft': False
    }
},
    timeout=30,
)

# Instagram video / Reel
response = requests.post(
    API_BASE_URL + '/api/content/post',
    headers=headers,
    json={
    'platform': 'instagram',
    'accountId': 'INSTAGRAM_ACCOUNT_ID',
    'content': 'Instagram Reel caption #campaign',
    'mediaItems': [
        {
            'url': 'https://your-domain.com/video-instagram.mp4'
        }
    ],
    'instagramSettings': {
        'share_to_feed': True
    }
},
    timeout=30,
)

# Facebook Page video
response = requests.post(
    API_BASE_URL + '/api/content/post',
    headers=headers,
    json={
    'platform': 'facebook',
    'accountId': 'FACEBOOK_PAGE_ACCOUNT_ID',
    'content': 'Facebook Page video description',
    'mediaItems': [
        {
            'url': 'https://your-domain.com/video-facebook.mp4'
        }
    ],
    'facebookSettings': {}
},
    timeout=30,
)

# Threads video
response = requests.post(
    API_BASE_URL + '/api/content/post',
    headers=headers,
    json={
    'platform': 'threads',
    'accountId': 'THREADS_ACCOUNT_ID',
    'content': 'Threads video post text',
    'mediaItems': [
        {
            'url': 'https://your-domain.com/video-threads.mp4'
        }
    ],
    'threadsSettings': {
        'who_can_reply': 'everyone'
    }
},
    timeout=30,
)

# TikTok video
curl -X POST "https://api.wahdx.com/api/content/post" \
  -H "X-API-Key: $WAHDX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "platform": "tiktok",
  "accountId": "TIKTOK_ACCOUNT_ID",
  "content": "TikTok video caption #launch",
  "mediaItems": [
    {
      "url": "https://your-domain.com/video-tiktok.mp4"
    }
  ],
  "tiktokSettings": {
    "privacy_level": "PUBLIC_TO_EVERYONE",
    "allow_comment": true,
    "allow_duet": true,
    "allow_stitch": true,
    "video_cover_timestamp_ms": 3000,
    "video_made_with_ai": false,
    "draft": false
  }
}'

# Instagram video / Reel
curl -X POST "https://api.wahdx.com/api/content/post" \
  -H "X-API-Key: $WAHDX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "platform": "instagram",
  "accountId": "INSTAGRAM_ACCOUNT_ID",
  "content": "Instagram Reel caption #campaign",
  "mediaItems": [
    {
      "url": "https://your-domain.com/video-instagram.mp4"
    }
  ],
  "instagramSettings": {
    "share_to_feed": true
  }
}'

# Facebook Page video
curl -X POST "https://api.wahdx.com/api/content/post" \
  -H "X-API-Key: $WAHDX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "platform": "facebook",
  "accountId": "FACEBOOK_PAGE_ACCOUNT_ID",
  "content": "Facebook Page video description",
  "mediaItems": [
    {
      "url": "https://your-domain.com/video-facebook.mp4"
    }
  ],
  "facebookSettings": {}
}'

# Threads video
curl -X POST "https://api.wahdx.com/api/content/post" \
  -H "X-API-Key: $WAHDX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "platform": "threads",
  "accountId": "THREADS_ACCOUNT_ID",
  "content": "Threads video post text",
  "mediaItems": [
    {
      "url": "https://your-domain.com/video-threads.mp4"
    }
  ],
  "threadsSettings": {
    "who_can_reply": "everyone"
  }
}'

Preflight checks

Run basic media checks before calling the API to reduce failed publishing attempts.

Confirm the media URL is accessible by the backend.
Confirm file size and duration are within platform limits.
Avoid mixing photos and videos in the same post payload.
Use platform-specific settings only when they apply to the selected platform.

FAQ

Common questions about this API topic.

What video format should I use?

MP4 with H.264 is the safest recommended format for most short-form publishing workflows.

Does video use a different endpoint from photo carousel?

No. Both use POST /api/content/post. Video uses one video URL in mediaItems, while photo carousel uses multiple image URLs.

Can I set a custom video cover frame?

Yes. Use video_cover_timestamp_ms inside tiktokSettings when the platform workflow supports it.

Can one post mix photos and videos?

No. Keep each post payload either video-based or photo-based to avoid media-type conflicts.

Related docs

Continue with another integration topic.

Authenticate Wahdx Connection API Requests

Learn how to authenticate Wahdx Connection API requests with X-API-Key and keep keys secure in backend or server-side environments.

List Connected Social Accounts with the Public API

Use GET /api/content/accounts to list TikTok, Instagram, Threads, and Facebook accounts connected to a Wahdx Connection workspace using an API key.

Photo Carousel Publishing API Guide

Learn how to prepare photo carousel posts, cover images, title fields, and media arrays for Wahdx Connection publishing workflows.

Track Social Post Status with Wahdx Connection API

Check individual or batch post status for social publishing workflows and monitor queued, processing, published, or failed content.