LINGTU AI OpenAPI
Commerce video publishing flow
This page covers TikTok Shop commerce videos only. The creator must already be authorized through TikTok Shop; then follow: select creators → products and schedule → video upload and settings → validation and task creation → publishing records.
Publishing flow
What each step does
Step 1 · Select creators
Choose the authorized creator account that will publish the videos.
- List commerce creators with authSource=TIKTOK_SHOP_CREATOR
- For commerce videos, permissions containing both LIVE_STREAM_PERMISSION and SELF_SALE_PERMISSION guarantees video commerce permission
- Use creatorId for publishing tasks and the account id for product queries
Step 2 · Products and schedule
Choose a shop or showcase product and set the publishing dates.
- Products come from the shop or the showcase; add a product by ID or link when it is missing
- Set the publishing timezone, dates and posts per day, or publish immediately
- Keep the product in stock, otherwise the platform may drop the shopping anchor
Step 3 · Upload the video
Upload one video per task through presigned storage.
- Compute the file hash, then call presign with fileName, contentType, size and hash
- When isNew=true, PUT the file to uploadUrl and call confirm
- When isNew=false, reuse the returned fileId and skip PUT and confirm
- businessId is the video fileId converted to a string; businessType=FILE
Step 4 · Commerce settings
Set the product title, music, cover and AI-generated label for each task.
- Product title is required and editable; forbidden characters and length are validated before publishing
- Search music or reuse the LINGTU favorites library; publish with musicId
- Cover: use a video frame timestamp, or upload a custom cover and pass photoFile.photoUri as tiktokShop.coverUri
- When a custom cover is uploaded, put coverFileId at the request root and omit coverTimestampMs
- Mark the content as AI-generated when applicable
Step 5 · Validate and create the task
Optionally enable the video pre-check, validate, then create the publishing task.
- Pre-check is optional and off by default; when enabled, set a timeout so publishing continues if the official check does not finish
- Scheduled tasks must be at least 5 minutes ahead; immediate publishing uses the current time
- Validate the title, video fileId, product and schedule
- Call createPost with scheduledAt, scheduledTz and the tiktokShop block
After publishing · Records
Track pre-check results, platform post ID and failures.
- Creation success only means the task was accepted
- Query publishing records and details for the final status
- Submit a scheduled task immediately, edit tasks that can still change, or cancel
- Store the postId for follow-up
Key branches
Scheduled or immediate
Scheduled tasks must be at least 5 minutes ahead; immediate publishing sets scheduledAt to the current time.
New video or deduplicated
presign reports isNew; only new files need PUT and confirm.
Pre-check is optional
Pre-check only applies to commerce videos. When enabled, set a timeout; publishing continues after the timeout.
Cover: frame or upload
Use coverTimestampMs for a frame, or upload a cover and pass coverUri with coverFileId. The two are mutually exclusive.
Creation vs publishing
createPost only accepts the task; use publishing records for the final platform status.
Integration notes
- The creator must be authorized with TikTok Shop before publishing; see the creator authorization flow.
- Product title length and forbidden characters are validated; fix them before creating tasks.
- Custom covers require returnCoverFileId=true on upload, then pass both photoUri and coverFileId.
- scheduledAt is an absolute timestamp, scheduledTz is the IANA timezone of the target market.
- When isNew=false, reuse the fileId instead of uploading the same video again.