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

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

サービス

サービス名	サービス ID	サービスの説明	API 呼び出しの QPS 上限 (ルートアカウントと RAM ユーザーを含む)
Video Snapshot Service 001	ops-video-snapshot-001	Video Snapshot Service 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

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

コンソールで、左側メニューの [API キー] をクリックします。[エンドポイント] の下に、[パブリック API ドメイン] (HTTPS をサポート) と、[プライベート API ドメイン] (VPC 環境向け) が表示されます。左上隅のワークスペースのドロップダウンリストから、対象のワークスペースに切り替えます。

workspace_name ：「デフォルト」などのワークスペース名です。
service_id ：「ops-video-snapshot-001」などの組み込みサービス ID です。

リクエストパラメーター

ヘッダーパラメーター

API キー認証

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

ボディパラメーター

パラメーター	タイプ	必須	説明
input	オブジェクト (input)	はい	処理するマルチメディアファイルを指定します。
parameters	オブジェクト	いいえ	サービスパラメーターを指定します。
output	オブジェクト (output)	はい	出力形式とファイルの保存先パスを制御します。

input

パラメーター	タイプ	必須	説明
content	文字列	いいえ	Base64 エンコードされた動画データ。mp4、avi、mkv、mov、flv、webm をサポートします。説明 `input.content` パラメーターと `input.oss` パラメーターは相互排他的です。いずれか 1 つのみを指定してください。 Base64 データの使用：エンコードされた Base64 文字列を `content` パラメーターに `data:video/<FORMAT>;base64,<BASE64_VIDEO>` の形式で渡します。各項目の説明は次のとおりです。 `video/<FORMAT>`：動画形式。たとえば、MP4 動画の場合は `video/mp4` を使用します。 `<BASE64_VIDEO>`：Base64 エンコードされた動画データ。例：data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	文字列	いいえ	入力ファイルの OSS パス。例：oss://<BUCKET_NAME>/xxx/xxx.mp4
file_name	文字列	いいえ	動画ファイル名。指定しない場合、ファイルの内容から名前を解析します。

parameters

パラメーター	タイプ	必須	説明
interval	Int	いいえ	フレーム抽出の間隔 (秒) です。デフォルトは 1 秒です。
format	文字列	いいえ	出力フレームの形式。jpg と png をサポートします。デフォルトは jpg です。

output

パラメーター

タイプ

必須

説明

type

文字列

いいえ

base64：Base64 形式で画像コンテンツを返します。同期呼び出しでのみ使用できます。

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

oss

文字列

はい (type が oss の場合)

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

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

レスポンスパラメーター

パラメーター	タイプ	説明	値の例
result.task_id	文字列	ビデオ抽出タスクの一意の 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}

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

workspace_name ：ワークスペース名。例：デフォルト。
service_id ：組み込みサービス ID。例： ops-video-snapshot-001。

リクエストパラメーター

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

レスポンスパラメータ

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

SnapshotResult

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

Curl リクエストの例

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <お使いの API キー>" \
"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******",  // リクエスト ID
  "latency":11,                                     // レイテンシー
  "usage":{                                          // 使用量
      "image":64                                     // 画像
          },
  "result":{                                         // 結果
      "task_id":"snapshot-20250617102142-1108418170738252-******", // タスク ID
      "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

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

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

リクエストパラメータ

ヘッダーパラメーター

API キー認証

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

ボディパラメーター

パラメーター	タイプ	必須	説明
input	オブジェクト (input)	はい	処理するマルチメディアファイルを指定します。
parameters	オブジェクト	いいえ	サービスパラメーターを指定します。
output	オブジェクト (output)	はい	出力形式とファイルの保存先パスを制御します。

input

パラメーター	タイプ	必須	説明
content	文字列	いいえ	Base64 エンコードされた動画データ。mp4、avi、mkv、mov、flv、webm をサポートします。説明 `input.content` パラメーターと `input.oss` パラメーターは相互排他的です。いずれか 1 つのみを指定してください。 Base64 データの使用：エンコードされた Base64 文字列を `content` パラメーターに `data:video/<FORMAT>;base64,<BASE64_VIDEO>` の形式で渡します。各項目の説明は次のとおりです。 `video/<FORMAT>`：動画形式。たとえば、MP4 動画の場合は `video/mp4` を使用します。 `<BASE64_VIDEO>`：Base64 エンコードされた動画データ。例：data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	文字列	いいえ	入力ファイルの OSS パス。例：oss://<BUCKET_NAME>/xxx/xxx.mp4
file_name	文字列	いいえ	動画ファイル名。指定しない場合、ファイルの内容から名前を解析します。

parameters

パラメーター	タイプ	必須	説明
interval	Int	いいえ	フレーム抽出の間隔 (秒) です。デフォルトは 1 秒です。
format	文字列	いいえ	出力フレームの形式。jpg と png をサポートします。デフォルトは jpg です。

output

パラメーター

タイプ

必須

説明

type

文字列

いいえ

base64：Base64 形式で画像コンテンツを返します。同期呼び出しでのみ使用できます。

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

oss

文字列

はい (type が oss の場合)

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

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

レスポンスパラメータ

パラメーター	タイプ	説明	値の例
result.task_id	文字列	動画抽出タスクの一意の ID。	snapshot-xxxx-abc-123

Curl リクエストの例

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <あなたのAPIキー>" \
  "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/video-snapshot/ops-video-snapshot-001/sync"
  --data '{
    "input":{
        "oss" : "oss://<バケット名>/test.mp4"
    },
    "parameters" : {
    },
    "output": {
        "type":"oss",
        "oss" :"oss://<バケット名>/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****",
    "レイテンシー": 2.0,
    "コード": "InvalidParameter",
    "http_code": 400,
    "メッセージ": "JSON 解析エラー：文字列 \\"xxx\\" から `ImageStorage` 型の値を逆シリアル化できません"
}

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

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

サービス

非同期タスクの作成

URL

リクエストパラメーター

ヘッダーパラメーター

ボディパラメーター

レスポンス パラメーター

curl リクエストの例

レスポンスの例

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

URL

リクエストパラメーター

レスポンスパラメータ

Curl リクエストの例

レスポンスの例

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

URL

リクエストパラメータ

ヘッダーパラメーター

ボディパラメーター

レスポンスパラメータ

Curl リクエストの例

レスポンス例

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

レスポンスパラメーター

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