Developer docs / Publishing tasks
Create a publishing task
Creates TikTok Shop, TikTok or TikTok Business publishing tasks. Success means accepted; inspect publishing records for completion.
POST
/v1/creator/post/create- Authentication:
- Request header x-api-key: <YOUR_API_KEY>; keep the key on the server and never expose it in client code, logs or shared files.
- Success criteria:
- HTTP 2xx with code=0; for asynchronous tasks, also query the final status.
Request body fields
| Field | Type | Required | Description |
|---|---|---|---|
businessId | string | Yes | FILE: file ID; EXTERNAL_URL: original HTTPS MP4 URL |
businessType | FILE | EXTERNAL_URL | Yes | Uploaded file or external video URL |
creatorId | string | Yes | creatorId returned by the creator endpoint |
title | string | Yes | Post caption, up to 4,000 characters |
platform | TIKTOK_SHOP | TIKTOK | TIKTOK_BUSINESS | Yes | Publishing platform |
mediaType | VIDEO | PHOTO | No | Optional explicit media type; inferred from the request body when omitted |
scheduledAt | integer | No | Unix epoch in milliseconds |
scheduledTz | string | No | IANA timezone |
oauthRegion | string | No | Creator OAuth authorization region |
coverFileId | integer | string | No | Custom video cover file ID; pass together with tiktokShop.coverUri and omit for photo posts |
tiktokShop | object | Conditional | TikTok Shop video options: products, cover, pre-check, music and AI label |
tiktokShop.preCheck | boolean | No | Whether to submit a pre-check before publishing; defaults to false |
tiktokShop.preCheckOvertime | integer | No | Pre-check timeout in seconds, from 600 to 3600 inclusive. If the official pre-check remains incomplete beyond this time, automatically skip it and continue publishing. |
tiktokShop.isAiGenerated | boolean | No | Whether to label the video as AI-generated; TikTok adds an AI-generated label when true |
tiktokShop.coverUri | string | No | URI returned by the cover upload endpoint; pass coverFileId with it |
tiktokShop.coverTimestampMs | integer | No | Video timestamp in milliseconds to use as the cover frame; omit when coverUri is present |
tiktokShop.musicInfo | object | No | Video background music; omit when no music is needed |
tiktokShop.musicInfo.id | string | Conditional | Music ID, required when musicInfo is provided |
tiktokShop.productInfo.productId | string | Conditional | Required for VIDEO; product ID returned by the product endpoint |
tiktokShop.productInfo.title | string | Conditional | Required for VIDEO; product anchor title, up to 30 characters |
tiktokShop.productInfo.source | SHOP | SHOWCASE | Conditional | Required for VIDEO; SHOP for shop products or SHOWCASE for showcase products |
tiktokShopPhoto | object | Conditional | TikTok Shop photo options |
tiktokShopPhoto.postType | MULTI_PHOTO_ONE_ANCHOR | Conditional | Use MULTI_PHOTO_ONE_ANCHOR for PHOTO |
tiktokShopPhoto.businessIds | string[] | Conditional | Required for PHOTO; 1–15 image fileIds in final display order |
tiktokShopPhoto.productLinks[0].productId | string | Conditional | Required for PHOTO; product ID for the single product anchor |
tiktokShopPhoto.productLinks[0].title | string | Conditional | Required for PHOTO; product anchor title, up to 30 characters |
tiktokShopPhoto.productLinks[0].source | SHOP | SHOWCASE | Conditional | Required for PHOTO; product source |
tiktokShopPhoto.musicInfo | object | No | Photo post background music; omit when no music is needed |
tiktokShopPhoto.musicInfo.id | string | Conditional | Music ID, required when musicInfo is provided |
tiktokBusiness | object | No | Business video options: interaction restrictions, cover, brand flags, AI label, music and location; no privacy level. |
tiktokBusinessPhoto | object | Conditional | Required for Business PHOTO; 1–15 image file IDs and privacyLevel from publishing settings. |
tiktok | object | Conditional | TikTok video publishing settings |
tiktokBusiness.musicSoundInfo.musicSoundId | string | No | Commercial song_clip_id; omit to add no platform music |
tiktokBusiness.musicSoundInfo.musicSoundVolume | integer | No | Music volume 0–100, default 50 |
tiktokBusiness.musicSoundInfo.videoOriginalSoundVolume | integer | No | Original audio volume 0–100, default 50 |
tiktokBusiness.locationInfo | object | No | locationId and locationName must be paired; locationAddress is display-only |
tiktokBusinessPhoto.businessIds | integer[] | Conditional | 1–15 image file IDs in display order |
tiktokBusinessPhoto.privacyLevel | string | Conditional | Required for Business photos; use a value from publishing settings |
tiktokBusinessPhoto.photoCoverIndex | integer | No | Zero-based cover index; default 0 |
tiktokBusinessPhoto.autoAddMusic | boolean | No | Auto music; forced false when musicSoundInfo selects a track |
tiktokBusinessPhoto.musicSoundInfo | object | No | Music ID, name and artist; no volume fields for photos |
tiktokBusinessPhoto.locationInfo | object | No | Location ID and name must be paired |
For a video cover, use tiktokShop.coverTimestampMs for a frame or pass coverFileId together with tiktokShop.coverUri for a custom cover; do not mix the two methods.
TikTok Shop photo posts support 1–15 images and one product; businessId must equal businessIds[0], and the first image is the cover.
Persist postId and status, then verify the final state in publishing records.
Business location ID and name must be provided together. Use musicSoundId (song_clip_id), never commercialMusicId. Video volumes range from 0 to 100 and default to 50. Photos have no volume parameters; selected music overrides autoAddMusic.
For Business video covers, coverFileId overrides coverTimestampMs. Account-disabled interactions cannot be enabled.
EXTERNAL_URL supports only TikTok Shop VIDEO on Pro/Elite or equivalent legacy plans: HTTPS URL at most 256 characters, Content-Type video/mp4, Content-Length strictly below 200 MiB.
Success response
{
"code": 0,
"data": {
"id": 100,
"postId": "post_xxx",
"platform": "TIKTOK_SHOP",
"title": "Summer Sale 2026 #summer",
"videoUrl": "https://cdn.ailingtu.com/media/video.mp4",
"status": "SCHEDULED"
},
"message": "success"
}Request example · TikTok Shop commerce video
{
"businessId": "1465129",
"businessType": "FILE",
"coverFileId": 1465137,
"creatorId": "2077242233106595840",
"title": "Womens midlength Tshirt",
"platform": "TIKTOK_SHOP",
"scheduledAt": 1787752245233,
"scheduledTz": "America/New_York",
"tiktokShop": {
"preCheck": true,
"preCheckOvertime": 1800,
"isAiGenerated": false,
"coverUri": "tos-useast5-i-photomode-tx/owJB0AmAiCIAINiw1WSCmp1ftJzwBqxROEB5w5",
"productInfo": {
"productId": "1729452608393351351",
"title": "Womens midlength Tshirt",
"source": "SHOWCASE"
}
}
}Request example · TikTok Shop commerce photo post
{
"businessId": "591",
"businessType": "FILE",
"creatorId": "2077242233106595840",
"title": "Summer Sale 2026 #summer",
"platform": "TIKTOK_SHOP",
"mediaType": "PHOTO",
"scheduledAt": 1784896665989,
"scheduledTz": "America/New_York",
"oauthRegion": "USA",
"tiktokShopPhoto": {
"postType": "MULTI_PHOTO_ONE_ANCHOR",
"businessIds": [
"591",
"592"
],
"productLinks": [
{
"productId": "1732280564607717841",
"title": "Summer Vibes Cord",
"source": "SHOP"
}
],
"musicInfo": {
"id": "7567668059796720391",
"title": "original sound",
"author": "Ivan",
"duration": "15"
}
}
}Request example · TikTok Business video
{
"creatorId": "2077242233106595840",
"businessType": "FILE",
"businessId": "591",
"title": "New collection",
"platform": "TIKTOK_BUSINESS",
"mediaType": "VIDEO",
"tiktokBusiness": {
"musicSoundInfo": {
"musicSoundId": "7123456789012345678",
"musicSoundVolume": 50,
"videoOriginalSoundVolume": 50
},
"locationInfo": {
"locationId": "loc-1",
"locationName": "London"
}
}
}Request example · TikTok Business photo post
{
"creatorId": "2077242233106595840",
"businessType": "FILE",
"businessId": "591",
"title": "New collection",
"platform": "TIKTOK_BUSINESS",
"mediaType": "PHOTO",
"tiktokBusinessPhoto": {
"businessIds": [
591,
592
],
"privacyLevel": "SELF_ONLY",
"photoCoverIndex": 0
}
}Response and errors
Main response fields come from the published contract; see the JSON Schema. Required refers to the constraint in the containing object.
| Field | Type | Required | Description |
|---|---|---|---|
code | integer | Yes | Fixed value: 0 |
message | string | No | — |
data | object | Yes | — |
data.id | union | Yes | — |
data.postId | string | Yes | — |
data.platform | string | Yes | Allowed values: TIKTOK_SHOP, TIKTOK, TIKTOK_BUSINESS |
data.title | string | Yes | — |
data.videoUrl | string | null | No | — |
data.status | string | Yes | — |
timestamp | integer | No | Response timestamp in milliseconds. |
HTTP 400The request parameters or body are invalid. Fix them and retry.HTTP 401The API key is missing or invalid. Check x-api-key.HTTP 403The API key has no permission to call this endpoint.HTTP 429Too many requests. Retry with exponential backoff.HTTP 500The server failed. Retry transient failures with exponential backoff.
Fix parameter, permission or authorization errors before retrying. If task creation times out, query existing tasks first and do not submit duplicates after an interrupted poll.
Last updated · 2026-11-16