# 上传 TikTok 视频封面

- API 版本：1.10.0
- 最后更新：2026-09-29
- 服务地址：`https://api.ailingtu.com`
- 网页文档：[上传 TikTok 视频封面](/openapi/upload-tiktok-cover)
- 完整接口约束：[JSON Schema](/openapi/operations/uploadTikTokShopVideoCover.json)
- 接口发现：[接口索引](/openapi/operations/index.json)

## POST /v1/creator/tiktokshop/uploadPhoto

接口标识：`uploadTikTokShopVideoCover`

上传 TikTok Shop 带货视频的自定义封面。响应中的 photoFile.photoUri 传给发布请求的 tiktokShop.coverUri，coverFileId 则放在请求根节点，与 businessType 平级。

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

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

### 请求参数

| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `id` | body | integer | 是 | 创作者账号 ID（creator account id） |
| `file` | body | string(binary) | 是 | 封面图片文件 |
| `returnCoverFileId` | body | true | 是 | 固定传 true，以返回发布所需的 coverFileId |

请求格式：`multipart/form-data`

### 请求示例

```json
{
  "id": 3754,
  "file": "<binary image file>",
  "returnCoverFileId": true
}
```

### 成功响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "videoFile": null,
    "photoFile": {
      "photoUri": "tos-useast5-i-photomode-tx/owJB0AmAiCIAINiw1WSCmp1ftJzwBqxROEB5w5"
    },
    "coverFileId": 1465137
  },
  "timestamp": 1787733209676
}
```

### 响应字段

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

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | integer | 是 | 固定值：0 |
| `message` | string | 是 | 固定值：success |
| `data` | object | 是 | — |
| `data.videoFile` | null | 是 | — |
| `data.photoFile` | object | 是 | — |
| `data.photoFile.photoUri` | string | 是 | 将此值原样传给 tiktokShop.coverUri。 |
| `data.coverFileId` | union | 是 | 将此值放在发布请求根节点，与 businessType 平级。 |
| `timestamp` | integer | 是 | — |

### 接入说明与限制

- 请求必须使用 multipart/form-data；由 HTTP 客户端自动生成 boundary，不要手动拼接 Content-Type boundary。
- 将 data.photoFile.photoUri 原样传给 tiktokShop.coverUri。
- 将 data.coverFileId 传到发布请求根节点，与 businessType 平级。

### 错误处理

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

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

### 相关接口

- [创建发布任务](/openapi/create-post) · [Markdown](/openapi/operations/createCreatorPost.md)