Skip to main content
Wahdx Logo
DocsSign In
Back to API docs

Photo carousel publishing

Photo Carousel Publishing API Guide

Photo carousel workflows require clear media arrays, platform-aware limits, and title or description fields that match each platform. Wahdx Connection uses the same POST /api/content/post endpoint for video and photo carousel publishing; photo carousel is selected by sending image URLs in mediaItems, not by changing the endpoint.

Get Started FreeView Docs Hub

Endpoint difference: video vs photo carousel

Use POST /api/content/post for both video and photo carousel. The backend determines mediaType from the URL extensions in mediaItems. Send exactly one video URL for video posts. Send multiple image URLs for a carousel. Do not mix video and image URLs in one request.

// 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"
    }
  ]
};

Complete photo carousel samples for every platform

These examples show the same endpoint for TikTok, Instagram, Facebook, and Threads. TikTok supports photoTitle and photo_cover_index. Instagram supports up to 10 carousel media items. Facebook uses multiple photos to create a multi-photo post. Threads uses the same mediaItems pattern for carousel creation.

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 photo carousel
await fetch(API_BASE_URL + '/api/content/post', {
  method: 'POST',
  headers,
  body: JSON.stringify(
    {
      "platform": "tiktok",
      "accountId": "TIKTOK_ACCOUNT_ID",
      "photoTitle": "TikTok carousel title",
      "content": "TikTok carousel description #photo",
      "mediaItems": [
        {
          "url": "https://your-domain.com/tiktok-photo-1.jpg"
        },
        {
          "url": "https://your-domain.com/tiktok-photo-2.jpg"
        },
        {
          "url": "https://your-domain.com/tiktok-photo-3.jpg"
        }
      ],
      "tiktokSettings": {
        "privacy_level": "PUBLIC_TO_EVERYONE",
        "allow_comment": true,
        "auto_add_music": true,
        "photo_cover_index": 0,
        "draft": false
      }
    }
  )
});

// Instagram carousel
await fetch(API_BASE_URL + '/api/content/post', {
  method: 'POST',
  headers,
  body: JSON.stringify(
    {
      "platform": "instagram",
      "accountId": "INSTAGRAM_ACCOUNT_ID",
      "content": "Instagram carousel caption #gallery",
      "mediaItems": [
        {
          "url": "https://your-domain.com/instagram-photo-1.jpg"
        },
        {
          "url": "https://your-domain.com/instagram-photo-2.jpg"
        },
        {
          "url": "https://your-domain.com/instagram-photo-3.jpg"
        }
      ],
      "instagramSettings": {}
    }
  )
});

// Facebook multi-photo post
await fetch(API_BASE_URL + '/api/content/post', {
  method: 'POST',
  headers,
  body: JSON.stringify(
    {
      "platform": "facebook",
      "accountId": "FACEBOOK_PAGE_ACCOUNT_ID",
      "content": "Facebook multi-photo post caption",
      "mediaItems": [
        {
          "url": "https://your-domain.com/facebook-photo-1.jpg"
        },
        {
          "url": "https://your-domain.com/facebook-photo-2.jpg"
        },
        {
          "url": "https://your-domain.com/facebook-photo-3.jpg"
        }
      ],
      "facebookSettings": {}
    }
  )
});

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

Photo requirements checklist

Prepare image assets before submitting the request.

  • Use JPEG, PNG, WebP, or GIF where supported.
  • Use 9:16 vertical images when targeting short-form feeds.
  • Keep file sizes within platform limits.
  • TikTok photo carousel supports up to 35 photos.
  • Instagram carousel supports up to 10 media items.
  • Do not mix image and video media in one payload.

FAQ

Common questions about this API topic.

How do I send multiple photos?

Pass each photo URL as an item inside the mediaItems array in your publishing payload.

Does photo carousel use a different endpoint?

No. Use POST /api/content/post and provide multiple image URLs in mediaItems. The backend detects the photo media type from the file extensions.

Can I choose the cover image?

Yes. Use photo_cover_index where the target platform workflow supports cover selection.

Can a photo carousel include video?

No. Keep carousel payloads photo-only 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.

Video Requirements for Social Publishing API Workflows

Review recommended video formats, size, duration, aspect ratio, and thumbnail settings 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.