シーン要約のリクエスト

VPC環境で利用できます。

アセットの最新のインデックスを対象に、VLMベースのシーン要約をリクエストします。アセットごとに最新のインデックスが1件自動的に対象となるため、インデックス IDを指定せずにシーン概要をリクエストします。シーン要約が完了すると、シーンごとの自然言語によるテキスト要約が作成されます。

参考

シーン要約はインデクシングが完了したアセットでのみリクエストできます。
最初の分析は、必ずシーン全体を対象として実行します。全体分析が完了した後にのみ、特定のシーンを指定した一部だけ再分析することができます。
既にシーン要約が進行中である場合、新しいリクエストは失敗します。
要約結果の言語(locale)は全体分析時にのみ指定可能であり、それ以降のシーン要約に固定されます。一部再分析時には指定できず、既存の言語を継承します。言語の変更は全体再分析でのみ可能です。

リクエスト

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

メソッド	URI
POST	/api/v1/workspaces/{workspace_name}/projects/{project_id}/assets/{asset_id}/scene-summary

リクエストヘッダ

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

リクエストパスパラメータ

リクエストパスパラメータの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`workspace_name`	String	Required	ワークスペース名
`project_id`	String	Required	プロジェクト ID プロジェクトリストの照会を参照
`asset_id`	String	Required	メディアアセット ID メディアアセットリストの照会を参照

リクエストボディ

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

フィールド	タイプ	必須の有無	説明
`scenes`	Array<Integer>	Optional	再分析対象シーン IDリスト最初の全体分析が完了している場合にのみ利用可能入力がない場合は、インデックス内の全シーンを対象に分析入力時、指定されたシーンのみを再分析し、そのシーンの要約のみを更新(既存の他のシーン要約は維持)
`locale`	String	Optional	要約結果の言語 BCP 47形式(例: `ko-KR`、`en-US`)。デフォルト: `ko-KR` 全体分析(`scenes`は未入力)時にのみ指定可能で、指定された値はシーン概要に固定される一部再分析(`scenes`を指定)時、指定できない — 既存の固定言語を継承

リクエスト例

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

curl --location --request POST 'https://mi.apigw.ntruss.com/api/v1/workspaces/my-workspace/projects/1234/assets/5678/scene-summary' \
--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 '{
    "scenes": [12, 13]
}'

レスポンス

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

レスポンスボディ

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

フィールド	タイプ	必須の有無	説明
`code`	String	-	API処理結果コード
`message`	String	-	API処理結果メッセージ
`result`	Object	-	シーン要約のリクエスト情報
`result.sceneSummaryId`	Integer	-	シーン要約のリクエスト ID
`result.indexId`	Integer	-	分析対象のインデックス ID アセットの最新のインデックスが自動的に決まる
`result.locale`	String	-	要約結果の言語 BCP 47形式(例: `ko-KR`、`en-US`)
`result.targetScenes`	Array<Integer>	-	分析対象シーン IDリストすべて分析の場合、`null`
`result.createdTime`	String	-	分析リクエストの作成日時 ISO 8601形式
`result.createdUserName`	String	-	分析をリクエストしたユーザー名

レスポンスステータスコード

Media Intelligence APIで共通して使用されるレスポンスステータスコードの詳細は、Media Intelligenceのレスポンスステータスコードをご参照ください。

エラーコード	メッセージ	説明
400	Invalid scenes	無効なシーン ID
400	Full analysis required before partial analysis	全体分析が完了していない状態で`scenes`を指定
400	Language cannot be specified for partial analysis	一部再分析で`locale`を指定
409	Scene summary already in progress	既に進行中のシーン要約が存在する

レスポンス例

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

{
    "code": "0",
    "message": "success",
    "result": {
        "sceneSummaryId": 101,
        "indexId": 23844,
        "locale": "ko-KR",
        "targetScenes": [12, 13],
        "createdTime": "2026-07-01T11:00:00",
        "createdUserName": "username"
    }
}

Documentation Index