# LINGTU AI Open API

LINGTU AI OpenAPI documentation covering TikTok Shop creator authorization, products, media upload, publishing, AI image and video generation, and public content data.

- API version: 1.11.0
- Last updated: 2026-11-16
- Server: `https://api.ailingtu.com`
- Authentication: request header `x-api-key: <YOUR_API_KEY>`. Keep the key on the server and never write it into browser code, logs or shared files.
- A request usually succeeds when HTTP is 2xx and the business `code=0`; asynchronous, SSE and model endpoints follow their own documented conditions.

## Read on demand

Read the [Operation index](/en/openapi/operations/index.json) first, then the Markdown or JSON of a single operation, instead of loading the whole specification.

[OpenAPI JSON](/openapi.json) · [OpenAPI YAML](/openapi.yaml) · [Web document](/en/openapi) · [Markdown](/en/openapi.md)

## Publishing flow

1. Create the TikTok Shop authorization URL for the target oauthRegion and let the creator finish authorization.
2. List authorized accounts. Query products with the account id and create publishing tasks with creatorId; do not mix them up.
3. Search music when needed. New media goes through presign, PUT upload and confirmation to get a fileId; skip PUT and confirmation when isNew=false.
4. Upload a custom video cover first, pass photoFile.photoUri as tiktokShop.coverUri and put coverFileId at the request root.
5. Save the postId after creating a task, then query publishing records for the final status. Update or cancel tasks that can still change when needed.

Diagrams and endpoint sequences: [commerce publishing overview](/en/openapi/workflows/commerce-publishing.md) · [creator authorization](/en/openapi/workflows/creator-authorization.md) · [commerce video](/en/openapi/workflows/commerce-video.md) · [commerce photo](/en/openapi/workflows/commerce-photo.md).

## AI image and video generation

See the [AI generation workflow](/en/openapi/workflows/ai-generation.md): create one schedule, save scheduleId, poll that schedule and read the results.

## Viral video prompt replication

1. Call POST /v1/material/analysisTask/stream with type=REPLICATION and a public video URL; upload local files first and pass businessId and businessType.
2. Read the data: JSON events from text/event-stream and concatenate result chunks with status=streaming in order; when a done event arrives, use its complete result.
3. Submit the full prompt to the AI generation endpoint if needed; on failure check the HTTP status and JSON error message.

## Creator analysis flow

1. Use /v1/influencer/fetchPosts for recent TikTok posts or /v1/influencer/ins/fetchPosts for recent Instagram posts.
2. Compute verifiable posting frequency, engagement metrics and content evidence first; distinguish missing fields from real zeros.
3. Feed the evidence to /v1/relay/chat/completions when a report is needed, separating observed facts from AI inference.

## GET /v1/creator/post/detail

Operation ID: `getCreatorPost`

Returns source, schedule and platform-specific publishing options. For EXTERNAL_URL, businessId is the URL SHA-256 and videoUrl holds the original URL. snapshot can be null for older records; PHOTO snapshots preserve all source files in original order.

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 |
|---|---|---|---|---|
| `postId` | query | string | Yes | Publishing task ID |

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "postId": "2011014932023390208",
    "platform": "TIKTOK_BUSINESS",
    "businessType": "FILE",
    "businessId": "591",
    "title": "New collection",
    "videoUrl": "https://cdn.example.com/video.mp4",
    "snapshot": {
      "sourceFiles": [
        {
          "materialType": "VIDEO",
          "name": "video.mp4",
          "uploadedAt": "2026-09-29 10:00:00"
        }
      ]
    },
    "scheduledAt": 1790640000000,
    "scheduledTz": "Asia/Shanghai",
    "status": "SCHEDULED",
    "tiktokBusiness": {
      "musicSoundInfo": {
        "musicSoundId": "7123456789012345678",
        "musicSoundName": "Sunrise",
        "musicSoundArtist": "Example artist",
        "musicSoundVolume": 50,
        "videoOriginalSoundVolume": 50
      },
      "locationInfo": {
        "locationId": "loc-1",
        "locationName": "London"
      }
    }
  },
  "timestamp": 1790640000000
}
```

### 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 | — |
| `message` | string | Yes | — |
| `data` | object | Yes | — |
| `data.postId` | string | Yes | — |
| `data.platform` | string | Yes | — |
| `data.businessType` | string | No | Material source, such as FILE or EXTERNAL_URL |
| `data.businessId` | string | No | FILE is the file ID; EXTERNAL_URL is the SHA-256 of the original URL. The original URL is in videoUrl. |
| `data.title` | string | Yes | — |
| `data.videoUrl` | string | Yes | — |
| `data.snapshot` | object \| null | No | Original media snapshot saved when the publishing task was created. Null for older records or tasks without files. PHOTO returns every source file. |
| `data.snapshot.sourceFiles` | object[] | No | Source files. VIDEO has one file; PHOTO returns every file in the original order. |
| `data.snapshot.sourceFiles[].materialType` | string | Yes | Source media type: VIDEO or PHOTO |
| `data.snapshot.sourceFiles[].name` | string | Yes | Source file name |
| `data.snapshot.sourceFiles[].uploadedAt` | string | Yes | Source file upload time |
| `data.scheduledAt` | integer | Yes | — |
| `data.scheduledTz` | string | Yes | — |
| `data.status` | string | Yes | — |
| `data.tiktokShop` | union | No | — |
| `data.tiktok` | object | No | — |
| `data.tiktok.coverTimestampMs` | integer | Yes | — |
| `data.tiktok.privacyLevel` | string | Yes | — |
| `data.tiktok.disableComment` | boolean | Yes | — |
| `data.tiktok.disableDuet` | boolean | Yes | — |
| `data.tiktok.disableStitch` | boolean | Yes | — |
| `data.tiktok.brandContentToggle` | boolean | Yes | — |
| `data.tiktok.brandOrganicToggle` | boolean | Yes | — |
| `data.tiktok.aigc` | boolean | Yes | — |
| `data.tiktokBusiness` | object | No | Optional Business video settings without privacyLevel. coverFileId takes precedence over coverTimestampMs, and interactions disabled at account level can only stay disabled. |
| `data.tiktokBusiness.disableComment` | boolean | No | Disable comments. Must be true when comments are disabled at account level |
| `data.tiktokBusiness.disableDuet` | boolean | No | Disable Duet. Must be true when Duet is disabled at account level |
| `data.tiktokBusiness.disableStitch` | boolean | No | Disable Stitch. Must be true when Stitch is disabled at account level |
| `data.tiktokBusiness.coverTimestampMs` | integer | No | Video frame timestamp used as the cover (milliseconds) |
| `data.tiktokBusiness.brandContentToggle` | boolean | No | Brand content (paid partnership) |
| `data.tiktokBusiness.brandOrganicToggle` | boolean | No | Brand organic (promoting your own business) |
| `data.tiktokBusiness.aigc` | boolean | No | AI-generated content |
| `data.tiktokBusiness.musicSoundInfo` | object | No | Use musicSoundId (song_clip_id), never commercialMusicId. Omit it to publish without platform music; title and artist are display snapshots. |
| `data.tiktokBusiness.musicSoundInfo.musicSoundId` | string | No | musicSoundId from the trending music endpoint (the platform song_clip_id); never use commercialMusicId |
| `data.tiktokBusiness.musicSoundInfo.musicSoundName` | string | No | Track title snapshot for display and detail lookups; publishing uses musicSoundId |
| `data.tiktokBusiness.musicSoundInfo.musicSoundArtist` | string | No | Artist snapshot for display and detail lookups |
| `data.tiktokBusiness.musicSoundInfo.musicSoundVolume` | integer | No | Music volume 0-100; defaults to 50 (the platform treats a missing volume as 0, which is muted) |
| `data.tiktokBusiness.musicSoundInfo.videoOriginalSoundVolume` | integer | No | Original video volume 0-100; defaults to 50 |
| `data.tiktokBusiness.locationInfo` | object | No | Submit locationId and locationName together; locationAddress is display-only. |
| `data.tiktokBusiness.locationInfo.locationId` | string | No | locationId from the location search endpoint; publishing maps it to post_info.location_id |
| `data.tiktokBusiness.locationInfo.locationName` | string | No | Location name, submitted together with the ID (post_info.location_name) |
| `data.tiktokBusiness.locationInfo.locationAddress` | string | No | Extra address for display and detail lookups only; never sent to the platform |
| `data.tiktokBusinessPhoto` | object | No | TikTok Business photo options. Required when platform=TIKTOK_BUSINESS and mediaType=PHOTO, and cannot be combined with tiktokShopPhoto. Pass our file IDs; the server resolves them to public image URLs. The privacy level must be one of the values allowed for the account, otherwise the task fails. |
| `data.tiktokBusinessPhoto.businessIds` | integer[] | Yes | Image file IDs in display order, 1–15 images |
| `data.tiktokBusinessPhoto.photoUrls` | string[] | No | Image URLs resolved by the server; do not send them |
| `data.tiktokBusinessPhoto.photoCoverIndex` | integer | No | Cover image index starting at 0; defaults to 0 |
| `data.tiktokBusinessPhoto.privacyLevel` | string | Yes | Privacy level; required and must be one of the values allowed for the account |
| `data.tiktokBusinessPhoto.autoAddMusic` | boolean | No | Ignored when musicSoundInfo.musicSoundId is present; the server always sends false. |
| `data.tiktokBusinessPhoto.disableComment` | boolean | No | Disable comments. Must be true when comments are disabled at account level |
| `data.tiktokBusinessPhoto.brandOrganicToggle` | boolean | No | Brand organic (promoting your own business) |
| `data.tiktokBusinessPhoto.brandContentToggle` | boolean | No | Brand content (paid partnership) |
| `data.tiktokBusinessPhoto.locationInfo` | object | No | Submit locationId and locationName together; locationAddress is display-only. |
| `data.tiktokBusinessPhoto.locationInfo.locationId` | string | No | locationId from the location search endpoint; publishing maps it to post_info.location_id |
| `data.tiktokBusinessPhoto.locationInfo.locationName` | string | No | Location name, submitted together with the ID (post_info.location_name) |
| `data.tiktokBusinessPhoto.locationInfo.locationAddress` | string | No | Extra address for display and detail lookups only; never sent to the platform |
| `data.tiktokBusinessPhoto.musicSoundInfo` | object | No | Selected commercial music, sharing the same structure as non-commerce videos. Omit it (or musicSoundId) to publish without platform music. Photo publishing has no volume options: only musicSoundId is sent to TikTok (post_info.music_sound_info.music_sound_id), and the title and artist are display snapshots. |
| `data.tiktokBusinessPhoto.musicSoundInfo.musicSoundId` | string | No | musicSoundId from the trending music endpoint (the platform song_clip_id). Never use commercialMusicId. Photo publishing maps it to post_info.music_sound_info.music_sound_id |
| `data.tiktokBusinessPhoto.musicSoundInfo.musicSoundName` | string | No | Track title snapshot for display and detail lookups; publishing uses musicSoundId |
| `data.tiktokBusinessPhoto.musicSoundInfo.musicSoundArtist` | string | No | Artist snapshot for display and detail lookups |
| `timestamp` | integer | Yes | — |

### Integration notes and limits

- Returns source, schedule and platform-specific publishing options. For EXTERNAL_URL, businessId is the URL SHA-256 and videoUrl holds the original URL. snapshot can be null for older records; PHOTO snapshots preserve all source files in original order.

### Related endpoints

- [Update a publishing task](/en/openapi/update-post) · [Markdown](/en/openapi/operations/updateCreatorPost.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)

## GET /v1/creator/tiktokshop/product/listByShop

Operation ID: `listTikTokShopProducts`

Queries shop products with pagination, keyword and sorting options. The supplied source document contains an account-list response instead of product data; the response data structure is pending confirmation.

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 |
|---|---|---|---|---|
| `pageSize` | query | integer | Yes | Items per page |
| `id` | query | integer | Yes | Creator account ID |
| `pageToken` | query | string | No | Previous pagination token; omit on first request |
| `titleKeyword` | query | string | No | Product title keyword |
| `sortField` | query | string | No | Sort field, such as PRODUCT_ID or PRICE |
| `sortOrder` | query | string | No | Sort direction: ASC or DESC |

### 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 | — |
| `message` | string | Yes | — |
| `data` | object | Yes | The shop product response structure is pending confirmation. Use the actual response and do not infer unconfirmed fields. |
| `timestamp` | integer | Yes | — |

## POST /v1/creator/tiktokshop/affiliateOrders/search

Operation ID: `searchCreatorAffiliateOrders`

Queries TikTok Shop creator affiliate orders through /affiliate_creator/202410/orders/search. This is a creator-scoped endpoint: id is the creator account ID because the creator access_token is used, not a shop ID. startTime and endTime use YYYY-MM-DD and are converted from the start of the first day to the start of the day after endTime. Omit pageToken on the first request, then reuse nextPageToken with the same date range; an empty token means the last page. Amounts are localized strings with a currency; commission rates are in hundredths of a percent, so 3000 means 30%.

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 (not a shop ID) |
| `startTime` | body | string | Yes | Start date in YYYY-MM-DD |
| `endTime` | body | string | Yes | End date in YYYY-MM-DD, inclusive of the whole day |
| `pageToken` | body | string | No | Pagination token; omit on the first request |
| `pageSize` | body | integer | No | Items per page from 1 to 100; defaults to 20 and is validated before calling the platform |

Request format: `application/json`

### Request example

```json
{
  "id": 12345,
  "startTime": "2026-11-01",
  "endTime": "2026-11-16",
  "pageSize": 20
}
```

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "orders": [
      {
        "id": "789078671231123124",
        "createTime": 1685548800,
        "deliveryTime": 1685548800,
        "status": "SETTLED",
        "skus": [
          {
            "id": "1729793769377925388",
            "campaignId": "73661290629",
            "productName": "black_suit",
            "productId": "1729793769377859852",
            "price": {
              "amount": "Rp9.900",
              "currency": "IDR"
            },
            "shopName": "TestCase idl2l",
            "contentType": "VIDEO",
            "contentId": "7493990579714164574",
            "quantity": 2,
            "commissionRate": 3000,
            "commissionModel": "Fixed commission",
            "estimatedCommission": {
              "amount": "Rp1.980",
              "currency": "IDR"
            },
            "actualCommission": {
              "amount": "Rp1.900",
              "currency": "IDR"
            },
            "returnedQuantity": 0,
            "refundedQuantity": 0,
            "traceInfo": {
              "id": "15678763",
              "type": "SPECIFIC"
            },
            "lastUpdateTime": 1685548800,
            "isCarousel": false
          }
        ]
      }
    ],
    "nextPageToken": "",
    "totalCount": 1
  },
  "timestamp": 1794463889000
}
```

### 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 | 0 indicates success |
| `message` | string | Yes | — |
| `data` | object | Yes | — |
| `data.orders` | object[] | No | Matched orders. |
| `data.orders[].id` | string | No | Order identifier |
| `data.orders[].createTime` | integer | No | Order creation time in Unix seconds |
| `data.orders[].deliveryTime` | integer | No | Delivery time in Unix seconds |
| `data.orders[].status` | string | No | Order status: UNSPECIFIED (undefined, may update later), AWAITING PAYMENT (unpaid, estimated commission only), To-SETTLE (waiting for settlement, estimated commission only), SETTLED (commission settled), REFUNDED (returned/refunded/cancelled, no commission settled), FROZEN (possible fraud, unfrozen after review) |
| `data.orders[].skus` | object[] | No | SKUs in the order. |
| `data.orders[].skus[].id` | string | No | SKU identifier |
| `data.orders[].skus[].campaignId` | string | No | Campaign ID associated with the order |
| `data.orders[].skus[].openCollaborationId` | string | No | Open collaboration ID |
| `data.orders[].skus[].targetCollaborationId` | string | No | Target collaboration ID |
| `data.orders[].skus[].productName` | string | No | TikTok Shop product name |
| `data.orders[].skus[].productId` | string | No | Product ID |
| `data.orders[].skus[].price` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].shopName` | string | No | Shop name of the product |
| `data.orders[].skus[].contentType` | string | No | Content format that generated the order: SHOP, VIDEO, LIVE, PRE_LIVE, PROMOTION_PAGE or LINKSHARE |
| `data.orders[].skus[].contentId` | string | No | Content ID that generated the order |
| `data.orders[].skus[].quantity` | integer | No | SKU quantity, including refunded units |
| `data.orders[].skus[].commissionRate` | integer | No | Total commission rate in hundredths of a percent: 3000 = 30%; the sum of standard, shop ads, bonus and reward rates |
| `data.orders[].skus[].commissionTierSetting` | string | No | Tier rates configured by the seller under the tiered commission model, such as 3.0 OR 5.0 |
| `data.orders[].skus[].commissionModel` | string | No | Commission model: Fixed commission or Tiered commission |
| `data.orders[].skus[].commissionBonusRate` | integer | No | Bonus commission rate in hundredths of a percent |
| `data.orders[].skus[].estimatedCommissionBase` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].standardCommissionRate` | integer | No | Standard affiliate commission rate in hundredths of a percent |
| `data.orders[].skus[].shopAdsCommissionRate` | integer | No | Shop ads commission rate in hundredths of a percent |
| `data.orders[].skus[].estimatedBonusCommission` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].estimatedStandardCommission` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].estimatedShopAdsCommission` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].estimatedCommission` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].actualCommission` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].actualBonusCommission` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].actualCommissionBase` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].actualStandardCommission` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].actualShopAdsCommission` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].returnedQuantity` | integer | No | Returned quantity for this SKU |
| `data.orders[].skus[].refundedQuantity` | integer | No | Refunded quantity for this SKU |
| `data.orders[].skus[].tag` | string | No | User-defined tag for caller-side tracking |
| `data.orders[].skus[].creatorCommissionRewardRate` | integer | No | Commission reward rate the affiliate partner gives the creator, in hundredths of a percent: 1000 = 10% |
| `data.orders[].skus[].estimatedCreatorCommissionRewardFee` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].actualCreatorCommissionRewardFee` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].isr` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].iva` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].pit` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].sharedWithPartner` | object | No | Localized amount: amount is a formatted string with currency symbol and separators; never convert it to a number for calculations. |
| `data.orders[].skus[].traceInfo` | object | No | Attribution information. |
| `data.orders[].skus[].lastUpdateTime` | integer | No | Last update time of the record, in Unix seconds |
| `data.orders[].skus[].isCarousel` | boolean | No | Whether the order is attributed to carousel content, which may involve a commission rate discount |
| `data.nextPageToken` | string | No | Token for the next page; an empty string means the last page |
| `data.totalCount` | integer | No | Total matched SKU rows. One order can contain multiple SKUs, so the number of order objects may be smaller than pageSize |
| `timestamp` | integer | No | — |

### Integration notes and limits

- Creator-scoped: id is the creator account ID, and the server calls TikTok Shop /affiliate_creator/202410/orders/search with that creator's access_token. It is not a shop ID.
- startTime and endTime use YYYY-MM-DD and are converted from the start of the first day to the start of the day after endTime.
- Omit pageToken on the first request, then reuse nextPageToken with the same date range; an empty token means the last page. totalCount and pageSize count SKU rows, so an order with several SKUs can make the returned order objects fewer than pageSize.
- Amounts are localized strings with a currency and must not be converted to numbers for calculations; commission rates are in hundredths of a percent, so 3000 means 30%.
- isr and iva are returned for Mexico creators only, and pit for VN/TH/PH/ID creators only; other regions may omit them.

### Related endpoints

- [List authorized creators](/en/openapi/creators) · [Markdown](/en/openapi/operations/listCreatorAccounts.md)
- [List publishing records](/en/openapi/post-records) · [Markdown](/en/openapi/operations/listCreatorPosts.md)

## GET /v1/creator/tiktokBusiness/searchLocation

Operation ID: `searchTikTokBusinessLocations`

Queries up to 20 live location tags without local storage or caching. Submit locationId and locationName together in tiktokBusiness.locationInfo or tiktokBusinessPhoto.locationInfo; a single field fails validation. Entries missing either field are omitted. The server resolves business_id from the account open_id; expired authorization returns “授权过期，请重新授权” (authorization expired, reauthorize).

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` | query | integer | Yes | Creator account ID |
| `searchQuery` | query | string | Yes | Location query, up to 100 characters |

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "locations": [
      {
        "locationId": "loc-1",
        "locationName": "City of London, United Kingdom",
        "locationAddress": "London, United Kingdom"
      }
    ]
  },
  "timestamp": 1790640000000
}
```

### 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 | — |
| `message` | string | Yes | — |
| `data` | object | Yes | — |
| `data.locations` | object[] | Yes | — |
| `data.locations[].locationId` | string | Yes | Passed as post_info.location_id when publishing |
| `data.locations[].locationName` | string | Yes | Location name, submitted with the ID when publishing and used in lists |
| `data.locations[].locationAddress` | string | No | Extra location detail: a country, state, city or full address. Display only |
| `timestamp` | integer | Yes | — |

### Integration notes and limits

- Queries up to 20 live location tags without local storage or caching. Submit locationId and locationName together in tiktokBusiness.locationInfo or tiktokBusinessPhoto.locationInfo; a single field fails validation. Entries missing either field are omitted. The server resolves business_id from the account open_id; expired authorization returns “授权过期，请重新授权” (authorization expired, reauthorize).

### Related endpoints

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

## GET /v1/creator/tiktokBusiness/trendingMusic

Operation ID: `listTikTokBusinessTrendingMusic`

Queries up to 100 live commercial music library tracks without local storage or caching. Preview URLs are guaranteed for only six hours. Publish using musicSoundId (song_clip_id), never commercialMusicId. Tracks without song_clip_id are omitted. The server resolves business_id from the account open_id. Expired authorization returns “授权过期，请重新授权” (authorization expired, reauthorize); token renewal returns “账号授权需要续期，请稍后重试” (authorization needs renewal, retry later).

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` | query | integer | Yes | Creator account ID |
| `genre` | query | string | No | Music genre; defaults to ALL |
| `countryCode` | query | string | No | Country code; defaults to US |
| `dateRange` | query | string | No | Chart period; defaults to 7DAY |

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "music": [
      {
        "musicSoundId": "7123456789012345678",
        "commercialMusicId": "1234567890",
        "name": "Sunrise",
        "artist": "Example artist",
        "duration": 123,
        "coverUrl": "https://cdn.example.com/cover.jpg",
        "previewUrl": "https://cdn.example.com/preview.mp3",
        "genres": [
          "POP"
        ],
        "rankPosition": "3"
      }
    ]
  },
  "timestamp": 1790640000000
}
```

### 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 | — |
| `message` | string | Yes | — |
| `data` | object | Yes | — |
| `data.music` | object[] | Yes | — |
| `data.music[].musicSoundId` | string | Yes | Passed as music_sound_id when publishing; use the platform song_clip_id |
| `data.music[].commercialMusicId` | string | No | Commercial music library track ID for display and troubleshooting only; never use it as music_sound_id |
| `data.music[].name` | string | No | Track title |
| `data.music[].artist` | string | No | Artist |
| `data.music[].duration` | integer | No | Duration in seconds; may be 0 when the platform only provides a clip |
| `data.music[].coverUrl` | string | No | Cover image URL |
| `data.music[].previewUrl` | string | No | Preview URL; the platform guarantees it for six hours only |
| `data.music[].genres` | string[] | No | — |
| `data.music[].rankPosition` | string | No | Current rank of the track in the selected region |
| `timestamp` | integer | Yes | — |

### Integration notes and limits

- Queries up to 100 live commercial music library tracks without local storage or caching. Preview URLs are guaranteed for only six hours. Publish using musicSoundId (song_clip_id), never commercialMusicId. Tracks without song_clip_id are omitted. The server resolves business_id from the account open_id. Expired authorization returns “授权过期，请重新授权” (authorization expired, reauthorize); token renewal returns “账号授权需要续期，请稍后重试” (authorization needs renewal, retry later).

### Related endpoints

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

## POST /v1/creatorAccount/setTags

Operation ID: `setCreatorAccountTags`

Sets account tags using id or ids and tagNames. The optional append flag controls appending tags.

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 | No | Creator account ID |
| `ids` | body | integer[] | No | Creator account IDs |
| `tagNames` | body | string[] | Yes | Tag names |
| `append` | body | boolean | No | Append tags |

Request format: `application/json`

### Request example

```json
{
  "ids": [
    12345
  ],
  "tagNames": [
    "team-a"
  ],
  "append": false
}
```

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": null,
  "timestamp": 1790640000000
}
```

### 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 | — |
| `message` | string | Yes | — |
| `data` | null | Yes | — |
| `timestamp` | integer | Yes | — |

## POST /v1/creatorAccount/revoke

Operation ID: `revokeCreatorAccount`

Revokes the specified creator account authorization.

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 |

Request format: `application/json`

### Request example

```json
{
  "id": 12345
}
```

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": null,
  "timestamp": 1790640000000
}
```

### 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 | — |
| `message` | string | Yes | — |
| `data` | null | Yes | — |
| `timestamp` | integer | Yes | — |

## POST /v1/creatorAccount/sync

Operation ID: `syncCreatorAccount`

Refreshes profile data according to TIKTOK_LOGIN_KIT, TIKTOK_BUSINESS_ACCOUNT_API or TIKTOK_SHOP_CREATOR authorization. Missing or unsupported sources fail. Does not change authorization status or initiate reauthorization.

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 |

Request format: `application/json`

### Request example

```json
{
  "id": 12345
}
```

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": null,
  "timestamp": 1790640000000
}
```

### 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 | — |
| `message` | string | Yes | — |
| `data` | null | Yes | — |
| `timestamp` | integer | Yes | — |

### Integration notes and limits

- Refreshes profile data according to TIKTOK_LOGIN_KIT, TIKTOK_BUSINESS_ACCOUNT_API or TIKTOK_SHOP_CREATOR authorization. Missing or unsupported sources fail. Does not change authorization status or initiate reauthorization.

## POST /v1/creator/tiktokshop/music/unfavorite

Operation ID: `unfavoriteTikTokShopMusic`

Idempotently removes a track from the LINGTU music favorites library for TIKTOK_SHOP. This library is stored by LINGTU and is not a TikTok official favorite. A missing entry also succeeds.

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 |
|---|---|---|---|---|
| `musicId` | body | string | Yes | Platform music ID |

Request format: `application/json`

### Request example

```json
{
  "musicId": "7567668059796720391"
}
```

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": null,
  "timestamp": 1790640000000
}
```

### 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 | No | — |
| `message` | string | No | — |
| `data` | null | No | — |
| `timestamp` | integer | No | — |

### Integration notes and limits

- The LINGTU favorites library is stored by LINGTU, not by TikTok, and is scoped to the current company, user and TIKTOK_SHOP platform.
- Idempotent: removing a track that is not in the library also succeeds.

### Related endpoints

- [List LINGTU music favorites](/en/openapi/favorite-music-list) · [Markdown](/en/openapi/operations/listTikTokShopFavoriteMusic.md)

## POST /v1/creator/tiktokshop/music/favorite

Operation ID: `favoriteTikTokShopMusic`

Idempotently adds a track to the LINGTU music favorites library for TIKTOK_SHOP. This library is stored by LINGTU and is not a TikTok official favorite. Existing entries refresh non-empty title, author, duration, coverUrl and playUrl. Use coverThumb.urlList[0] and playUrl.urlList[0] from music search for URL snapshots.

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 |
|---|---|---|---|---|
| `musicId` | body | string | Yes | Platform music ID |
| `title` | body | string | No | Title; case-insensitive matching for favorites |
| `author` | body | string | No | Artist or author |
| `duration` | body | string | No | Duration snapshot |
| `coverUrl` | body | string | No | Cover URL snapshot |
| `playUrl` | body | string | No | Playback URL snapshot |

Request format: `application/json`

### Request example

```json
{
  "musicId": "7567668059796720391",
  "title": "Sunrise",
  "author": "Example artist",
  "duration": "30",
  "coverUrl": "https://cdn.example.com/music-cover.jpg",
  "playUrl": "https://cdn.example.com/music.mp3"
}
```

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": null,
  "timestamp": 1790640000000
}
```

### 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 | No | — |
| `message` | string | No | — |
| `data` | null | No | — |
| `timestamp` | integer | No | — |

### Integration notes and limits

- The LINGTU favorites library is stored by LINGTU, not by TikTok, and is scoped to the current company, user and TIKTOK_SHOP platform.
- Idempotent: existing entries refresh non-empty title, author, duration, coverUrl and playUrl.
- Use coverThumb.urlList[0] and playUrl.urlList[0] from music search for URL snapshots; snapshots may expire, so publish with musicId.

### Related endpoints

- [List LINGTU music favorites](/en/openapi/favorite-music-list) · [Markdown](/en/openapi/operations/listTikTokShopFavoriteMusic.md)
- [Remove from LINGTU music favorites](/en/openapi/unfavorite-music) · [Markdown](/en/openapi/operations/unfavoriteTikTokShopMusic.md)

## GET /v1/creator/tiktokshop/music/favorites

Operation ID: `listTikTokShopFavoriteMusic`

Returns the LINGTU music favorites library for the current company, user and TIKTOK_SHOP platform, newest first. The library is stored by LINGTU and is not a TikTok official favorite. Title matching is case-insensitive. Cover and playback snapshots may expire; publish using the music ID.

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 |
|---|---|---|---|---|
| `pageNumber` | query | integer | No | Page number; default 1 |
| `pageSize` | query | integer | No | Items per page |
| `title` | query | string | No | Title; case-insensitive matching for favorites |

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": "7567668059796720391",
        "platform": "TIKTOK_SHOP",
        "title": "Sunrise",
        "author": "Example artist",
        "duration": "30",
        "coverUrl": "https://cdn.example.com/music-cover.jpg",
        "playUrl": "https://cdn.example.com/music.mp3",
        "favorited": true
      }
    ],
    "total": 1,
    "pageNumber": 1,
    "pageSize": 10,
    "totalPages": 1
  },
  "timestamp": 1790640000000
}
```

### 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 | No | — |
| `message` | string | No | — |
| `data` | object | No | — |
| `data.list` | object[] | No | — |
| `data.list[].id` | string | No | Platform musicId |
| `data.list[].platform` | string | No | For example TIKTOK_SHOP |
| `data.list[].title` | string | No | — |
| `data.list[].author` | string | No | — |
| `data.list[].duration` | string | No | — |
| `data.list[].coverUrl` | string | No | Cover URL snapshot |
| `data.list[].playUrl` | string | No | Playback/preview URL snapshot |
| `data.list[].favorited` | boolean | No | Always true; Fixed value: true |
| `data.total` | integer | No | — |
| `data.pageNumber` | integer | No | — |
| `data.pageSize` | integer | No | — |
| `data.totalPages` | integer | No | — |
| `timestamp` | integer | No | — |

### Integration notes and limits

- The LINGTU favorites library is stored by LINGTU, not by TikTok, and is scoped to the current company, user and TIKTOK_SHOP platform, newest first.
- Cover and playback URLs are snapshots taken when the track was added and may expire; publish with musicId.
- Optional title filters by snapshot title, case-insensitively; an empty title returns the whole library.

### Related endpoints

- [Search TikTok Shop music](/en/openapi/search-music) · [Markdown](/en/openapi/operations/searchTikTokShopMusic.md)
- [Add to LINGTU music favorites](/en/openapi/favorite-music) · [Markdown](/en/openapi/operations/favoriteTikTokShopMusic.md)
- [Remove from LINGTU music favorites](/en/openapi/unfavorite-music) · [Markdown](/en/openapi/operations/unfavoriteTikTokShopMusic.md)

## GET /v1/creatorAccount/tiktokShopOauth/authorize

Operation ID: `createTikTokShopAuthorizationUrl`

Create a TikTok Shop creator authorization URL for a market and shop type. Open the returned url in a browser or render it as a QR code for the creator.

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 |
|---|---|---|---|---|
| `oauthRegion` | query | us_cross \| us_local \| br_local \| br_cross \| mx_local \| mx_cross \| gb_local \| de_local \| de_cross \| fr_local \| fr_cross \| es_local \| es_cross \| it_local \| it_cross \| ie_local \| ie_cross \| jp_local \| jp_cross \| th_local \| th_cross \| my_local \| my_cross \| id_local \| id_cross \| sg_local \| sg_cross \| vn_local \| vn_cross \| ph_local \| ph_cross | Yes | Authorization market and shop type; _local means local shop and _cross means cross-border shop |

### Success response

```json
{
  "code": 0,
  "data": {
    "url": "https://services.tiktokshop.com/open/authorize?service_id=example&state=example"
  },
  "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.url` | string | Yes | TikTok Shop OAuth authorization URL. |
| `timestamp` | integer | No | Response timestamp in milliseconds. |

### Integration notes and limits

- Use us_cross for US cross-border shops and us_local for US local or ACCU shops.
- UK cross-border authorization is no longer available; use gb_local only.
- Request the URL from your server with the API key; never expose the API key in browser code.
- The authorized entity is a TikTok account with commerce permission. After confirming, the page must redirect to the callback URL (for example https://app.ailingtu.com/oauth/tiktokshop); open it in a browser or inside the TikTok app and confirm it shows “SUCCESS/成功”.
- One QR code or authorization URL binds a single account; generate a separate one for each creator account.

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

## GET /v1/creatorAccount/pageList

Operation ID: `listCreatorAccounts`

List authorized TikTok Shop creators, regions, and posting permissions. Use id for product queries and creatorId when creating a post.

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 |
|---|---|---|---|---|
| `pageSize` | query | integer | Yes | Items per page, up to 200 |
| `pageNumber` | query | integer | Yes | Page number, starting at 1 |
| `valid` | query | boolean | No | Return valid authorizations only; defaults to true |
| `authSource` | query | string | No | Use TIKTOK_SHOP_CREATOR for commerce posts |
| `usernames` | query | string[] | No | Repeat the query parameter for multiple usernames |
| `selectionRegion` | query | string | No | Target region, such as US |
| `hasPhotoPermission` | query | boolean | No | Return accounts with shoppable photo permission only |
| `ids` | query | integer[] | No | Account IDs; an empty array returns an empty page. Omission disables this filter; company/member permissions still apply. |
| `username` | query | string | No | Username filter |
| `registerRegion` | query | string | No | Registration region |
| `tagName` | query | string | No | Tag name |

### Success response

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 12345,
        "creatorId": "2077242233106595840",
        "username": "shop_creator",
        "authSource": "TIKTOK_SHOP_CREATOR",
        "oauthRegion": "USA",
        "registerRegion": "US",
        "selectionRegion": "US",
        "targetMarket": "US",
        "valid": true,
        "tagNames": [
          "top-tier"
        ],
        "permissions": [
          "VIDEO_SHOPPABLE_PERMISSION",
          "PHOTO_SHOPPABLE_PERMISSION_PRODUCT"
        ]
      }
    ],
    "total": 1,
    "pageNumber": 1,
    "pageSize": 200,
    "totalPages": 1
  },
  "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.list` | object[] | Yes | — |
| `data.list[].id` | integer | Yes | Account record ID used by the product query endpoints. |
| `data.list[].creatorId` | string | Yes | Creator business ID used when creating publishing tasks. |
| `data.list[].username` | string | Yes | — |
| `data.list[].authSource` | string \| null | Yes | Authorization source; null for older records.; Allowed values: TIKTOK_LOGIN_KIT, TIKTOK_BUSINESS_ACCOUNT_API, TIKTOK_SHOP_CREATOR,  |
| `data.list[].oauthRegion` | string | No | — |
| `data.list[].registerRegion` | string | No | — |
| `data.list[].selectionRegion` | string | No | — |
| `data.list[].targetMarket` | string \| null | No | — |
| `data.list[].valid` | boolean | Yes | — |
| `data.list[].tagNames` | string[] | No | — |
| `data.list[].permissions` | string[] | Yes | — |
| `data.list[].creatorUserId` | string | No | — |
| `data.list[].avatar` | string | No | — |
| `data.list[].sellerType` | string | No | — |
| `data.list[].userType` | string | No | — |
| `data.list[].creatorOpenId` | string | No | — |
| `data.list[].shopId` | integer \| null | No | — |
| `data.list[].shopName` | string \| null | No | — |
| `data.list[].createdAt` | string | No | — |
| `data.list[].managerList` | object[] | No | — |
| `data.list[].managerList[].id` | integer | No | — |
| `data.list[].managerList[].userId` | integer | No | — |
| `data.list[].managerList[].displayName` | string | No | — |
| `data.list[].managerAssigned` | boolean | No | — |
| `data.total` | integer | Yes | — |
| `data.pageNumber` | integer | Yes | — |
| `data.pageSize` | integer | Yes | — |
| `data.totalPages` | integer | No | — |
| `timestamp` | integer | No | Response timestamp in milliseconds. |

### Integration notes and limits

- For commerce videos, permissions containing both LIVE_STREAM_PERMISSION and SELF_SALE_PERMISSION guarantees video commerce permission.
- Photo posts require PHOTO_SHOPPABLE_PERMISSION_PRODUCT or PHOTO_SHOPPABLE_PERMISSION_SHOP in permissions; without either, the account has no photo publishing permission.
- Business authorization sources, bound shops and account managers are included in account data.

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

## GET /v1/creator/tiktokshop/product/listByShowcase

Operation ID: `listTikTokShowcaseProducts`

List products in a creator showcase. Use SHOWCASE as the product source when creating a post.

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` | query | integer | Yes | Creator account id |
| `origin` | query | LIVE \| SHOWCASE | Yes | Product source: LIVE or SHOWCASE |
| `pageSize` | query | integer | Yes | Items per page |
| `pageToken` | query | string | No | Pagination token from the previous response |

### Success response

```json
{
  "code": 0,
  "data": {
    "products": [
      {
        "id": "1732280564607717841",
        "title": "Summer Vibes Cord",
        "price": {
          "amount": "19.99",
          "currency": "USD"
        },
        "images": [
          {
            "url": "https://cdn.example.com/product.jpg",
            "width": 800,
            "height": 800
          }
        ]
      }
    ],
    "nextPageToken": "",
    "totalCount": 1
  },
  "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.products` | object[] | Yes | — |
| `data.products[].id` | string | Yes | — |
| `data.products[].title` | string | Yes | — |
| `data.products[].price` | union | No | — |
| `data.products[].images` | object[] | No | — |
| `data.products[].images[].url` | string | Yes | — |
| `data.products[].images[].width` | integer | No | — |
| `data.products[].images[].height` | integer | No | — |
| `data.products[].shop` | object | No | — |
| `data.products[].shop.name` | string | Yes | — |
| `data.products[].addition` | null | No | — |
| `data.products[].mainImages` | object[] | No | — |
| `data.products[].mainImages[].width` | integer \| null | Yes | — |
| `data.products[].mainImages[].height` | integer \| null | Yes | — |
| `data.products[].mainImages[].url` | string | Yes | — |
| `data.products[].status` | object | No | — |
| `data.products[].status.inventoryStatus` | string | Yes | — |
| `data.products[].status.reviewStatus` | string | Yes | — |
| `data.products[].status.isHidden` | boolean | Yes | — |
| `data.products[].status.addedStatus` | string | Yes | — |
| `data.products[].source` | string | No | — |
| `data.products[].detailLink` | null | No | — |
| `data.products[].thirdPartyLink` | null | No | — |
| `data.products[].saleRegions` | array \| null | No | — |
| `data.products[].commission` | object | No | — |
| `data.products[].commission.rate` | integer | Yes | — |
| `data.products[].commission.rewardRate` | null | Yes | — |
| `data.products[].collaboration` | object | No | — |
| `data.products[].collaboration.id` | string | Yes | — |
| `data.products[].collaboration.type` | string | Yes | — |
| `data.products[].collaboration.partner` | null | Yes | — |
| `data.nextPageToken` | string | Yes | — |
| `data.totalCount` | integer | Yes | — |

### Integration notes and limits

- This endpoint does not accept titleKeyword. Filter by title on the client when needed.

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

## GET /v1/creator/tiktokshop/searchMusic

Operation ID: `searchTikTokShopMusic`

Search TikTok Shop music available to a creator. Reuse searchId and nextPageToken for subsequent pages.

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` | query | integer | Yes | Creator account ID |
| `keyword` | query | string | Yes | Music search keyword |
| `language` | query | string | No | Language tag in BCP 47 format |
| `pageSize` | query | integer | Yes | Items per page |
| `pageToken` | query | string \| null | No | Pagination token; send null or omit it for the first request |
| `region` | query | string | No | Region code in ISO 3166-1 alpha-2 format |
| `searchId` | query | string | No | Search session ID returned by the first request; reuse it for pagination |

### Success response

```json
{
  "code": 0,
  "data": {
    "music": [
      {
        "id": "7567668059796720391",
        "title": "original sound",
        "author": "Ivan",
        "duration": "15",
        "coverThumb": {
          "urlList": [
            "https://cdn.example.com/music-cover.jpg"
          ]
        },
        "playUrl": {
          "urlList": [
            "https://cdn.example.com/music-preview.mp3"
          ]
        },
        "favorited": false
      }
    ],
    "nextPageToken": "next_page_token",
    "hasMore": true,
    "searchId": "music_search_xxx"
  },
  "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.music` | object[] | Yes | — |
| `data.music[].id` | string | Yes | — |
| `data.music[].title` | string | Yes | — |
| `data.music[].author` | string | Yes | — |
| `data.music[].duration` | string | Yes | — |
| `data.music[].coverThumb` | object | Yes | — |
| `data.music[].coverThumb.urlList` | string[] | Yes | — |
| `data.music[].playUrl` | object | Yes | — |
| `data.music[].playUrl.urlList` | string[] | Yes | — |
| `data.music[].favorited` | boolean | No | Whether the track is in the LINGTU music favorites library (stored by LINGTU, not a TikTok official favorite) |
| `data.nextPageToken` | string | Yes | — |
| `data.hasMore` | boolean | Yes | — |
| `data.searchId` | string | Yes | — |
| `timestamp` | integer | No | Response timestamp in milliseconds. |

### Integration notes and limits

- Omit pageToken and searchId on the first request; for pagination, use nextPageToken and searchId from the response.
- favorited reflects the LINGTU favorites library (not a TikTok official favorite), scoped to the current company, user and TIKTOK_SHOP platform. Use listTikTokShopFavoriteMusic for the default music list.

### 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 LINGTU music favorites](/en/openapi/favorite-music-list) · [Markdown](/en/openapi/operations/listTikTokShopFavoriteMusic.md)
- [Add to LINGTU music favorites](/en/openapi/favorite-music) · [Markdown](/en/openapi/operations/favoriteTikTokShopMusic.md)
- [Create a publishing task](/en/openapi/create-post) · [Markdown](/en/openapi/operations/createCreatorPost.md)
- [Update a publishing task](/en/openapi/update-post) · [Markdown](/en/openapi/operations/updateCreatorPost.md)

## POST /v1/creator/tiktokshop/product/addToShowcase

Operation ID: `addTikTokShowcaseProducts`

Add TikTok Shop products to an authorized creator showcase by product IDs or a product link.

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 |
| `addType` | body | PRODUCT_ID \| PRODUCT_LINK | Yes | How products are identified |
| `productIds` | body | string[] | Conditional | Required for PRODUCT_ID; 1–20 product IDs |
| `productLink` | body | string(uri) | Conditional | Required for PRODUCT_LINK |

Request format: `application/json`

### Request example: Add by product ID

```json
{
  "id": 12345,
  "addType": "PRODUCT_ID",
  "productIds": [
    "1732280564607717841",
    "1732280564607717842"
  ]
}
```

### Request example: Add by product link

```json
{
  "id": 12345,
  "addType": "PRODUCT_LINK",
  "productLink": "https://shop.tiktok.com/view/product/1732280564607717841"
}
```

### Success response: All products added

```json
{
  "code": 0,
  "data": {},
  "message": "success",
  "timestamp": 1786406400000
}
```

### Success response: Some products failed

```json
{
  "code": 0,
  "data": {
    "errors": [
      {
        "code": 16001001,
        "message": "Product is unavailable for this creator",
        "detail": {
          "productId": "1732280564607717842"
        }
      }
    ]
  },
  "message": "success",
  "timestamp": 1786406400000
}
```

### Success response: Creator authorization expired

```json
{
  "code": 40101,
  "data": {},
  "message": "授权过期，请重新授权",
  "timestamp": 1786406400000
}
```

### 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 | Business status code. 0 means the request was processed; still check the per-product results. |
| `data` | object | Yes | — |
| `data.errors` | object[] | No | Per-product failures; empty or omitted when every product was added. |
| `data.errors[].code` | integer | No | — |
| `data.errors[].message` | string | No | — |
| `data.errors[].detail` | object | No | — |
| `data.errors[].detail.productId` | string | No | Product ID that failed to be added. |
| `message` | string | Yes | — |
| `timestamp` | integer | Yes | Unix timestamp in milliseconds. |

### Integration notes and limits

- Required scopes: creator.showcase.write and creator.video.write.
- A request can contain at most 20 product IDs.
- Check data.errors even when code is 0; entries identify products that failed.
- An expired creator authorization returns the business error “授权过期，请重新授权” (authorization expired, reauthorize).

### 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 showcase products](/en/openapi/showcase-products) · [Markdown](/en/openapi/operations/listTikTokShowcaseProducts.md)
- [Creator TTS - Remove showcase products](/en/openapi/remove-showcase-products) · [Markdown](/en/openapi/operations/removeTikTokShowcaseProducts.md)
- [Creator TTS - Move showcase products to top](/en/openapi/move-showcase-products-to-top) · [Markdown](/en/openapi/operations/moveTikTokShowcaseProductsToTop.md)

## POST /v1/creator/tiktokshop/product/removeFromShowcase

Operation ID: `removeTikTokShowcaseProducts`

Remove TikTok Shop products from an authorized creator showcase by product IDs.

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 |
| `productIds` | body | string[] | Yes | Product IDs to remove; 1–200 entries |

Request format: `application/json`

### Request example

```json
{
  "id": 12345,
  "productIds": [
    "12390753231",
    "7102893481290"
  ]
}
```

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": null,
  "timestamp": 1790640000000
}
```

### 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 | Business status code. 0 indicates success. |
| `message` | string | Yes | — |
| `data` | null | Yes | This endpoint returns no business data. |
| `timestamp` | integer | Yes | Unix timestamp in milliseconds. |

### Integration notes and limits

- Required scope: creator.showcase.write.
- A request can remove up to 200 product IDs.
- data is null on success; this endpoint has no per-product result.
- Platform error 16015001 becomes “商品已不在橱窗中，请刷新列表后重试” (the product is no longer in the showcase; refresh and retry).
- Platform error 16015027 is returned as-is and can be retried.
- An expired creator authorization returns “授权过期，请重新授权” (authorization expired, reauthorize) and marks the account invalid; a missing scope returns “该达人未授予此功能需要的权限” (the creator has not granted the required permission) without invalidating the account.

### 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 showcase products](/en/openapi/showcase-products) · [Markdown](/en/openapi/operations/listTikTokShowcaseProducts.md)
- [Creator TTS - Add showcase products](/en/openapi/add-showcase-products) · [Markdown](/en/openapi/operations/addTikTokShowcaseProducts.md)
- [Creator TTS - Move showcase products to top](/en/openapi/move-showcase-products-to-top) · [Markdown](/en/openapi/operations/moveTikTokShowcaseProductsToTop.md)

## POST /v1/creator/tiktokshop/product/moveToTopInShowcase

Operation ID: `moveTikTokShowcaseProductsToTop`

Move products that are already in an authorized creator showcase to the top in array order.

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 |
| `productIds` | body | string[] | Yes | Product IDs already in the showcase, pinned in array order |

Request format: `application/json`

### Request example

```json
{
  "id": 12345,
  "productIds": [
    "12390753231",
    "7102893481290"
  ]
}
```

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": null,
  "timestamp": 1790640000000
}
```

### 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 | Business status code. 0 indicates success. |
| `message` | string | Yes | — |
| `data` | null | Yes | This endpoint returns no business data. |
| `timestamp` | integer | Yes | Unix timestamp in milliseconds. |

### Integration notes and limits

- Required scope: creator.showcase.write.
- productIds must already be in the showcase; products are pinned in array order.
- data is null on success; this endpoint has no per-product result.
- Platform error 16015001 becomes “商品已不在橱窗中，请刷新列表后重试” (the product is no longer in the showcase; refresh and retry).
- Platform error 16015027 is returned as-is and can be retried.
- An expired creator authorization returns 授权过期，请重新授权 and marks the account invalid; a missing scope returns a permission error without invalidating the account.

### 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 showcase products](/en/openapi/showcase-products) · [Markdown](/en/openapi/operations/listTikTokShowcaseProducts.md)
- [Creator TTS - Add showcase products](/en/openapi/add-showcase-products) · [Markdown](/en/openapi/operations/addTikTokShowcaseProducts.md)
- [Creator TTS - Remove showcase products](/en/openapi/remove-showcase-products) · [Markdown](/en/openapi/operations/removeTikTokShowcaseProducts.md)

## POST /v1/shop/material/batchAdd

Operation ID: `batchAddShopMaterials`

Batch add video materials to a shop using video URLs.

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 |
|---|---|---|---|---|
| `thirdShopId` | body | string | Yes | Shop ID |
| `videoUrls` | body | string[] | No | List of video URLs |

Request format: `application/json`

### Request example

```json
{
  "thirdShopId": "66",
  "videoUrls": [
    "https://www.tiktok.com/@vacbird.fr/video/7513181869366725910"
  ]
}
```

### Success response

```json
{
  "code": 0,
  "message": "success",
  "timestamp": 0,
  "data": null
}
```

### 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 | — |
| `message` | string | Yes | — |
| `timestamp` | integer | Yes | — |
| `data` | null | Yes | — |

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

## POST /v1/file/presign

Operation ID: `createFileUpload`

Submit file metadata and the compatible hash to receive a fileId and object-storage URL. Skip upload and confirmation when isNew is false.

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 |
|---|---|---|---|---|
| `fileName` | body | string | Yes | File name including extension |
| `contentType` | body | string | Yes | File MIME type |
| `size` | body | integer | Yes | File size in bytes |
| `hash` | body | string | Yes | SHA-256 of the UTF-8 encoded lowercase hex representation of the file bytes |

Request format: `application/json`

### Request example

```json
{
  "fileName": "video.mp4",
  "contentType": "video/mp4",
  "size": 12345678,
  "hash": "3786a02b..."
}
```

### Success response

```json
{
  "code": 0,
  "data": {
    "fileId": 591,
    "uploadUrl": "https://object-storage.example.com/presigned-url",
    "url": "https://cdn.ailingtu.com/media/video.mp4",
    "isNew": true,
    "expiresAt": "2026-07-29T12:00:00Z"
  },
  "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.fileId` | union | Yes | — |
| `data.uploadUrl` | string \| null | No | — |
| `data.url` | string | Yes | — |
| `data.isNew` | boolean | Yes | — |
| `data.expiresAt` | string \| null | No | — |

### Integration notes and limits

- When isNew is true, PUT the raw file to uploadUrl with the same Content-Type, then call confirm.
- Do not send x-api-key to the object-storage PUT URL.

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

## POST /v1/file/confirm

Operation ID: `confirmFileUpload`

Call only after a new file is successfully PUT to its presigned URL. Deduplicated files do not require confirmation.

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 |
|---|---|---|---|---|
| `fileId` | body | integer \| string | Yes | File ID returned by the presign endpoint |

Request format: `application/json`

### Request example

```json
{
  "fileId": 591
}
```

### Success response

```json
{
  "code": 0,
  "data": {
    "fileId": 591,
    "confirmed": true
  },
  "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 \| null | No | — |
| `data.fileId` | union | No | — |
| `data.confirmed` | boolean | No | — |

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

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

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

## POST /v1/creator/post/submit

Operation ID: `submitCreatorPost`

Submit an existing commerce video publishing task immediately using its postId.

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 |
|---|---|---|---|---|
| `postId` | body | string | Yes | Publishing task ID from task creation or publishing records; pass it as a string |

Request format: `application/json`

### Request example

```json
{
  "postId": "2098014809185456128"
}
```

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": null,
  "timestamp": 1790640000000
}
```

### 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 |
| `data` | null | Yes | — |
| `message` | string | Yes | — |
| `timestamp` | integer | No | Response timestamp in milliseconds. |

### Integration notes and limits

- This operation triggers publishing; verify the task identified by postId before submitting.
- Successful submission returns code=0 and data=null; check publishing records for the final status.

### 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)
- [List publishing records](/en/openapi/post-records) · [Markdown](/en/openapi/operations/listCreatorPosts.md)

## POST /v1/creator/post/cancel

Operation ID: `cancelCreatorPost`

Cancel a publishing task that has not reached a terminal state by using its postId.

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 |
|---|---|---|---|---|
| `postId` | body | string | Yes | postId returned when the publishing task was created |

Request format: `application/json`

### Request example

```json
{
  "postId": "post_xxx"
}
```

### Success response

```json
{
  "code": 0,
  "data": null,
  "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 |
| `data` | null | Yes | — |
| `message` | string | Yes | — |
| `timestamp` | integer | No | Response timestamp in milliseconds. |

### Integration notes and limits

- A completed, failed, or already cancelled task cannot be cancelled again.

### 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 publishing records](/en/openapi/post-records) · [Markdown](/en/openapi/operations/listCreatorPosts.md)

## POST /v1/creator/post/update

Operation ID: `updateCreatorPost`

Update the caption, schedule, TikTok publishing settings, and TikTok Shop product, music, and cover settings of an editable task.

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 |
|---|---|---|---|---|
| `postId` | body | string | Yes | Publishing task ID |
| `scheduledAt` | body | integer | Yes | Unix epoch in milliseconds |
| `scheduledTz` | body | string | Yes | IANA timezone |
| `title` | body | string | Yes | Post caption |
| `tiktok` | body | object | Conditional | TikTok publishing settings |
| `tiktok.aigc` | body | boolean | Conditional | Whether to label the content as AI-generated |
| `tiktok.brandContentToggle` | body | boolean | Conditional | Branded-content toggle |
| `tiktok.brandOrganicToggle` | body | boolean | Conditional | Organic branded-content toggle |
| `tiktok.coverTimestampMs` | body | integer | Conditional | Cover frame timestamp in milliseconds |
| `tiktok.disableComment` | body | boolean | Conditional | Whether comments are disabled |
| `tiktok.disableDuet` | body | boolean | Conditional | Whether Duet is disabled |
| `tiktok.disableStitch` | body | boolean | Conditional | Whether Stitch is disabled |
| `tiktok.privacyLevel` | body | string | Conditional | TikTok privacy level |
| `tiktokshop` | body | object | Conditional | TikTok Shop publishing settings |
| `tiktokshop.coverTimestampMs` | body | integer | Conditional | Cover frame timestamp in milliseconds |
| `tiktokshop.coverUri` | body | string | Conditional | Custom cover URI |
| `tiktokshop.musicInfo` | body | object | Conditional | Music information |
| `tiktokshop.preCheck` | body | boolean | Conditional | Whether to submit a pre-check before publishing |
| `tiktokshop.productInfo` | body | object | Conditional | Product anchor information |
| `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. |
| `businessId` | body | string | No | Replacement original URL for an existing EXTERNAL_URL video task |
| `coverFileId` | body | integer \| string | No | Custom video cover file ID |
| `tiktokshop.preCheckOvertime` | body | integer | Conditional | Pre-check timeout, 600–3600 seconds |
| `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

```json
{
  "postId": "post_xxx",
  "scheduledAt": 1787752245233,
  "scheduledTz": "America/New_York",
  "title": "Updated commerce video caption",
  "tiktok": {
    "aigc": false,
    "brandContentToggle": false,
    "brandOrganicToggle": false,
    "coverTimestampMs": 1500,
    "disableComment": false,
    "disableDuet": false,
    "disableStitch": false,
    "privacyLevel": "PUBLIC_TO_EVERYONE"
  },
  "tiktokshop": {
    "coverTimestampMs": 1500,
    "coverUri": "tos-useast5-i-photomode-tx/example-cover-uri",
    "musicInfo": {
      "author": "Ivan",
      "id": "7567668059796720391",
      "title": "original sound"
    },
    "preCheck": false,
    "productInfo": {
      "productId": "1729452608393351351",
      "source": "SHOWCASE",
      "title": "Womens midlength Tshirt"
    }
  }
}
```

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

- Only publishing tasks that are still editable can be updated.
- 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.
- Only cancelled or failed tasks can be updated. businessType is immutable. Existing EXTERNAL_URL video tasks can replace businessId with a new URL; remote MP4 validation runs only when the trimmed URL SHA-256 changes.

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

- [Search TikTok Shop music](/en/openapi/search-music) · [Markdown](/en/openapi/operations/searchTikTokShopMusic.md)
- [Cancel a publishing task](/en/openapi/cancel-post) · [Markdown](/en/openapi/operations/cancelCreatorPost.md)
- [List publishing records](/en/openapi/post-records) · [Markdown](/en/openapi/operations/listCreatorPosts.md)

## GET /v1/creator/post/pageList

Operation ID: `listCreatorPosts`

List paginated TikTok and TikTok Shop publishing records to track status and read platform post IDs, failure reasons, media, product, and scheduling details.

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 |
|---|---|---|---|---|
| `pageSize` | query | integer | Yes | Items per page, up to 200 |
| `pageNumber` | query | integer | Yes | Page number, starting at 1 |
| `beginTime` | query | integer | No | Scheduled publishing time start (inclusive), as a 13-digit Unix timestamp in milliseconds; can be provided independently. Example: 1789056000000 |
| `endTime` | query | integer | No | Scheduled publishing time end (inclusive), as a 13-digit Unix timestamp in milliseconds; can be provided independently. Example: 1789142399999 |
| `status` | query | WAITING_SUBMIT \| SUBMITTING \| PRE_CHECK_SUBMITTING \| PRE_CHECK \| PRE_CHECK_PASSED \| PRE_CHECK_REJECTED \| PENDING \| PROCESSING \| SUCCESS \| COMPLETED \| FAILED \| CANCELLED \| SUBMIT_FAILED | No | Publishing status |
| `postId` | query | string | No | LINGTU publishing task ID |
| `title` | query | string | No | Post title or caption keyword |
| `creatorUsername` | query | string | No | TikTok creator username |
| `platform` | query | TIKTOK \| TIKTOK_SHOP \| TIKTOK_BUSINESS | No | Publishing platform |
| `managerIds` | query | integer[] | No | Account manager IDs; repeat the query parameter for multiple values |
| `noManager` | query | boolean | No | Return accounts without an assigned manager only |

### Success response

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 100,
        "postId": "post_xxx",
        "platform": "TIKTOK_SHOP",
        "title": "Summer Sale 2026 #summer",
        "videoUrl": "https://cdn.ailingtu.com/media/video.mp4",
        "coverUrl": "https://cdn.ailingtu.com/media/video-cover.jpg",
        "reason": null,
        "remark": null,
        "platformPostId": "7541234567890123456",
        "scheduledAt": 1784896665989,
        "scheduledTz": "America/New_York",
        "publishedAt": 1784896765989,
        "status": "COMPLETED",
        "creatorUsername": "shop_creator",
        "createdByName": "Operations Team",
        "productInfo": {
          "productId": "1732280564607717841",
          "title": "Summer Vibes Cord",
          "source": "SHOP"
        },
        "productLinks": null,
        "musicInfo": {
          "id": "7567668059796720391",
          "title": "original sound",
          "author": "Ivan",
          "duration": "15"
        },
        "materialType": "VIDEO",
        "mediaType": "VIDEO",
        "shopMaterialId": null
      }
    ],
    "total": 1,
    "pageNumber": 1,
    "pageSize": 10,
    "totalPages": 1
  },
  "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.list` | object[] | Yes | — |
| `data.list[].id` | union | Yes | — |
| `data.list[].postId` | string | Yes | — |
| `data.list[].platform` | string | Yes | Allowed values: TIKTOK_SHOP, TIKTOK, TIKTOK_BUSINESS |
| `data.list[].title` | string | Yes | — |
| `data.list[].videoUrl` | string \| null | No | — |
| `data.list[].coverUrl` | string \| null | No | — |
| `data.list[].reason` | string \| null | No | — |
| `data.list[].remark` | string \| null | No | — |
| `data.list[].platformPostId` | string \| null | No | — |
| `data.list[].scheduledAt` | union | No | — |
| `data.list[].scheduledTz` | string \| null | No | — |
| `data.list[].publishedAt` | integer \| string \| null | No | Publish time; the response may return a timestamp or a date string. |
| `data.list[].status` | string | Yes | Allowed values: WAITING_SUBMIT, SUBMITTING, PRE_CHECK_SUBMITTING, PRE_CHECK, PRE_CHECK_PASSED, PRE_CHECK_REJECTED, PENDING, PROCESSING, SUCCESS, COMPLETED, FAILED, CANCELLED, SUBMIT_FAILED |
| `data.list[].creatorUsername` | string | Yes | — |
| `data.list[].createdByName` | string \| null | No | — |
| `data.list[].productInfo` | union | No | — |
| `data.list[].productLinks` | union | No | — |
| `data.list[].musicInfo` | union | No | — |
| `data.list[].materialType` | string \| null | No | — |
| `data.list[].mediaType` | string \| null | No | — |
| `data.list[].shopMaterialId` | union | No | — |
| `data.list[].snapshot` | object \| null | No | Original media snapshot saved when the publishing task was created. Null for older records or tasks without files. PHOTO returns every source file. |
| `data.list[].snapshot.sourceFiles` | object[] | No | Source files. VIDEO has one file; PHOTO returns every file in the original order. |
| `data.total` | integer | Yes | — |
| `data.pageNumber` | integer | Yes | — |
| `data.pageSize` | integer | Yes | — |
| `data.totalPages` | integer | Yes | — |
| `timestamp` | integer | No | Response timestamp in milliseconds. |

### Integration notes and limits

- The minimal request only needs pageSize and pageNumber, for example ?pageSize=10&pageNumber=1.
- Task creation does not mean platform publishing is complete. Persist postId and use this endpoint to verify the final status.
- SUCCESS, COMPLETED, and PRE_CHECK_PASSED are success-like states; FAILED, SUBMIT_FAILED, and PRE_CHECK_REJECTED are failure-like states.
- When both beginTime and endTime are supplied, beginTime must not exceed endTime and the interval is at most 90 days. snapshot preserves original source files and may be null for older records; photo files retain their order.

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

- [Publish a commerce video immediately](/en/openapi/submit-post) · [Markdown](/en/openapi/operations/submitCreatorPost.md)
- [Update a publishing task](/en/openapi/update-post) · [Markdown](/en/openapi/operations/updateCreatorPost.md)
- [Cancel a publishing task](/en/openapi/cancel-post) · [Markdown](/en/openapi/operations/cancelCreatorPost.md)

## POST /v1/ai/schedule/create

Operation ID: `createAiGenerationSchedule`

Create scheduled AI image or video generation tasks with prompts, references, model options, dimensions, and output count. Use the returned scheduleId to query status and assets.

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 |
|---|---|---|---|---|
| `taskId` | body | string | No | Caller-generated task identifier; an 8-character lowercase alphanumeric value is recommended |
| `type` | body | IMAGE_GENERATION \| VIDEO_GENERATION | Yes | Media generation type |
| `params.prompt` | body | string | Yes | Image or video generation prompt |
| `params.model` | body | gpt-image-2 \| nano-banana-2 \| nano-banana-2-2k \| nano-banana-2-4k \| seedream5.0-lite \| gemini-omni-video \| veo3.1-lite-extend \| veo3.1-extend \| grok-imagine-1.5 \| seedance2.0-mini \| seedance2.0 \| seedance2.0-fast | Yes | Select one of the image or video models listed below, matching type |
| `params.aspectRatio` | body | string | Conditional | Required for images, for example 1:1 or 9:16 |
| `params.seconds` | body | integer | Conditional | Video duration; allowed values depend on the model |
| `params.size` | body | string | Conditional | Video dimensions, for example 720x1280 |
| `params.inputReference` | body | string(uri) | No | One remote reference image URL, primarily for video generation |
| `params.inputReferences` | body | string(uri)[] | No | Ordered remote reference image URLs; data URLs are not supported |
| `params.watermark` | body | boolean | No | Whether to add a video watermark; defaults to false |
| `nums` | body | integer | Yes | Number of outputs; use 1 unless multiple results are needed |
| `businessId` | body | string | No | Optional related business object ID |
| `businessType` | body | MERCHANT_SKU \| AI_PURCHASE_TASK | No | Related business object type |
| `promptId` | body | string | No | Saved prompt ID |
| `execAt` | body | string(date-time) | No | ISO 8601 execution time; omit to create immediately |
| `name` | body | string | No | Display name for the generation schedule |

Request format: `application/json`

### Request example: Generate image

```json
{
  "taskId": "img8a1b2",
  "type": "IMAGE_GENERATION",
  "params": {
    "prompt": "A clean product hero image on a bright studio background",
    "model": "gpt-image-2",
    "aspectRatio": "1:1",
    "inputReferences": [
      "https://static.ailingtu.com/ai-images/product-reference.jpg"
    ]
  },
  "nums": 1,
  "name": "Product hero image"
}
```

### Request example: Generate video

```json
{
  "taskId": "vid8c3d4",
  "type": "VIDEO_GENERATION",
  "params": {
    "prompt": "A clean 10-second product reveal video with a slow camera push-in",
    "model": "gemini-omni-video",
    "seconds": 10,
    "size": "720x1280",
    "inputReferences": [
      "https://static.ailingtu.com/ai-images/product-reference.jpg"
    ],
    "watermark": false
  },
  "nums": 1,
  "name": "Product reveal video"
}
```

### Success response

```json
{
  "code": 0,
  "data": {
    "scheduleId": "schedule_01k1example",
    "taskIds": [
      "task_01k1example"
    ]
  },
  "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.scheduleId` | string | Yes | — |
| `data.taskIds` | string[] | No | — |

### Integration notes and limits

- Image models: gpt-image-2, nano-banana-2, nano-banana-2-2k, nano-banana-2-4k, seedream5.0-lite.
- Video models: gemini-omni-video, veo3.1-lite-extend, veo3.1-extend, grok-imagine-1.5, seedance2.0-mini, seedance2.0, seedance2.0-fast.
- Video durations: gemini-omni-video supports 6/8/10s; veo3.1-lite-extend and veo3.1-extend are fixed at 8s; grok-imagine-1.5 supports 6/10/15/20/25/30s; seedance2.0-mini, seedance2.0, and seedance2.0-fast support 4/8/10/12/15s.
- For images, use IMAGE_GENERATION with params.aspectRatio. For videos, use VIDEO_GENERATION with params.seconds and params.size.
- References must be accessible http/https URLs. Upload local files before passing their URLs.
- scheduleId and taskId are different. Query the same scheduleId after creation and do not recreate a task only because polling was interrupted.

### 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 AI generation tasks](/en/openapi/schedule-tasks) · [Markdown](/en/openapi/operations/listAiTasksByScheduleId.md)

## GET /v1/ai/task/listByScheduleId

Operation ID: `listAiTasksByScheduleId`

List image or video generation tasks using the scheduleId returned at creation. Poll about every five seconds until tasks complete or explicitly fail.

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 |
|---|---|---|---|---|
| `scheduleId` | query | string | Yes | scheduleId returned when the generation schedule was created |

### Success response

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "taskId": "task_01k1example",
        "scheduleId": "schedule_01k1example",
        "type": "VIDEO_GENERATION",
        "status": "COMPLETED",
        "model": "gemini-omni-video",
        "params": {
          "prompt": "A clean 10-second product reveal video with a slow camera push-in",
          "model": "gemini-omni-video",
          "seconds": 10,
          "size": "720x1280"
        },
        "result": {
          "url": "https://static.ailingtu.com/ai-videos/result.mp4",
          "thumbnailUrl": "https://static.ailingtu.com/ai-images/cover.jpg"
        },
        "customResult": {
          "videoUrl": "https://static.ailingtu.com/ai-videos/result.mp4",
          "coverUrl": "https://static.ailingtu.com/ai-images/cover.jpg"
        },
        "createdAt": "2026-08-10T10:00:00Z"
      }
    ],
    "total": 1,
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 1
  },
  "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.list` | object[] | Yes | — |
| `data.list[].taskId` | string | Yes | — |
| `data.list[].scheduleId` | string | No | — |
| `data.list[].type` | string | Yes | Allowed values: IMAGE_GENERATION, VIDEO_GENERATION |
| `data.list[].status` | string | Yes | Allowed values: WAITING_SUBMIT, SUBMITTING, SUBMIT_FAILED, PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED, EXPIRED |
| `data.list[].model` | string | No | — |
| `data.list[].params` | union | No | — |
| `data.list[].result` | object | No | — |
| `data.list[].result.url` | string | No | — |
| `data.list[].result.resultUrl` | string | No | — |
| `data.list[].result.videoUrl` | string | No | — |
| `data.list[].result.thumbnailUrl` | string | No | — |
| `data.list[].resultUrl` | string | No | — |
| `data.list[].customResult` | object | No | — |
| `data.list[].customResult.videoUrl` | string | No | — |
| `data.list[].customResult.coverUrl` | string | No | — |
| `data.list[].reason` | string \| null | No | — |
| `data.list[].createdAt` | string | No | — |
| `data.list[].finishTime` | string \| null | No | — |
| `data.total` | integer | No | — |
| `data.pageNumber` | integer | No | — |
| `data.pageSize` | integer | No | — |
| `data.totalPages` | integer | No | — |

### Integration notes and limits

- Waiting states include WAITING_SUBMIT, SUBMITTING, PENDING, and PROCESSING. COMPLETED is successful.
- Retry only after an explicit failure, cancellation, or expiration. A network or polling-process error does not mean generation failed.
- For videos, prefer customResult.videoUrl or result.url. Images usually use result.url or resultUrl.

### 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 an AI image or video schedule](/en/openapi/schedule-create) · [Markdown](/en/openapi/operations/createAiGenerationSchedule.md)

## GET /v1/influencer/fetchPosts

Operation ID: `fetchTikTokCreatorPosts`

Fetch a public TikTok creator profile and recent post views, likes, comments, shares, and saves for creator analysis or monitoring.

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: Check the HTTP status and the matching response structure.

### Request parameters

| Field | Location | Type | Required | Description |
|---|---|---|---|---|
| `uniqueId` | query | string | Yes | TikTok creator username without the leading @ |
| `count` | query | integer | No | Number of recent posts to return; defaults to 40 |

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "authorInfo": {
      "id": "6614519312189947909",
      "uniqueId": "vacbirdusa",
      "nickname": "Vacbird",
      "signature": "Product finds and everyday solutions",
      "followerCount": 101037,
      "followingCount": 29,
      "awemeCount": 2573,
      "totalFavorited": 644435
    },
    "posts": [
      {
        "videoId": "7634589785687854366",
        "desc": "A useful product find #musthave",
        "createTime": 1777662000,
        "duration": 18100,
        "isAd": false,
        "cover": "https://cdn.example.com/tiktok-cover.jpg",
        "stats": {
          "playCount": 10844609,
          "diggCount": 46314,
          "commentCount": 552,
          "shareCount": 16457,
          "collectCount": 16257,
          "repostCount": 0
        }
      }
    ],
    "cursor": "1",
    "hasMore": true
  },
  "timestamp": 1787417005
}
```

### Integration notes and limits

- This operation currently returns TikTok creator data. Do not infer accounts on other platforms from matching usernames.
- Treat the request as successful only when HTTP is 200 and code is 0. code -1 means no public creator posts were available.
- To generate an AI creator report, turn this response into evidence and send it to /v1/relay/chat/completions.

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

- [AI Model API](/en/openapi/ai-model-api) · [Markdown](/en/openapi/operations/createRelayChatCompletion.md)

## GET /v1/influencer/ins/fetchPosts

Operation ID: `fetchInstagramCreatorPosts`

Fetch a public Instagram profile and recent posts for creator analysis and content benchmarking.

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: Check the HTTP status and the matching response structure.

### Request parameters

| Field | Location | Type | Required | Description |
|---|---|---|---|---|
| `uniqueId` | query | string | Yes | Instagram username without the leading @ |
| `count` | query | integer | No | Number of recent posts to return; defaults to 40 |

### Success response

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "author": {
      "id": "1234567890",
      "username": "creator",
      "fullName": "Creator",
      "biography": "Product reviews and daily finds",
      "followerCount": 45200,
      "followingCount": 318,
      "postCount": 604
    },
    "posts": [
      {
        "postId": "3456789012345678901",
        "shortCode": "ExampleCode",
        "caption": "A quick product demo #productreview",
        "takenAtTimestamp": 1787000000,
        "videoDuration": 18.4,
        "isVideo": true,
        "videoPlayCount": 128400,
        "videoViewCount": 128400,
        "likeCount": 6200,
        "commentCount": 184,
        "displayUrl": "https://cdn.example.com/instagram-cover.jpg",
        "videoUrl": "https://cdn.example.com/instagram-video.mp4"
      }
    ],
    "endCursor": "QVFEexample",
    "hasMore": true
  },
  "timestamp": 1787417005
}
```

### Integration notes and limits

- Image and carousel posts may not have video views, and list data can omit some engagement fields. Do not interpret missing metrics as poor performance.
- Treat the request as successful only when HTTP is 200 and code is 0. code -1 means no public creator posts were available.
- To generate an AI creator report, turn this response into evidence and send it to /v1/relay/chat/completions.

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

- [AI Model API](/en/openapi/ai-model-api) · [Markdown](/en/openapi/operations/createRelayChatCompletion.md)

## POST /v1/material/fetch

Operation ID: `fetchPublicVideoData`

Fetch public video views and engagement metrics from TikTok, Instagram, Douyin, Xiaohongshu, WeChat Channels, and YouTube.

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 |
|---|---|---|---|---|
| `videoUrl` | body | string(uri) | Yes | Public http/https URL of the content |

Request format: `application/json`

### Request example

```json
{
  "videoUrl": "https://www.tiktok.com/@creator/video/7123456789012345678"
}
```

### Success response

```json
{
  "code": 0,
  "data": {
    "videoId": "7624922739500993822",
    "uniqueId": "creator",
    "playCount": 2109422,
    "diggCount": 143027,
    "commentCount": 1320,
    "shareCount": 36150,
    "collectCount": 17710,
    "coverUrl": "https://cdn.example.com/cover.jpg",
    "videoDesc": "caption #tag",
    "releaseAt": 1775315687
  },
  "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 | Normalized fields plus platform-specific public content fields. |
| `data.videoId` | string | No | — |
| `data.uniqueId` | string | No | — |
| `data.playCount` | integer | No | — |
| `data.diggCount` | integer | No | — |
| `data.commentCount` | integer | No | — |
| `data.shareCount` | integer | No | — |
| `data.collectCount` | integer | No | — |
| `data.coverUrl` | string | No | — |
| `data.videoDesc` | string | No | — |
| `data.releaseAt` | integer | No | — |

### 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. |
| 404 | The public post does not exist or has been deleted. |
| 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.

## POST /v1/material/analysisTask/stream

Operation ID: `streamViralVideoReplication`

Stream a reusable replication prompt from a public video URL or an uploaded file. Concatenate result from streaming events in order; if a done event arrives, use its result as the complete prompt.

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: Decide success from the SSE events and concatenate the streaming chunks; use the complete result from the done event. On errors, check the HTTP status and message instead of JSON code=0.

### Request parameters

| Field | Location | Type | Required | Description |
|---|---|---|---|---|
| `type` | body | REPLICATION | Yes | Always send REPLICATION; ANALYSIS is reserved and not covered here |
| `url` | body | string(uri) | Conditional | Public video URL; send this or businessId. Supports TikTok, Douyin, Xiaohongshu, WeChat Channels, Instagram, YouTube, and Bilibili |
| `businessId` | body | string | Conditional | Uploaded file or material ID; send this or url. Upload a local file first, then pass the fileId as a string |
| `businessType` | body | FILE \| MATERIAL | Conditional | Required with businessId; use FILE for uploaded files and MATERIAL for library assets |

Request format: `application/json`

### Request example: Replicate a public video URL

```json
{
  "type": "REPLICATION",
  "url": "https://www.tiktok.com/@creator/video/7123456789012345678"
}
```

### Request example: Replicate an uploaded file

```json
{
  "type": "REPLICATION",
  "businessId": "591",
  "businessType": "FILE"
}
```

### Stream events: Prompt delta

```json
{
  "status": "streaming",
  "result": "**Video Script Title**\nA clean product reveal with a slow camera push-in.\n",
  "thinking": null,
  "id": 2066122904659169300
}
```

### Stream events: Full prompt

```json
{
  "status": "done",
  "result": "**Video Script Title**\nA clean product reveal with a slow camera push-in.\n\n**Characters / Main Subjects**\nA seller presenting a summer product against a bright studio backdrop.\n\n**Scene / Environment**\nBright studio lighting, close-up product shots, and a final call to action.\n\n**Script**\n00:00-00:02 Hook the viewer with the product in hand.\n00:02-00:08 Show the key selling points in short cuts.\n00:08-00:10 End with a clear purchase CTA.\n\n**Notes**\nKeep the pacing tight and preserve the original hook-to-CTA structure.",
  "thinking": null,
  "id": 2066122904659169300
}
```

### 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 |
|---|---|---|---|
| `status` | string | Yes | streaming carries a prompt delta; when the server sends the terminal event, done carries the full prompt.; Allowed values: streaming, done |
| `result` | string | Yes | Prompt delta in streaming events and the full prompt in the done event. |
| `thinking` | string \| null | No | — |
| `id` | integer | No | Analysis task ID; it stays the same for every chunk of one request. |

### Integration notes and limits

- A successful response uses Content-Type text/event-stream. Do not judge success by JSON code === 0.
- Each SSE line is data:<json> with status, result, thinking, and a task id. The id stays constant for one request.
- Concatenate result from status=streaming events in arrival order. If status=done arrives, use that result as the complete prompt.
- Failures return a JSON error body instead of SSE. Read the HTTP status and message.
- For a local MP4, call /v1/file/presign and /v1/file/confirm first, then send businessId with businessType=FILE.
- The assembled prompt is usually Markdown with title, subjects, scene, timestamped script, and notes, and can feed AI video generation.

### 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 presigned upload](/en/openapi/presign) · [Markdown](/en/openapi/operations/createFileUpload.md)
- [Confirm an uploaded file](/en/openapi/confirm) · [Markdown](/en/openapi/operations/confirmFileUpload.md)
- [Create an AI image or video schedule](/en/openapi/schedule-create) · [Markdown](/en/openapi/operations/createAiGenerationSchedule.md)

## POST /v1/relay/chat/completions

Operation ID: `createRelayChatCompletion`

Call supported LINGTU text and vision models through one OpenAI-compatible endpoint with JSON or SSE streaming responses.

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: Read choices for non-streaming responses; concatenate choices[0].delta.content for streaming responses and stop after data: [DONE]; also check the HTTP status.

### Request parameters

| Field | Location | Type | Required | Description |
|---|---|---|---|---|
| `model` | body | string | Yes | Supported model identifier available to the current account |
| `messages` | body | RelayChatMessage[] | Yes | OpenAI-compatible messages with text and supported image_url content |
| `stream` | body | boolean | No | When true, returns incremental SSE content; defaults to false |
| `max_tokens` | body | integer | No | Maximum output tokens |
| `thinking.type` | body | enabled \| disabled | No | Enable or disable thinking when supported by the selected model |

Request format: `application/json`

### Stream events: Model output delta

```json
{
  "id": "chatcmpl_2066122904659169280",
  "model": "deepseek-v4-flash-vision-exp",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "请求已"
      },
      "finish_reason": null
    }
  ]
}
```

### 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 |
|---|---|---|---|
| `id` | string | No | — |
| `model` | string | No | — |
| `choices` | object[] | Yes | — |
| `choices[].index` | integer | Yes | — |
| `choices[].message` | object | Yes | — |
| `choices[].message.role` | string | Yes | Fixed value: assistant |
| `choices[].message.content` | string | Yes | — |
| `choices[].finish_reason` | string \| null | No | — |
| `choices[].delta` | object | Yes | — |
| `choices[].delta.content` | string | No | — |

### Integration notes and limits

- Keep API keys on the server. Never place x-api-key in browser code, logs, or public files.
- With stream=true, parse each data: line and concatenate choices[0].delta.content until data: [DONE].
- Compute usage depends on the selected model, input content, output length, and multimodal inputs such as images.
- image_url must be reachable by the model service; choose an appropriate detail level for the task.

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


## Retries and duplicate tasks

- Retry safe requests with exponential backoff on network timeouts, HTTP 408, 429 or transient 5xx; respect Retry-After when the server sends it.
- Fix parameter, permission and authorization errors before retrying.
- Before retrying an object storage PUT, check that the presigned URL is still valid; PUT requests do not carry x-api-key.
- A timeout when creating a publishing or generation task does not mean it failed. Query existing tasks first and do not create duplicates when polling was interrupted.
