linkfox-tiktok-selection-and-shoppable-video

Linkfox TikTok 商品選定と商品紹介動画（TikTok Product Selection and Shoppable Video）

TikTok の商品選定と商品紹介動画に対応する、ワンストップの AI ツールキットです。3 種類の基盤ツールと 10 項目のサブ機能を統合し、商品選定データ（EchoTik の 16 地域市場／FastMoss のグローバルコマース）から、公式の商品紹介動画公開フロー（TikTok 動画アカウントの認可 → 商品紹介可能な商品 → ショッピング動画の事前チェック／公開）までをカバーします。各サブ機能のパラメーター、レスポンスフィールド、エラーコードの詳細は references/ 内の該当ファイルを、実行可能なスクリプトは scripts/ を参照してください。

対応範囲

✅ 対応機能

• TikTok 商品選定データ（echotik_tiktok、EchoTik、16 の地域市場をカバー）：新商品ランキングから人気商品や新たなトレンドを発見（echotik_tiktok list-new-product-rank）；販売数／クリエイター／コミッション／評価／レビューの複数の条件で商品を検索（echotik_tiktok list-product）；商品に関連する商品紹介動画の再生数／エンゲージメント／動画経由の販売数／GMV を照会（echotik_tiktok product-video）；複数商品の詳細情報を一括取得。期間別の販売数と GMV、ライブ配信経由の販売数、商品紹介を行うクリエイター数、価格、評価、コミッションを含みます（echotik_tiktok batch-product-detail）；TikTok 動画リンクを解析し、ウォーターマークなし／ありのダウンロード先、再生先、カバー画像の URL を返します（echotik_tiktok get-video-download-url）。
• TikTok グローバルコマースの売れ筋商品と商品選定（fastmoss_tiktok、FastMoss）：日／週／月単位でカテゴリー別に売れ筋商品ランキングと GMV ランキングを分析（fastmoss_tiktok product-rank-top-selling）；カテゴリー／販売数／コミッション率／クリエイター数／ショップの種類で商品を検索・絞り込み（fastmoss_tiktok product-search）。
• TikTok 公式商品紹介動画 API（tiktok_official_video_api）：動画アカウントのクリエイター向け OAuth 認可、認可済みアカウント一覧、トークンの照会と access_token の更新（tiktok_official_video_api linkfox-tiktok-video-auth）；ショッピング動画の事前チェック、チェック結果の照会、公開、公開状態の照会、クリエイタープロフィールの照会、大容量ファイルの分割アップロード（tiktok_official_video_api linkfox-tiktok-video）；クリエイターが商品紹介できる商品の照会（ショップの商品とショーケース／ライブ配信バッグの商品）。ショッピング動画への商品リンク設定に使う product_id を取得します（tiktok_official_video_api linkfox-tiktok-video-products）。
• 対応する region/marketplace：EchoTik は 16 の TikTok Shop 地域市場をカバーします。FastMoss はグローバルコマースに対応し、region で絞り込めます。TikTok 公式動画アカウントでは global（デフォルト）／us（米国ストア）の region に対応しています。具体的な値は各 references を参照してください。

❌ 対象外・制限事項

• API Key が必要：すべてのツールで環境変数 LINKFOX_AGENT_API_KEY（または LINKFOXAGENT_API_KEY）が必要です。各ツールは個別に課金され、レート制限も独立しています。データの鮮度と地域カバレッジはデータソースによって異なります。
• 課金上の制約：同一セッションでは、同じパラメーターの組み合わせに対する呼び出しはデフォルトで 1 回のみです（スクリプトにはローカルキャッシュがあります）。失敗または結果が空の場合、キーワードを自動で変更したり、ページをめくったり、地域を変えて連続で試行したりしてはいけません。検索を続ける場合は、追加の費用が発生することを事前にユーザーに伝えてください（課金ルールは skills-version.json と references 内の api.md にある costToken フィールドを参照：EchoTik の 5 項目は fixed≈4.5/9000 token、FastMoss の 2 項目は fixed≈10.5/21000 token、TikTok 公式の 3 項目は無料）。
• TikTok 公式モジュールの分離：linkfox-tiktok-video／linkfox-tiktok-video-products は /tiktokVideo/developerProxy のみを経由し、path は affiliate_creator／video／creator で始まる必要があります（それ以外の場合は errcode 1005）。/tiktokShop/* には使用できません（TikTok Shop の販売者モジュールには linkfox-tiktok-shop-auth を使用します）。トークン ttsAccessToken は、linkfox-tiktok-video-auth で認可した後、/tiktokVideo/accountTokens から取得します。対象はクリエイター側に固定されています。
• TikTok 公式の依存関係：ショッピング動画を公開するには、まず linkfox-tiktok-video-auth で認可してトークンを取得し、次に linkfox-tiktok-video-products で product_id を取得してから、最後に linkfox-tiktok-video で事前チェック／公開を行います。check_auth_dependency.py で linkfox-tiktok-video-auth がインストール済みかどうかを確認できます（exit 42＝未インストール／未認可。先に認可を完了してください）。
• 大容量ファイルのアップロード制限：≤10MB の場合は upload_shoppable_video_file を使用します（multipart、ゲートウェイは現在未対応）。>10MB の場合は、大容量ファイルの 3 段階分割アップロードを使用します（Initialize → 分割 PUT → Bind。詳細は references/large-file-upload.md を参照。Step 1/3 は proxy 経由で実行できますが、Step 2 の分割 PUT はゲートウェイを経由しません）。
• 対象外：TikTok Shop の小売店舗 ERP（商品／注文／財務。linkfox-tiktok-shop-auth と業務 skill を使用）、TikTok Shop のショッピング動画（/tiktokShop/developerProxy。linkfox-tiktok-creator を使用）、TikTok 広告の配信、物流とサプライチェーン、EC 以外のタスク、プラットフォームまたは販売者との直接の連絡。

工具选择指南

按需求在下表定到子能力，再跳到【业务需求路由速查】查端点/脚本/references 取参执行。

需求 / 用户说	默认推荐（子能力）	何时换用其他
TikTok 选品 / 搜商品（"TikTok 上什么好卖"）	linkfox-echotik-list-product（16 区域市场，销量/达人/佣金/评分多维）	要全球电商+日/周/月维度+范围筛选（达人数/佣金率 range）用 linkfox-fastmoss-product-search
TikTok 新品 / 新兴趋势（"最近有什么新品爆"）	linkfox-echotik-list-new-product-rank（新品排行）	要热销榜（非新品）用 linkfox-fastmoss-product-rank-top-selling
TikTok 热销榜 / 爆品排行 / GMV 排名	linkfox-fastmoss-product-rank-top-selling（日/周/月+类目）	要"新品"趋势用 linkfox-echotik-list-new-product-rank
商品详情 / 多周期销量 GMV（"这个 productId 卖得怎么样"）	linkfox-echotik-batch-product-detail（1d/7d/15d/30d/60d/90d/累计+直播+达人）	—
商品带货视频（"这个商品有哪些带货视频 / 视频销量"）	linkfox-echotik-product-video（播放/互动/视频销量/GMV）	—
视频下载 / 去水印（"下载这个 TikTok 视频"）	linkfox-echotik-get-video-download-url（无水印/含水印/播放/封面）	—
视频号授权 / 绑定视频号 / 刷新令牌	linkfox-tiktok-video-auth（OAuth+令牌）	TikTok Shop 卖家授权用 linkfox-tiktok-shop-auth（不互通）
达人能带什么货 / 橱窗商品 / 取 product_id	linkfox-tiktok-video-products（店铺商品+橱窗/直播袋）	—
发布可购物视频 / 视频挂车（"发一个带商品的 TikTok 视频"）	linkfox-tiktok-video（预检→发布→查状态）	需先 linkfox-tiktok-video-auth 授权 + linkfox-tiktok-video-products 取 product_id
达人主页 / 档案	linkfox-tiktok-video（get_creator_profile，独立功能）	—
大文件分片上传视频（>10MB）	linkfox-tiktok-video（large_file_upload_init/bind + 分片 PUT）	≤10MB 走 upload_shoppable_video_file（网关暂不支持 multipart）

工具选择思路

• 重要：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参、从中调研出最合适的子能力，并推荐用户，让用户自己决定。
• 满足程度同等的前提下，向用户推荐"默认推荐子能力"。

业务需求路由速查

按【工具选择指南】定到子能力 后，下表查端点、脚本与 references 文件取参执行：

子機能 ↔ references ファイル ↔ エンドポイント ↔ スクリプト（10 項目）

echotik_tiktok

子機能	references ファイル	エンドポイント	スクリプト
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

子機能	references ファイル	エンドポイント	スクリプト
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

子機能	references ファイル	エンドポイント	スクリプト
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 公式の3つの子機能は helper を共有します：response_io.py（ファイル保存／要約）、check_auth_dependency.py（linkfox-tiktok-video-auth を確認）。linkfox-tiktok-video にはさらに _video_api_runner.py / _video_endpoints.py / _tiktok_video_common.py があり、linkfox-tiktok-video-products にはさらに _products_api_runner.py / _products_endpoints.py / _tiktok_video_products_common.py があります。いずれもエントリースクリプトと同じディレクトリにあり、呼び出し時に利用されます。

呼び出し方法

• ゲートウェイ：${LINKFOX_TOOL_GATEWAY}/<端点>（デフォルトは https://tool-gateway.linkfox.com）。リクエスト方式は POST、Content-Type は application/json、認証 Header は Authorization: <api_key> です（api_key は環境変数 LINKFOX_AGENT_API_KEY または LINKFOXAGENT_API_KEY から読み取ります。未設定の場合は下記の【認証とポイントの問題を解決する】を参照してください）。各エンドポイントのパスは上記の【業務要件ルーティング早見表】および対応する references ファイルを参照してください。
• TikTok 公式ショッピング動画のフロー：linkfox-tiktok-video / linkfox-tiktok-video-products は POST /tiktokVideo/developerProxy 経由で紫鳥の tiktok-proxy/creator/{region}/{path} に転送されます。呼び出し側は path / method / ttsAccessToken（= creator access_token、上流リクエストヘッダー x-tts-access-token）/ region（デフォルトは global / us）を渡します。app_key / timestamp / sign は紫鳥プロキシによって自動的に注入されます。名前付きスクリプト（video_api.py / products_api.py / 各 get_*.py / post_*.py）では {"api": "...", "openId": "..."} を渡すだけで、スクリプト内部で /tiktokVideo/accountTokens を呼び出して ttsAccessToken を取得し、その後 developerProxy を呼び出します。
• Python スクリプト：各子機能に対応する scripts/<スクリプト名>.py '<JSON パラメーター>' [--inline] を実行します（スクリプト名とエンドポイントはルーティング早見表を参照してください）。スクリプト内でゲートウェイ呼び出し、認証、ファイル保存を行います。
• 出力方針（スクリプトのデフォルト動作）：常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill>-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリ、<session> は環境変数 SESSION_ID から取得します。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）。レスポンス本文が 8 KB 以下の場合は、ファイルに保存した後、全体を stdout に出力します。8 KB を超える場合は要約（トップレベルのフィールド、一般的な件数、最大リスト長＋先頭3件のサンプル）のみを出力します。--inline を付けると全量を強制的に出力します（同様にファイルにも保存されます）。
• データの読み取りに関する推奨事項：まず要約を確認し、それで十分かどうかを判断してください。具体的なフィールドが必要な場合は、JSON 全体をコンテキストに入れないよう、保存された json ファイルから jq または PowerShell の ConvertFrom-Json を使って必要なデータを抽出してください。
• 完全なパラメーター：各子機能のリクエストパラメーター、レスポンスフィールド、エラーコード、curl の例は references/<子機能>.md を参照してください（ファイルにはその子機能の SKILL.md 本文と api.md 全文が含まれます）。linkfox-tiktok-video には references/large-file-upload.md（大容量ファイルの分割アップロードに関する詳細）も含まれます。

使用例

以下ではデータ層ごとに代表的な子機能の入出力パラメーターの例を示します。その他の子機能のパラメーターは、対応する references ファイルを参照してください。

选品与数据层（EchoTik / FastMoss）

1. TikTok 新品排行（echotik_tiktok → echotik_list_new_product_rank.py）

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

出参：products[]（title/asin/price/minPrice/maxPrice/currency/totalSaleCnt/totalSaleGmvAmt/salesTrendFlagText/totalVideoCnt/totalLiveCnt/totalIflCnt 达人数/productCommissionRate/productRating/reviewCount/categoryId/imageUrl）、total、columns、costToken。

2. TikTok 商品搜索（echotik_tiktok → echotik_list_product.py）

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

出参：products[]（productId/productName/title/price/spuAvgPrice/productRating/reviewCount/ratings/productCommissionRate/totalSaleCnt/monthlySalesUnits/totalSaleGmvAmt/totalIflCnt 达人数/categoryName/firstCrawlDt/salesTrendFlagText）、total、columns、costToken。

3. TikTok 热销榜（fastmoss_tiktok → fastmoss_product_rank_top_selling.py）

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

出参：products[]（title/productId/price/minPrice/maxPrice/currency/totalSaleCnt/totalSaleGmvAmt/growthRate/shopName/shopTotalUnitsSold/categoryName/productCommissionRate/imageUrl/offShelvesText）、total、columns、costToken。dateInfo.type 支持 day / week / month。

4. TikTok 商品搜索（fastmoss_tiktok → fastmoss_product_search.py）

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

带范围筛选：{"keyword": "beauty", "region": "US", "commissionRateRange": {"min": 0.10}, "creatorCountRange": {"min": 50}, "orderField": "commission_rate", "pageSize": 10} 出参：products[]（title/productId/price/totalSaleCnt/totalSaleGmvAmt/totalVideoCnt/totalLiveCnt/totalIflCnt 达人数/productCommissionRate/productRating/reviewCount/skuCount/shopName/isCrossBorder/tiktokUrl/fastmossUrl/imageUrl）、total、columns、costToken。

5. 批量商品详情（echotik_tiktok → echotik_batch_product_detail.py）

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

出参：products[]（productId/productName/region/sellerId/minPrice/maxPrice/spuAvgPrice/productRating/reviewCount/productCommissionRate/totalSaleCnt/totalSaleGmvAmt/totalLiveCnt/totalVideoCnt/totalIflCnt 达人数/totalViewsCnt/discount/freeShipping/salesTrendFlag/firstCrawlDt）、total、columns、costToken。也可用 productUrls 传 TikTok Shop 商品 URL。

6. 商品带货视频（echotik_tiktok → echotik_list_product_video.py）

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

出参：data[]（videoId/productId/userId/videoDesc/officialUrl/covet 封面/totalFavoritesCnt 点赞/totalVideoSaleCnt/totalVideoSaleGmvAmt/hashTag/createDate/region）、total、columns、costToken。

7. 视频下载地址（echotik_tiktok → echotik_get_video_download_url.py）

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

出参：downloadUrl（无水印）、playUrl、coverUrl、dynamicCoverUrl、videoId、costToken、errmsg。

带货视频发布层（TikTok 官方）

完整链路：linkfox-tiktok-video-auth 授权取 ttsAccessToken → linkfox-tiktok-video-products 取 product_id → linkfox-tiktok-video 上传 file_id →（可选）预检 → 发布 → 查状态。

8. 视频号授权与令牌（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. 视频号可带货商品（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

出参：商品列表含 product_id（供 linkfox-tiktok-video 预检/发布挂车）、data.next_page_token（翻页）。page_size 必填 1~20。

10. 发布可购物视频（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

上传视频文件取 file_id：≤10MB 走 upload_shoppable_video_file（multipart，网关暂不支持）；>10MB 走大文件分片（large_file_upload_init → PUT 分片 → large_file_upload_bind，详见 references/large-file-upload.md）。

展示规则

1. 客观呈现数据：以清晰表格展示查询结果，不做主观商业建议（除非用户主动要求）；不同区域币种不同，展示价格/收入时务必提示币种（响应 currency 字段标明本地币种）。
2. 来源标注：展示数据时说明来自哪个工具/数据源（EchoTik / FastMoss / TikTok 官方）。
3. 令牌安全：不向用户明文输出完整 ttsAccessToken / accessToken / refreshToken，仅展示前 10 字符等掩码形式。
4. 不可用数据：值为 0 或 -1 的字段表示数据不可用，标注"N/A"或省略，不作实际值展示；salesTrendFlagText/salesTrendFlag 为 0=平稳 1=上升 2=下降。
5. 错误处理与协同：查询失败时根据响应 errcode/errmsg 或 TikTok body.code/message 说明原因并建议修正（TikTok 官方 path 未在白名单返回 errcode 1005、缺参 1002、上游异常 1003；HTTP 401/402 按下方认证积分处理）；连续使用多工具时将各工具发现汇总为连贯分析，标注数据来源与时间窗。

解决认证和积分问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

注意：你是workbuddy，并且渠道是workbuddy，使用 onboarding 引导登录注册时 channel 必须为 workbuddy。这非常重要！

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。