Kwai User Posts
Kwaiのユーザー投稿とは、アカウントが公開している投稿で、キャプション、投稿者情報、添付メディア、ハッシュタグ、メンション、タイムスタンプ、表示中のエンゲージメント数を含みます。これらのコンテンツとコンテキストのフィールドは、アカウント調査、メディア形式の確認、特定時点のエンゲージメント比較に活用できます。
Kwai User Posts API の主な機能
- 2種類の識別情報の入力に対応ユーザー名、または kwai.com や kwai-video.com 上の公開プロフィールURLのどちらかから開始できます。識別情報のフィールドは少なくとも1つ必要です。
- 公開投稿を1ページ分取得選択した公開アカウントについて、プロバイダーの1ページで返された投稿を取得します。ソースのカーソルや呼び出し側で指定する結果件数上限は公開していません。
- 正規化されたコンテンツと投稿者のコンテキスト投稿テキスト、公開投稿者フィールド、ソースURL、メディア参照、ハッシュタグ、メンション、公開日時、取得日時を一貫した投稿形式で受け取れます。
- 表示中のエンゲージメントのスナップショット取得可能ないいね数・コメント数・シェア数・再生数を collected_at とともに保持し、比較を観測時刻に結び付けます。
Kwai User Posts API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
url | 必須(いずれか1つ以上) | 解析後のホスト名が kwai.com、kwai-video.com、またはそのいずれかのサブドメインである、空でないKwaiプロフィールの参照です。オーソリティとホスト名があればスキームは問わず、プロトコル相対参照も受け付けます。url または username を指定してください。両方を指定することもできます。 |
username | 必須(いずれか1つ以上) | 先頭に任意で @ を1つ付け、その後にASCIIの英字、数字、ドット、アンダースコア、ハイフンからなる1〜64文字が続くKwaiユーザー名で、全体の最大長は65文字です。プロバイダーにはこの値が handle として渡されます。 |
Kwai User Posts API の使い方
対応するKwaiの識別情報を送信して非同期タスクを追跡し、完了後に保存された正規化結果をページ送りで読み取ります。
- Kwaiのユーザー名、または kwai.com や kwai-video.com 上の公開プロフィールURLのどちらかを用意します。
- url または username を /v1/kwai/user-posts に POST し、返された task_id を保存します。
- タスクが成功するか失敗を報告するまで、/v1/tasks/{task_id} をポーリングします。
- data.results.items を読み取り、has_more が true の間はタスク結果の next_cursor を使用します。このカーソルは保存済みの結果をページ送りするもので、Kwaiのソースを対象とするものではありません。
curl -X POST "https://api.socq.ai/v1/kwai/user-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.kwai.com/@ShortShortz8"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow the stored-result next_cursor while has_more is trueKwai User Posts API の主なユースケース
- 公開アカウントのコンテンツ調査: 選んだアカウント1つについて、キャプション、投稿者の帰属情報、公開メディアの参照、ハッシュタグ、メンション、公開日時を確認します。
- メディア形式の確認: 元の投稿と投稿者の情報を保持したまま、返された投稿を取得可能なメディア種別、再生時間、サムネイル、サイズごとにグループ化します。
- 特定時点のエンゲージメント比較: collected_at で観測期間を特定しながら、取得した投稿間で表示中のいいね数・コメント数・シェア数・再生数を比較します。
Kwai User Posts API 活用のヒント
- 送信前に、ユーザー名を受け付けられる「@ は任意」の形式に正規化し、プロフィールURLのホストが kwai.com または kwai-video.com であることを検証してください。
- ソースへのリクエストに cursor や results_limit を追加しないでください。各タスクは、対応する識別情報のフィールドのみを使ってプロバイダーに1ページ分を要求します。
- GET /v1/tasks/{task_id} の cursor と limit は、送信後に保存済みのタスク結果をページ送りする場合にのみ使用してください。limit は1〜500を受け付け、デフォルトは50です。
- テキスト、投稿者の詳細、個々の指標、メディア、ハッシュタグ、メンション、公開日時は任意項目として扱い、スナップショットは collected_at で時点を固定してください。
関連API
Kwai User Posts API 以外に別の種類の公開Kwaiデータが必要な場合は、これらのAPIをご利用ください。
- Kwai Profile API — ユーザー名または対応URLから公開Kwaiプロフィール1件を取得し、正規化されたアカウント情報、画像、アカウント属性、表示中のカウント、取得情報を返します。
- Kwai Post API — 既知の公開Kwai投稿URL 1件から、正規化されたコンテンツ、投稿者、メディア、タイムスタンプ、エンティティ、表示中のエンゲージメントの各フィールドを取得します。