# 编辑发布记录

- API 版本：1.10.0
- 最后更新：2026-09-29
- 服务地址：`https://api.ailingtu.com`
- 网页文档：[编辑发布记录](/openapi/update-post)
- 完整接口约束：[JSON Schema](/openapi/operations/updateCreatorPost.json)
- 接口发现：[接口索引](/openapi/operations/index.json)

## POST /v1/creator/post/update

接口标识：`updateCreatorPost`

编辑可修改发布任务的文案、排期、TikTok 发布设置以及 TikTok Shop 商品、音乐和封面设置。

鉴权：请求头 `x-api-key: <YOUR_API_KEY>`；密钥仅保存在服务端。

成功判断：HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

### 请求参数

| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `postId` | body | string | 是 | 发布任务 ID |
| `scheduledAt` | body | integer | 是 | Unix Epoch 毫秒 |
| `scheduledTz` | body | string | 是 | IANA 时区 |
| `title` | body | string | 是 | 发布文案 |
| `tiktok` | body | object | 条件必填 | TikTok 发布设置 |
| `tiktok.aigc` | body | boolean | 条件必填 | 是否标识为 AI 生成内容 |
| `tiktok.brandContentToggle` | body | boolean | 条件必填 | 品牌内容开关 |
| `tiktok.brandOrganicToggle` | body | boolean | 条件必填 | 品牌自然内容开关 |
| `tiktok.coverTimestampMs` | body | integer | 条件必填 | 封面截帧时间，单位毫秒 |
| `tiktok.disableComment` | body | boolean | 条件必填 | 是否关闭评论 |
| `tiktok.disableDuet` | body | boolean | 条件必填 | 是否关闭合拍 |
| `tiktok.disableStitch` | body | boolean | 条件必填 | 是否关闭拼接 |
| `tiktok.privacyLevel` | body | string | 条件必填 | TikTok 隐私级别 |
| `tiktokshop` | body | object | 条件必填 | TikTok Shop 发布设置 |
| `tiktokshop.coverTimestampMs` | body | integer | 条件必填 | 封面截帧时间，单位毫秒 |
| `tiktokshop.coverUri` | body | string | 条件必填 | 自定义封面 URI |
| `tiktokshop.musicInfo` | body | object | 条件必填 | 音乐信息 |
| `tiktokshop.preCheck` | body | boolean | 条件必填 | 是否在发布前提交预审 |
| `tiktokshop.productInfo` | body | object | 条件必填 | 挂车商品信息 |
| `tiktokBusiness` | body | object | 否 | Business 视频设置：互动限制、封面、品牌、AI 标识、音乐及地域；不传隐私级别。 |
| `tiktokBusinessPhoto` | body | object | 条件必填 | Business 图文必填；1～15 个图片文件 ID，privacyLevel 必须来自发布配置。 |
| `businessId` | body | string | 否 | 仅已有 EXTERNAL_URL 任务可替换原始视频 URL |
| `coverFileId` | body | integer \| string | 否 | 自定义视频封面文件 ID |
| `tiktokshop.preCheckOvertime` | body | integer | 条件必填 | 预审超时，600–3600 秒 |
| `tiktokBusiness.musicSoundInfo.musicSoundId` | body | string | 否 | 商用音乐片段 ID（song_clip_id），不传则不加平台音乐 |
| `tiktokBusiness.musicSoundInfo.musicSoundVolume` | body | integer | 否 | 音乐音量 0–100，默认 50 |
| `tiktokBusiness.musicSoundInfo.videoOriginalSoundVolume` | body | integer | 否 | 原声音量 0–100，默认 50 |
| `tiktokBusiness.locationInfo` | body | object | 否 | locationId、locationName 必须成对；locationAddress 仅展示 |
| `tiktokBusinessPhoto.businessIds` | body | integer[] | 条件必填 | 按图序传 1～15 个图片文件 ID |
| `tiktokBusinessPhoto.privacyLevel` | body | string | 条件必填 | Business 图文必填，取发布配置允许值 |
| `tiktokBusinessPhoto.photoCoverIndex` | body | integer | 否 | 封面图下标，从 0 开始，默认 0 |
| `tiktokBusinessPhoto.autoAddMusic` | body | boolean | 否 | 自动配乐；指定 musicSoundInfo 后固定为 false |
| `tiktokBusinessPhoto.musicSoundInfo` | body | object | 否 | 音乐 ID、曲名、歌手；图文不传音量 |
| `tiktokBusinessPhoto.locationInfo` | body | object | 否 | 地域 ID 和名称必须成对 |

请求格式：`application/json`

### 请求示例

```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"
    }
  }
}
```

### 成功响应

```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"
}
```

### 响应字段

以下列出主要层级；完整结构、联合类型及校验规则以接口 JSON Schema 为准。必填指字段所在对象中的约束。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | integer | 是 | 固定值：0 |
| `message` | string | 否 | — |
| `data` | object | 是 | — |
| `data.id` | union | 是 | — |
| `data.postId` | string | 是 | — |
| `data.platform` | string | 是 | 可选值：TIKTOK_SHOP、TIKTOK、TIKTOK_BUSINESS |
| `data.title` | string | 是 | — |
| `data.videoUrl` | string \| null | 否 | — |
| `data.status` | string | 是 | — |
| `timestamp` | integer | 否 | 响应时间戳，单位毫秒。 |

### 接入说明与限制

- 仅可编辑仍处于可修改状态的发布任务。
- Business 地域 ID 与名称必须成对；音乐使用 musicSoundId（song_clip_id），不能用 commercialMusicId。视频两种音量 0–100，默认均为 50；图文不传音量，指定音乐后 autoAddMusic 不生效。
- Business 视频封面优先使用 coverFileId，否则按 coverTimestampMs 截帧；账号已禁用的互动不能重新开启。
- 仅更新取消或失败的任务。businessType 创建后不可修改；已有 EXTERNAL_URL 视频任务可用 businessId 替换 URL，trim 后 SHA-256 变化时才校验远端 MP4。

### 错误处理

| HTTP | 说明 |
|---|---|
| 400 | 请求参数或请求体无效，请修正后重试。 |
| 401 | API 密钥缺失或无效，请检查 x-api-key。 |
| 403 | API 密钥没有此接口的调用权限。 |
| 429 | 请求过于频繁，请采用指数退避重试。 |
| 500 | 服务端发生错误；对于暂时性故障采用指数退避重试。 |

业务 code 非零时也应按失败处理。不要对参数、权限或授权错误盲目重试。创建发布或生成任务超时后先查询原任务，避免重复创建。

### 相关接口

- [搜索音乐](/openapi/search-music) · [Markdown](/openapi/operations/searchTikTokShopMusic.md)
- [取消发布](/openapi/cancel-post) · [Markdown](/openapi/operations/cancelCreatorPost.md)
- [查询发布记录](/openapi/post-records) · [Markdown](/openapi/operations/listCreatorPosts.md)