Developer docs / Publishing tasks
Get publishing task details
Returns source, schedule and platform-specific publishing options. For EXTERNAL_URL, businessId is the URL SHA-256 and videoUrl holds the original URL. snapshot can be null for older records; PHOTO snapshots preserve all source files in original order.
GET
/v1/creator/post/detail- 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.
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
postId | string | Yes | Publishing task ID |
Returns source, schedule and platform-specific publishing options. For EXTERNAL_URL, businessId is the URL SHA-256 and videoUrl holds the original URL. snapshot can be null for older records; PHOTO snapshots preserve all source files in original order.
Success response
{
"code": 0,
"message": "success",
"data": {
"postId": "2011014932023390208",
"platform": "TIKTOK_BUSINESS",
"businessType": "FILE",
"businessId": "591",
"title": "New collection",
"videoUrl": "https://cdn.example.com/video.mp4",
"snapshot": {
"sourceFiles": [
{
"materialType": "VIDEO",
"name": "video.mp4",
"uploadedAt": "2026-09-29 10:00:00"
}
]
},
"scheduledAt": 1790640000000,
"scheduledTz": "Asia/Shanghai",
"status": "SCHEDULED",
"tiktokBusiness": {
"musicSoundInfo": {
"musicSoundId": "7123456789012345678",
"musicSoundName": "Sunrise",
"musicSoundArtist": "Example artist",
"musicSoundVolume": 50,
"videoOriginalSoundVolume": 50
},
"locationInfo": {
"locationId": "loc-1",
"locationName": "London"
}
}
},
"timestamp": 1790640000000
}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 | — |
message | string | Yes | — |
data | object | Yes | — |
data.postId | string | Yes | — |
data.platform | string | Yes | — |
data.businessType | string | No | Material source, such as FILE or EXTERNAL_URL |
data.businessId | string | No | FILE is the file ID; EXTERNAL_URL is the SHA-256 of the original URL. The original URL is in videoUrl. |
data.title | string | Yes | — |
data.videoUrl | string | Yes | — |
data.snapshot | object | null | No | Original media snapshot saved when the publishing task was created. Null for older records or tasks without files. PHOTO returns every source file. |
data.snapshot.sourceFiles | object[] | No | Source files. VIDEO has one file; PHOTO returns every file in the original order. |
data.snapshot.sourceFiles[].materialType | string | Yes | Source media type: VIDEO or PHOTO |
data.snapshot.sourceFiles[].name | string | Yes | Source file name |
data.snapshot.sourceFiles[].uploadedAt | string | Yes | Source file upload time |
data.scheduledAt | integer | Yes | — |
data.scheduledTz | string | Yes | — |
data.status | string | Yes | — |
data.tiktokShop | union | No | — |
data.tiktok | object | No | — |
data.tiktok.coverTimestampMs | integer | Yes | — |
data.tiktok.privacyLevel | string | Yes | — |
data.tiktok.disableComment | boolean | Yes | — |
data.tiktok.disableDuet | boolean | Yes | — |
data.tiktok.disableStitch | boolean | Yes | — |
data.tiktok.brandContentToggle | boolean | Yes | — |
data.tiktok.brandOrganicToggle | boolean | Yes | — |
data.tiktok.aigc | boolean | Yes | — |
data.tiktokBusiness | object | No | Optional Business video settings without privacyLevel. coverFileId takes precedence over coverTimestampMs, and interactions disabled at account level can only stay disabled. |
data.tiktokBusiness.disableComment | boolean | No | Disable comments. Must be true when comments are disabled at account level |
data.tiktokBusiness.disableDuet | boolean | No | Disable Duet. Must be true when Duet is disabled at account level |
data.tiktokBusiness.disableStitch | boolean | No | Disable Stitch. Must be true when Stitch is disabled at account level |
data.tiktokBusiness.coverTimestampMs | integer | No | Video frame timestamp used as the cover (milliseconds) |
data.tiktokBusiness.brandContentToggle | boolean | No | Brand content (paid partnership) |
data.tiktokBusiness.brandOrganicToggle | boolean | No | Brand organic (promoting your own business) |
data.tiktokBusiness.aigc | boolean | No | AI-generated content |
data.tiktokBusiness.musicSoundInfo | object | No | Use musicSoundId (song_clip_id), never commercialMusicId. Omit it to publish without platform music; title and artist are display snapshots. |
data.tiktokBusiness.musicSoundInfo.musicSoundId | string | No | musicSoundId from the trending music endpoint (the platform song_clip_id); never use commercialMusicId |
data.tiktokBusiness.musicSoundInfo.musicSoundName | string | No | Track title snapshot for display and detail lookups; publishing uses musicSoundId |
data.tiktokBusiness.musicSoundInfo.musicSoundArtist | string | No | Artist snapshot for display and detail lookups |
data.tiktokBusiness.musicSoundInfo.musicSoundVolume | integer | No | Music volume 0-100; defaults to 50 (the platform treats a missing volume as 0, which is muted) |
data.tiktokBusiness.musicSoundInfo.videoOriginalSoundVolume | integer | No | Original video volume 0-100; defaults to 50 |
data.tiktokBusiness.locationInfo | object | No | Submit locationId and locationName together; locationAddress is display-only. |
data.tiktokBusiness.locationInfo.locationId | string | No | locationId from the location search endpoint; publishing maps it to post_info.location_id |
data.tiktokBusiness.locationInfo.locationName | string | No | Location name, submitted together with the ID (post_info.location_name) |
data.tiktokBusiness.locationInfo.locationAddress | string | No | Extra address for display and detail lookups only; never sent to the platform |
data.tiktokBusinessPhoto | object | No | TikTok Business photo options. Required when platform=TIKTOK_BUSINESS and mediaType=PHOTO, and cannot be combined with tiktokShopPhoto. Pass our file IDs; the server resolves them to public image URLs. The privacy level must be one of the values allowed for the account, otherwise the task fails. |
data.tiktokBusinessPhoto.businessIds | integer[] | Yes | Image file IDs in display order, 1–15 images |
data.tiktokBusinessPhoto.photoUrls | string[] | No | Image URLs resolved by the server; do not send them |
data.tiktokBusinessPhoto.photoCoverIndex | integer | No | Cover image index starting at 0; defaults to 0 |
data.tiktokBusinessPhoto.privacyLevel | string | Yes | Privacy level; required and must be one of the values allowed for the account |
data.tiktokBusinessPhoto.autoAddMusic | boolean | No | Ignored when musicSoundInfo.musicSoundId is present; the server always sends false. |
data.tiktokBusinessPhoto.disableComment | boolean | No | Disable comments. Must be true when comments are disabled at account level |
data.tiktokBusinessPhoto.brandOrganicToggle | boolean | No | Brand organic (promoting your own business) |
data.tiktokBusinessPhoto.brandContentToggle | boolean | No | Brand content (paid partnership) |
data.tiktokBusinessPhoto.locationInfo | object | No | Submit locationId and locationName together; locationAddress is display-only. |
data.tiktokBusinessPhoto.locationInfo.locationId | string | No | locationId from the location search endpoint; publishing maps it to post_info.location_id |
data.tiktokBusinessPhoto.locationInfo.locationName | string | No | Location name, submitted together with the ID (post_info.location_name) |
data.tiktokBusinessPhoto.locationInfo.locationAddress | string | No | Extra address for display and detail lookups only; never sent to the platform |
data.tiktokBusinessPhoto.musicSoundInfo | object | No | Selected commercial music, sharing the same structure as non-commerce videos. Omit it (or musicSoundId) to publish without platform music. Photo publishing has no volume options: only musicSoundId is sent to TikTok (post_info.music_sound_info.music_sound_id), and the title and artist are display snapshots. |
data.tiktokBusinessPhoto.musicSoundInfo.musicSoundId | string | No | musicSoundId from the trending music endpoint (the platform song_clip_id). Never use commercialMusicId. Photo publishing maps it to post_info.music_sound_info.music_sound_id |
data.tiktokBusinessPhoto.musicSoundInfo.musicSoundName | string | No | Track title snapshot for display and detail lookups; publishing uses musicSoundId |
data.tiktokBusinessPhoto.musicSoundInfo.musicSoundArtist | string | No | Artist snapshot for display and detail lookups |
timestamp | integer | Yes | — |
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