linkfox-tiktok-selection-and-shoppable-video

Linkfox Tiktok Product Selection and Shoppable Video

A one-stop AI toolset for TikTok product selection and shoppable videos, integrating 3 types of underlying tools, 10 sub-capabilities, covering product selection data (EchoTik 16 regional markets / FastMoss global e-commerce) and the official shoppable video publishing pipeline (TikTok video account authorization → shoppable products → shoppable video pre-check/publish). For complete parameters, response fields, and error codes of each sub-capability, see references/ for the corresponding files; for executable scripts, see scripts/。

Capability Boundaries

✅ Scope of Capabilities

TikTok product selection data (echotik_tiktok, EchoTik, covering 16 regional markets): New product rankings to discover hot-selling hit products and emerging trends (echotik_tiktok list-new-product-rank); product search with multi-dimensional filtering by sales/creators/commission/rating/reviews (echotik_tiktok list-product); query of videos associated with products for views/interactions/video sales/GMV (echotik_tiktok product-video); batch product details including multi-period sales and GMV, livestream sales, number of selling creators, price rating, and commission (echotik_tiktok batch-product-detail); parsing TikTok video links to return no-watermark/watermark downloads, playback, and cover URLs (echotik_tiktok get-video-download-url）。
TikTok global e-commerce best sellers and product selection (fastmoss_tiktok，FastMoss）: analysis of best-selling product rankings and GMV rankings by day/week/month dimension and category (fastmoss_tiktok product-rank-top-selling); multi-dimensional product search and filtering by category/sales/commission rate/number of creators/store type (fastmoss_tiktok product-search）。
TikTok official shoppable video API (tiktok_official_video_api）: video account creator OAuth authorization, authorized account list, token query, and access_token refresh (tiktok_official_video_api linkfox-tiktok-video-auth); shoppable video content pre-check, pre-check result query, publish, publish status query, creator profile query, and large file chunked upload (tiktok_official_video_api linkfox-tiktok-video); query of products a creator can sell (store products and showcase/live bag products), obtaining product_id for attaching products to shoppable videos (tiktok_official_video_api linkfox-tiktok-video-products）。
Covered region/marketplace: EchoTik 16 TikTok Shop regional markets; FastMoss global e-commerce (filtered by region); TikTok official video account region supports global(default) / us(US site). For specific values, see each references.

❌ Boundaries and Limitations

API Key required: All tools require the environment variable LINKFOX_AGENT_API_KEY(or LINKFOXAGENT_API_KEY); each tool is billed independently and rate-limited independently, and data timeliness and regional coverage vary by data source.
Billing constraints: Within the same session, the same parameter combination is called only once by default (scripts include local caching); on failure or empty results, do not automatically switch keywords, paginate, or change regions for continuous probing; if further retrieval is needed, first explain to the user that additional consumption will be incurred (for billing rules, see skills-version.json and the costToken field in api.md within references: EchoTik 5 items fixed≈4.5/9000 token, FastMoss 2 items fixed≈10.5/21000 token, TikTok official 3 items free).
TikTok official module isolation：linkfox-tiktok-video / linkfox-tiktok-video-products only goes through /tiktokVideo/developerProxy, and the path must start with affiliate_creator / video / creator (otherwise errcode 1005); it cannot be used for /tiktokShop/*(the TikTok Shop seller module uses linkfox-tiktok-shop-auth). Token ttsAccessToken is obtained via linkfox-tiktok-video-auth after authorization by /tiktokVideo/accountTokens , fixed to the creator side.
TikTok official dependency chain: Publishing a shoppable video requires first authorizing via linkfox-tiktok-video-auth to obtain a token, then linkfox-tiktok-video-products to obtain product_id, and finally linkfox-tiktok-video pre-check/publish;check_auth_dependency.py detects whether linkfox-tiktok-video-auth is installed (exit 42 = not installed/not authorized, authorization must be completed first).
Large file upload limit: ≤10MB uses upload_shoppable_video_file(multipart, not currently supported by the gateway); >10MB uses the three-step large file chunking (Initialize → PUT chunks → Bind, see references/large-file-upload.mdfor details; Step 1/3 can go through the proxy, Step 2 chunk PUT does not go through the gateway).
Out of scope: TikTok Shop seller ERP (products/orders/finance, use linkfox-tiktok-shop-auth + business skill), TikTok Shop shoppable videos (/tiktokShop/developerProxy, use linkfox-tiktok-creator), TikTok ad delivery, logistics and supply chain, non-e-commerce tasks, direct communication with the platform or sellers.

Tool selection guide

Determine the sub-capability in the table below based on the requirement, then jump to [Business Requirement Routing Quick Reference] to look up endpoints/scripts/references for parameters and execution.

Requirement / User says	Default recommendation (sub-capability)	When to switch to another
TikTok product selection / product search ("What sells well on TikTok")	`linkfox-echotik-list-product`(16 regional markets, multi-dimensional sales/creators/commission/rating)	For global e-commerce + daily/weekly/monthly dimensions + range filters (creator count/commission rate range), use `linkfox-fastmoss-product-search`
TikTok new products / emerging trends ("What new products are trending recently")	`linkfox-echotik-list-new-product-rank`(new product ranking)	For the bestseller list (not new products), use `linkfox-fastmoss-product-rank-top-selling`
TikTok bestseller list / hit product ranking / GMV ranking	`linkfox-fastmoss-product-rank-top-selling`(daily/weekly/monthly + category)	For "new product" trends, use `linkfox-echotik-list-new-product-rank`
Product details / multi-period sales GMV ("How is this productId selling")	`linkfox-echotik-batch-product-detail`(1d/7d/15d/30d/60d/90d/cumulative + livestream + creators)	—
Product promotion videos ("What promotion videos does this product have / video sales")	`linkfox-echotik-product-video`(views/interactions/video sales/GMV)	—
Video download / watermark removal ("Download this TikTok video")	`linkfox-echotik-get-video-download-url`(no watermark/with watermark/playback/cover)	—
Video account authorization / bind video account / refresh token	`linkfox-tiktok-video-auth`(OAuth + token)	For TikTok Shop seller authorization, use `linkfox-tiktok-shop-auth`(not interoperable)
What products a creator can promote / showcase products / get product_id	`linkfox-tiktok-video-products`(shop products + showcase/livestream bag)	—
Publish shoppable video / attach product to video ("Post a TikTok video with a product")	`linkfox-tiktok-video`(pre-check → publish → check status)	Requires first `linkfox-tiktok-video-auth` authorization + `linkfox-tiktok-video-products` to get product_id
Creator homepage / profile	`linkfox-tiktok-video`(get_creator_profile, standalone feature)	—
Large file chunked video upload (>10MB)	`linkfox-tiktok-video`(large_file_upload_init/bind + chunk PUT)	≤10MB uses `upload_shoppable_video_file`(gateway does not currently support multipart)

Tool selection approach

Important: When multiple sub-capabilities meet the requirement, conduct an in-depth analysis of the sub-capabilities' functions, purposes, and input/output parameters based on the requirement, identify the most suitable sub-capability, and recommend it to the user so the user can decide for themselves.
When the degree of suitability is equal, recommend the "default recommended sub-capability" to the user.

Business Requirement Routing Quick Reference

After determining the sub-capability according to the [Tool Selection Guide], look up the endpoint, script, and references file in the table below to retrieve parameters and execute:

Sub-capability ↔ references file ↔ endpoint ↔ script (10 items)

echotik_tiktok

Sub-capability	references file	Endpoint	Script
linkfox-echotik-list-new-product-rank	references/linkfox-echotik-list-new-product-rank.md	POST /echotik/listNewProductRank	echotik_list_new_product_rank.py
linkfox-echotik-list-product	references/linkfox-echotik-list-product.md	POST /echotik/listProduct	echotik_list_product.py
linkfox-echotik-product-video	references/linkfox-echotik-product-video.md	POST /echotik/listProductVideo	echotik_list_product_video.py
linkfox-echotik-batch-product-detail	references/linkfox-echotik-batch-product-detail.md	POST /echotik/batchProductDetail	echotik_batch_product_detail.py
linkfox-echotik-get-video-download-url	references/linkfox-echotik-get-video-download-url.md	POST /echotik/getVideoDownloadUrl	echotik_get_video_download_url.py

fastmoss_tiktok

Sub-capability	references file	Endpoint	Script
linkfox-fastmoss-product-rank-top-selling	references/linkfox-fastmoss-product-rank-top-selling.md	POST /fastmoss/productRankTopSelling	fastmoss_product_rank_top_selling.py
linkfox-fastmoss-product-search	references/linkfox-fastmoss-product-search.md	POST /fastmoss/productSearch	fastmoss_product_search.py

tiktok_official_video_api

Sub-capability	references file	Endpoint	Script
linkfox-tiktok-video-auth	references/linkfox-tiktok-video-auth.md	POST /tiktokVideo/authorizeUrl、/authorizedAccounts、/accountTokens、/refreshToken	authorize_url.py、authorized_accounts.py、account_tokens.py、refresh_token.py
linkfox-tiktok-video	references/linkfox-tiktok-video.md	POST /tiktokVideo/developerProxy	video_api.py、video_proxy.py、get_creator_profile.py、precheck_shoppable_video.py、get_shoppable_video_precheck_result.py、post_shoppable_video.py、get_shoppable_video_status.py、upload_shoppable_video_file.py、large_file_upload_init.py、large_file_upload_bind.py
linkfox-tiktok-video-products	references/linkfox-tiktok-video-products.md	POST /tiktokVideo/developerProxy	get_shop_products.py、get_showcase_products.py、products_api.py

TikTok official three sub-capabilities shared helper:response_io.py(write to disk/summary),check_auth_dependency.py(detect linkfox-tiktok-video-auth）；linkfox-tiktok-video also has _video_api_runner.py / _video_endpoints.py / _tiktok_video_common.py，linkfox-tiktok-video-products also has _products_api_runner.py / _products_endpoints.py / _tiktok_video_products_common.py, all in the same directory as this entry script, ready for use at any time.

Invocation Method

Gateway：${LINKFOX_TOOL_GATEWAY}/<端点>(default https://tool-gateway.linkfox.com), request method POST, Content-Type application/json, authentication Header Authorization: <api_key>(api_key read from environment variable LINKFOX_AGENT_API_KEY or LINKFOXAGENT_API_KEY ; if not configured, handle according to [Resolving Authentication and Credit Issues] below). For each endpoint path, see [Business Requirement Routing Quick Reference] above and the corresponding references file.
TikTok official product video pipeline：linkfox-tiktok-video / linkfox-tiktok-video-products forwarded via POST /tiktokVideo/developerProxy to ZiNiao tiktok-proxy/creator/{region}/{path}; the caller passes path / method / ttsAccessToken（= creator access_token, upstream request header x-tts-access-token）/ region（global default / us）；app_key / timestamp / sign automatically injected by the ZiNiao proxy. Named scripts (video_api.py / products_api.py / each get_*.py / post_*.py) only need to pass {"api": "...", "openId": "..."}, and the script internally calls /tiktokVideo/accountTokens to retrieve ttsAccessToken and then calls developerProxy.
Python script: each sub-capability corresponds to scripts/<脚本名>.py '<JSON 参数>' [--inline](script name and endpoint see the routing quick reference table). The script internally completes the gateway call, authentication, and writing to disk.
Output strategy (script default behavior): always write the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill>-<timestamp>.json（<cwd> is the working directory when the script is executed;<session> taken from environment variable SESSION_ID; writing to /tmp is prohibited, and an error is reported if the current directory is not writable); after writing to disk, if the response body ≤ 8 KB, print it in full to stdout; if > 8 KB, print only a summary (top-level fields, common counts, maximum list length + first 3 samples); add --inline to force full printing (also written to disk).
Data reading suggestion: first look at the summary to determine whether it is sufficient; when specific fields are needed, prefer using jq or PowerShell ConvertFrom-Json to extract as needed from the saved json file, avoiding the entire JSON entering the context.
Complete parameters: for each sub-capability's request parameters, response fields, error codes, and curl examples, see references/<子能力>.md(the file contains the sub-capability's SKILL.md main text and the full api.md text);linkfox-tiktok-video also contains references/large-file-upload.md(detailed explanation of large file chunked upload).

Usage Examples

The following provides representative input/output examples for sub-capabilities by data layer; for the remaining sub-capability parameters, see the corresponding references files.

Product Selection and Data Layer (EchoTik / FastMoss)

1. TikTok New Product Ranking (echotik_tiktok → echotik_list_new_product_rank.py)

{"date": "2025-06-15", "region": "US", "pageNum": 1, "pageSize": 50}

Output parameters:products[](title/asin/price/minPrice/maxPrice/currency/totalSaleCnt/totalSaleGmvAmt/salesTrendFlagText/totalVideoCnt/totalLiveCnt/totalIflCnt creator count/productCommissionRate/productRating/reviewCount/categoryId/imageUrl),total、columns、costToken。

2. TikTok Product Search (echotik_tiktok → echotik_list_product.py)

{"keyword": "phone case", "region": "US", "minTotalSale30dCnt": 1000, "productSortField": 5, "sortType": 1, "pageSize": 20}

Output parameters:products[](productId/productName/title/price/spuAvgPrice/productRating/reviewCount/ratings/productCommissionRate/totalSaleCnt/monthlySalesUnits/totalSaleGmvAmt/totalIflCnt creator count/categoryName/firstCrawlDt/salesTrendFlagText),total、columns、costToken。

3. TikTok Top Selling Ranking (fastmoss_tiktok → fastmoss_product_rank_top_selling.py)

{"region": "US", "dateInfo": {"type": "day", "value": "2026-04-15"}, "page": 1, "pageSize": 10}

Output parameters:products[]（title/productId/price/minPrice/maxPrice/currency/totalSaleCnt/totalSaleGmvAmt/growthRate/shopName/shopTotalUnitsSold/categoryName/productCommissionRate/imageUrl/offShelvesText）、total、columns、costToken。dateInfo.type Supports day / week / month。

4. TikTok Product Search (fastmoss_tiktok → fastmoss_product_search.py)

{"keyword": "phone case", "region": "US", "orderField": "day7_units_sold", "pageSize": 10}

With range filtering:{"keyword": "beauty", "region": "US", "commissionRateRange": {"min": 0.10}, "creatorCountRange": {"min": 50}, "orderField": "commission_rate", "pageSize": 10} Output parameters:products[](title/productId/price/totalSaleCnt/totalSaleGmvAmt/totalVideoCnt/totalLiveCnt/totalIflCnt creator count/productCommissionRate/productRating/reviewCount/skuCount/shopName/isCrossBorder/tiktokUrl/fastmossUrl/imageUrl),total、columns、costToken。

5. Batch Product Details (echotik_tiktok → echotik_batch_product_detail.py)

{"productIds": ["1729382310407603945", "1729382310407603946"]}

Output parameters:products[](productId/productName/region/sellerId/minPrice/maxPrice/spuAvgPrice/productRating/reviewCount/productCommissionRate/totalSaleCnt/totalSaleGmvAmt/totalLiveCnt/totalVideoCnt/totalIflCnt creator count/totalViewsCnt/discount/freeShipping/salesTrendFlag/firstCrawlDt),total、columns、costToken. You can also use productUrls to pass a TikTok Shop product URL.

6. Product Sales Videos (echotik_tiktok → echotik_list_product_video.py)

{"productId": "1729382310407603945", "productVideoSortField": 1, "sortType": 1, "pageSize": 20}

Output parameters:data[](videoId/productId/userId/videoDesc/officialUrl/covet cover/totalFavoritesCnt likes/totalVideoSaleCnt/totalVideoSaleGmvAmt/hashTag/createDate/region),total、columns、costToken。

7. Video Download URL (echotik_tiktok → echotik_get_video_download_url.py)

{"url": "https://www.tiktok.com/@user/video/1234567890"}

Output parameters:downloadUrl(watermark-free),playUrl、coverUrl、dynamicCoverUrl、videoId、costToken、errmsg。

Sales Video Publishing Layer (TikTok Official)

Full flow:linkfox-tiktok-video-auth authorization to obtain ttsAccessToken → linkfox-tiktok-video-products obtain product_id → linkfox-tiktok-video upload file_id → (optional) precheck → publish → check status.

8. Video Account Authorization and Tokens (tiktok_official_video_api → authorize_url.py / authorized_accounts.py / account_tokens.py / refresh_token.py)

// POST /tiktokVideo/authorizeUrl
{"displayName": "My Channel", "region": "global"}
// → {"authorizeUrl": "https://services.tiktokshop.com/open/authorize?service_id=xxx&state=abc123"}（约 1 小时失效）
// POST /tiktokVideo/authorizedAccounts  {}   → accounts[](openId/displayName/region/userType)、total
// POST /tiktokVideo/accountTokens       {"openId": "<creator_open_id>"}
//   → accessToken/refreshToken/accessTokenExpireIn/refreshTokenExpireIn（accessToken 即下游 ttsAccessToken）
// POST /tiktokVideo/refreshToken        {"openId": "<creator_open_id>"}   → 续签并回写

9. Video Account Shoppable Products (tiktok_official_video_api → get_shop_products.py / get_showcase_products.py)

// 店铺商品（get_shop_products，GET affiliate_creator/202509/shop_products）
{"openId": "...", "title_keyword": "apple", "sort_field": "PRICE", "sort_order": "DESC", "page_size": 20}
// 橱窗/直播袋商品（get_showcase_products，GET affiliate_creator/202405/showcases/products）
{"openId": "...", "page_size": 20, "origin": "SHOWCASE"}   // origin: SHOWCASE（默认）/ LIVE

Output parameters: product list includes product_id(for linkfox-tiktok-video precheck/publish product attachment),data.next_page_token(pagination).page_size Required 1~20.

10. Publish Shoppable Video (tiktok_official_video_api → precheck_shoppable_video.py / get_shoppable_video_precheck_result.py / post_shoppable_video.py / get_shoppable_video_status.py)

// 内容预检（precheck_shoppable_video，POST affiliate_creator/202511/videos/precheck_task）
{"openId": "...", "video_info": {"file_id": "..."}, "product_link_info": {"product_id": "...", "title": "Product anchor"}}
// → data.precheck.task_id
// 查预检结果（GET affiliate_creator/202511/videos/precheck_tasks/{task_id}）
{"openId": "...", "task_id": "1123123123"}
// → result（SUCCESS/FAIL/PROCESSING）；FAIL 时看 issues[] 整改
// 发布可购物视频（post_shoppable_video，POST affiliate_creator/202603/videos）
{"openId": "...", "video_info": {"file_id": "...", "title": "My shoppable video"}, "product_link_info": {"product_id": "...", "title": "Product anchor"}}
// → data.video.id
// 查发布状态（get_shoppable_video_status，GET affiliate_creator/202509/videos/{video_id}/status）
{"openId": "...", "video_id": "7548431509997292816"}
// → post_status（SUCCESS/FAIL/PROCESSING）、post_time

Upload video file to obtain file_id: ≤10MB use upload_shoppable_video_file(multipart, not currently supported by the gateway); >10MB use large file chunking (large_file_upload_init → PUT chunks → large_file_upload_bind, see references/large-file-upload.md）。

Display Rules

Present data objectively: Display query results in clear tables, without subjective business advice (unless the user actively requests it); different regions use different currencies, so always indicate the currency when displaying prices/revenue (respond with the currency field to indicate the local currency).
Source attribution: When displaying data, state which tool/data source it comes from (EchoTik / FastMoss / TikTok Official).
Token security: Do not output the full ttsAccessToken / accessToken / refreshTokento the user in plain text; only display masked forms such as the first 10 characters.
Unavailable data: Fields with a value of 0 or -1 indicate that the data is unavailable; mark them as "N/A" or omit them, and do not display them as actual values;salesTrendFlagText/salesTrendFlag is 0=stable 1=rising 2=falling.
Error handling and collaboration: When a query fails, explain the reason based on the response errcode/errmsg or TikTok body.code/message and suggest corrections (TikTok Official path not in whitelist returns errcode 1005, missing parameter 1002, upstream exception 1003; HTTP 401/402 are handled according to the authentication and credits section below); when using multiple tools consecutively, summarize the findings from each tool into a coherent analysis, noting the data source and time window.

Resolve authentication and credits issues

When the following exceptional situations occur, use references/onboarding.md to guide the user in resolving the issue:

Note: You are workbuddy, and the channel is workbuddy; when using onboarding to guide login and registration, the channel mustbe workbuddy. This is very important!

Exceptional situations

API Key not configured: The environment variable is not configured with LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY。
Response 401 or 402 status code
Response indicates insufficient credits or balance: The message contains "insufficient credit balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or similar meaning.