Douyin Video Detail
Douyinの動画詳細レコードは、既知の公開動画URLを、正規化されたコンテンツ、クリエイター、メディア、日時、表示中のエンゲージメントの各フィールドと結び付けます。ワークフローですでに正確な動画リンクを持っていて、情報補完、レビュー、後日の比較のために一貫したレコードが1件必要な場合に役立ちます。
Douyin Video Detail API の主な機能
- 対応するDouyin URLdouyin.com、iesdouyin.com、または対応するサブドメイン上のURLを1つ受け付けます。/video/ が含まれる場合は、その後に数値IDが続く必要があります。
- 動画1件に限定した結果プロバイダーへの詳細リクエストを1回実行し、正規化された動画レコードを最大1件保存します。ソースのページネーションや results_limit はありません。
- キャプションとクリエイターのコンテキスト取得可能な動画テキストに加え、正規化されたクリエイターID、ユーザー名、表示名、プロフィールURL、アバター、アカウントフラグを返します。
- メディアと再生時間のフィールド取得可能な動画や画像の参照、プレビュー、サイズ、メディアの再生時間、正規化された duration_seconds フィールドを保持します。
- タイムスタンプ付きのエンゲージメントのスナップショット取得可能ないいね数・コメント数・シェア数・再生数・視聴数を、リアルタイムのカウンターとしてではなく、published_at と collected_at と組み合わせて提供します。
Douyin Video Detail API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
url | 必須 | 必須。douyin.com、iesdouyin.com、または対応するサブドメイン上の空でないURLです。/video/ が含まれる場合は、その後に数値IDが続く必要があります。タスク1件につき受け付けるURLは1つのみです。 |
Douyin Video Detail API の使い方
対応するDouyin動画URLを1つ送信して非同期タスクを追跡し、成功後に保存された正規化結果を読み取ります。
- DOUYIN_VIDEO_URL に、ホストが douyin.com、iesdouyin.com、またはそのサブドメインである公開URLを設定します。/video/ セグメントがある場合は、その後に数値IDが続く必要があります。
- url 文字列を /v1/douyin/video-detail に POST し、返された task_id を保存します。
- タスクが成功または失敗するまで、/v1/tasks/{task_id} をポーリングします。タスクが完了するまで結果フィールドは利用できません。
- 成功したら data.results.items を読み取ります。プロバイダーが生成するアイテムは最大1件で、limit と next_cursor はSocQの保存済み結果リーダーに属するものです。
curl -X POST "https://api.socq.ai/v1/douyin/video-detail" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"url\":\"$DOUYIN_VIDEO_URL\"}"
# Poll GET /v1/tasks/{task_id}
# Read the normalized video from data.results.itemsDouyin Video Detail API の主なユースケース
- 既知動画カタログの補完: 承認済みのDouyin動画リンクに、正規化されたID、キャプション、クリエイター、公開日時、再生時間、メディア、ソースの各フィールドを追加します。
- 発見から詳細取得への接続: Douyinのユーザー動画や動画検索のレコードから保持している対応動画URLを、詳細照会の正確な入力として使用します。
- 特定時点の比較の準備: 繰り返し取得した成功結果を collected_at とともに保存し、決めたスケジュールで取得可能な公開エンゲージメントのスナップショットを比較します。
Douyin Video Detail API 活用のヒント
- プロバイダーが正しく解決できるよう、対応するホスト名上の公開動画への直接の参照を使用してください。/video/ を含む場合は、数値の動画IDをそのまま残してください。
- 実際の公開動画URLを用意するまで、Playgroundのフィールドは空欄のままにしてください。このエンドポイントには、どの場合にも使える信頼性の高いデフォルト値はありません。
- 公開リクエストで受け付けるのは url のみのため、タスク1件につきURLを1つ送信し、results_limit、cursor、無関係なIDは省略してください。
- クリエイター、メディア、音声、ハッシュタグ、メンション、エンゲージメントの各フィールドが欠けている場合は、空文字列や0ではなく、取得できなかったものとして扱ってください。
- 指標の比較には collected_at を、コンテンツの時系列には published_at を使用してください。両者は異なる時点を表します。
- 動画コメントの取得に進む場合は、詳細タスクがコメントまで展開されるとは想定せず、取得できた対応動画URLを別のエンドポイントに渡してください。
関連API
Douyin Video Detail API 以外に別の種類の公開Douyinデータが必要な場合は、これらのAPIをご利用ください。
- Douyin Live Room Detail API — 数値のルームIDから既知のDouyinライブ配信ルーム1件を取得し、正規化されたルーム情報、配信者情報、メディア、表示中の視聴者数を返します。
- Douyin User Profile API
- Douyin User Videos API
- Douyin Video Comments API
- Douyin Video Search API