Post to TikTok API: Post Videos and Photo Carousels Step by Step
Post videos and photo carousels to TikTok through the API, selecting draft mode or direct publishing according to audit status and privacy levels. The steps below keep the exact request contract for linking an account, sending media, configuring TikTok-specific options, and scheduling, including the TikTok Content Posting API audit constraint that determines whether direct publishing is available.
What you need and how to get an API key
Prepare an API access key, a TikTok account under your control, and a publicly reachable URL for each video or image. All requests carry the x-access-key header, as shown in the example titled Connect TikTok account. Handle the key as a secret and keep it out of source control. When authentication fails, confirm the header name matches x-access-key exactly and that you replaced the placeholder with an actual key.
Connect your TikTok account and retrieve accountId
Send GET {{API_BASE_URL}}/v1/connect/tiktok with the x-access-key header to receive an authorization URL, open that URL in a browser, and authorize the app. Next send GET {{API_BASE_URL}}/v1/connect/integrations with the same header. Each connected account returns an id; pass that value as accountId when posting. If the expected account is missing, redo authorization and check you approved the correct TikTok account before trying again.
Post a video in draft mode
For a first post, place draft set to true inside platformSpecificData and publishNow set to true at the top level. The clip is delivered to the creator's TikTok inbox and finishes with status SEND_TO_USER_INBOX. The creator then opens the TikTok app, locates the draft in the inbox, and publishes it from there. Follow the worked example titled Post a video in draft mode, and check the media URL is reachable before sending.
Set TikTok-specific options and privacy levels
TikTok-specific settings belong in platformSpecificData. privacyLevel accepts PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, or SELF_ONLY, and unaudited apps must use SELF_ONLY for direct posts. disableComment, disableDuet, and disableStitch are booleans defaulting to false, so interactions remain allowed unless changed. brandOrganicToggle flags promotion of your own business, brandContentToggle flags a paid partnership with another brand, and isAigc flags AI-generated content disclosure. videoCoverTimestampMs chooses the cover frame in milliseconds, defaulting to 1000ms. The complete field map appears in the table titled TikTok platformSpecificData field map.
Publish directly after audit
Once the app passes the TikTok Content Posting API audit, set draft to false and the post goes live immediately. Upload polling continues until the status reaches PUBLISH_COMPLETE, and the response returns the public TikTok video URL. Use the worked example titled Publish directly without draft mode. Before passing the audit, avoid direct publishing with a public privacyLevel; instead use draft mode or SELF_ONLY as described in the decision table.
Post a photo carousel
Photo carousels present several images as one swipeable post. Supply image mediaItems in place of a video, and set autoAddMusic and photoCoverIndex inside platformSpecificData. Music is added automatically unless you set autoAddMusic to false. Use the worked example titled Post a photo carousel, and verify every image URL loads before posting.
Schedule a TikTok post with scheduledFor
To schedule, omit publishNow and instead provide scheduledFor and timezone. The post is queued and delivered at the chosen time. The example sets scheduledFor to 2026-05-01T14:00:00 and timezone to America/New_York. Use the worked example titled Schedule a TikTok post, and check the timezone carefully because it determines the actual send time.
Cross-post a vertical video to TikTok, Reels, and Shorts
A single POST {{API_BASE_URL}}/v1/posts request can reach multiple platforms by adding one entry per platform in the platforms array. Each entry has its own platform, accountId, and platformSpecificData, while mediaItems are shared. The worked example titled Cross-post a vertical video to TikTok, Reels, and Shorts includes TikTok, YouTube, and Instagram entries. Check each accountId points to the intended account before sending, since one request attempts delivery to every listed platform.
Failure checks and choosing draft vs direct
Pick draft mode when the app has not passed the TikTok Content Posting API audit, and pick direct publishing only after the audit. Review the failure and decision matrix before sending: unaudited apps must use SELF_ONLY, brandContentToggle forces the post public, SEND_TO_USER_INBOX means the draft is waiting in the inbox, and PUBLISH_COMPLETE means the direct post finished. If a post does not reach the expected status, check accountId, media URL, privacyLevel, and draft value in that order.
| Field | Type | Required | Description |
|---|---|---|---|
| privacyLevel | string enum | No | PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, or SELF_ONLY. Unaudited apps must use SELF_ONLY. |
| draft | boolean | No | true for inbox draft upload, false for direct publish. |
| disableComment | boolean | No | Defaults to false; interactions allowed. |
| disableDuet | boolean | No | Defaults to false; interactions allowed. |
| disableStitch | boolean | No | Defaults to false; interactions allowed. |
| brandOrganicToggle | boolean | No | true if the post promotes you or your business; labeled promotional content. |
| brandContentToggle | boolean | No | true for paid partnerships with another brand; labeled paid partnership and forces the post public. |
| isAigc | boolean | No | AI-generated content disclosure. |
| videoCoverTimestampMs | number | No | Cover frame in milliseconds; defaults to 1000ms. |
| autoAddMusic | boolean | No | Photo carousels only; set false to disable automatic background music. |
| photoCoverIndex | number | No | Photo carousels only; index of the cover image. |
Field names, enums, and defaults preserved from the captured source contract.
| Situation | Mode | privacyLevel | Expected status |
|---|---|---|---|
| App has not passed Content Posting audit | draft mode with draft: true | Not specified for draft example | SEND_TO_USER_INBOX |
| App has passed Content Posting audit | Direct publish with draft: false | PUBLIC_TO_EVERYONE in example | PUBLISH_COMPLETE |
| Unaudited app, direct post | Direct publish | SELF_ONLY required | Not specified |
| brandContentToggle: true | Direct publish | Forced public; SELF_ONLY not usable per source | Not specified |
Decision criteria preserved from the captured source; audit criteria themselves were not supplied.
| Check | What to verify | Failure signal |
|---|---|---|
| Authentication | x-access-key header present and correct | Request rejected before posting |
| Account | accountId from GET /v1/connect/integrations matches the intended TikTok account | Post targets the wrong account or fails |
| Media | mediaItems URL is reachable and matches video or image type | Upload cannot fetch media |
| Privacy | privacyLevel matches audit status; unaudited apps use SELF_ONLY | Direct public post not permitted |
| Mode outcome | SEND_TO_USER_INBOX for draft, PUBLISH_COMPLETE for direct | Post not in expected state |
Status strings preserved from the captured source; full error schemas were not supplied.
Frequently asked questions
How do I post to TikTok without passing the Content Posting audit?
Set draft to true. The clip goes to the creator's TikTok inbox, where the creator can finish and publish it inside the TikTok app. That inbox route does not depend on passing the TikTok Content Posting API audit.
When can I publish directly instead of using draft mode?
Set draft to false and pick a privacyLevel. Direct publishing becomes available once the app passes the TikTok Content Posting API audit, and the finished status is PUBLISH_COMPLETE.
How do photo carousels differ from video posts?
Supply image mediaItems rather than a video, and set autoAddMusic and photoCoverIndex inside platformSpecificData. Use autoAddMusic set to false when you want to turn off automatic background music.
How does scheduling work in the request?
Swap publishNow for scheduledFor plus timezone. The sample pairs a scheduledFor timestamp with a timezone such as America/New_York.
Can one request cross-post to TikTok, YouTube, and Instagram?
Add a separate entry for each platform in the platforms array, giving each entry its own platform, accountId, and platformSpecificData when needed, while mediaItems stay shared across entries.
curl {{API_BASE_URL}}/v1/connect/tiktok \
-H "x-access-key: YOUR_API_KEY"curl {{API_BASE_URL}}/v1/connect/integrations \
-H "x-access-key: YOUR_API_KEY"curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{
"platform": "tiktok",
"accountId": "your-account-id",
"platformSpecificData": {
"draft": true
}
}
],
"mediaItems": [
{ "type": "video", "url": "https://your-cdn.com/clip.mp4" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{
"platform": "tiktok",
"accountId": "your-account-id",
"platformSpecificData": {
"privacyLevel": "PUBLIC_TO_EVERYONE",
"disableComment": false,
"disableDuet": false,
"disableStitch": false,
"brandContentToggle": false,
"brandOrganicToggle": false,
"isAigc": false,
"videoCoverTimestampMs": 2000,
"draft": false
}
}
],
"mediaItems": [
{ "type": "video", "url": "https://your-cdn.com/clip.mp4" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{
"platform": "tiktok",
"accountId": "your-account-id",
"platformSpecificData": {
"privacyLevel": "PUBLIC_TO_EVERYONE",
"draft": false
}
}
],
"mediaItems": [
{ "type": "video", "url": "https://your-cdn.com/launch.mp4" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{
"platform": "tiktok",
"accountId": "your-account-id",
"platformSpecificData": {
"privacyLevel": "PUBLIC_TO_EVERYONE",
"autoAddMusic": true,
"photoCoverIndex": 0,
"draft": false
}
}
],
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/slide-1.jpg" },
{ "type": "image", "url": "https://your-cdn.com/slide-2.jpg" },
{ "type": "image", "url": "https://your-cdn.com/slide-3.jpg" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{
"platform": "tiktok",
"accountId": "your-account-id",
"platformSpecificData": { "privacyLevel": "PUBLIC_TO_EVERYONE", "draft": false }
}
],
"mediaItems": [
{ "type": "video", "url": "https://your-cdn.com/tutorial.mp4" }
],
"scheduledFor": "2026-05-01T14:00:00",
"timezone": "America/New_York"
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{
"platform": "tiktok",
"accountId": "acc_tt_123",
"platformSpecificData": { "privacyLevel": "PUBLIC_TO_EVERYONE", "draft": false }
},
{
"platform": "youtube",
"accountId": "acc_yt_456",
"platformSpecificData": { "title": "New Tutorial", "visibility": "public" }
},
{
"platform": "instagram",
"accountId": "acc_ig_789"
}
],
"mediaItems": [
{ "type": "video", "url": "https://your-cdn.com/vertical.mp4" }
],
"publishNow": true
}'