linkfox-kalodata-tiktok-video

Kalodata - TikTok 動画検索と詳細

このスキルは、Kalodata データソースを介した 2 段階の TikTok 動画ワークフローをサポートします。

1. TikTok Shop の動画ランキングを閲覧し、成果の高い購入可能な動画を見つけます。
2. videoId を指定して、1 本の動画のパフォーマンス詳細を取得します。

ユーザーがランキング、人気動画、バイラル動画、または動画の検索を求めている場合は、検索エンドポイントを使用します。ユーザーがすでに videoId を持っている場合、またはランキング結果から 1 本の動画を選択した場合は、詳細エンドポイントを使用します。

主な概念

動画ランキングエンドポイントは、region、dateRange、language、currency、および任意の GMV 範囲 revenue_range で絞り込んだ、ページ分割されたランキングを返します。sortField を使用して revenue で並べ替えます。各動画行には、動画の識別情報、エンゲージメント、収益、広告パフォーマンス、クリエイターの各フィールドが含まれます。結果は pageNumber（1～5）と pageSize（5～100）でページ分割されます。

動画詳細エンドポイントは、videoId で指定した購入可能な TikTok 動画を1 本取得します。動画のエンゲージメント指標、収益化指標、広告指標、クリエイターの識別情報、地域、再生時間、リンクされた商品の数を返します。videoId は通常、ランキングレスポンスの video_id フィールドから取得します。

どちらのエンドポイントも、統計データの反映に遅延（T+1）が生じる場合があります。リクエストとレスポンスの詳細については、references/api.md を参照してください。

データフィールド

ランキング行には次の項目が含まれます。

フィールド	説明
video_id	動画の一意な ID。詳細を取得する際に videoId として渡します
video_title	動画のタイトル／キャプション
views	動画の視聴回数
digg_count / comment_count / share_count	いいね、コメント、シェアの数
revenue	指定した通貨での総 GMV
revenue_growth_rate	収益の成長率（%）
ad / ad_view_ratio / ad_revenue_ratio / ads_roas	広告パフォーマンスに関するフィールド
belonged_creator_id / belonged_creator_handle	クリエイターの識別情報
creator_debut	クリエイターのデビュー日

詳細行には、さらに次の項目が含まれます。

フィールド	説明
video_region	動画の地域。空の場合があります
sales_volumn	販売数量。フィールド名は volumn と綴られています
video_gpm	1000 回の視聴あたりの GMV（収益）
ads_views / ad_cpa / ads_period	広告の視聴回数、CPA、広告配信期間
duration	動画の再生時間（秒）
product_number	動画にリンクされている商品の数

パラメーターガイド

動画ランキング（/kalodata/video/rank）

パラメーター	型	必須	説明
region	string	いいえ	市場地域コード。例：US
dateRange	string	いいえ	期間。例：last7Day、last30Day
pageNumber	integer	いいえ	ページ番号。1～5
pageSize	integer	いいえ	ページサイズ。5～100
language	string	いいえ	レスポンスの言語。例：zh-CN、en-US
currency	string	いいえ	金額指標の通貨。例：USD
category_id	string	いいえ	カテゴリー ID のフィルター
shop_id	string	いいえ	ショップ ID のフィルター
creator_id	string	いいえ	クリエイター ID のフィルター
product_id	string	いいえ	商品 ID のフィルター
revenue_range	string	いいえ	レスポンスの revenue フィールドは総 GMV であるため、GMV の範囲を指定します。例：1-100、>1000、<100
followers_range	string	いいえ	クリエイターのフォロワー数の範囲フィルター
ads_roas	number	いいえ	広告 ROAS のフィルター
sortField	object	いいえ	GMV の並べ替え指定。例：{"field":"revenue","type":"DESC"}

動画詳細（/kalodata/video/detail）

パラメーター	型	必須	説明
videoId	string	はい	ランキングの video_id フィールド、または TikTok 動画 URL から取得した TikTok 動画 ID
region	string	いいえ	市場地域コード。例：US
dateRange	string	いいえ	期間。例：last7Day、last30Day
language	string	いいえ	レスポンスの言語。例：zh-CN、en-US
currency	string	いいえ	金額指標の通貨。例：USD

呼び出し方法

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

出力ポリシー（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-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. 米国のTikTok動画ランキングを表示

{"region":"US","dateRange":"last7Day","pageSize":10,"pageNumber":1,"currency":"USD"}

2. GMVで絞り込み、GMV順に並べ替え

{"region":"US","dateRange":"last7Day","revenue_range":"1-100","sortField":{"field":"revenue","type":"DESC"},"pageSize":10,"pageNumber":1,"currency":"USD"}

3. 1本の動画の詳細を取得

{"videoId":"7659161409279806734","region":"US","dateRange":"last7Day","currency":"USD"}

4. 動画の検索から詳細確認までのワークフロー

Run kalodata_video_search.py first, choose a row's video_id, then pass that value as videoId to kalodata_video_detail.py.

表示ルール

1. ランキング結果は、タイトル、動画ID、再生回数、エンゲージメント、収益、広告の指標、クリエイターのハンドル名を含むテーブルで表示します。
2. 詳細結果は、識別情報、エンゲージメント、収益化、広告、クリエイター、再生時間、関連商品をまとめたプロフィールとして表示します。
3. 指標を表示する際は、必ず dateRange、region、currency を明記します。
4. 正確なフィールド名 sales_volumn を使用します。
5. video_gpm は1000回あたりのGMVです。パーセンテージとして表示しないでください。
6. ユーザーが対応している sortField を明示的に指定しない限り、ランキング順を維持してください。

重要な制限事項

• ランキングはキーワード検索ではありません。地域と期間に基づいてランキングを参照します。
• バックエンドは revenue_range によるGMVの範囲指定をサポートしています。レスポンスの revenue はGMVであり、利益や広告費ではありません。
• 詳細の取得には videoId が必要です。タイトルだけでは動画を見つけられません。
• ランキングのレスポンスには総件数やページ数が含まれません。結果数は data.length で確認できます。
• pageNumber の範囲は1～5、pageSize の範囲は5～100です。
• 一時的な上流エラーは、Kalodata の HTTP 554 メッセージを伴う errcode 501 として表示されることがあります。同じパラメーターで1～2回再試行してください。パラメーターを自動で変更しないでください。
• 動画以外のエンティティには、該当する Kalodata の商品／クリエイター／ショップ／ライブ配信スキルを使用してください。

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

該当 -- TikTok動画のランキングまたは動画詳細の検索：

ユーザーの表現	シナリオ
「TikTok動画ランキング」、「TikTok動画順位」	動画ランキングの検索
「TikTok人気動画」、「TikTokでバズっている動画」	人気動画またはバズ動画のランキング
「TikTok販売動画ランキング」、「top TikTok videos」	地域別のショッパブル動画ランキング
「TikTok動画の詳細」、「TikTok販売動画データ」	単一動画の詳細検索
「動画再生回数」、「動画のエンゲージメントデータ」、「動画GPM」	動画のエンゲージメントまたは収益化指標
「kalodata video search/detail」	データソースの直接指定

該当しない -- TikTok動画以外の情報が必要な場合：

• TikTokの商品／クリエイター／ショップ／ライブ配信のランキングまたは詳細
• キーワードによる動画または商品の検索
• TikTok広告／広告キャンペーンの管理
• 動画編集、動画ダウンロード、コンテンツ作成

計算リソース消費ルール

呼び出しごとに計算リソースを 7.0 消費します。

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

フィードバック：

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

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

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

---

高品質でプロフェッショナルな越境ECスキルをもっとお探しなら、LinkFox Skills をご覧ください。