Skip to main content

​
Endpoint

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

​
Overview

Create and schedule a video post to be published on TikTok or Instagram. The video will be uploaded and posted to the specified account.

​
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.
​
videoUrl
string
required
URL to the video file (must be publicly accessible)Supported formats: MP4, MOV, AVIRecommended specs:
  • Resolution: 1080x1920 (9:16 aspect ratio)
  • Duration: 15-60 seconds
  • File size: Under 100MB
​
caption
string
Post caption/descriptionCan include hashtags and emojisLimit: Maximum 4000 characters
​
captionOverlays
CaptionOverlay[]
Text overlays to display on the videoEach overlay is an object:
  • text (string) — the overlay text
  • x (number) — horizontal center of the overlay as a fraction (0-1) of the video width
  • y (number) — vertical center of the overlay as a fraction (0-1) of the video height
  • fontSize (number) — text size as a fraction (0-1) of the video height
Example: [{ "text": "Wait for it...", "x": 0.5, "y": 0.2, "fontSize": 0.04 }]
​
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.createVideo({
  accountId: 'acc_123456',
  videoUrl: 'https://example.com/video.mp4',
  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/video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_123456",
    "videoUrl": "https://storage.example.com/video.mp4",
    "caption": "My awesome video! 🎥 #viral #content",
    "socialAudioId": "audio_xyz789",
    "postTime": "2024-12-31T12:00:00Z"
  }'

import requests

response = requests.post(
    'https://api.ugc.inc/post/video',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'accountId': 'acc_123456',
        'videoUrl': 'https://storage.example.com/video.mp4',
        'caption': 'My awesome video! 🎥 #viral #content',
        'socialAudioId': 'audio_xyz789',
        'postTime': '2024-12-31T12:00:00Z'
    }
)

data = response.json()

if data['ok']:
    print('Post created:', data['data']['id'])
    print('Status:', data['data']['status'])

const response = await fetch('https://api.ugc.inc/post/video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    accountId: 'acc_123456',
    videoUrl: 'https://storage.example.com/video.mp4',
    caption: 'My awesome video! 🎥 #viral #content',
    socialAudioId: 'audio_xyz789',
    postTime: '2024-12-31T12:00:00Z'
  })
});

const data = await response.json();

if (data.ok) {
  console.log('Post created:', data.data.id);
  console.log('Status:', data.data.status);
}

import { UGCClient } from 'ugcinc';

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

// Standard: Post with specific account
const response = await client.posts.createVideo({
  accountId: 'acc_123456',
  videoUrl: 'https://storage.example.com/video.mp4',
  caption: 'My awesome video! 🎥 #viral #content',
  socialAudioId: 'audio_xyz789',
  postTime: '2024-12-31T12:00:00Z'
});

// Auto-select with strict=true: picks least recently posted account
const autoResponse1 = await client.posts.createVideo({
  accountId: null,  // Auto-select
  videoUrl: 'https://storage.example.com/video.mp4',
  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.createVideo({
  accountId: null,  // Auto-select
  videoUrl: 'https://storage.example.com/video.mp4',
  caption: 'Auto-posted at nearest time',
  postTime: '2024-12-31T14:00:00Z',
  strict: false,  // Posts at nearest available time
  user_group: 'creators'  // Only consider accounts in this user group
});

if (response.ok) {
  console.log(`Post 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": "Video post created successfully",
  "data": {
    "id": "post_abc123",
    "account_id": "acc_123456",
    "type": "video",
    "status": "scheduled",
    "social_id": null,
    "caption": "My awesome video! 🎥 #viral #content",
    "media_urls": [
      "https://storage.example.com/video.mp4"
    ],
    "social_audio_id": "audio_xyz789",
    "scheduled_at": "2024-12-31T12:00:00Z"
  }
}

{
  "ok": false,
  "code": 400,
  "message": "Invalid video URL or format"
}