シーン検索のリクエスト

最新のコンテンツが反映されていません。早急にアップデート内容をご提供できるよう努めております。最新のコンテンツ内容は韓国語ページをご参照ください。

VPC環境で利用できます。

テキスト、画像、人物、セリフの条件を利用してシーンを検索します。

参考

シーン検索リクエスト APIは非同期 APIであり、シーン検索結果照会 APIで確認できます。
クエリは1つだけ入力可能で、textQueryまたはimageQueryのうち、いずれか一方だけ使用できます。
フィルタは、人物(persons)とセリフ(dialogues)に基づいて must/any/not条件を設定できます。

リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

メソッド	URI
POST	/api/v1/scene-search

リクエストヘッダ

Media AI Understanding API で共通して使用されるヘッダの詳細は、Media AI Understandingのリクエストヘッダをご参照ください。

リクエストボディ

リクエストボディは、query、queryOption、filterの3つのオブジェクトで構成されます。

フィールド	タイプ	必須の有無	説明
`query`	Object	Required	シーン検索条件(テキスト、画像、人物、セリフ)
`queryOption`	Object	Optional	類似度信頼レベルの設定
`filter`	Object	Optional	検索対象プロジェクト、動画、インデックスの更新日フィルタ

query

フィールド	タイプ	必須の有無	説明
`textQuery`	String	Conditional	シーンのテキストクエリ `textQuery`または`imageQuery`のうち、いずれか一方は必ず入力セミコロン(`;`)、バーティカルバー(`\\|`)、バッククォート(`)は使用できない
`imageQuery`	String	Conditional	アップロード完了した画像ファイルのキー値 `textQuery`または`imageQuery`のうち、いずれか一方は必ず入力
`personQuery`	Object	Optional	シーン内に含めるか、除外する人物の条件
`personQuery.must`	Array<Integer>	Optional	必ず含めるべき人物 IDリスト
`personQuery.any`	Array<Integer>	Optional	1つ以上含まれるべき人物 IDリスト
`personQuery.not`	Array<Integer>	Optional	含めてはいけない人物 IDリスト
`dialogQuery`	Object	Optional	シーン内に含めるか、除外するセリフの条件セミコロン(`;`)、バーティカルバー(`\\|`)、バッククォート(`)は使用できない
`dialogQuery.must`	Array<String>	Optional	必ず含めるべきセリフリスト
`dialogQuery.any`	Array<String>	Optional	1つ以上含まれるべきセリフリスト
`dialogQuery.not`	Array<String>	Optional	含めてはいけないセリフリスト

queryOption

フィールド	タイプ	必須の有無	説明
`confidenceLevel`	String	Optional	類似度信頼レベル `LOW` \| `MEDIUM`(デフォルト) \| `HIGH`

filter

フィールド	タイプ	必須の有無	説明
`projectIds`	Array<Integer>	Conditional	検索するプロジェクト IDリスト `projectIds`または`videoAssetIds`のうち、いずれか一方は必ず入力
`videoAssetIds`	Array<Integer>	Conditional	検索するビデオアセット IDリスト `projectIds`または`videoAssetIds`のうち、いずれか一方は必ず入力
`indexModifiedFrom`	String	Optional	インデックス更新の開始日時 ISO 8601形式
`indexModifiedTo`	String	Optional	インデックス更新の終了日時 ISO 8601形式

リクエスト例

{
  "query": {
    "textQuery": "暗い路地",
    "imageQuery": null,
    "personQuery": {
      "must": [101, 102],
      "any": [103],
      "not": [104]
    },
    "dialogQuery": {
      "must": ["逃げろ"],
      "any": ["危ない"],
      "not": ["静かにしろ"]
    }
  },
  "queryOption": {
    "confidenceLevel": "MEDIUM"
  },
  "filter": {
    "projectIds": [201],
    "indexModifiedFrom": "2025-08-01T00:00:00Z",
    "indexModifiedTo": "2025-08-07T23:59:59Z"
  }
}

レスポンス

レスポンス形式を説明します。

レスポンスボディ

レスポンスボディの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`code`	String	Required	API処理結果コード
`message`	String	Required	API処理結果メッセージ
`result`	Object	Required	検索リクエスト結果情報
`result.searchId`	String	Required	作成されたシーン検索識別子シーン検索結果照会 APIで使用

レスポンス例

レスポンスのサンプルコードは次の通りです。

{
  "code": "0",
  "message": "success",
  "result": {
    "searchId": "JtWJKTDCKknMHP8Id4Gt"
  }
}

参考

呼び出し制限: APIは、1分当たり1,000回まで呼び出すことができます。
お問い合わせ: 呼び出し数の調整が必要な場合、サポートにお問い合わせください。