検索

このガイドでは、index 済み動画を自然言語検索でクエリし、関連度順の結果を読む方法を説明します。

検索は pure-read POST operation です。SEARCH_CONTENT を使い、Idempotency-Key を無視します。

Index 済みエビデンスを検索する

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/search" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "person entering through the north door",
    "video_ids": ["vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"],
    "threshold": 0.82,
    "limit": 10
  }'

query は必須です。threshold の既定値は 0.7 で、0 から 1 までです。limit の既定値は 25 で、1 から 100 までです。video_ids を指定する場合、すべての id がキーのワークスペースから見える必要があります。

Result shape

response の形は標準の list envelope に似ています。

{
  "data": [
    {
      "id": "vid_0190b5d4_frame_0042",
      "video_id": "vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
      "title": "warehouse-inspection.mp4",
      "time_position": 222000,
      "score": 0.94,
      "tags": ["person", "north door"],
      "scene_description": "A person enters through the north door."
    }
  ],
  "next_cursor": null,
  "has_more": false
}

time_position は動画開始からの millisecond です。image と video_url は、存在する場合、確認可能な signed URL です。score を evidence として扱わず、timestamp と返された media または scene description を使ってください。

検索結果は 1 ページのみです。リクエストボディに cursor パラメータが存在しないため、next_cursor と has_more を使って次のページを取得することはできません。結果の件数を調整するには limit（最大 100）を変更するか、video_ids または threshold で検索範囲を絞り込んでください。

Empty と stale result

data が空の response は有効です。最近の index write は search に遅れて反映される場合があります。検索前に video status が completed になるまで待ち、空の page を failure に変換しないでください。