linkfox-echotik-list-video

EchoTik TikTok 動画検索

このスキルは TikTok 動画のデータを検索・分析し、越境販売者やマーケターがパフォーマンスの高い動画を見つけ、コンテンツ戦略を比較し、TikTok マーケットプレイス全体で動画単位のエンゲージメントや売上への貢献度を評価できるようにします。

主な概念

EchoTik は TikTok Shop の分析プラットフォームです。このツールでは、地域、クリエイター、商品、カテゴリ、再生回数、再生時間、公開日時、広告・AI・販売動画のフラグで詳細に絞り込み、TikTok 動画を一覧表示できます。エンゲージメント指標（再生回数、いいね、コメント、シェア、お気に入り）、推定売上貢献度（動画経由の販売数と GMV）、動画のメタデータ（再生時間、解像度、カバー画像、公開日）を返します。

必須入力：region は必須です。クリエイター（userId）、商品（productId）、カテゴリ（productCategoryId）、再生回数の範囲、再生時間の範囲、公開日時の範囲、動画タイプ（広告／AI／販売）の任意のフィルターを指定して、結果を絞り込めます。

並べ替えフィールド：動画は、いいね数（1）、公開日時（2）、または再生回数（3、デフォルト）で並べ替えられます。

ページネーション：pageSize は 10 の倍数である必要があり、最大値は 100 です。バックエンドは 10 件ずつ取得し、結果を統合します。

関連スキル：このツールでは、地域やフィルターを指定して動画を一覧表示できます（商品は不要です）。特定の商品に関連付けられた動画を取得するには、代わりに productId を指定して linkfox-echotik-product-video を使用してください。

データフィールド

フィールド	説明
videoId	動画 ID
videoDesc	動画の説明／キャプション
officialUrl	TikTok 公式動画 URL
coverUrl	動画カバー画像 URL
duration	動画の再生時間（秒）
width / height	動画の寸法（ピクセル単位、例：576×1090）
ratio	動画の解像度ラベル（例：540p/720p）
dataSize	動画ファイルのサイズ
createDate	公開日
userId / uniqueId / avatar	クリエイター ID / TikTok の unique_id / クリエイターのアバター
totalViewsCnt	合計再生回数（1 日／7 日／30 日別：totalViews1dCnt / 7dCnt / 30dCnt）
totalDiggCnt	合計いいね数（1 日／7 日／30 日別：totalDigg1dCnt / 7dCnt / 30dCnt）
totalCommentsCnt	合計コメント数
totalSharesCnt	合計シェア数
totalFavoritesCnt	合計お気に入り数
totalVideoSaleCnt	動画経由の販売数（件数）
totalVideoSaleGmvAmt	動画経由の販売 GMV（金額）
salesFlagText	販売動画フラグ（是／否）
isAdText	広告動画フラグ（是／否）
createdByAiText	AI 動画フラグ（是／否／不明）
productCategoryList	商品カテゴリ
videoProducts	関連商品
region	マーケットプレイスコード
sourceType / sourceTool	ソースタイプ / ソースツール

パラメーターガイド

必須項目と地域

パラメーター	型	必須	デフォルト	説明
region	string	はい	-	マーケットプレイスコード。以下の対応リストを参照してください

クリエイター／商品／カテゴリ

パラメーター	型	説明
userId	string	クリエイター（インフルエンサー）IDで絞り込みます
productId	string	関連商品 ID で絞り込みます
productCategoryId	string	関連商品カテゴリ ID で絞り込みます

エンゲージメント／再生時間／日時

パラメーター	型	説明
minTotalViewsCnt / maxTotalViewsCnt	integer	合計再生回数の範囲（最小／最大）
minDuration / maxDuration	integer	再生時間の範囲（秒、最小／最大）
minCreateTime / maxCreateTime	integer	公開日時の範囲（Unix タイムスタンプ、秒、最小／最大）

動画タイプのフラグ

パラメーター	型	説明
salesFlag	integer	販売動画：0=販売なし、1=販売あり（带车）
isAd	integer	広告動画：0=広告なし、1=広告あり（投流）
createdByAi	string	AI 動画："true"=AI、"false"=非 AI（文字列であり、ブール値ではありません）

並べ替えとページネーション

パラメーター	型	デフォルト	説明
videoSortField	integer	3	並べ替えフィールド：1=いいね数（total_digg_cnt）、2=公開日時（create_time）、3=視聴回数（total_views_cnt）
sortType	integer	1	並べ替え順：0=昇順、1=降順
pageNum	integer	1	ページ番号（1から開始）
pageSize	integer	50	ページサイズ — 10の倍数である必要があり、最大100

対応マーケットプレイス

US（米国）、ID（インドネシア）、TH（タイ）、PH（フィリピン）、MY（マレーシア）、VN（ベトナム）、GB（英国）、MX（メキシコ）、SG（シンガポール）、SA（サウジアラビア）、BR（ブラジル）、ES（スペイン）、JP（日本）、DE（ドイツ）、IT（イタリア）、FR（フランス）

ユーザーがマーケットプレイスを指定しない場合は、確認するか、USをデフォルトとして使用してください。

呼び出し方法

• API エンドポイント：POST /echotik/listVideo（パラメーター／レスポンス／エラーコードの詳細は references/api.md を参照）
• Python スクリプト：python scripts/echotik_list_video.py '<JSON 参数>' [--inline]
• コスト制約：このツールは計算リソースを消費します。同一セッション内で同じパラメーターの組み合わせを指定した場合、デフォルトでは1回のみ呼び出します。スクリプトには24時間のローカルキャッシュがあります。失敗または結果が空の場合、キーワードを変更したり、ページをめくったり、郵便番号を変更したりして自動的に続けて試行してはいけません。検索を続ける必要がある場合は、追加の消費が発生することを事前にユーザーに伝えてください。

出力方針（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-echotik-list-video-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリで、Claude Code では現在のプロジェクトディレクトリです。<session> は環境変数 SESSION_ID から取得し、ユーザーのタスクごとに自動的にまとめられます。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーにします）
• レスポンス本文が8 KB以下：ファイルに保存した後、完全な JSON を stdout に出力します
• レスポンス本文が8 KBを超える場合：ファイルに保存した後、stdout には要約のみを出力します（トップレベルのフィールド、total／costToken などの一般的な件数、最大のリストフィールドの長さと先頭3件のサンプル）
• --inline を付けると、stdout に全量を強制出力します（同様にファイルにも保存します）

データの読み取りに関する推奨事項：まず要約を確認して十分か判断してください。具体的なフィールドが必要な場合は、保存された JSON ファイルから jqまたはConvertFrom-Json を使って必要なデータだけを抽出し、JSON 全体をコンテキストに読み込まないようにしてください。

認証と計算リソースの問題の解決

以下の異常が発生した場合は、references/onboarding.md の案内に従って問題を解決してください。

異常な状況

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY も LINKFOXAGENT_API_KEY も設定されていません。
• 401または402のレスポンスステータスコード
• 計算リソースまたは残高不足を示すレスポンス：メッセージに「算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值」、または同様の意味の内容が含まれています。

使用例

1. 視聴回数が多い米国の動画

{
  "region": "US",
  "videoSortField": 3,
  "sortType": 1,
  "pageSize": 20,
  "pageNum": 1
}

2. コンバージョン率の高い販売動画（動画の販売数順）

{
  "region": "US",
  "salesFlag": 1,
  "videoSortField": 3,
  "sortType": 1,
  "pageSize": 20
}

3. 特定のクリエイターの動画

{
  "region": "US",
  "userId": "7234567890123456789",
  "videoSortField": 1,
  "sortType": 1
}

4. 指定期間内の視聴回数が多い動画（いいね数順）

{
  "region": "GB",
  "minTotalViewsCnt": 100000,
  "minCreateTime": 1717200000,
  "maxCreateTime": 1719792000,
  "videoSortField": 1,
  "sortType": 1
}

5. 公開日順に並べ替えた最近の AI 動画

{
  "region": "US",
  "createdByAi": "true",
  "videoSortField": 2,
  "sortType": 1,
  "pageSize": 50
}

表示ルール

1. データは表形式で表示：動画の説明（長い場合は省略）、視聴回数、いいね数、コメント数、シェア数、動画の販売数、動画の GMV、公開日、クリエイター ID を表示します
2. 元動画へのリンク：officialUrl が利用可能な場合は、ユーザーが TikTok で動画を見られるようにリンクを表示します
3. カバー画像：coverUrl がある場合は、動画のサムネイルを利用できることをユーザーに伝えます
4. 再生時間の形式：duration（秒）を読みやすい形式に変換します（例：90秒の場合は「1:30」）
5. 推定値に関する注意：動画の販売数と GMV は推定値です。概算であることをユーザーに伝えてください
6. 複数期間の指標：関連する場合は、1日／7日／30日ごとの視聴回数といいね数の内訳が保存された JSON にあることを伝えます
7. 結果件数：total のレコード数と現在のページを必ずユーザーに伝えてください。結果が多い場合は、ページネーションの利用またはフィルターの絞り込みを提案します

重要な制限事項

1. リージョンは必須：region は必須であり、API にデフォルト値は適用されません。
2. pageSize のルール：10の倍数である必要があり、最大100です。それ以外の値は拒否または調整される場合があります。
3. createdByAi は文字列："true"／"false" を渡してください（ブール値ではありません）。値は ^(true|false)$ に対して検証されます。
4. タイムスタンプ：minCreateTime／maxCreateTime は秒単位の Unix タイムスタンプです。
5. カテゴリ／商品 ID：productId／productCategoryId／userId は内部 ID です。前の結果から取得してください。
6. 二次処理なし：結果はリアルタイムのクエリであり、データベースには保存されません。二次的な SQL／データ処理は利用できません。
7. 特定の商品に関する動画：特定の商品（productId で指定）の動画を一覧表示する場合は、linkfox-echotik-product-video の使用を推奨します。ここでの productId は、リージョンで絞り込まれた動画一覧内のフィルターとしてのみ使用します。

ユーザーの表現とシナリオのクイックリファレンス

適用対象 — TikTok 動画の検索とパフォーマンス分析：

ユーザーの表現	シナリオ
"TikTok热门视频" / "TikTok top videos"	再生数（フィールド 3）で並べ替えた動画を一覧表示
"TikTok带货视频排行"	salesFlag=1 で絞り込み、再生数／売上で並べ替え
"某个达人的TikTok视频"	userId で絞り込み
"TikTok投流视频" / "TikTok广告视频"	isAd=1 で絞り込み
"TikTok AI视频"	createdByAi="true" で絞り込み
"近期高播放TikTok视频"	再生数の範囲と期間で絞り込み
"哪个TikTok视频GMV最高"	再生数で並べ替え、GMV 列を確認

適用対象外 — 地域を指定した動画一覧の範囲を超える要件：

• 特定の 1 つの商品に関する動画（linkfox-echotik-product-video を使用）
• TikTok の商品検索またはランキング（EchoTik の商品検索／ランキングスキルを使用）
• TikTok クリエイター／インフルエンサーのプロフィール分析（フォロワー数、プロフィール文）
• TikTok ライブ配信データ
• 動画のダウンロード URL の解決（linkfox-echotik-get-video-download-url を使用）
• TikTok 以外のプラットフォームの動画データ

適用範囲の判断：ユーザーが「TikTok動画」について尋ねた場合、地域を指定した動画一覧と絞り込みを求めているのか（このスキル）、既知の商品 1 つに関連する動画を求めているのか（linkfox-echotik-product-video）を判断してください。地域や、「热门／带货／投流视频」のような絞り込み条件に言及していて、特定の商品を指定していない場合は、このスキルが適用されます。

計算リソース消費ルール

計算リソースを 5 消費します。

ユーザーは計算リソースの消費に応じて料金を支払います。このスキルを高頻度で呼び出す必要がある場合、またはユーザーが計算リソースの消費量を十分に把握していない場合は、十分に検討したうえで必ずユーザーに通知し、続行するかどうかはユーザーに判断してもらってください。

フィードバック：

以下のいずれかに該当する場合は、フィードバック API を通じてフィードバックを自動検出し、報告してください。

1. このスキルで説明されている機能や目的が、実際の動作と一致しない場合
2. スキルの結果がユーザーの意図と一致しない場合
3. ユーザーがこのスキルへの不満または称賛を表明した場合
4. 改善できると思われることがある場合

references/api.md に記載されているとおりにフィードバック API を呼び出してください。ユーザーの作業を中断しないでください。

---

高品質でプロフェッショナルな越境 EC スキルについては、LinkFox Skills をご覧ください。