# LINGTU AI OpenAPI

- OpenAPI: 3.1.2
- API version: 1.0.0
- Last updated: 2026-07-29
- Base URL: `https://api.ailingtu.com`
- Authentication: `x-api-key: <YOUR_API_KEY>`
- Success condition: HTTP 2xx and response `code === 0`

Machine-readable descriptions: [JSON](/openapi.json) · [YAML](/openapi.yaml)

API keys must remain on the server and must not be included in browser code, logs, or shared files.

## Publishing workflow

1. Query an authorized creator account.
2. Query shop or showcase products with the account `id`.
3. Create a presigned upload, PUT new files to object storage, and confirm them.
4. Create a publishing task with the account `creatorId` and uploaded `fileId`.

## GET /v1/creatorAccount/pageList

Operation ID: `listCreatorAccounts`

List authorized creator accounts

Returns authorized creator accounts and publishing permissions. Use `id` for product queries and `creatorId` when creating publishing tasks.

| Field | Location | Type | Required | Description |
|---|---|---|---:|---|
| `pageSize` | query | integer | yes | Items per page. |
| `pageNumber` | query | integer | yes | Page number starting at 1. |
| `valid` | query | boolean | no | Return valid authorizations only. |
| `authSource` | query | `TIKTOK_SHOP_CREATOR` \| `TIKTOK_LOGIN_KIT` | no | Authorization source. Use TIKTOK_SHOP_CREATOR for commerce publishing. |
| `usernames` | query | string[] | no | TikTok usernames. Repeat the query parameter for multiple values. |
| `selectionRegion` | query | string | no | Target TikTok Shop region. |
| `hasPhotoPermission` | query | boolean | no | Return accounts with shoppable photo permission only. |

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

### Errors

| HTTP | Meaning |
|---:|---|
| 400 | Invalid request parameters or body. |
| 401 | The API key is missing or invalid. |
| 403 | The API key does not have permission for this operation. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | Unexpected server error. Retry transient failures with exponential backoff. |

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

Operation ID: `listTikTokShopProducts`

List TikTok Shop products

Lists shop products using the creator account `id`. Use `SHOP` as the product source when creating a publishing task.

| Field | Location | Type | Required | Description |
|---|---|---|---:|---|
| `id` | query | integer | yes | Creator account table ID, not creatorId. |
| `origin` | query | `TIKTOK` | yes | Product platform origin. |
| `pageSize` | query | integer | yes | Items per page. |
| `pageToken` | query | string | no | Pagination token from the previous response. |
| `titleKeyword` | query | string | no | Product title keyword. |

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

### Errors

| HTTP | Meaning |
|---:|---|
| 400 | Invalid request parameters or body. |
| 401 | The API key is missing or invalid. |
| 403 | The API key does not have permission for this operation. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | Unexpected server error. Retry transient failures with exponential backoff. |

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

Operation ID: `listTikTokShowcaseProducts`

List creator showcase products

Lists products in a creator showcase. Use `SHOWCASE` as the product source when creating a publishing task.

| Field | Location | Type | Required | Description |
|---|---|---|---:|---|
| `id` | query | integer | yes | Creator account table ID. |
| `origin` | query | `TIKTOK` | yes | Product platform origin. |
| `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"
}
```

### Errors

| HTTP | Meaning |
|---:|---|
| 400 | Invalid request parameters or body. |
| 401 | The API key is missing or invalid. |
| 403 | The API key does not have permission for this operation. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | Unexpected server error. Retry transient failures with exponential backoff. |

## POST /v1/file/presign

Operation ID: `createFileUpload`

Create a presigned file upload

Returns a file ID and a presigned object-storage URL. When `isNew` is false, skip PUT and confirmation. When `isNew` is true, PUT the raw file bytes to `uploadUrl` with the same Content-Type, without the x-api-key header, then confirm the upload.

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

### Errors

| HTTP | Meaning |
|---:|---|
| 400 | Invalid request parameters or body. |
| 401 | The API key is missing or invalid. |
| 403 | The API key does not have permission for this operation. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | Unexpected server error. Retry transient failures with exponential backoff. |

## POST /v1/file/confirm

Operation ID: `confirmFileUpload`

Confirm a file upload

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

| Field | Location | Type | Required | Description |
|---|---|---|---:|---|
| `fileId` | body | integer | string | yes | File ID returned by the presign endpoint |

### Request example

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

### Success response

```json
{
  "code": 0,
  "data": {
    "fileId": 591,
    "confirmed": true
  },
  "message": "success"
}
```

### Errors

| HTTP | Meaning |
|---:|---|
| 400 | Invalid request parameters or body. |
| 401 | The API key is missing or invalid. |
| 403 | The API key does not have permission for this operation. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | Unexpected server error. Retry transient failures with exponential backoff. |

## POST /v1/creator/post/create

Operation ID: `createCreatorPost`

Create a creator publishing task

Creates a TikTok Shop commerce video or photo publishing task. A successful response means the task was accepted, not that TikTok publishing has completed.

| Field | Location | Type | Required | Description |
|---|---|---|---:|---|
| `businessId` | body | string | yes | Video fileId; first image fileId for photo posts |
| `businessType` | body | FILE | yes | Use FILE for uploaded media |
| `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 | yes | Use TIKTOK_SHOP for commerce posts |
| `mediaType` | body | VIDEO | PHOTO | yes | Explicitly select video or photo |
| `scheduledAt` | body | integer | no | Unix epoch in milliseconds |
| `scheduledTz` | body | string | no | IANA timezone |
| `tiktokShop` | body | object | conditional | Required for VIDEO |
| `tiktokShopPhoto` | body | object | conditional | Required for PHOTO |

### Request example

```json
{
  "video": {
    "businessId": "591",
    "businessType": "FILE",
    "creatorId": "2077242233106595840",
    "title": "Summer Sale 2026 #summer",
    "platform": "TIKTOK_SHOP",
    "mediaType": "VIDEO",
    "scheduledAt": 1784896665989,
    "scheduledTz": "America/New_York",
    "oauthRegion": "USA",
    "tiktokShop": {
      "productInfo": {
        "productId": "1732280564607717841",
        "title": "Summer Vibes Cord",
        "source": "SHOP"
      }
    }
  },
  "photo": {
    "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"
        }
      ]
    }
  }
}
```

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

### Errors

| HTTP | Meaning |
|---:|---|
| 400 | Invalid request parameters or body. |
| 401 | The API key is missing or invalid. |
| 403 | The API key does not have permission for this operation. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | Unexpected server error. Retry transient failures with exponential backoff. |

## POST /v1/material/fetch

Operation ID: `fetchPublicVideoData`

Fetch public video data

Fetches public video views and engagement metrics. Supported sources include TikTok, Instagram, Douyin, Xiaohongshu, WeChat Channels, and YouTube.

| Field | Location | Type | Required | Description |
|---|---|---|---:|---|
| `videoUrl` | body | string(uri) | yes | Public http/https URL of the content |

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

### Errors

| HTTP | Meaning |
|---:|---|
| 400 | Invalid request parameters or body. |
| 401 | The API key is missing or invalid. |
| 403 | The API key does not have permission for this operation. |
| 404 | The public work does not exist or has been deleted. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | Unexpected server error. Retry transient failures with exponential backoff. |

## Retry guidance

- Retry network timeouts, HTTP 408, 429, and 5xx responses with exponential backoff.
- Do not blindly retry parameter, permission, or authorization errors.
- Before retrying an object-storage PUT, confirm that the presigned URL is still valid.
- If creating a publishing task times out, check publishing records before creating another task to avoid duplicates.