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
​
musicPostId
string
ID of a post that uses the song you want to attach
Music Support:
  • ✅ TikTok: Fully supported
  • ❌ Instagram: Not yet supported
How to use: To add music to your video, provide the ID of any post that already uses the song you want. For example, if you want to use the song from this TikTok: https://www.tiktok.com/music/The-Fate-of-Ophelia-7556815852168759313, find a video that uses that song (e.g., https://www.tiktok.com/@taylorswift/video/7559313483398008095) and provide its ID: 7559313483398008095 as the musicPostId.
​
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

​
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",
    "musicPostId": "music_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"
    ],
    "music_post_id": "music_xyz789",
    "scheduled_at": "2024-12-31T12:00:00Z"
  }
}