VPC環境で利用できます。
メディアアセットを分析し、分析結果であるインデックスを作成します。アセットごとに最新のインデックスは1件のみ保持され、分析が完了すると、既存の最新のインデックスは新しいインデックスに置き換えられます。分析が行われている間は、既存のインデックスの結果はそのまま有効であり、分析に失敗した場合でも既存のインデックスは保持されます。
参考
- メディアアセットの登録が完了した後、分析をリクエストできます。
- アセットで分析が実行中の場合、新しい分析をリクエストすると
409エラーが返されます。現在進行中の分析が完了した後、再度リクエストしてください。 sceneRangeとminSceneDurationSec/maxSceneDurationSecは、同時には使用できません。シーンの長さをカスタム設定する場合は、必ずminSceneDurationSecとmaxSceneDurationSecを併せて入力してください。
リクエスト
リクエスト形式を説明します。リクエスト形式は次の通りです。
| メソッド | URI |
|---|---|
| POST | /api/v1/workspaces/{workspace_name}/projects/{project_id}/assets/{asset_id}/index |
リクエストヘッダ
Media Intelligence APIで共通して使用されるヘッダの詳細は、Media Intelligenceのリクエストヘッダをご参照ください。
リクエストパスパラメータ
リクエストパスパラメータの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
workspace_name |
String | Required | ワークスペース名 |
project_id |
String | Required | プロジェクト ID
|
asset_id |
String | Required | メディアアセット ID |
リクエストボディ
リクエストボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
sceneRange |
String | Optional | (ビデオ分析時)自動で分割されるシーンの長さ
|
minSceneDurationSec |
Integer | Optional | (ビデオ分析時)シーンの最小時間 (秒)
|
maxSceneDurationSec |
Integer | Optional | (ビデオ分析時)シーンの最大時間 (秒)
|
analysisPersonCount |
Integer | Required | 分析時に検出する人物の数
|
tagIdList |
Array<Integer> | Optional | 分析時に検出する人物タグの ID
|
sourceLanguage |
String | Optional | 分析対象ソースの言語情報
|
detectAudioEffects |
Boolean | Optional | (ビデオ分析時)音声効果を検出するか
|
リクエスト例
リクエストのサンプルコードは次の通りです。
プリセット方式
curl --location --request POST 'https://mi.apigw.ntruss.com/api/v1/workspaces/my-workspace/projects/1234/assets/5678/index' \
--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 '{
"sceneRange": "MEDIUM",
"analysisPersonCount": 6,
"tagIdList": [101, 203],
"sourceLanguage": "KO",
"detectAudioEffects": false
}'
シーンの長さを直接指定
curl --location --request POST 'https://mi.apigw.ntruss.com/api/v1/workspaces/my-workspace/projects/1234/assets/5678/index' \
--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 '{
"minSceneDurationSec": 15,
"maxSceneDurationSec": 120,
"analysisPersonCount": 6,
"sourceLanguage": "KO"
}'
レスポンス
レスポンス形式を説明します。
レスポンスボディ
レスポンスボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
code |
String | - | API処理結果コード |
message |
String | - | API処理結果メッセージ |
result |
Object | - | 分析リクエスト受付情報 |
result.assetId |
String | - | メディアアセット ID |
result.createdTime |
String | - | 分析リクエストの作成日時
|
result.createdUserName |
String | - | 分析をリクエストしたユーザー名 |
参考
分析の進行状況はレスポンスに含まれません。分析の状態は、メディアアセット分析状態の照会で確認できます。
レスポンスステータスコード
Media Intelligence APIで共通して使用されるレスポンスステータスコードの詳細は、Media Intelligenceのレスポンスステータスコードをご参照ください。
| エラーコード | メッセージ | 説明 |
|---|---|---|
| 400 | sceneRange and minSceneDurationSec/maxSceneDurationSec are mutually exclusive | sceneRangeとカスタム範囲を同時入力 |
| 400 | minSceneDurationSec and maxSceneDurationSec must be provided together | minSceneDurationSecまたはmaxSceneDurationSecを単独で入力 |
| 400 | minSceneDurationSec must be less than or equal to maxSceneDurationSec | minSceneDurationSec > maxSceneDurationSecの場合 |
| 400 | minSceneDurationSec out of range (10–30) | minSceneDurationSecの有効な範囲を超過 |
| 400 | maxSceneDurationSec out of range (25–300) | maxSceneDurationSecの有効な範囲を超過 |
| 409 | Analysis already in progress | アセットで実行中の分析がある |
レスポンス例
レスポンスのサンプルコードは次の通りです。
{
"code": "0",
"message": "success",
"result": {
"assetId": "5678",
"createdTime": "2026-07-01T10:00:00",
"createdUserName": "username"
}
}