TikTok

Overview

Publish TikTok videos, photos, and photo carousels programmatically. PostPeer handles TikTok's multi-step upload process, content policies, and OAuth.

Quick Start

1. Connect a TikTok Account

curl https://api.postpeer.dev/v1/connect/tiktok \
  -H "x-access-key: YOUR_API_KEY"

Returns a TikTok OAuth URL. The user authorizes video upload permissions. See Connect Accounts for the full OAuth flow.

2. Publish a Video

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Quick tutorial! #coding #devtips",
    "platforms": [
      { "platform": "tiktok", "accountId": "tt_321" }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://cdn.example.com/video.mp4" }
    ],
    "publishNow": true
  }'

import PostPeer from '@postpeer/node';

const client = new PostPeer();
const { data } = await client.posts.create({
	body: {
		content: 'Quick tutorial! #coding #devtips',
		platforms: [{ platform: 'tiktok', accountId: 'tt_321' }],
		mediaItems: [{ type: 'video', url: 'https://cdn.example.com/video.mp4' }],
		publishNow: true,
	},
});

from postpeer import PostPeer

with PostPeer() as client:
    post = client.posts.create(
        content="Quick tutorial! #coding #devtips",
        platforms=[{"platform": "tiktok", "accountId": "tt_321"}],
        media_items=[
            {"type": "video", "url": "https://cdn.example.com/video.mp4"},
        ],
        publish_now=True,
    )

Response:

{
	"success": true,
	"status": "published",
	"postId": "post_pqr678",
	"platforms": [
		{
			"platform": "tiktok",
			"success": true,
			"platformPostUrl": "https://www.tiktok.com/@user/video/7123456789"
		}
	]
}

3. Publish a Photo Carousel

Pass two or more image items to create a carousel. For photo posts, content becomes the title. Use platformSpecificData.description for the longer description.

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Summer road trip",
    "platforms": [
      {
        "platform": "tiktok",
        "accountId": "tt_321",
        "platformSpecificData": {
          "description": "Five stops worth adding to your next road trip. Save this route for later! #roadtrip #travel",
          "privacyLevel": "PUBLIC_TO_EVERYONE",
          "autoAddMusic": true,
          "photoCoverIndex": 0
        }
      }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/stop-1.jpg" },
      { "type": "image", "url": "https://cdn.example.com/stop-2.jpg" },
      { "type": "image", "url": "https://cdn.example.com/stop-3.jpg" }
    ],
    "publishNow": true
  }'

Photo metadata uses these limits:

Request field	TikTok field	Limit
`content`	`title`	90 characters
`platformSpecificData.description`	`description`	4,000 characters

The description is optional. When omitted, PostPeer also uses content as the description for backward compatibility. TikTok does not support the separate description field for video posts.

Platform-Specific Data

Pass TikTok options in platformSpecificData for the TikTok platform entry:

{
	"platform": "tiktok",
	"accountId": "tt_321",
	"platformSpecificData": {
		"privacyLevel": "PUBLIC_TO_EVERYONE",
		"disableComment": false,
		"disableDuet": false,
		"disableStitch": false,
		"draft": false
	}
}

Pass this object in platformSpecificData when posting to TikTok.

Field	Type	Required	Values and constraints	Description
`privacyLevel`	string	No	`PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY`	Who can see this post. Defaults to "PUBLIC_TO_EVERYONE".
`disableComment`	boolean	No	—	Disable comments on this post. Defaults to false.
`disableDuet`	boolean	No	—	Disable duet for this video. Videos only. Defaults to false.
`disableStitch`	boolean	No	—	Disable stitch for this video. Videos only. Defaults to false.
`brandContentToggle`	boolean	No	—	Mark as branded content (paid partnership). Defaults to false.
`brandOrganicToggle`	boolean	No	—	Mark as organic brand promotion. Defaults to false.
`isAigc`	boolean	No	—	AI-generated content disclosure. Videos only. Defaults to false.
`videoCoverTimestampMs`	number	No	Range: 0–unbounded	Timestamp in milliseconds to use as the video cover frame. Videos only.
`autoAddMusic`	boolean	No	—	Automatically add background music to photo carousels. Photo posts only. Defaults to true.
`photoCoverIndex`	number	No	Range: 0–unbounded	0-indexed position of the cover image in a photo carousel. Photo posts only. Defaults to 0.
`description`	string	No	Length: 0–4000	Separate description for a TikTok photo or carousel post. Max 4,000 characters. When omitted, the post content is also used as the description. Photo posts only.
`draft`	boolean	No	—	When true, sends content to the creator's TikTok inbox as a draft. Defaults to false (publishes immediately via DIRECT_POST).

Creator Info

Before showing a custom TikTok publishing UI, fetch the connected creator's current posting options:

curl "https://api.postpeer.dev/v1/tiktok/creator-info?accountId=tt_321" \
  -H "x-access-key: YOUR_API_KEY"

Use the returned privacyLevelOptions, commentDisabled, duetDisabled, stitchDisabled, and maxVideoPostDurationSec to restrict the form before upload.

Media Requirements

Videos

Specification	TikTok requirement
Container	MP4 recommended; MOV and WebM supported
Video codec	H.264 recommended; H.265, VP8, and VP9 supported
Frame rate	23-60 FPS
Dimensions	Width and height must each be 360-4,096 px
Duration	Creator-specific; maximum API upload length is 10 minutes
File size	4 GB maximum

TikTok requires the video's duration to fit the connected creator's maxVideoPostDurationSec. Fetch Creator Info before publishing. See TikTok's official media transfer guide for current restrictions.

Photos and carousels

Requirement	PostPeer support
Images per post	1-32; two or more images create a carousel
Media type	Images only; TikTok carousels cannot mix images and videos
Aspect ratio	Between 1:2.13 and 2.13:1
Matching slides	Every carousel image must use the same aspect ratio
Delivery format	PostPeer normalizes images to TikTok-compatible JPEG files
Cover image	Set `photoCoverIndex`; indexes start at `0`

Each image URL must be publicly reachable. PostPeer downloads, normalizes, and rehosts the images before TikTok fetches them. See TikTok's official Photo Post API for the underlying title, description, and photo fields.

Cross-Post

Upload one vertical video to TikTok, YouTube Shorts, and Instagram Reels in a single request:

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New tutorial out now!",
    "platforms": [
      { "platform": "tiktok", "accountId": "tt_321" },
      { "platform": "youtube", "accountId": "yt_789", "platformSpecificData": { "title": "New Tutorial", "visibility": "public" } },
      { "platform": "instagram", "accountId": "ig_456" }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://cdn.example.com/vertical.mp4" }
    ],
    "publishNow": true
  }'

On this page