Bangun ekstraksi keyframe video dengan OpenSearch Snapshot API - OpenSearch

AI Search Open Platform memungkinkan Anda memanggil layanan tangkapan video melalui API untuk mengekstraksi keyframe dari video. Layanan ini dapat dikombinasikan dengan Optical Character Recognition (OCR), penguraian gambar, atau embedding multimoda guna melakukan analisis mendalam dan pemrosesan terstruktur terhadap konten video.

Layanan

Nama layanan	ID layanan	Deskripsi layanan	Batas QPS panggilan API (termasuk Akun Alibaba Cloud dan Pengguna RAM)
Video Snapshot Service 001	ops-video-snapshot-001	Video Snapshot Service 001 (ops-video-snapshot-001) menyediakan kemampuan ekstraksi konten video untuk menangkap keyframe dari video. Anda dapat menggabungkan layanan ini dengan kemampuan embedding multimoda atau penguraian gambar untuk mengaktifkan pengambilan lintas-modalitas.	5 Catatan Untuk mengajukan peningkatan QPS, kirim tiket.

Informasi otentikasi telah diperoleh.
Saat memanggil layanan AI Search Open Platform melalui API, Anda perlu mengotentikasi identitas pemanggil.
Alamat akses layanan telah diperoleh.
Anda dapat memanggil layanan melalui Internet atau virtual private cloud (VPC). Untuk informasi selengkapnya, lihat Dapatkan alamat registrasi 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 VPC. Untuk informasi selengkapnya, lihat Dapatkan alamat akses layanan.

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

Parameter permintaan

Parameter header

Otentikasi kunci API

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

Parameter body

Parameter	Tipe	Wajib	Deskripsi
input	Object(input)	Ya	Menentukan file multimedia yang akan diproses.
parameters	Object	Tidak	Menentukan parameter untuk layanan.
output	Object(output)	Ya	Mengontrol format output dan jalur penyimpanan file.

input

Parameter	Type	Wajib	Deskripsi
content	String	Tidak	Data konten video yang dikodekan Base64. Format yang didukung meliputi mp4, avi, mkv, mov, flv, dan webm. Catatan Parameter input.content dan input.oss saling eksklusif. Tentukan hanya salah satu. Gunakan data Base64: Kirim data Base64 yang telah dikodekan ke parameter `content` dalam format `data:video/<FORMAT>;base64,<BASE64_VIDEO>`. Parameter dijelaskan sebagai berikut: `video/<FORMAT>`: Format video. Misalnya, jika video dalam format MP4, atur parameter ini menjadi `video/mp4`. `<BASE64_VIDEO>`: Data Base64 dari gambar. Contoh: data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	Tidak	Jalur OSS dari file input. Contoh: oss://<BUCKET_NAME>/xxx/xxx.mp4.
file_name	String	Tidak	Nama file video. Jika parameter ini tidak ditetapkan, nama file akan diurai dari konten.

Parameters

Parameter	Tipe	Wajib	Deskripsi
interval	Int	Tidak	Interval keyframe dalam detik. Nilai default adalah 1 detik.
format	String	Tidak	Format output untuk frame yang diambil. Nilai yang valid adalah jpg dan png. Nilai default adalah jpg.

output

Parameter

Tipe

Wajib

Deskripsi

type

String

Tidak

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

oss: Menyimpan file snapshot di OSS. Ini adalah nilai default.

oss

String

Tidak

Jalur OSS untuk file output. Parameter ini wajib jika Anda menetapkan `type` ke `oss`.

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

Parameter respons

Parameter	Jenis	Deskripsi	Contoh
result.task_id	String	ID unik dari 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 VPC. Untuk informasi selengkapnya, lihat Dapatkan alamat akses layanan.

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

Parameter permintaan

Nama Parameter	Tipe	Wajib	Deskripsi	Contoh
service_id	String	Ya	ID layanan.	ops-video-snapshot-001
task_id	String	Ya	ID tugas dari respons permintaan pembuatan tugas tangkapan video asinkron.	snapshot-xxxx-abc-123

Parameter respons

Parameter	Jenis	Deskripsi	Contoh
result.task_id	String	ID unik dari tugas ekstraksi video.	snapshot-xxxx-abc-123
result.status	String	Status pekerjaan: PENDING: Tugas sedang tertunda. SUCCESS: Tugas berhasil. FAIL: Tugas gagal.	PENDING
result.error	String	Pesan kesalahan jika `status` bernilai `FAIL`. Kosong jika tugas berhasil.
result.data	List(SnapshotResult)	Hasil pemrosesan video.
usage.image_count	Int	Jumlah gambar yang dihasilkan dari operasi snapshot.

SnapshotResult

Parameter	Tipe	Deskripsi
frame_index	Int	Indeks frame dalam video.
path	String	Jalur OSS file. Jika Anda menetapkan output ke OSS, ini adalah jalur penyimpanan hasil snapshot di OSS yang telah di-encode URL.
content	String	Konten gambar yang dikodekan Base64. Hanya salah satu dari `content` atau `path` yang dikembalikan. `content` hanya dikembalikan untuk tugas sinkron.
frame_time	Float	Timestamp frame saat ini 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 tangkapan video sinkron

URL

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

host: Titik akhir layanan. Anda dapat memanggil API melalui Internet atau VPC. Untuk informasi selengkapnya, lihat Dapatkan alamat akses layanan.

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

Parameter permintaan

Parameter header

Otentikasi kunci API

Parameter	Tipe	Wajib	Deskripsi	Contoh
Content-Type	String	Ya	Jenis permintaan: application/json	application/json
Authorization	String	Ya	Kunci API	Bearer OS-d1**2a

Parameter body

Parameter	Tipe	Wajib	Deskripsi
input	Object(input)	Ya	Menentukan file multimedia yang akan diproses.
parameters	Object	Tidak	Menentukan parameter untuk layanan.
output	Object(output)	Ya	Mengontrol format output dan jalur penyimpanan file.

input

Parameter	Tipe	Wajib	Deskripsi
content	String	Tidak	Data konten video yang dikodekan Base64. Format yang didukung meliputi mp4, avi, mkv, mov, flv, dan webm. Catatan Parameter input.content dan input.oss saling eksklusif. Tentukan hanya salah satu. Gunakan data Base64: Kirim data Base64 yang telah dikodekan ke parameter `content` dalam format `data:video/<FORMAT>;base64,<BASE64_VIDEO>`. Parameter dijelaskan sebagai berikut: `video/<FORMAT>`: Format video. Misalnya, jika video dalam format MP4, atur parameter ini menjadi `video/mp4`. `<BASE64_VIDEO>`: Data Base64 dari gambar. Contoh: data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	Tidak	Jalur OSS dari file input. Contoh: oss://<BUCKET_NAME>/xxx/xxx.mp4.
file_name	String	Tidak	Nama file video. Jika parameter ini tidak ditetapkan, nama file akan diurai dari konten.

Parameters

Parameter	Tipe	Wajib	Deskripsi
interval	Int	Tidak	Interval keyframe dalam detik. Nilai default adalah 1 detik.
format	String	Tidak	Format output untuk frame yang diambil. Nilai yang valid adalah jpg dan png. Nilai default adalah jpg.

output

Parameter

Tipe

Wajib

Deskripsi

type

String

Tidak

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

oss: Menyimpan file snapshot di OSS. Ini adalah nilai default.

oss

String

Tidak

Jalur OSS untuk file output. Parameter ini wajib jika Anda menetapkan `type` ke `oss`.

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

Parameter respons

Parameter	Tipe	Deskripsi	Contoh
result.task_id	String	ID unik dari 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
                }                
              ]
            }
}

Deskripsi kode status

Jika permintaan gagal, respons mencakup `code` dan `message` yang menunjukkan penyebab kesalahan.

{
    "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	Deskripsi
200	-	Permintaan berhasil. Ini mencakup skenario di mana tugas gagal. Status tugas sebenarnya ditunjukkan oleh parameter `result.status`.
404	BadRequest.TaskNotExist	Tugas tidak ada.
400	InvalidParameter	Permintaan tidak valid.
500	InternalServerError	Kesalahan internal.

Untuk informasi selengkapnya tentang kode status, lihat Deskripsi kode status.