TikTok Posting API
The TikTok Posting API lets a product, automation, agency workflow, or AI system publish videos and photo carousels through one unified posts endpoint.
POST {{API_BASE_URL}}/v1/posts
{
"content": "A short example update.",
"platforms": [
{
"platform": "tiktok",
"accountId": "tt_321",
"platformSpecificData": {
"privacyLevel": "PUBLIC_TO_EVERYONE",
"disableComment": false,
"disableDuet": false,
"disableStitch": false,
"draft": false
}
}
],
"mediaItems": [
{
"type": "video",
"url": "https://cdn.example.com/video.mp4"
}
],
"publishNow": true
}POST {{API_BASE_URL}}/v1/posts
{
"content": "A short example update.",
You supply the caption, connected account, media, and TikTok-specific settings, and the same request shape can be reused across other supported social platforms. This page documents the exact POST /v1/posts contract for TikTok, including privacy, interaction, cover, branded-content, scheduling, and status handling.
Who this TikTok publishing contract is for and the three-step integration flow
This guide suits developers and product builders adding TikTok output to a SaaS feature, an automation, an agency tool, or an AI-driven system via a single connection. Your job here is to ship video, photo, and photo-carousel publishing against the precise POST /v1/posts shape, covering TikTok-only visibility, interaction, cover, scheduling, and result fields. Link accounts once, then reuse one interface for publishing, scheduling, reading data, comments, and messages, rather than maintaining a bespoke connector per network. The sequence is straightforward: obtain a key, wire up the posts endpoint, and expose every supported network through those linked accounts.
Exact POST /v1/posts contract and Video Post worked example
One endpoint serves every format; you adjust only the fields that format needs. The worked example in the code examples titled Video Post Request and Video Post Response reproduces the captured request and its 202 reply, with the origin swapped for the modular base URL placeholder. Before dispatching, walk this checklist: caption text in content, the linked TikTok accountId, a mediaItems entry carrying type plus url, privacyLevel nested in platformSpecificData, the three interaction switches disableComment, disableDuet, and disableStitch, the draft flag, and publishNow. Avoid adding fields the captured contract does not show. Afterwards, inspect the returned status, the top-level postId, and the TikTok entry's success flag and platformPostUrl. Post webhooks provide a second channel for learning the final outcome.
Field map: shared fields and TikTok platformSpecificData
Top-level fields handle caption, targets, media, and immediate publishing, while TikTok-only choices sit inside platformSpecificData on that target, keeping the outer shape portable across networks. The table titled Field Map: Shared and TikTok platformSpecificData Fields separates the two groups and shows captured example values. Media may arrive by URL or by direct upload, with the staged upload sequence abstracted away. Hashtags ride along in content, and caption length gets checked against TikTok's ceiling, though the numeric ceiling is not given in the captured material. Visibility is driven by privacyLevel, illustrated with PUBLIC_TO_EVERYONE. Comments, Duet, and Stitch are governed by disableComment, disableDuet, and disableStitch respectively; what a creator account actually allows shapes which switches matter, so retrieve creator details ahead of publishing and mirror those options in your interface.
Format decision matrix: video, photo, photo carousel
Pick the format first, then assemble the payload accordingly. Moving-picture posts reference a video item. Still-picture posts reference one or more images, and supplying two or more turns the post into a carousel. The allowed image count runs from 1 to 32, and a carousel must never blend pictures with clips, so check the media list up front. The table titled Format Decision Matrix: Video, Photo, and Photo Carousel condenses these rules. For clips, MP4, MOV, and WebM containers are accepted with MP4 preferred; H.264, H.265, VP8, and VP9 codecs are accepted with H.264 preferred. Size may reach 4 GB and length may reach 10 minutes at the API level, yet an individual creator's own configuration can impose tighter bounds.
Privacy, interaction, branded-content, cover, scheduling, cross-posting, and OAuth
Visibility, interaction, disclosure, and thumbnail choices all live in platformSpecificData. Set privacyLevel for visibility, disableComment for comments, disableDuet for Duet, and disableStitch for Stitch. Set brandContentToggle when material is branded and brandOrganicToggle when promoting your own brand organically, remembering that TikTok's commercial labelling rules still apply to anything you expose. Set videoCoverTimestampMs to choose a clip thumbnail moment, and photoCoverIndex to choose a still-picture thumbnail. In the captured example draft is false alongside immediate publishing; reproduce that field and value when copying the example. Scheduling is handled separately by queueing a TikTok item for a future date and time. A single vertical clip can also go to TikTok, YouTube Shorts, and Instagram Reels together by listing each target. Account linking uses managed OAuth, so you do not need to run your own TikTok developer application for this workflow, and credential upkeep stays behind the integration.
Stacks, other platforms, and status handling
The same interface fits typed SDKs and REST calls in a developer stack, automation tools such as Zapier, Make, and n8n, and agent setups using a hosted MCP server, agent skills, or an OpenAI tool-calling schema. The same linked accounts also reach Twitter / X, Instagram, YouTube, Facebook, Threads, Pinterest, LinkedIn, Bluesky, and Google Business, plus scheduling, analytics, comments, messaging, and comment-to-DM automation. TikTok has dedicated scheduling and analytics extensions beyond basic publishing. For result checking, read status and platformPostUrl on the TikTok entry, and rely on post webhooks for asynchronous outcome updates rather than treating a 202 alone as proof the TikTok item is live.
| Field | Location | Captured example value | Purpose |
|---|---|---|---|
| content | Top level | "Quick tutorial! #coding #devtips" | Caption with hashtags |
| platforms[].platform | Top level | "tiktok" | Platform target |
| platforms[].accountId | Top level | "tt_321" | Connected TikTok account |
| platforms[].platformSpecificData.privacyLevel | TikTok target | "PUBLIC_TO_EVERYONE" | Video visibility |
| platforms[].platformSpecificData.disableComment | TikTok target | false | Disable comments |
| platforms[].platformSpecificData.disableDuet | TikTok target | false | Disable Duet |
| platforms[].platformSpecificData.disableStitch | TikTok target | false | Disable Stitch |
| platforms[].platformSpecificData.draft | TikTok target | false | Draft flag in captured example |
| platforms[].platformSpecificData.brandContentToggle | TikTok target | Named in source FAQ; no captured example value | Branded-content disclosure |
| platforms[].platformSpecificData.brandOrganicToggle | TikTok target | Named in source FAQ; no captured example value | Organic promotion of own brand |
| platforms[].platformSpecificData.videoCoverTimestampMs | TikTok target | Named in source FAQ; no captured example value | Video cover frame by timestamp |
| platforms[].platformSpecificData.photoCoverIndex | TikTok target | Named in source FAQ; no captured example value | Photo cover image index |
| mediaItems[].type | Top level | "video" | Media type |
| mediaItems[].url | Top level | "https://cdn.example.com/video.mp4" | Media URL |
| publishNow | Top level | true | Publish immediately in captured example |
Requiredness and types beyond the captured Video Post example are not fully specified in the source; values below reproduce the captured example only.
| Format | Media rule | Cover field | Notes |
|---|---|---|---|
| Video Post | Video media item; MP4, MOV, or WebM; H.264, H.265, VP8, or VP9; up to 4 GB; up to 10 minutes subject to creator settings | videoCoverTimestampMs | MP4 and H.264 recommended |
| Photo Post | 1 to 32 images; a single image is a photo post | photoCoverIndex | Cannot mix images and videos in a carousel |
| Photo Carousel | Two or more images, up to 32; images only | photoCoverIndex | Two or more images create a carousel |
Photo count and no-mixing rules are from the captured source FAQ; video container, codec, size, and duration limits are source-bounded and creator settings may further limit duration.
Frequently asked questions
What can I publish with the TikTok Posting API?
Three shapes are supported: a video, a single image, and a multi-image carousel. Image-based posts accept anywhere from one through thirty-two pictures; once you supply at least two, the result is treated as a carousel. Mixing still pictures with moving clips inside one carousel is not allowed.
Why use a unified API instead of TikTok's Content Posting API directly?
Going direct means handling sign-in, creator checks, permission handling, media checks, a staged upload sequence, and result tracking yourself. Routing through a shared posts endpoint lets you supply caption text, the linked account, media references, and TikTok-only options, while the staged upload and result handling sit behind that endpoint.
Do I need my own TikTok developer app?
No separate developer application is needed from you for this workflow. Account linking happens through the managed sign-in flow, and credential upkeep is handled behind the integration.
What video formats does TikTok support?
Accepted containers are MP4, MOV, and WebM, with MP4 preferred. Inside those containers, H.264, H.265, VP8, and VP9 are accepted, with H.264 preferred. File size may reach 4 GB. Length is capped at 10 minutes at the API level, yet a given creator may have a shorter allowance in their own account configuration.
Can I enable or disable comments, Duet, and Stitch?
Yes, all three can be switched off individually. They live under platformSpecificData as disableComment, disableDuet, and disableStitch. Whether a switch has any effect depends on what the linked creator account permits, so fetch creator details first and shape the interface around what comes back.
Does the TikTok Posting API support branded-content disclosures?
Yes. Two TikTok-only switches cover this: brandContentToggle marks branded material, while brandOrganicToggle marks organic promotion of your own brand. If you surface either switch, your product must still meet TikTok's rules for commercial-content labelling.
Can I choose the TikTok video cover?
Yes. For moving pictures, videoCoverTimestampMs picks the moment whose frame becomes the thumbnail. For still-picture posts, photoCoverIndex picks which picture in the set becomes the thumbnail.
Can I schedule TikTok posts?
Yes. A separate scheduling capability lets you place a TikTok item in a queue for a later date and time, then manage that queued item through the scheduling workflow.
How do I know whether my TikTok post actually published?
Look at the returned status together with platformPostUrl on the TikTok entry. For later updates, post webhooks can notify your system when the outcome lands as success or failure.
What can I build with the TikTok Posting API?
Typical fits include social management dashboards, SaaS features, agency tooling, repurposing pipelines, and autonomous agents that need to push content to TikTok.
202
{
"success": true,
"status": "published",
"postId": "post_abc123",
"platforms": [
{
"platform": "tiktok",
"success": true,
"platformPostUrl": "https://www.tiktok.com/@user/video/7123456789"
}
]
}