Create Video Post

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"
}

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

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

string

Filter accounts by tag (only used when accountId is null)

string

Filter accounts by user group (only used when accountId is null)

string

Filter accounts by organization group (only used when accountId is null)

string

Custom tag stored on the created post itself (returned as tag on the Post object). Distinct from tag, which filters account auto-selection.

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

string

Post caption/descriptionCan include hashtags and emojisLimit: Maximum 4000 characters

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 }]

ID of a social audio record to attach to the post

Music Support:

✅ TikTok: Fully supported
❌ Instagram: Not yet supported

How to use:

First, import the audio using the Upload Social Audio endpoint with a TikTok video or music URL
This returns a social audio record with an id
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
});

string

When to schedule the post (ISO 8601 format)If omitted, the post will be published immediatelyExample: 2024-12-31T12:00:00Z

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

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

Post

The created post object

Show Post properties

string

Unique post identifier - use this to track the post status

string

ID of the account that will post this

'video'

Post type (always video for this endpoint)

string

Initial status: scheduled or pending

Platform post ID (null until posted)

string | null

Post caption

string | null

Custom tag stored on the post (from post_tag)

CaptionOverlay[] | null

Text overlays to display on the video ({ text, x, y, fontSize } each; positions/size are fractions of the video dimensions)

string[]

Array containing the video URL

ID of the attached social audio record

string | null

When the post is scheduled to be published (ISO 8601 format)

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"
}

Getting Started

Data Structures

Posts

Comments

Accounts

Statistics

Tasks

Organization

Media

Billing

Automations

Endpoint

Overview

Request Body

Response

​Endpoint

​Overview

​Request Body

​Response

Endpoint

Overview

Request Body

Response