# Update a publishing task

- API version: 1.11.0
- Last updated: 2026-11-16
- Server: `https://api.ailingtu.com`
- Web document: [Update a publishing task](/en/openapi/update-post)
- Full schema: [JSON Schema](/en/openapi/operations/updateCreatorPost.json)
- Discovery: [Operation index](/en/openapi/operations/index.json)

## POST /v1/creator/post/update

Operation ID: `updateCreatorPost`

Update the caption, schedule, TikTok publishing settings, and TikTok Shop product, music, and cover settings of an editable task.

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 parameters

| Field | Location | Type | Required | Description |
|---|---|---|---|---|
| `postId` | body | string | Yes | Publishing task ID |
| `scheduledAt` | body | integer | Yes | Unix epoch in milliseconds |
| `scheduledTz` | body | string | Yes | IANA timezone |
| `title` | body | string | Yes | Post caption |
| `tiktok` | body | object | Conditional | TikTok publishing settings |
| `tiktok.aigc` | body | boolean | Conditional | Whether to label the content as AI-generated |
| `tiktok.brandContentToggle` | body | boolean | Conditional | Branded-content toggle |
| `tiktok.brandOrganicToggle` | body | boolean | Conditional | Organic branded-content toggle |
| `tiktok.coverTimestampMs` | body | integer | Conditional | Cover frame timestamp in milliseconds |
| `tiktok.disableComment` | body | boolean | Conditional | Whether comments are disabled |
| `tiktok.disableDuet` | body | boolean | Conditional | Whether Duet is disabled |
| `tiktok.disableStitch` | body | boolean | Conditional | Whether Stitch is disabled |
| `tiktok.privacyLevel` | body | string | Conditional | TikTok privacy level |
| `tiktokshop` | body | object | Conditional | TikTok Shop publishing settings |
| `tiktokshop.coverTimestampMs` | body | integer | Conditional | Cover frame timestamp in milliseconds |
| `tiktokshop.coverUri` | body | string | Conditional | Custom cover URI |
| `tiktokshop.musicInfo` | body | object | Conditional | Music information |
| `tiktokshop.preCheck` | body | boolean | Conditional | Whether to submit a pre-check before publishing |
| `tiktokshop.productInfo` | body | object | Conditional | Product anchor information |
| `tiktokBusiness` | body | object | No | Business video options: interaction restrictions, cover, brand flags, AI label, music and location; no privacy level. |
| `tiktokBusinessPhoto` | body | object | Conditional | Required for Business PHOTO; 1–15 image file IDs and privacyLevel from publishing settings. |
| `businessId` | body | string | No | Replacement original URL for an existing EXTERNAL_URL video task |
| `coverFileId` | body | integer \| string | No | Custom video cover file ID |
| `tiktokshop.preCheckOvertime` | body | integer | Conditional | Pre-check timeout, 600–3600 seconds |
| `tiktokBusiness.musicSoundInfo.musicSoundId` | body | string | No | Commercial song_clip_id; omit to add no platform music |
| `tiktokBusiness.musicSoundInfo.musicSoundVolume` | body | integer | No | Music volume 0–100, default 50 |
| `tiktokBusiness.musicSoundInfo.videoOriginalSoundVolume` | body | integer | No | Original audio volume 0–100, default 50 |
| `tiktokBusiness.locationInfo` | body | object | No | locationId and locationName must be paired; locationAddress is display-only |
| `tiktokBusinessPhoto.businessIds` | body | integer[] | Conditional | 1–15 image file IDs in display order |
| `tiktokBusinessPhoto.privacyLevel` | body | string | Conditional | Required for Business photos; use a value from publishing settings |
| `tiktokBusinessPhoto.photoCoverIndex` | body | integer | No | Zero-based cover index; default 0 |
| `tiktokBusinessPhoto.autoAddMusic` | body | boolean | No | Auto music; forced false when musicSoundInfo selects a track |
| `tiktokBusinessPhoto.musicSoundInfo` | body | object | No | Music ID, name and artist; no volume fields for photos |
| `tiktokBusinessPhoto.locationInfo` | body | object | No | Location ID and name must be paired |

Request format: `application/json`

### Request example

```json
{
  "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

```json
{
  "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 fields

Main levels are listed below. The endpoint JSON Schema is authoritative for the full structure, unions and validation rules; Required refers to 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. |

### Integration notes and limits

- 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.

### Error handling

| HTTP | Description |
|---|---|
| 400 | The request parameters or body are invalid. Fix them and retry. |
| 401 | The API key is missing or invalid. Check x-api-key. |
| 403 | The API key has no permission to call this endpoint. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | The server failed. Retry transient failures with exponential backoff. |

Treat any non-zero business code as a failure. Do not blindly retry parameter, permission or authorization errors. If creating a publishing or generation task times out, query the existing task first instead of creating another one.

### Related endpoints

- [Search TikTok Shop music](/en/openapi/search-music) · [Markdown](/en/openapi/operations/searchTikTokShopMusic.md)
- [Cancel a publishing task](/en/openapi/cancel-post) · [Markdown](/en/openapi/operations/cancelCreatorPost.md)
- [List publishing records](/en/openapi/post-records) · [Markdown](/en/openapi/operations/listCreatorPosts.md)
