Skip to main content

​
Overview

Postiz integrates with TikTok’s official API to schedule videos and photo posts with advanced privacy controls and content settings.
TikTok requires at least one attachment: One video OR one picture OR multiple pictures. Cannot be text-only.

​
Authentication

TikTok uses OAuth 2.0 with short-lived tokens (24 hours).
1

Connect TikTok

Click “Connect TikTok” in Integrations
2

Authorize

Grant all requested permissions
3

Auto-Refresh

Tokens automatically refresh every 23 hours
If using HTTP (not HTTPS), Postiz automatically redirects through redirectmeto.com for OAuth compatibility.

​
Required Permissions

  • video.list - List videos
  • user.info.basic - Basic user info
  • video.publish - Publish videos
  • video.upload - Upload videos
  • user.info.profile - Profile information
  • user.info.stats - User statistics

​
Supported Features

​
Content Types

Direct Post:
  • Publish immediately to profile
  • Full privacy controls
  • Duet, comment, stitch settings
  • AI-generated content labeling
Inbox Upload:
  • Sends to TikTok inbox for approval
  • Limited settings
  • Mobile app review required

​
Post Settings

Control who can view your content:
  • PUBLIC_TO_EVERYONE (default)
  • MUTUAL_FOLLOW_FRIENDS
  • SELF_ONLY
{
  duet: boolean,              // Allow duets
  comment: boolean,           // Allow comments
  stitch: boolean,            // Allow stitches
  video_made_with_ai: boolean // AI-generated label
}
These settings only apply to video posts, not photos.
{
  brand_content_toggle: boolean,  // Mark as branded
  brand_organic_toggle: boolean   // Organic brand content
}

{
  title: string,              // Photo post title (90 chars max)
  description: string,        // Main caption
  autoAddMusic: "yes" | "no" // Auto-add music to slideshow
}

​
Posting Methods

​
Direct Post

Publish immediately to your profile:
1

Initialize Post

Request publish endpoint based on content type
2

Submit Content

TikTok pulls media from provided URLs
3

Processing

TikTok processes the media
4

Publication

Post appears on profile when complete

​
Inbox Upload

Send to TikTok inbox for review:
  • Posts sent to your TikTok mobile app inbox
  • Review and approve from mobile device
  • Limited to 5 pending posts maximum
  • Use when direct post isn’t available
If posting method is UPLOAD, content goes to inbox. If DIRECT_POST, it publishes immediately.

​
Media Requirements

​
Video Specifications

  • Format: MP4 (pulled from URL)
  • Resolution: Minimum 720p
  • Duration: Check with /maxVideoLength endpoint
  • Cover: Optional timestamp for thumbnail

​
Photo Specifications

  • Format: JPG/PNG (pulled from URL)
  • Resolution: Maximum 1080p, minimum depends on account
  • Quantity: Multiple photos create slideshow
  • Auto Music: Optional background music
Resolution Requirements:
  • Videos must be at least 720p
  • Photos must not exceed 1080p
  • Error picture_size_check_failed indicates resolution issues

​
Upload Status Tracking

TikTok posts go through several statuses:
  1. PROCESSING_DOWNLOAD: Downloading media
  2. PROCESSING_UPLOAD: Uploading to TikTok
  3. PROCESSING: Processing media
  4. SEND_TO_USER_INBOX: Sent to inbox
  5. PUBLISH_COMPLETE: Successfully published
  6. FAILED: Upload failed
Postiz polls status every 10 seconds until complete.

​
Analytics

​
Account-Level Analytics

  • Followers: Total follower count
  • Following: Following count
  • Total Likes: All-time likes
  • Videos: Total video count
  • Views: Recent video views (aggregated)
  • Recent Likes: Likes on recent videos
  • Recent Comments: Comments on recent videos
  • Recent Shares: Shares of recent videos

​
Video-Level Analytics

  • Views: Total views
  • Likes: Like count
  • Comments: Comment count
  • Shares: Share count

​
Rate Limits

TikTok Posting Limits:
  • Maximum 300 concurrent jobs
  • Daily post limit (varies by account)
  • Maximum 5 pending inbox posts
  • Spam detection applies

​
Error Handling

Common TikTok errors:
ErrorCauseSolution
access_token_invalidToken expiredAutomatic refresh/reconnect
rate_limit_exceededToo many requestsWait and retry
spam_risk_too_many_postsDaily limit reachedWait until tomorrow
spam_risk_too_many_pending_share5 inbox posts pendingApprove pending posts in app
spam_risk_textContent flagged as spamModify text content
spam_risk_user_banned_from_postingAccount bannedCheck TikTok account status
picture_size_check_failedResolution issueVideos: 720p+, Photos: ≤1080p
duration_check_failedVideo duration invalidCheck max duration for account
video_pull_failedCan’t download videoVerify video URL is accessible
Spam detection is aggressive. Vary your content and avoid repetitive posting patterns.

​
Best Practices

Video Format

Vertical 9:16 videos (1080x1920) perform best

Content Timing

Post during peak hours: 6-9 PM local time

Hashtag Strategy

Use trending and niche hashtags (3-5 per post)

Engagement Settings

Enable duets and stitches for maximum reach

​
Troubleshooting

If posts only go to inbox:
  • Check if account is verified
  • Unaudited apps may be restricted to private accounts
  • Try using DIRECT_POST method
  • Contact TikTok for API approval
If content is flagged:
  • Vary your posting content
  • Avoid repetitive text/hashtags
  • Check daily posting limit (5+ may trigger)
  • Review TikTok Community Guidelines
If video download fails:
  • Ensure URL is publicly accessible
  • Check video format is MP4
  • Verify file isn’t corrupted
  • Try re-uploading to hosting
For size check failures:
  • Videos: Must be 720p or higher
  • Photos: Cannot exceed 1080p
  • Check aspect ratio compatibility
  • Resize media before uploading

Build docs developers (and LLMs) love

Get started for freeTalk to us