# Upload a TikTok video cover

- API version: 1.11.0
- Last updated: 2026-11-16
- Server: `https://api.ailingtu.com`
- Web document: [Upload a TikTok video cover](/en/openapi/upload-tiktok-cover)
- Full schema: [JSON Schema](/en/openapi/operations/uploadTikTokShopVideoCover.json)
- Discovery: [Operation index](/en/openapi/operations/index.json)

## POST /v1/creator/tiktokshop/uploadPhoto

Operation ID: `uploadTikTokShopVideoCover`

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

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 |
|---|---|---|---|---|
| `id` | body | integer | Yes | Creator account id |
| `file` | body | string(binary) | Yes | Cover image file |
| `returnCoverFileId` | body | true | Yes | Set to true so the response includes the coverFileId required for publishing |

Request format: `multipart/form-data`

### Request example

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

### Success response

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

### 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 | Yes | Fixed value: success |
| `data` | object | Yes | — |
| `data.videoFile` | null | Yes | — |
| `data.photoFile` | object | Yes | — |
| `data.photoFile.photoUri` | string | Yes | Pass this value unchanged as tiktokShop.coverUri. |
| `data.coverFileId` | union | Yes | Put this value at the root of the publish request, next to businessType. |
| `timestamp` | integer | Yes | — |

### Integration notes and limits

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

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

- [Create a publishing task](/en/openapi/create-post) · [Markdown](/en/openapi/operations/createCreatorPost.md)
