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)
​
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 500 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.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"
  }'

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