Skip to main content

​
Endpoint

POST https://api.ugc.inc/post/slideshow

​
Overview

Create and schedule a slideshow post from multiple images to be published on TikTok or Instagram. The images will be combined into a slideshow with optional music.

​
Request Body

​
accountId
string | null
required
Account ID to post from, or null for automatic account selectionAuto-Selection Behavior:
  • Set to null to automatically select an account
  • With strict: true: Selects the least recently posted account
  • With strict: false: Selects the account with the closest available time slot to your requested postTime
  • Can be filtered using tag, user_group, and org_group parameters
​
tag
string
Filter accounts by tag (only used when accountId is null)
​
user_group
string
Filter accounts by user group (only used when accountId is null)
​
org_group
string
Filter accounts by organization group (only used when accountId is null)
​
post_tag
string
Custom tag stored on the created post itself (returned as tag on the Post object). Distinct from tag, which filters account auto-selection.
​
imageUrls
string[]
required
Array of image URLs (must be publicly accessible)Requirements:
  • Minimum: 1 image
  • Maximum: 35 images (platform limit)
  • Formats: JPG, JPEG, PNG
  • Resolution: 1080x1920 recommended (9:16 aspect ratio)
  • File size: Under 5MB per image
  • All URLs must be publicly accessible
​
caption
string
Post caption/descriptionCan include hashtags and emojisLimit: Maximum 4000 characters
​
socialAudioId
string
ID of a social audio record to attach to the post
Music Support:
  • ✅ TikTok: Fully supported
  • ❌ Instagram: Not yet supported
How to use:
  1. First, import the audio using the Upload Social Audio endpoint with a TikTok video or music URL
  2. This returns a social audio record with an id
  3. Use that id as the socialAudioId here
Example workflow:
// Step 1: Import audio from a TikTok video
const audioResponse = await client.media.createSocialAudio({
  url: 'https://www.tiktok.com/@username/video/1234567890'
});

// Step 2: Use the returned ID in your post
const postResponse = await client.posts.createSlideshow({
  accountId: 'acc_123456',
  imageUrls: ['https://example.com/img1.jpg'],
  socialAudioId: audioResponse.data.id
});
​
postTime
string
When to schedule the post (ISO 8601 format)If omitted, the post will be published immediatelyExample: 2024-12-31T12:00:00Z
​
strict
boolean
default:false
Scheduling mode - controls timing behaviorWhen strict: true:
  • Post must be scheduled at the exact requested time
  • If using auto-selection (accountId: null), picks the least recently posted account
  • Will return an error if the account cannot post at the exact time
When strict: false:
  • Post will be scheduled at the nearest available time
  • If using auto-selection (accountId: null), picks the account that can post closest to the requested time
  • Automatically adjusts to the next available slot if requested time is unavailable
​
mustPostBy
string
Latest allowed scheduled time (ISO 8601 format)If the post cannot be scheduled before this deadline, the request will return an error.When using auto-selection (accountId: null), accounts that cannot post before this time are excluded from selection.Example: 2024-12-31T23:59:59Z

​
Response

​
data
Post
The created post object
curl -X POST https://api.ugc.inc/post/slideshow \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_123456",
    "imageUrls": [
      "https://storage.example.com/img1.jpg",
      "https://storage.example.com/img2.jpg",
      "https://storage.example.com/img3.jpg"
    ],
    "caption": "Check out these amazing photos! 📸 #photography",
    "socialAudioId": "audio_xyz789",
    "postTime": "2024-12-31T12:00:00Z"
  }'

import requests

response = requests.post(
    'https://api.ugc.inc/post/slideshow',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'accountId': 'acc_123456',
        'imageUrls': [
            'https://storage.example.com/img1.jpg',
            'https://storage.example.com/img2.jpg',
            'https://storage.example.com/img3.jpg'
        ],
        'caption': 'Check out these amazing photos! 📸 #photography',
        'socialAudioId': 'audio_xyz789',
        'postTime': '2024-12-31T12:00:00Z'
    }
)

data = response.json()

if data['ok']:
    print('Slideshow created:', data['data']['id'])
    print('Status:', data['data']['status'])
    print('Images:', len(data['data']['media_urls']))

const response = await fetch('https://api.ugc.inc/post/slideshow', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    accountId: 'acc_123456',
    imageUrls: [
      'https://storage.example.com/img1.jpg',
      'https://storage.example.com/img2.jpg',
      'https://storage.example.com/img3.jpg'
    ],
    caption: 'Check out these amazing photos! 📸 #photography',
    socialAudioId: 'audio_xyz789',
    postTime: '2024-12-31T12:00:00Z'
  })
});

const data = await response.json();

if (data.ok) {
  console.log('Slideshow created:', data.data.id);
  console.log('Status:', data.data.status);
  console.log('Images:', data.data.media_urls.length);
}

import { UGCClient } from 'ugcinc';

const client = new UGCClient({
  apiKey: 'YOUR_API_KEY'
});

// Standard: Post with specific account
const response = await client.posts.createSlideshow({
  accountId: 'acc_123456',
  imageUrls: [
    'https://storage.example.com/img1.jpg',
    'https://storage.example.com/img2.jpg',
    'https://storage.example.com/img3.jpg'
  ],
  caption: 'Check out these amazing photos! 📸 #photography',
  socialAudioId: 'audio_xyz789',
  postTime: '2024-12-31T12:00:00Z'
});

// Auto-select with strict=true: picks least recently posted account
const autoResponse1 = await client.posts.createSlideshow({
  accountId: null,  // Auto-select
  imageUrls: ['img1.jpg', 'img2.jpg', 'img3.jpg'],
  caption: 'Auto-posted at exact time',
  postTime: '2024-12-31T10:00:00Z',
  strict: true,  // Must post at exactly 10:00 AM
  tag: 'production'  // Only consider accounts with this tag
});

// Auto-select with strict=false: picks account with closest available slot
const autoResponse2 = await client.posts.createSlideshow({
  accountId: null,  // Auto-select
  imageUrls: ['img1.jpg', 'img2.jpg'],
  caption: 'Auto-posted at nearest time',
  postTime: '2024-12-31T14:00:00Z',
  strict: false,  // Posts at nearest available time
  org_group: 'team-a'  // Only consider accounts in this org group
});

if (response.ok) {
  console.log(`Slideshow created with ID: ${response.data.id}`);
  console.log(`Account used: ${response.data.account_id}`);
  console.log(`Scheduled for: ${response.data.scheduled_at}`);
}

{
  "ok": true,
  "code": 200,
  "message": "Slideshow post created successfully",
  "data": {
    "id": "post_def456",
    "account_id": "acc_123456",
    "type": "slideshow",
    "status": "scheduled",
    "social_id": null,
    "caption": "Check out these amazing photos! 📸 #photography",
    "media_urls": [
      "https://storage.example.com/img1.jpg",
      "https://storage.example.com/img2.jpg",
      "https://storage.example.com/img3.jpg"
    ],
    "social_audio_id": "audio_xyz789",
    "scheduled_at": "2024-12-31T12:00:00Z"
  }
}

{
  "ok": false,
  "code": 400,
  "message": "At least one image URL is required"
}