クイックスタート

小さな動画を 1 本アップロードし、インデックス完了後に最初の検索を行います。

このガイドでは、Bash または Zsh から最短の一連の操作を行います。MP4 ファイルを 1 本アップロードし、処理が完了するまで待ってから、動画内の場面を検索します。直接アップロードを使うため、200 MiB 以下のファイルを選んでください。

始める前に

curl、jq、Public API Alpha が有効なワークスペース、UPLOAD_VIDEOS、READ_VIDEOS、SEARCH_CONTENT 権限を持つキーが必要です。信頼できるシェルだけで実行してください。API キーをブラウザのコードやソース管理に入れないでください。

入力値を設定する

キー、ローカルファイルのパス、検索する質問を置き換えます。結果を確認しやすいように、動画に含まれると分かっている内容を質問してください。

export BASE_URL="https://api.deepframe.cloud"
export DEEPFRAME_API_KEY="df_live_..."
export VIDEO_FILE="/absolute/path/to/your-video.mp4"
export SEARCH_QUERY="ドアから入ってくる人物を説明してください"
export QUICKSTART_RUN_ID=$(date -u +%Y%m%dT%H%M%SZ)

command -v curl >/dev/null || {
  echo "続行する前に curl をインストールしてください。"
  exit 1
}

command -v jq >/dev/null || {
  echo "続行する前に jq をインストールしてください。"
  exit 1
}

test -r "$VIDEO_FILE" || {
  echo "VIDEO_FILE には読み取り可能な MP4 ファイルを指定してください。"
  exit 1
}

FILE_NAME=$(basename "$VIDEO_FILE")
FILE_SIZE=$(wc -c < "$VIDEO_FILE" | tr -d ' ')

test "$FILE_SIZE" -le 209715200 || {
  echo "このクイックスタートで使えるファイルは 200 MiB 以下です。大きなファイルには分割アップロードガイドを使ってください。"
  exit 1
}

エラーが表示されなければ準備完了です。アップロードガイドでは、10 GiB までのファイルと再開可能な分割アップロードを説明しています。

アップロードセッションを作成する

API がアップロード方法を選び、短時間だけ有効な保存先を返します。後で使う値は、次のコマンドですべて保存します。

UPLOAD_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "$BASE_URL/api/v1alpha1/videos" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-upload-$QUICKSTART_RUN_ID" \
  -d "$(jq -n \
    --arg filename "$FILE_NAME" \
    --argjson file_size "$FILE_SIZE" \
    '{
      filename: $filename,
      file_size: $file_size
    }')")

VIDEO_ID=$(jq -er '.video_id' <<<"$UPLOAD_RESPONSE")
UPLOAD_STRATEGY=$(jq -er '.strategy' <<<"$UPLOAD_RESPONSE")
TARGET_URL=$(jq -er '.target.url' <<<"$UPLOAD_RESPONSE")
TARGET_CONTENT_TYPE=$(jq -er '.target.headers["Content-Type"]' <<<"$UPLOAD_RESPONSE")

printf 'video_id=%s\nstrategy=%s\n' "$VIDEO_ID" "$UPLOAD_STRATEGY"

想定される出力:

video_id=vid_...
strategy=direct

request には filename と正確な file size だけを含めます。content type、duration、upload strategy は server が管理します。再開可能な session には分割アップロードを使います。

動画をアップロードする

返された保存先 URL と Content-Type を使い、動画ファイルを直接送ります。

curl --silent --show-error --fail-with-body \
  -X PUT "$TARGET_URL" \
  -H "Content-Type: $TARGET_CONTENT_TYPE" \
  --data-binary "@$VIDEO_FILE"

直接アップロードが成功すると、HTTP の成功応答が返ります。保存先の有効期限が切れた場合は、POST /api/v1alpha1/videos/{video_id}/upload/targets で新しい保存先を取得してください。別の動画を作り直す必要はありません。

アップロードを完了する

完了操作では、保存されたバイト数を確認して動画処理を開始します。

curl --silent --show-error --fail-with-body \
  -X POST "$BASE_URL/api/v1alpha1/videos/$VIDEO_ID/upload/complete" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-complete-$QUICKSTART_RUN_ID" \
  -d '{}' |
  jq '{id, status, progress}'

API は 202 Accepted を返します。これは処理の開始を示し、処理が完了したことを示すものではありません。

処理が完了するまで待つ

処理時間は動画によって異なります。次のループは 10 秒ごとに状態を確認し、成功または失敗で明確に停止します。

while true; do
  VIDEO_RESPONSE=$(curl --silent --show-error --fail-with-body \
    "$BASE_URL/api/v1alpha1/videos/$VIDEO_ID" \
    -H "Authorization: Bearer $DEEPFRAME_API_KEY")

  VIDEO_STATUS=$(jq -er '.status' <<<"$VIDEO_RESPONSE")
  printf 'status=%s\n' "$VIDEO_STATUS"

  if [ "$VIDEO_STATUS" = "completed" ]; then
    break
  fi

  if [ "$VIDEO_STATUS" = "failed" ]; then
    echo "動画の処理に失敗しました。"
    jq '{status, error, progress}' <<<"$VIDEO_RESPONSE"
    exit 1
  fi

  sleep 10
done

status=completed が成功条件です。検索は処理が完了して初めて利用できます。失敗した動画は検索できません。再試行する前に、返されたエラーを確認してください。

最初の検索を行う

今アップロードした動画だけを検索します。最初は低い threshold で候補を広く取り、実際の用途に合わせて後から調整してください。

SEARCH_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "$BASE_URL/api/v1alpha1/search" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg query "$SEARCH_QUERY" \
    --arg video_id "$VIDEO_ID" \
    '{
      query: $query,
      video_ids: [$video_id],
      limit: 5,
      threshold: 0
    }')")

jq '{
  match_count: (.data | length),
  matches: [.data[] | {
    video_id,
    time_position,
    score,
    scene_description,
    image,
    video_url
  }]
}' <<<"$SEARCH_RESPONSE"

data 配列が返ればリクエストは成功です。空の配列も正常な結果で、条件に合うインデックス済みの根拠がなかったことを示します。各候補の time_position と scene_description を確認し、image または video_url がある場合は、結果を利用する前に開いて確認してください。

安全に終了する

アップロードを完了する前に中断する場合は、API キーを削除する前に未完了のアップロードを中止できます。

curl --silent --show-error --fail-with-body \
  -X DELETE "$BASE_URL/api/v1alpha1/videos/$VIDEO_ID/upload" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY"

正常に完了した後は、このコマンドを実行しないでください。DeepFrame API には現在、完了済み動画を削除するルートがありません。テストデータを準備するときは、この制約を考慮してください。

作業が終わったら、現在のシェルからキーと一時的な値を削除します。

unset DEEPFRAME_API_KEY UPLOAD_RESPONSE VIDEO_RESPONSE SEARCH_RESPONSE
unset TARGET_URL TARGET_CONTENT_TYPE QUICKSTART_RUN_ID

次に、必要な成果を選びます。

検索: インデックス済み動画から関連度順の場面を探します。
分析ランと状態: 型付き分析または繰り返し可能なルールブックレビューを行います。