質問する

インデックス済み動画について引用付きの質問を行い、会話の文脈を保って追加の質問を続けます。

このガイドでは、セッションを作成して質問し、引用付きで回答を確認する方法を説明します。

一致する場面の一覧ではなく回答が必要な場合は、会話を使用します。セッションは 1 つ以上のインデックス済み動画と、サーバー側に保持される短い会話履歴を結び付けます。完了した回答には、ユーザーが確認できる引用が含まれます。

始める前に

各動画がインデックス済みで検索可能であり、API キーの作成者から参照できることを確認します。
API キーには QUERY_CONTENT 権限が必要です。
認証とアクセスの手順で BASE_URL と DEEPFRAME_API_KEY を設定します。

1. セッションを作成する

会話で使用するすべての動画を指定し、セッションを一度だけ作成します。

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/sessions" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: session-create-01" \
  -d '{"video_ids":["vid_01JABC123"]}'

返された不透明（opaque）な sess_... の値を保存します。

export SESSION_ID="sess_01JSESSION123"

レスポンスの expires_at は現在の有効期限です。セッションの読み取り、質問の送信、質問結果の確認を行うと、セッションの利用時刻が更新されます。

2. 質問を送信する

curl --fail-with-body -X POST \
  "$BASE_URL/api/v1alpha1/sessions/$SESSION_ID/queries" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: question-create-01" \
  -d '{"query":"北側のドアが開いた後、何が変わりましたか？"}'

API は HTTP 202 と、不透明な qry_... 識別子、processing 状態を返します。結果の確認に使う識別子を保存します。

export QUERY_ID="qry_01JQUERY123"

3. 回答を確認する

約 1 秒ごとに次のリクエストを送ります。

curl --fail-with-body \
  "$BASE_URL/api/v1alpha1/sessions/$SESSION_ID/queries/$QUERY_ID" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY"

status が completed または failed になったら確認を止めます。どちらも終了状態です。完了した質問には、保存された answer と citations が含まれます。失敗した質問には query_age_exceeded や engine_error などの理由が含まれます。確認を無期限に続けず、新しい質問を送るべきか判断してください。

4. 引用を検証する

回答と引用を 1 つの結果として扱います。ユーザーが引用先のエビデンスを開き、主張に基づいて行動する前に、元の動画の該当時刻を確認できるようにしてください。引用のない文章を、検証済みのエビデンスとして提示しないでください。

追加の質問を行う

同じ SESSION_ID で別のクエリを送信します。DeepFrame は直近の質問と完了した回答を文脈として使用するため、リクエストには新しい質問だけを含めます。会話履歴を送信しないでください。

質問を変更する場合は、新しいべき等性キー（Idempotency-Key）を使用します。過去の質問を確認するには、GET /api/v1alpha1/sessions/{session_id}/queries を呼び出します。正確なリクエストとレスポンスのスキーマは API リファレンスで確認してください。