开发者文档 / 文件上传

上传 TikTok 视频封面

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

POST/v1/creator/tiktokshop/uploadPhoto

鉴权：: 请求头 x-api-key: <YOUR_API_KEY>；密钥仅保存在服务端。
成功判断：: HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

请求字段

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

请求必须使用 multipart/form-data；由 HTTP 客户端自动生成 boundary，不要手动拼接 Content-Type boundary。

将 data.photoFile.photoUri 原样传给 tiktokShop.coverUri。

将 data.coverFileId 传到发布请求根节点，与 businessType 平级。

请求体

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

成功响应

{
  "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`	是	—

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

参数、权限或授权错误需先修正。创建发布或生成任务超时后先查询已有任务，避免重复创建；不要因轮询中断而重复提交。

最后更新 · 2026-09-29