您的浏览器不支持JavaScript,请启用JavaScript以获得最佳体验。
Update a publishing task
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

FieldTypeRequiredDescription
postIdstringYesPublishing task ID
scheduledAtintegerYesUnix epoch in milliseconds
scheduledTzstringYesIANA timezone
titlestringYesPost caption
tiktokobjectConditionalTikTok publishing settings
tiktok.aigcbooleanConditionalWhether to label the content as AI-generated
tiktok.brandContentTogglebooleanConditionalBranded-content toggle
tiktok.brandOrganicTogglebooleanConditionalOrganic branded-content toggle
tiktok.coverTimestampMsintegerConditionalCover frame timestamp in milliseconds
tiktok.disableCommentbooleanConditionalWhether comments are disabled
tiktok.disableDuetbooleanConditionalWhether Duet is disabled
tiktok.disableStitchbooleanConditionalWhether Stitch is disabled
tiktok.privacyLevelstringConditionalTikTok privacy level
tiktokshopobjectConditionalTikTok Shop publishing settings
tiktokshop.coverTimestampMsintegerConditionalCover frame timestamp in milliseconds
tiktokshop.coverUristringConditionalCustom cover URI
tiktokshop.musicInfoobjectConditionalMusic information
tiktokshop.preCheckbooleanConditionalWhether to submit a pre-check before publishing
tiktokshop.productInfoobjectConditionalProduct anchor information
tiktokBusinessobjectNoBusiness video options: interaction restrictions, cover, brand flags, AI label, music and location; no privacy level.
tiktokBusinessPhotoobjectConditionalRequired for Business PHOTO; 1–15 image file IDs and privacyLevel from publishing settings.
businessIdstringNoReplacement original URL for an existing EXTERNAL_URL video task
coverFileIdinteger | stringNoCustom video cover file ID
tiktokshop.preCheckOvertimeintegerConditionalPre-check timeout, 600–3600 seconds
tiktokBusiness.musicSoundInfo.musicSoundIdstringNoCommercial song_clip_id; omit to add no platform music
tiktokBusiness.musicSoundInfo.musicSoundVolumeintegerNoMusic volume 0–100, default 50
tiktokBusiness.musicSoundInfo.videoOriginalSoundVolumeintegerNoOriginal audio volume 0–100, default 50
tiktokBusiness.locationInfoobjectNolocationId and locationName must be paired; locationAddress is display-only
tiktokBusinessPhoto.businessIdsinteger[]Conditional1–15 image file IDs in display order
tiktokBusinessPhoto.privacyLevelstringConditionalRequired for Business photos; use a value from publishing settings
tiktokBusinessPhoto.photoCoverIndexintegerNoZero-based cover index; default 0
tiktokBusinessPhoto.autoAddMusicbooleanNoAuto music; forced false when musicSoundInfo selects a track
tiktokBusinessPhoto.musicSoundInfoobjectNoMusic ID, name and artist; no volume fields for photos
tiktokBusinessPhoto.locationInfoobjectNoLocation 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.

FieldTypeRequiredDescription
codeintegerYesFixed value: 0
messagestringNo—
dataobjectYes—
data.idunionYes—
data.postIdstringYes—
data.platformstringYesAllowed values: TIKTOK_SHOP, TIKTOK, TIKTOK_BUSINESS
data.titlestringYes—
data.videoUrlstring | nullNo—
data.statusstringYes—
timestampintegerNoResponse 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