OpenAPI Documentation

Publishing flow

https://api.ailingtu.com

Find a creator

id + creatorId

Select a product

SHOP / SHOWCASE

Upload media

presign → PUT → confirm

Create a post

VIDEO / PHOTO

Authentication

x-api-key: <YOUR_API_KEY>

Keep API keys on your server. Never expose them in browser code or logs.

Success condition

HTTP 2xx && response.code === 0

Treat non-2xx responses, invalid JSON, or a non-zero business code as failures.

Machine-readable API descriptions

Use the OpenAPI description as the source for agents, SDK generation, and contract validation.

OpenAPI JSON JSON OpenAPI YAML YAML Markdown docs MD llms.txt TXT Operation index JSON AI generation workflow MD

Commerce publishing

Resolve creators and products before creating TikTok Shop publishing tasks.

GET/v1/creatorAccount/pageListAvailable

operationId: listCreatorAccounts

AI Markdown OpenAPI JSON

List authorized creators

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

Query parameters

Field	Type	Required	Description
`pageSize`	`integer`	Yes	Items per page, up to 200
`pageNumber`	`integer`	Yes	Page number, starting at 1
`valid`	`boolean`	No	Return valid authorizations only; defaults to true
`authSource`	`string`	No	Use TIKTOK_SHOP_CREATOR for commerce posts
`usernames`	`string[]`	No	Repeat the query parameter for multiple usernames
`selectionRegion`	`string`	No	Target region, such as US
`hasPhotoPermission`	`boolean`	No	Return accounts with shoppable photo permission only

Photo posts require PHOTO_SHOPPABLE_PERMISSION_PRODUCT in permissions.

Success response

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

GET/v1/creator/tiktokshop/product/listByShowcaseAvailable

operationId: listTikTokShowcaseProducts

AI Markdown OpenAPI JSON

List showcase products

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

Query parameters

Field	Type	Required	Description
`id`	`integer`	Yes	Creator account id
`origin`	`TIKTOK`	Yes	Always TIKTOK
`pageSize`	`integer`	Yes	Items per page
`pageToken`	`string`	No	Pagination token from the previous response

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

Success response

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

POST/v1/creator/tiktokshop/product/addToShowcaseAvailable

operationId: addTikTokShowcaseProducts

AI Markdown OpenAPI JSON

Creator TTS - Add showcase products

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

Request fields

Field	Type	Required	Description
`id`	`integer`	Yes	Creator account id
`addType`	`PRODUCT_ID \| PRODUCT_LINK`	Yes	How products are identified
`productIds`	`string[]`	Conditional	Required for PRODUCT_ID; 1–20 product IDs
`productLink`	`string(uri)`	Conditional	Required for PRODUCT_LINK

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 “授权过期，请重新授权”.

Request body

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

Success response

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

File upload

Request a presigned URL, upload media directly to object storage, then confirm new files.

POST/v1/file/presignAvailable

operationId: createFileUpload

AI Markdown OpenAPI JSON

Create a presigned upload

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

Request fields

Field	Type	Required	Description
`fileName`	`string`	Yes	File name including extension
`contentType`	`string`	Yes	File MIME type
`size`	`integer`	Yes	File size in bytes
`hash`	`string`	Yes	SHA-256 of the UTF-8 encoded lowercase hex representation of the file bytes

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.

Request body

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

Success response

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

POST/v1/file/confirmAvailable

operationId: confirmFileUpload

AI Markdown OpenAPI JSON

Confirm an uploaded file

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

Request fields

Field	Type	Required	Description
`fileId`	`integer \| string`	Yes	File ID returned by the presign endpoint

Request body

{
  "fileId": 591
}

Success response

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

POST/v1/creator/post/createAvailable

operationId: createCreatorPost

AI Markdown OpenAPI JSON

Create a publishing task

Create a TikTok Shop commerce video or photo publishing task. A successful response means the task was accepted; verify the final result in publishing records.

Request fields

Field	Type	Required	Description
`businessId`	`string`	Yes	Video fileId; first image fileId for photo posts
`businessType`	`FILE`	Yes	Use FILE for uploaded media
`creatorId`	`string`	Yes	creatorId returned by the creator endpoint
`title`	`string`	Yes	Post caption, up to 4,000 characters
`platform`	`TIKTOK_SHOP`	Yes	Use TIKTOK_SHOP for commerce posts
`mediaType`	`VIDEO \| PHOTO`	Yes	Explicitly select video or photo
`scheduledAt`	`integer`	No	Unix epoch in milliseconds
`scheduledTz`	`string`	No	IANA timezone
`oauthRegion`	`string`	No	Creator OAuth authorization region
`coverFileId`	`integer \| string`	No	Custom video cover file ID; pass together with tiktokShop.coverUri and omit for photo posts
`tiktokShop`	`object`	Conditional	Required for VIDEO; contains product, cover, pre-check, music, and AI label options
`tiktokShop.preCheck`	`boolean`	No	Whether to submit a pre-check before publishing; defaults to false
`tiktokShop.isAiGenerated`	`boolean`	No	Whether to label the video as AI-generated; TikTok adds an AI-generated label when true
`tiktokShop.coverUri`	`string`	No	URI returned by the cover upload endpoint; pass coverFileId with it
`tiktokShop.coverTimestampMs`	`integer`	No	Video timestamp in milliseconds to use as the cover frame; omit when coverUri is present
`tiktokShop.musicInfo`	`object`	No	Video background music; omit when no music is needed
`tiktokShop.musicInfo.id`	`string`	Conditional	Music ID, required when musicInfo is provided
`tiktokShop.productInfo.productId`	`string`	Conditional	Required for VIDEO; product ID returned by the product endpoint
`tiktokShop.productInfo.title`	`string`	Conditional	Required for VIDEO; product anchor title, up to 30 characters
`tiktokShop.productInfo.source`	`SHOP \| SHOWCASE`	Conditional	Required for VIDEO; SHOP for shop products or SHOWCASE for showcase products
`tiktokShopPhoto`	`object`	Conditional	Required for PHOTO
`tiktokShopPhoto.postType`	`MULTI_PHOTO_ONE_ANCHOR`	Conditional	Use MULTI_PHOTO_ONE_ANCHOR for PHOTO
`tiktokShopPhoto.businessIds`	`string[]`	Conditional	Required for PHOTO; 1–15 image fileIds in final display order
`tiktokShopPhoto.productLinks[0].productId`	`string`	Conditional	Required for PHOTO; product ID for the single product anchor
`tiktokShopPhoto.productLinks[0].title`	`string`	Conditional	Required for PHOTO; product anchor title, up to 30 characters
`tiktokShopPhoto.productLinks[0].source`	`SHOP \| SHOWCASE`	Conditional	Required for PHOTO; product source
`tiktokShopPhoto.musicInfo`	`object`	No	Photo post background music; omit when no music is needed
`tiktokShopPhoto.musicInfo.id`	`string`	Conditional	Music ID, required when musicInfo is provided

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.

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.

Success response

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

Commerce 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": {
    "preCheck": false,
    "isAiGenerated": true,
    "coverTimestampMs": 1500,
    "musicInfo": {
      "id": "7567668059796720391",
      "title": "original sound",
      "author": "Ivan",
      "duration": "15"
    },
    "productInfo": {
      "productId": "1732280564607717841",
      "title": "Summer Vibes Cord",
      "source": "SHOP"
    }
  }
}

Commerce photo post

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

AI content generation

Create scheduled image or video generation tasks, then query the same schedule until generated assets are ready.

POST/v1/ai/schedule/createAvailable

operationId: createAiGenerationSchedule

AI Markdown OpenAPI JSON

Create an AI image or video schedule

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.

Request fields

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

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.

Success response

{
  "code": 0,
  "data": {
    "scheduleId": "schedule_01k1example",
    "taskIds": [
      "task_01k1example"
    ]
  },
  "message": "success"
}

Image generation

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

Video generation

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

GET/v1/ai/task/listByScheduleIdAvailable

operationId: listAiTasksByScheduleId

AI Markdown OpenAPI JSON

List AI generation tasks

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

Query parameters

Field	Type	Required	Description
`scheduleId`	`string`	Yes	scheduleId returned when the generation schedule was created

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.

Success response

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

Content data

POST/v1/material/fetchAvailable

operationId: fetchPublicVideoData

AI Markdown OpenAPI JSON

Video data sync

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

Request fields

Field	Type	Required	Description
`videoUrl`	`string(uri)`	Yes	Public http/https URL of the content

Request body

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

Success response

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

Integration checklist

Keep id and creatorId separate

Skip PUT and confirm when isNew is false

Keep photo businessIds in display order

Persist postId and verify the final status

Ready to integrate?

Create or manage an API key in the LINGTU AI workspace.

Manage API keys

LINGTU AI OpenAPI

Publishing flow

Machine-readable API descriptions

Commerce publishing

List authorized creators

Query parameters

List showcase products

Query parameters

Creator TTS - Add showcase products

Request fields

File upload

Create a presigned upload

Request fields

Confirm an uploaded file

Request fields

Create a publishing task

Request fields

AI content generation

Create an AI image or video schedule

Request fields

List AI generation tasks

Query parameters

Content data

Video data sync

Request fields

Integration checklist

Ready to integrate?