# Create a publishing task

- API version: 1.11.0
- Last updated: 2026-11-16
- Server: `https://api.ailingtu.com`
- Web document: [Create a publishing task](/en/openapi/create-post)
- Full schema: [JSON Schema](/en/openapi/operations/createCreatorPost.json)
- Discovery: [Operation index](/en/openapi/operations/index.json)

## POST /v1/creator/post/create

Operation ID: `createCreatorPost`

Creates TikTok Shop, TikTok or TikTok Business publishing tasks. Success means accepted; inspect publishing records for completion.

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 |
|---|---|---|---|---|
| `businessId` | body | string | Yes | FILE: file ID; EXTERNAL_URL: original HTTPS MP4 URL |
| `businessType` | body | FILE \| EXTERNAL_URL | Yes | Uploaded file or external video URL |
| `creatorId` | body | string | Yes | creatorId returned by the creator endpoint |
| `title` | body | string | Yes | Post caption, up to 4,000 characters |
| `platform` | body | TIKTOK_SHOP \| TIKTOK \| TIKTOK_BUSINESS | Yes | Publishing platform |
| `mediaType` | body | VIDEO \| PHOTO | No | Optional explicit media type; inferred from the request body when omitted |
| `scheduledAt` | body | integer | No | Unix epoch in milliseconds |
| `scheduledTz` | body | string | No | IANA timezone |
| `oauthRegion` | body | string | No | Creator OAuth authorization region |
| `coverFileId` | body | integer \| string | No | Custom video cover file ID; pass together with tiktokShop.coverUri and omit for photo posts |
| `tiktokShop` | body | object | Conditional | TikTok Shop video options: products, cover, pre-check, music and AI label |
| `tiktokShop.preCheck` | body | boolean | No | Whether to submit a pre-check before publishing; defaults to false |
| `tiktokShop.preCheckOvertime` | body | integer | No | Pre-check timeout in seconds, from 600 to 3600 inclusive. If the official pre-check remains incomplete beyond this time, automatically skip it and continue publishing. |
| `tiktokShop.isAiGenerated` | body | boolean | No | Whether to label the video as AI-generated; TikTok adds an AI-generated label when true |
| `tiktokShop.coverUri` | body | string | No | URI returned by the cover upload endpoint; pass coverFileId with it |
| `tiktokShop.coverTimestampMs` | body | integer | No | Video timestamp in milliseconds to use as the cover frame; omit when coverUri is present |
| `tiktokShop.musicInfo` | body | object | No | Video background music; omit when no music is needed |
| `tiktokShop.musicInfo.id` | body | string | Conditional | Music ID, required when musicInfo is provided |
| `tiktokShop.productInfo.productId` | body | string | Conditional | Required for VIDEO; product ID returned by the product endpoint |
| `tiktokShop.productInfo.title` | body | string | Conditional | Required for VIDEO; product anchor title, up to 30 characters |
| `tiktokShop.productInfo.source` | body | SHOP \| SHOWCASE | Conditional | Required for VIDEO; SHOP for shop products or SHOWCASE for showcase products |
| `tiktokShopPhoto` | body | object | Conditional | TikTok Shop photo options |
| `tiktokShopPhoto.postType` | body | MULTI_PHOTO_ONE_ANCHOR | Conditional | Use MULTI_PHOTO_ONE_ANCHOR for PHOTO |
| `tiktokShopPhoto.businessIds` | body | string[] | Conditional | Required for PHOTO; 1–15 image fileIds in final display order |
| `tiktokShopPhoto.productLinks[0].productId` | body | string | Conditional | Required for PHOTO; product ID for the single product anchor |
| `tiktokShopPhoto.productLinks[0].title` | body | string | Conditional | Required for PHOTO; product anchor title, up to 30 characters |
| `tiktokShopPhoto.productLinks[0].source` | body | SHOP \| SHOWCASE | Conditional | Required for PHOTO; product source |
| `tiktokShopPhoto.musicInfo` | body | object | No | Photo post background music; omit when no music is needed |
| `tiktokShopPhoto.musicInfo.id` | body | string | Conditional | Music ID, required when musicInfo is provided |
| `tiktokBusiness` | body | object | No | Business video options: interaction restrictions, cover, brand flags, AI label, music and location; no privacy level. |
| `tiktokBusinessPhoto` | body | object | Conditional | Required for Business PHOTO; 1–15 image file IDs and privacyLevel from publishing settings. |
| `tiktok` | body | object | Conditional | TikTok video publishing settings |
| `tiktokBusiness.musicSoundInfo.musicSoundId` | body | string | No | Commercial song_clip_id; omit to add no platform music |
| `tiktokBusiness.musicSoundInfo.musicSoundVolume` | body | integer | No | Music volume 0–100, default 50 |
| `tiktokBusiness.musicSoundInfo.videoOriginalSoundVolume` | body | integer | No | Original audio volume 0–100, default 50 |
| `tiktokBusiness.locationInfo` | body | object | No | locationId and locationName must be paired; locationAddress is display-only |
| `tiktokBusinessPhoto.businessIds` | body | integer[] | Conditional | 1–15 image file IDs in display order |
| `tiktokBusinessPhoto.privacyLevel` | body | string | Conditional | Required for Business photos; use a value from publishing settings |
| `tiktokBusinessPhoto.photoCoverIndex` | body | integer | No | Zero-based cover index; default 0 |
| `tiktokBusinessPhoto.autoAddMusic` | body | boolean | No | Auto music; forced false when musicSoundInfo selects a track |
| `tiktokBusinessPhoto.musicSoundInfo` | body | object | No | Music ID, name and artist; no volume fields for photos |
| `tiktokBusinessPhoto.locationInfo` | body | object | No | Location ID and name must be paired |

Request format: `application/json`

### Request example: TikTok Shop commerce video

```json
{
  "businessId": "1465129",
  "businessType": "FILE",
  "coverFileId": 1465137,
  "creatorId": "2077242233106595840",
  "title": "Womens midlength Tshirt",
  "platform": "TIKTOK_SHOP",
  "scheduledAt": 1787752245233,
  "scheduledTz": "America/New_York",
  "tiktokShop": {
    "preCheck": true,
    "preCheckOvertime": 1800,
    "isAiGenerated": false,
    "coverUri": "tos-useast5-i-photomode-tx/owJB0AmAiCIAINiw1WSCmp1ftJzwBqxROEB5w5",
    "productInfo": {
      "productId": "1729452608393351351",
      "title": "Womens midlength Tshirt",
      "source": "SHOWCASE"
    }
  }
}
```

### Request example: TikTok Shop commerce photo post

```json
{
  "businessId": "591",
  "businessType": "FILE",
  "creatorId": "2077242233106595840",
  "title": "Summer Sale 2026 #summer",
  "platform": "TIKTOK_SHOP",
  "mediaType": "PHOTO",
  "scheduledAt": 1784896665989,
  "scheduledTz": "America/New_York",
  "oauthRegion": "USA",
  "tiktokShopPhoto": {
    "postType": "MULTI_PHOTO_ONE_ANCHOR",
    "businessIds": [
      "591",
      "592"
    ],
    "productLinks": [
      {
        "productId": "1732280564607717841",
        "title": "Summer Vibes Cord",
        "source": "SHOP"
      }
    ],
    "musicInfo": {
      "id": "7567668059796720391",
      "title": "original sound",
      "author": "Ivan",
      "duration": "15"
    }
  }
}
```

### Request example: TikTok Business video

```json
{
  "creatorId": "2077242233106595840",
  "businessType": "FILE",
  "businessId": "591",
  "title": "New collection",
  "platform": "TIKTOK_BUSINESS",
  "mediaType": "VIDEO",
  "tiktokBusiness": {
    "musicSoundInfo": {
      "musicSoundId": "7123456789012345678",
      "musicSoundVolume": 50,
      "videoOriginalSoundVolume": 50
    },
    "locationInfo": {
      "locationId": "loc-1",
      "locationName": "London"
    }
  }
}
```

### Request example: TikTok Business photo post

```json
{
  "creatorId": "2077242233106595840",
  "businessType": "FILE",
  "businessId": "591",
  "title": "New collection",
  "platform": "TIKTOK_BUSINESS",
  "mediaType": "PHOTO",
  "tiktokBusinessPhoto": {
    "businessIds": [
      591,
      592
    ],
    "privacyLevel": "SELF_ONLY",
    "photoCoverIndex": 0
  }
}
```

### Success response

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

### 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 | No | — |
| `data` | object | Yes | — |
| `data.id` | union | Yes | — |
| `data.postId` | string | Yes | — |
| `data.platform` | string | Yes | Allowed values: TIKTOK_SHOP, TIKTOK, TIKTOK_BUSINESS |
| `data.title` | string | Yes | — |
| `data.videoUrl` | string \| null | No | — |
| `data.status` | string | Yes | — |
| `timestamp` | integer | No | Response timestamp in milliseconds. |

### Integration notes and limits

- For a video cover, use tiktokShop.coverTimestampMs for a frame or pass coverFileId together with tiktokShop.coverUri for a custom cover; do not mix the two methods.
- TikTok Shop photo posts support 1–15 images and one product; businessId must equal businessIds[0], and the first image is the cover.
- Persist postId and status, then verify the final state in publishing records.
- Business location ID and name must be provided together. Use musicSoundId (song_clip_id), never commercialMusicId. Video volumes range from 0 to 100 and default to 50. Photos have no volume parameters; selected music overrides autoAddMusic.
- For Business video covers, coverFileId overrides coverTimestampMs. Account-disabled interactions cannot be enabled.
- EXTERNAL_URL supports only TikTok Shop VIDEO on Pro/Elite or equivalent legacy plans: HTTPS URL at most 256 characters, Content-Type video/mp4, Content-Length strictly below 200 MiB.

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

- [List TikTok Business trending music](/en/openapi/business-trending-music) · [Markdown](/en/openapi/operations/listTikTokBusinessTrendingMusic.md)
- [Search Business locations](/en/openapi/business-locations) · [Markdown](/en/openapi/operations/searchTikTokBusinessLocations.md)
- [Get publishing task details](/en/openapi/post-detail) · [Markdown](/en/openapi/operations/getCreatorPost.md)
- [Search TikTok Shop music](/en/openapi/search-music) · [Markdown](/en/openapi/operations/searchTikTokShopMusic.md)
- [Upload a TikTok video cover](/en/openapi/upload-tiktok-cover) · [Markdown](/en/openapi/operations/uploadTikTokShopVideoCover.md)
- [Publish a commerce video immediately](/en/openapi/submit-post) · [Markdown](/en/openapi/operations/submitCreatorPost.md)
- [List publishing records](/en/openapi/post-records) · [Markdown](/en/openapi/operations/listCreatorPosts.md)
