アセット検索のリクエスト

VPC環境で利用できます。

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

参考

アセット検索リクエストは非同期で処理し、アセット検索結果の照会にて結果を確認できます。
クエリは1つだけ入力可能で、textQueryまたはimageQueryのうち、いずれか一方だけ使用できます。
フィルタは、人物(persons)とセリフ(dialogues)に基づいて must、any、not条件を設定できます。
1分当たり1,000回まで呼び出すことができます。呼び出し数の調整が必要な場合、サポートにお問い合わせください。

リクエスト

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

メソッド	URI
POST	/api/v1/workspaces/{workspace_name}/assets/search

リクエストヘッダ

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

リクエストボディ

リクエストボディの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`query`	Object	Required	メディアアセット検索条件(テキスト、画像、人物、セリフ)
`query.textQuery`	String	Conditional	メディアアセットのテキストクエリ `textQuery`または`imageQuery`は必ず入力セミコロン(`;`)、バーティカルバー(`\|`)、バッククォート(`)は使用できない
`query.imageQuery`	String	Conditional	アップロード完了した画像ファイルのキー値 `textQuery`または`imageQuery`は必ず入力
`query.personQuery`	Object	Optional	メディアアセット内に含めるか、除外する人物の条件
`query.personQuery.must`	Array[Integer]	Optional	必ず含めるべき人物 IDリスト
`query.personQuery.any`	Array[Integer]	Optional	1つ以上含まれるべき人物 IDリスト
`query.personQuery.not`	Array[Integer]	Optional	含めてはいけない人物 IDリスト
`query.dialogQuery`	Object	Optional	ビデオのメディアアセット内に含めるか、除外するセリフの条件セミコロン(`;`)、バーティカルバー(`\|`)、バッククォート(`)は使用できない画像アセットは0と表示
`query.dialogQuery.must`	Array[String]	Optional	ビデオ内で必ず含めるべきセリフリスト画像アセットは0と表示
`query.dialogQuery.any`	Array[String]	Optional	ビデオ内で1つ以上含まれるべきセリフリスト画像アセットは0と表示
`query.dialogQuery.not`	Array[String]	Optional	ビデオ内で含めてはいけないセリフリスト画像アセットは0と表示
`queryOption`	Object	Optional	類似度信頼レベルの設定
`queryOption.confidenceLevel`	String	Optional	類似度信頼レベル `LOW` \| `MEDIUM`(デフォルト) \| `HIGH`
`filter`	Object	Optional	検索対象プロジェクト、ビデオ、インデックスの更新日フィルタ
`filter.projectIds`	Array[Integer]	Conditional	検索するプロジェクト IDリスト `projectIds`または`assetIds`は必ず入力
`filter.assetIds`	Array[Integer]	Conditional	検索するメディアアセット IDリスト `projectIds`または`assetIds`は必ず入力
`filter.asseTypes`	Array[enum]	Optional	検索するアセットタイプ (未設定時、すべてのアセットタイプで検索を実行) `IMAGE` \| `VIDEO` `IMAGE`: 画像 `VIDEO`: ビデオ
`filter.indexModifiedFrom`	String	Optional	インデックス更新の開始日時 ISO 8601形式
`filter.indexModifiedTo`	String	Optional	インデックス更新の終了日時 ISO 8601形式

リクエスト例

リクエストのサンプルコードは次の通りです。

curl --location --request POST 'https://mi.apigw.ntruss.com/api/v1/workspaces/{workspace_name}/assets/search' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
  "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	-	API処理結果コード
`message`	String	-	API処理結果メッセージ
`result`	Object	-	検索リクエスト結果情報
`result.searchId`	String	-	作成されたアセット検索識別子アセット検索結果照会 APIで使用

レスポンス例

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

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