ビデオの詳細
ライブ YouTube フェッチをトリガーせずに、保存されている 1 つのビデオ スナップショットを読み取ります。
https://api.shortsmonkey.com/v1/videos/abc123発見すると1クレジット
ビデオの詳細#
ライブ YouTube フェッチをトリガーせずに、保存されている 1 つのビデオ スナップショットを読み取ります。
認証#
Authorization: Bearer sm_live_... を送信します。完全なキーを URL、Cookie、本文、ログ、または分析に決して配置しないでください。
データの鮮度#
ランキングは、ワーカーによって公開された安定したスナップショットを読み取ります。パブリック読み取りによって YouTube リフレッシュがトリガーされることはありません。
リクエスト#
| アイテム | 価値 | 説明 |
|---|---|---|
| 方法 | GET | HTTPリクエストメソッド |
| 完全な URL | https://api.shortsmonkey.com/v1/videos/abc123 | 生産 API URL |
| 認証 | Authorization: Bearer sm_live_... | ヘッダーのみで完全なキーを送信します |
| コンテンツタイプ | リクエスト本文がありません | GET リクエストにはリクエスト本文がありません |
| クレジット | 発見すると1クレジット | エラー応答には 0 クレジットがかかります |
リクエストパラメータ#
| 名前 | 位置 | タイプ | 必須 | デフォルト | 値または制限 | 説明 |
|---|---|---|---|---|---|---|
video_id | パス | string | はい | — | 6 ～ 32 個の URL セーフ文字 | 保存された YouTube ビデオ ID。欠落したレコードはコストゼロで 404 を返します |
成功の応答フィールド#
all_data は、安定したスナップショットからのフィルタされていないページです。 filter_data は、エンドポイントのデフォルトとリクエスト フィルター後の同じスナップショットからのページです。各結果は個別にページ分割されます。
ドット表記はネストされたオブジェクトを表し、[] は配列項目を表します。不明な加入者数は null と subscriber_count_hidden: true です。 1 つのリクエストは、両方のセットの合計ではなく、大きい方の返品アイテム数を使用して 1 回請求されます。
| フィールドパス | タイプ | Null可能 | 説明 |
|---|---|---|---|
data.all_data.items | array<object> | いいえ | 現在のページのフィルタされていないビデオ アイテム |
data.all_data.items[].video_id | string | いいえ | YouTube ビデオ ID |
data.all_data.items[].title | string | いいえ | 動画のタイトル |
data.all_data.items[].video_url | string | いいえ | YouTube ビデオ URL |
data.all_data.items[].channel.id | string | はい | チャンネルID |
data.all_data.items[].channel.title | string | いいえ | チャンネルタイトル |
data.all_data.items[].channel.subscribers | integer | はい | 購読者数;非表示時は null |
data.all_data.items[].channel.subscriber_count_hidden | boolean | いいえ | チャンネル登録者数を非表示にするかどうか |
data.all_data.items[].views | integer | いいえ | 閲覧数スナップショット |
data.all_data.items[].views_to_subscribers_ratio | number | はい | 視聴者数対チャンネル登録者数の比率 |
data.all_data.items[].opportunity_score | number | はい | オポチュニティースコア |
data.all_data.items[].duration_seconds | integer | いいえ | 動画の長さ (秒) |
data.all_data.items[].published_at | string(date-time) | はい | UTC ISO 8601 でのビデオ公開時間 |
data.all_data.items[].snapshot_at | string(date-time) | はい | データ収集時間 |
data.all_data.items[].niche | string | はい | ニッチまたはカテゴリー |
data.all_data.items[].track | string | はい | データセット トラック識別子 |
data.all_data.items[].region | string | はい | 地域コード |
data.all_data.items[].reasons | array<string> | いいえ | ランキングの理由 |
data.all_data.items[].video_type | string | いいえ | shorts または long |
data.all_data.next_cursor | string | はい | この結果セットの次のページ cursor。終了時はnull |
data.filter_data.items | array<object> | いいえ | デフォルトとリクエストフィルター後のビデオアイテム |
data.filter_data.items[].video_id | string | いいえ | YouTube ビデオ ID |
data.filter_data.items[].title | string | いいえ | 動画のタイトル |
data.filter_data.items[].video_url | string | いいえ | YouTube ビデオ URL |
data.filter_data.items[].channel.id | string | はい | チャンネルID |
data.filter_data.items[].channel.title | string | いいえ | チャンネルタイトル |
data.filter_data.items[].channel.subscribers | integer | はい | 購読者数;非表示時は null |
data.filter_data.items[].channel.subscriber_count_hidden | boolean | いいえ | チャンネル登録者数を非表示にするかどうか |
data.filter_data.items[].views | integer | いいえ | 閲覧数スナップショット |
data.filter_data.items[].views_to_subscribers_ratio | number | はい | 視聴者数対チャンネル登録者数の比率 |
data.filter_data.items[].opportunity_score | number | はい | オポチュニティースコア |
data.filter_data.items[].duration_seconds | integer | いいえ | 動画の長さ (秒) |
data.filter_data.items[].published_at | string(date-time) | はい | UTC ISO 8601 でのビデオ公開時間 |
data.filter_data.items[].snapshot_at | string(date-time) | はい | データ収集時間 |
data.filter_data.items[].niche | string | はい | ニッチまたはカテゴリー |
data.filter_data.items[].track | string | はい | データセット トラック識別子 |
data.filter_data.items[].region | string | はい | 地域コード |
data.filter_data.items[].reasons | array<string> | いいえ | ランキングの理由 |
data.filter_data.items[].video_type | string | いいえ | shorts または long |
data.filter_data.next_cursor | string | はい | この結果セットの次のページ cursor。終了時はnull |
meta.request_id | string | いいえ | リクエストトレースID |
credits.cost | integer | いいえ | 1 ビデオが見つかった場合 |
credits.remaining | integer | いいえ | アカウントの残りのクレジット |
credits.period_ends_at | string(date-time) | いいえ | 現在のクレジット期間の終了日 |
ページネーションと cursor#
all_data.next_cursor を all_cursor として送信し、filter_data.next_cursor を filter_cursor として送信します。 cursor は独立しており、不透明で、署名されており、24 時間有効です。従来の cursor は、filter_cursor のエイリアスにすぎません。
Eタグ#
ランキングはIf-None-Matchをサポートしています。ヒットすると、HTTP 304 と X-Credits-Cost: 0 が返されます。
エラーとレート制限#
すべてのエラーには、code、安定した英語の message、request_id、および details が含まれます。すべての 4xx/5xx 応答にはクレジットがかかりません。
| HTTP ステータス | コード | 原因 | 推奨されるアクション |
|---|---|---|---|
| 400 | INVALID_REQUEST | パラメータの形式、組み合わせ、または範囲が無効です | details.issues を使用してパラメータを修正します |
| 401 | INVALID_API_KEY | キーが無効または非アクティブです | Bearer ヘッダーとキーのステータスを確認する |
| 402 | SUBSCRIPTION_REQUIRED / CREDITS_EXHAUSTED | サブスクリプションまたはクレジットが利用できない | 計画、残高、主要な安全予算を確認する |
| 429 | RATE_LIMITED | レートまたは同時実行の制限を超えました | Retry-After 間隔後に再試行します |
| 503 | DATA_STALE / SERVICE_UNAVAILABLE | データまたはサービスが一時的に利用できない | 後で再試行し、request_id を保持します |
curl -X GET "https://api.shortsmonkey.com/v1/videos/abc123" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY"