Carousels, Stories and destinations

Ordered media, supported formats and a different caption or asset list for each account.

Ordered media

media_items is an ordered array. Each item has type: image | video and exactly one source: url or asset_id. The legacy single media: { url, type } remains supported; do not send it together with media_items.

{
  "profile_id": "prf_customer_id",
  "text": "A closer look.",
  "account_ids": ["acc_instagram", "acc_facebook"],
  "format": "feed",
  "media_items": [
    { "type": "image", "asset_id": "ast_front" },
    { "type": "image", "asset_id": "ast_detail" }
  ]
}

Supported formats

• Instagram: one feed image, mixed image/video carousel of 2–10 items, one video Reel, or one image/video Story. Stories require a Business account and no caption.
• Facebook Pages: text/photo feed posts, up to 10 images in a feed post, one video or Reel, or one image/video Story. Stories do not support caption overlays.
• TikTok: one video or 1–35 photos. No mixed photo/video carousel. Creator privacy, interaction, disclosure and explicit publishing-consent rules apply to both formats.
• YouTube: one video. YouTube classifies eligible uploads as Shorts. Carousels and Stories are unavailable.
• Pinterest: one image Pin or one video Pin, with an explicit board and optional section. Trial access supports Sandbox image Pins; video Pins need Standard access.
• LinkedIn: text, a link article with an optional image thumbnail, up to 20 ordered images, or one video. Personal profiles and permitted administered Pages are separate destinations.

Omit format for automatic behavior, or set feed, reel, story or video where supported. Unsupported combinations return a validation error before publication is queued. Media file encoding and platform-specific dimensions/duration can also affect delivery.

Instagram feed/carousel photos fit within 1080 × 1350 pixels, with white padding where needed to meet 4:5–1.91:1 while preserving the full composition. Instagram Stories and TikTok photos keep their original aspect ratio. Prepared JPEG copies remove private metadata.

Customize each destination

Keep account_ids as the selected destination list. Add destinations entries only for accounts that need overrides. Unspecified fields inherit the shared post. Empty text deliberately removes a caption; empty media_items deliberately removes shared media. Array ordering is preserved for each destination.

const { data: post } = await castrook.posts.create({
  text: 'The collection is here.',
  account_ids: [instagramId, facebookId, youtubeId],
  media_items: [{ asset_id: videoAssetId, type: 'video' }],
  destinations: [
    {
      account_id: instagramId,
      text: 'Every detail, up close.',
      format: 'feed',
      media_items: [
        { asset_id: photoOneId, type: 'image' },
        { asset_id: photoTwoId, type: 'image' },
      ],
    },
    { account_id: facebookId, text: '', format: 'story' },
    {
      account_id: youtubeId,
      format: 'video',
      options: {
        title: 'Inside the collection',
        privacy_status: 'private',
        made_for_kids: false,
      },
    },
  ],
}, { idempotencyKey: 'collection-launch-v1' });

Destination options merge over the selected platform’s platform_options. Format precedence is destination format, destination options.format, shared format, then shared platform_options[platform].format. Invalid format options are rejected even when a higher-precedence format overrides them. Reject conflicting duplicate account overrides in your own UI. Reuse the same idempotency key only for an identical complete request, including media order and all overrides.

TikTok photos

Photo posting uses the same video.publish permission as Direct Post videos. A separate photo-posting scope is not required. Your app’s approved products, review coverage and any extra statistics scopes are separate access questions.

{
  "tiktok": {
    "privacy_level": "SELF_ONLY",
    "consent": true,
    "title": "Studio details",
    "photo_cover_index": 0,
    "auto_add_music": false,
    "disable_comment": true,
    "brand_content_toggle": false,
    "brand_organic_toggle": false,
    "is_aigc": false
  }
}

Choose visibility from fresh creator settings; this example is not a default. Show all photos in order, let the creator choose the cover, and show only Allow comments for photo interactions. The creator must approve the exact final photos, caption, account, privacy, disclosures and schedule. See TikTok requirements.