您的浏览器不支持JavaScript,请启用JavaScript以获得最佳体验。
Upload a TikTok video cover
Developer docs / File upload

Upload a TikTok video cover

Upload a custom TikTok Shop commerce-video cover. Pass photoFile.photoUri as tiktokShop.coverUri and place coverFileId at the request root alongside businessType.

POST/v1/creator/tiktokshop/uploadPhoto
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 body fields

FieldTypeRequiredDescription
idintegerYesCreator account id
filestring(binary)YesCover image file
returnCoverFileIdtrueYesSet to true so the response includes the coverFileId required for publishing
Send multipart/form-data and let the HTTP client generate the Content-Type boundary.
Pass data.photoFile.photoUri unchanged as tiktokShop.coverUri.
Place data.coverFileId at the publishing-request root alongside businessType.
Request body
{
  "id": 3754,
  "file": "<binary image file>",
  "returnCoverFileId": true
}
Success response
{
  "code": 0,
  "message": "success",
  "data": {
    "videoFile": null,
    "photoFile": {
      "photoUri": "tos-useast5-i-photomode-tx/owJB0AmAiCIAINiw1WSCmp1ftJzwBqxROEB5w5"
    },
    "coverFileId": 1465137
  },
  "timestamp": 1787733209676
}

Response and errors

Main response fields come from the published contract; see the JSON Schema. Required refers to the constraint in the containing object.

FieldTypeRequiredDescription
codeintegerYesFixed value: 0
messagestringYesFixed value: success
dataobjectYes—
data.videoFilenullYes—
data.photoFileobjectYes—
data.photoFile.photoUristringYesPass this value unchanged as tiktokShop.coverUri.
data.coverFileIdunionYesPut this value at the root of the publish request, next to businessType.
timestampintegerYes—
  • HTTP 400The request parameters or body are invalid. Fix them and retry.
  • HTTP 401The API key is missing or invalid. Check x-api-key.
  • HTTP 403The API key has no permission to call this endpoint.
  • HTTP 429Too many requests. Retry with exponential backoff.
  • HTTP 500The server failed. Retry transient failures with exponential backoff.

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