Bangun ekstraksi keyframe video dengan OpenSearch Snapshot API - OpenSearch - Alibaba Cloud - OpenSearch

AI Search Open Platform mendukung pemanggilan layanan Video Snapshot melalui API. Layanan ini mengekstraksi keyframe dari video dan menggabungkannya dengan layanan OCR, penguraian gambar, atau embedding multimoda untuk memungkinkan analisis mendalam dan pemrosesan terstruktur terhadap konten video.

Services

Service Name	Service ID	Service Description	Batas QPS Pemanggilan API (Termasuk Akun Root dan Pengguna RAM)
Video Snapshot Service 001	ops-video-snapshot-001	Video Snapshot Service 001 (ops-video-snapshot-001) mengekstraksi konten dari video dengan menangkap keyframe. Dikombinasikan dengan kemampuan embedding multimoda atau penguraian gambar, layanan ini memungkinkan retrieval lintas-modal.	5 Catatan Untuk meminta batas QPS API yang lebih tinggi, kirimkan tiket ke dukungan teknis.

Dapatkan kredensial autentikasi

Platform Terbuka AI Search memerlukan Kunci API untuk autentikasi. Untuk petunjuknya, lihat Dapatkan Kunci API.
Dapatkan Titik Akhir layanan

Anda dapat memanggil layanan melalui jaringan publik atau VPC. Untuk detailnya, lihat Dapatkan Titik Akhir Layanan.

Buat Tugas Asinkron

Metode permintaan: POST

URL

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

host: Titik akhir layanan. Anda dapat memanggil API melalui Internet atau melalui VPC. Untuk detailnya, lihat Dapatkan Titik Akhir Layanan.

Di Konsol, klik API Keys di panel navigasi sebelah kiri. Di bawah Endpoints, Anda akan melihat Public API Domain (mendukung HTTPS) dan Private API Domain (untuk lingkungan VPC). Gunakan dropdown ruang kerja di pojok kiri atas untuk beralih ke ruang kerja target Anda.

workspace_name: Nama ruang kerja, misalnya default.
service_id: ID layanan bawaan, misalnya ops-video-snapshot-001.

Parameter Permintaan

Parameter Header

Autorisasi kunci API

Parameter	Type	Required	Description	Contoh Nilai
Content-Type	String	Ya	Jenis permintaan: application/json	application/json
Authorization	String	Ya	Kunci API	Bearer OS-d1**2a

Parameter Body

Parameter	Type	Required	Description
input	Object(input)	Ya	Menentukan file multimedia yang akan diproses.
parameters	Object	Tidak	Menentukan parameter layanan.
output	Object(output)	Ya	Mengontrol format output dan jalur penyimpanan file.

input

Parameter	Type	Required	Description
content	String	Tidak	Data video yang dikodekan Base64. Mendukung mp4, avi, mkv, mov, flv, dan webm. Catatan Parameter input.content dan input.oss saling eksklusif. Tentukan hanya salah satu. Gunakan data Base64: Kirim string Base64 yang telah dikodekan ke parameter `content` dalam format `data:video/<FORMAT>;base64,<BASE64_VIDEO>`, di mana: `video/<FORMAT>`: Format video. Misalnya, untuk video MP4, gunakan `video/mp4`. `<BASE64_VIDEO>`: Data video yang dikodekan Base64. Contoh: data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	Tidak	Jalur OSS file input, misalnya, oss://<BUCKET_NAME>/xxx/xxx.mp4.
file_name	String	Tidak	Nama file video. Jika tidak ditentukan, nama diurai dari konten file.

Parameters

Parameter	Type	Required	Description
interval	Int	Tidak	Interval ekstraksi frame dalam detik. Nilai default adalah 1 detik.
format	String	Tidak	Format frame output. Mendukung jpg dan png. Nilai default adalah jpg.

output

Parameter

Type

Required

Description

type

String

Tidak

base64: Mengembalikan konten gambar dalam format Base64. Hanya didukung untuk panggilan sinkron.

oss: Menyimpan frame yang diekstraksi di OSS (default).

oss

String

Tidak

Jalur OSS untuk file output. Wajib ditentukan jika type bernilai oss.

Contoh: oss://<BUCKET_NAME>/result/path

Parameter Respons

Parameter	Type	Description	Contoh Nilai
result.task_id	String	ID unik tugas ekstraksi video.	snapshot-xxxx-abc-123

Contoh Permintaan 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"
    }
  }' \

Contoh Respons

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

Dapatkan Status Tugas Asinkron

Metode permintaan: GET

URL

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

host: Titik akhir layanan. Anda dapat memanggil API melalui Internet atau melalui VPC. Untuk detailnya, lihat Dapatkan Titik Akhir Layanan.

workspace_name: Nama ruang kerja, misalnya default.
service_id: ID layanan bawaan, misalnya ops-video-snapshot-001.

Parameter Permintaan

Nama Parameter	Type	Required	Description	Contoh
service_id	String	Ya	ID layanan.	ops-video-snapshot-001
task_id	String	Ya	ID tugas yang dikembalikan saat membuat tugas video snapshot asinkron.	snapshot-xxxx-abc-123

Parameter Respons

Parameter	Type	Description	Contoh Nilai
result.task_id	String	ID unik tugas ekstraksi video.	snapshot-xxxx-abc-123
result.status	String	Status tugas: PENDING: Menunggu diproses SUCCESS: Tugas berhasil diselesaikan FAIL: Tugas gagal dan dihentikan	PENDING
result.error	String	Pesan kesalahan saat status bernilai FAIL. Kosong dalam kondisi normal.
result.data	List(SnapshotResult)	Hasil pemrosesan video.
usage.image_count	Int	Jumlah frame yang diekstraksi.

SnapshotResult

Parameter	Type	Description
frame_index	Int	Nomor frame dalam video.
path	String	Jalur OSS file. Saat output diatur ke OSS, bidang ini menampilkan jalur penyimpanan frame yang diekstraksi di OSS dalam format URL-encoded.
content	String	Konten gambar yang dikodekan Base64. Hanya salah satu dari content atau path yang ada, dan bidang ini hanya muncul untuk tugas sinkron.
frame_time	Float	Timestamp frame yang diekstraksi dalam video, dalam satuan detik.

Contoh Permintaan 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-******" \

Contoh Respons

{
  "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
                }                
              ]
            }
}

Buat Tugas Video Snapshot Sinkron

URL

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

host: Titik akhir layanan. Anda dapat memanggil API melalui Internet atau melalui VPC. Untuk detailnya, lihat Dapatkan Titik Akhir Layanan.

workspace_name: Nama ruang kerja, misalnya default.
service_id: ID layanan bawaan, misalnya ops-video-snapshot-001.

Parameter Permintaan

Parameter Header

Autorisasi kunci API

Parameter	Type	Required	Description	Contoh Nilai
Content-Type	String	Ya	Jenis permintaan: application/json	application/json
Authorization	String	Ya	Kunci API	Bearer OS-d1**2a

Parameter Body

Parameter	Type	Required	Description
input	Object(input)	Ya	Menentukan file multimedia yang akan diproses.
parameters	Object	Tidak	Menentukan parameter layanan.
output	Object(output)	Ya	Mengontrol format output dan jalur penyimpanan file.

input

Parameter	Type	Required	Description
content	String	Tidak	Data video yang dikodekan Base64. Mendukung mp4, avi, mkv, mov, flv, dan webm. Catatan Parameter input.content dan input.oss saling eksklusif. Tentukan hanya salah satu. Gunakan data Base64: Kirim string Base64 yang telah dikodekan ke parameter `content` dalam format `data:video/<FORMAT>;base64,<BASE64_VIDEO>`, di mana: `video/<FORMAT>`: Format video. Misalnya, untuk video MP4, gunakan `video/mp4`. `<BASE64_VIDEO>`: Data video yang dikodekan Base64. Contoh: data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	Tidak	Jalur OSS file input, misalnya, oss://<BUCKET_NAME>/xxx/xxx.mp4.
file_name	String	Tidak	Nama file video. Jika tidak ditentukan, nama diurai dari konten file.

Parameters

Parameter	Type	Required	Description
interval	Int	Tidak	Interval ekstraksi frame dalam detik. Nilai default adalah 1 detik.
format	String	Tidak	Format frame output. Mendukung jpg dan png. Nilai default adalah jpg.

output

Parameter

Type

Required

Description

type

String

Tidak

base64: Mengembalikan konten gambar dalam format Base64. Hanya didukung untuk panggilan sinkron.

oss: Menyimpan frame yang diekstraksi di OSS (default).

oss

String

Tidak

Jalur OSS untuk file output. Wajib ditentukan jika type bernilai oss.

Contoh: oss://<BUCKET_NAME>/result/path

Parameter Respons

Parameter	Type	Description	Contoh Nilai
result.task_id	String	ID unik tugas ekstraksi video.	snapshot-xxxx-abc-123

Contoh Permintaan 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"
    }
  }' \

Contoh Respons

{
  "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
                }                
              ]
            }
}

Referensi Kode Status

Jika permintaan gagal, respons mencakup kode dan pesan yang menjelaskan kesalahan tersebut.

{
    "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\\""
}

Kode Status HTTP	Kode Kesalahan	Description
200	-	Permintaan berhasil. Ini termasuk kasus di mana tugas itu sendiri gagal. Periksa result.status untuk mengetahui status tugas sebenarnya.
404	BadRequest.TaskNotExist	Tugas tidak ada.
400	InvalidParameter	Permintaan tidak valid.
500	InternalServerError	Kesalahan internal.

Untuk informasi selengkapnya tentang kode status, lihat Referensi Kode Status.