OpenSearch Snapshot API による動画キーフレーム抽出の構築 - OpenSearch - Alibaba Cloud - OpenSearch

AI Search オープンプラットフォームは、API を介したビデオスナップショットサービスの呼び出しをサポートしています。このサービスは、動画からキーフレームを抽出し、OCR、画像解析、またはマルチモーダル埋め込みサービスと組み合わせることで、動画コンテンツの詳細な分析と構造化処理を可能にします。

サービス

サービス名	サービス ID	サービスの説明	API 呼び出しの QPS 制限 (ルートアカウントと RAM ユーザーを含む)
ビデオスナップショットサービス 001	ops-video-snapshot-001	ビデオスナップショットサービス 001 (ops-video-snapshot-001) は、キーフレームをキャプチャすることで動画からコンテンツを抽出します。マルチモーダル埋め込みまたは画像解析機能と組み合わせることで、クロスモーダル検索が可能になります。	5 説明より高い API QPS 制限をリクエストするには、テクニカルサポートにチケットを送信してください。

認証情報の取得

AI Search オープンプラットフォームでは、認証に API キーが必要です。手順については、「API キーの取得」をご参照ください。
サービスエンドポイントの取得

サービスは、パブリックネットワークまたは VPC 経由で呼び出すことができます。詳細については、「サービスエンドポイントの取得」をご参照ください。

非同期タスクの作成

リクエストメソッド：POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/video-snapshot/{service_id}/async

host：サービスエンドポイント。API はインターネットまたは VPC 経由で呼び出すことができます。詳細については、「サービスエンドポイントの取得」をご参照ください。

コンソールで、左側のナビゲーションウィンドウにある [API キー] をクリックします。[エンドポイント] の下に、パブリック API ドメイン (HTTPS をサポート) とプライベート API ドメイン (VPC 環境用) が表示されます。左上のワークスペースドロップダウンを使用して、対象のワークスペースに切り替えます。

workspace_name：ワークスペース名 (例：default)。
service_id：組み込みのサービス ID (例：ops-video-snapshot-001)。

リクエストパラメーター

ヘッダーパラメーター

API キー認証

パラメーター	型	必須	説明	値の例
Content-Type	String	はい	リクエストタイプ：application/json	application/json
Authorization	String	はい	API キー	Bearer OS-d1**2a

ボディパラメーター

パラメーター	型	必須	説明
input	Object(input)	はい	処理するマルチメディアファイルを指定します。
parameters	Object	いいえ	サービスパラメーターを指定します。
output	Object(output)	はい	出力フォーマットとファイルストレージパスを制御します。

input

パラメーター	型	必須	説明
content	String	いいえ	Base64 エンコードされた動画データ。mp4、avi、mkv、mov、flv、webm をサポートしています。説明 input.content と input.oss パラメーターは相互排他的です。どちらか一方のみを指定してください。 Base64 データの使用：エンコードされた Base64 文字列を `content` パラメーターに `data:video/<FORMAT>;base64,<BASE64_VIDEO>` のフォーマットで渡します。ここで： `video/<FORMAT>`：動画のフォーマット。例えば、MP4 動画の場合は `video/mp4` を使用します。 `<BASE64_VIDEO>`：Base64 エンコードされた動画データ。例：data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	いいえ	入力ファイルの OSS パス。例：oss://<BUCKET_NAME>/xxx/xxx.mp4。
file_name	String	いいえ	動画ファイル名。指定しない場合、ファイルコンテンツから名前が解析されます。

Parameters

パラメーター	型	必須	説明
interval	Int	いいえ	フレーム抽出の間隔 (秒)。デフォルトは 1 秒です。
format	String	いいえ	出力フレームのフォーマット。jpg と png をサポートしています。デフォルトは jpg です。

output

パラメーター

型

必須

説明

type

String

いいえ

base64：画像コンテンツを Base64 フォーマットで返します。同期呼び出しでのみサポートされます。

oss：抽出されたフレームを OSS に保存します (デフォルト)。

oss

String

いいえ

出力ファイルの OSS パス。type が oss の場合に必須です。

例：oss://<BUCKET_NAME>/result/path

レスポンスパラメーター

パラメーター	型	説明	値の例
result.task_id	String	ビデオ抽出タスクの一意の ID。	snapshot-xxxx-abc-123

Curl リクエストの例

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Your API Key>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-snapshot/ops-video-snapshot-001/async"
  --data '{
    "input":{
        "oss" : "oss://<BUCKET_NAME>/test.mp4"
    },
    "parameters" : {
    },
    "output": {
        "type":"oss",
        "oss" :"oss://<BUCKET_NAME>/result/path"
    }
  }' \

レスポンスの例

{
  "request_id":"de81e152284a2d3b1f4315d*******",
  "latency":21,
  "usage":{},
  "result":{
        "task_id":"snapshot-20250617102142-110841*******-*******",
        "status":"PENDING"
            }
 }

非同期タスクのステータス取得

リクエストメソッド：GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/video-snapshot/{service_id}/async/task-status?task_id={task_id}

host：サービスエンドポイント。API はインターネットまたは VPC 経由で呼び出すことができます。詳細については、「サービスエンドポイントの取得」をご参照ください。

workspace_name：ワークスペース名 (例：default)。
service_id：組み込みのサービス ID (例：ops-video-snapshot-001)。

リクエストパラメーター

パラメーター名	型	必須	説明	例
service_id	String	はい	サービス ID。	ops-video-snapshot-001
task_id	String	はい	非同期ビデオスナップショットタスクの作成時に返されるタスク ID。	snapshot-xxxx-abc-123

レスポンスパラメーター

パラメーター	型	説明	値の例
result.task_id	String	ビデオ抽出タスクの一意の ID。	snapshot-xxxx-abc-123
result.status	String	タスクステータス： PENDING：処理待ち SUCCESS：タスクが正常に完了 FAIL：タスクが失敗して停止	PENDING
result.error	String	ステータスが FAIL の場合のエラーメッセージ。正常な状態では空です。
result.data	List(SnapshotResult)	動画処理の結果。
usage.image_count	Int	抽出されたフレームの数。

SnapshotResult

パラメーター	型	説明
frame_index	Int	動画内のフレーム番号。
path	String	ファイルの OSS パス。output が OSS に設定されている場合、このフィールドには抽出されたフレームの URL エンコードされたストレージパスが OSS に表示されます。
content	String	Base64 エンコードされた画像コンテンツ。content または path のいずれか一方のみが存在し、このフィールドは同期タスクの場合にのみ表示されます。
frame_time	Float	動画内で抽出されたフレームのタイムスタンプ (秒)。

Curl リクエストの例

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Your API Key>" \
"http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-snapshot/ops-video-snapshot-001/async/task-status?task_id=snapshot-20250617102142-1108418170738252-******" \

レスポンスの例

{
  "request_id":"83b423e2e63613a878c369c20******",
  "latency":11,
  "usage":{
      "image":64
          },
  "result":{
      "task_id":"snapshot-20250617102142-1108418170738252-******",
      "status":"SUCCESS",
       "data":[
                {
                  "frame_index": 0,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_0.jpg",
                  "frame_time": 0.0
                },
                ......
                {
                  "frame_index": 1890,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_63.jpg",
                  "frame_time": 63.0
                }                
              ]
            }
}

同期ビデオスナップショットタスクの作成

URL

{host}/v3/openapi/workspaces/{workspace_name}/video-snapshot/{service_id}/sync

host：サービスエンドポイント。API はインターネットまたは VPC 経由で呼び出すことができます。詳細については、「サービスエンドポイントの取得」をご参照ください。

workspace_name：ワークスペース名 (例：default)。
service_id：組み込みのサービス ID (例：ops-video-snapshot-001)。

リクエストパラメーター

ヘッダーパラメーター

API キー認証

パラメーター	型	必須	説明	値の例
Content-Type	String	はい	リクエストタイプ：application/json	application/json
Authorization	String	はい	API キー	Bearer OS-d1**2a

ボディパラメーター

パラメーター	型	必須	説明
input	Object(input)	はい	処理するマルチメディアファイルを指定します。
parameters	Object	いいえ	サービスパラメーターを指定します。
output	Object(output)	はい	出力フォーマットとファイルストレージパスを制御します。

input

パラメーター	型	必須	説明
content	String	いいえ	Base64 エンコードされた動画データ。mp4、avi、mkv、mov、flv、webm をサポートしています。説明 input.content と input.oss パラメーターは相互排他的です。どちらか一方のみを指定してください。 Base64 データの使用：エンコードされた Base64 文字列を `content` パラメーターに `data:video/<FORMAT>;base64,<BASE64_VIDEO>` のフォーマットで渡します。ここで： `video/<FORMAT>`：動画のフォーマット。例えば、MP4 動画の場合は `video/mp4` を使用します。 `<BASE64_VIDEO>`：Base64 エンコードされた動画データ。例：data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	いいえ	入力ファイルの OSS パス。例：oss://<BUCKET_NAME>/xxx/xxx.mp4。
file_name	String	いいえ	動画ファイル名。指定しない場合、ファイルコンテンツから名前が解析されます。

Parameters

パラメーター	型	必須	説明
interval	Int	いいえ	フレーム抽出の間隔 (秒)。デフォルトは 1 秒です。
format	String	いいえ	出力フレームのフォーマット。jpg と png をサポートしています。デフォルトは jpg です。

output

パラメーター

型

必須

説明

type

String

いいえ

base64：画像コンテンツを Base64 フォーマットで返します。同期呼び出しでのみサポートされます。

oss：抽出されたフレームを OSS に保存します (デフォルト)。

oss

String

いいえ

出力ファイルの OSS パス。type が oss の場合に必須です。

例：oss://<BUCKET_NAME>/result/path

レスポンスパラメーター

パラメーター	型	説明	値の例
result.task_id	String	ビデオ抽出タスクの一意の ID。	snapshot-xxxx-abc-123

Curl リクエストの例

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Your API Key>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-snapshot/ops-video-snapshot-001/sync"
  --data '{
    "input":{
        "oss" : "oss://<BUCKET_NAME>/test.mp4"
    },
    "parameters" : {
    },
    "output": {
        "type":"oss",
        "oss" :"oss://<BUCKET_NAME>/result/path"
    }
  }' \

レスポンスの例

{
  "request_id":"83b423e2e63613a878c369c20******",
  "latency":11,
  "usage":{
      "image":64
          },
  "result":{
      "task_id":"snapshot-20250617102142-1108418170738252-b******",
      "status":"SUCCESS",
       "data":[
                {
                  "frame_index": 0,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_0.jpg",
                  "frame_time": 0.0
                },
                ......
                {
                  "frame_index": 1890,
                  "path": "oss://bucket-name/result/path/snapshot-xxxx-abc-123-xxx/snapshot_63.jpg",
                  "frame_time": 63.0
                }                
              ]
            }
}

ステータスコードリファレンス

リクエストが失敗した場合、レスポンスにはエラーを説明するコードとメッセージが含まれます。

{
    "request_id": "6F33AFB6-A35C-4DA7-AFD2-9EA16CCF****",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "JSON parse error: Cannot deserialize value of type `ImageStorage` from String \\"xxx\\""
}

HTTP ステータスコード	エラーコード	説明
200	-	リクエストは成功しました。これには、タスク自体が失敗した場合も含まれます。実際のタスクステータスについては、result.status を確認してください。
404	BadRequest.TaskNotExist	タスクが存在しません。
400	InvalidParameter	無効なリクエストです。
500	InternalServerError	内部エラー。

ステータスコードの詳細については、「ステータスコードリファレンス」をご参照ください。