Developer docs / Publishing tasks
Update a publishing task
Update the caption, schedule, TikTok publishing settings, and TikTok Shop product, music, and cover settings of an editable task.
POST
/v1/creator/post/update- 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 |
|---|---|---|---|
postId | string | Yes | Publishing task ID |
scheduledAt | integer | Yes | Unix epoch in milliseconds |
scheduledTz | string | Yes | IANA timezone |
title | string | Yes | Post caption |
tiktok | object | Conditional | TikTok publishing settings |
tiktok.aigc | boolean | Conditional | Whether to label the content as AI-generated |
tiktok.brandContentToggle | boolean | Conditional | Branded-content toggle |
tiktok.brandOrganicToggle | boolean | Conditional | Organic branded-content toggle |
tiktok.coverTimestampMs | integer | Conditional | Cover frame timestamp in milliseconds |
tiktok.disableComment | boolean | Conditional | Whether comments are disabled |
tiktok.disableDuet | boolean | Conditional | Whether Duet is disabled |
tiktok.disableStitch | boolean | Conditional | Whether Stitch is disabled |
tiktok.privacyLevel | string | Conditional | TikTok privacy level |
tiktokshop | object | Conditional | TikTok Shop publishing settings |
tiktokshop.coverTimestampMs | integer | Conditional | Cover frame timestamp in milliseconds |
tiktokshop.coverUri | string | Conditional | Custom cover URI |
tiktokshop.musicInfo | object | Conditional | Music information |
tiktokshop.preCheck | boolean | Conditional | Whether to submit a pre-check before publishing |
tiktokshop.productInfo | object | Conditional | Product anchor information |
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. |
businessId | string | No | Replacement original URL for an existing EXTERNAL_URL video task |
coverFileId | integer | string | No | Custom video cover file ID |
tiktokshop.preCheckOvertime | integer | Conditional | Pre-check timeout, 600–3600 seconds |
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 |
Only publishing tasks that are still editable can be updated.
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.
Only cancelled or failed tasks can be updated. businessType is immutable. Existing EXTERNAL_URL video tasks can replace businessId with a new URL; remote MP4 validation runs only when the trimmed URL SHA-256 changes.
Request body
{
"postId": "post_xxx",
"scheduledAt": 1787752245233,
"scheduledTz": "America/New_York",
"title": "Updated commerce video caption",
"tiktok": {
"aigc": false,
"brandContentToggle": false,
"brandOrganicToggle": false,
"coverTimestampMs": 1500,
"disableComment": false,
"disableDuet": false,
"disableStitch": false,
"privacyLevel": "PUBLIC_TO_EVERYONE"
},
"tiktokshop": {
"coverTimestampMs": 1500,
"coverUri": "tos-useast5-i-photomode-tx/example-cover-uri",
"musicInfo": {
"author": "Ivan",
"id": "7567668059796720391",
"title": "original sound"
},
"preCheck": false,
"productInfo": {
"productId": "1729452608393351351",
"source": "SHOWCASE",
"title": "Womens midlength Tshirt"
}
}
}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"
}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