Tangkapan video - OpenSearch

Platform AI Search Open mendukung pemanggilan layanan tangkapan video melalui API untuk mengekstrak keyframe dari video. Dikombinasikan dengan OCR, penguraian gambar, atau layanan embedding multimoda, memungkinkan penguraian mendalam dan pemrosesan terstruktur konten video.

Layanan

Nama Layanan	ID Layanan	Deskripsi Layanan	Batas QPS panggilan API (termasuk Akun Alibaba Cloud dan Pengguna RAM)
Layanan Tangkapan Video 001	ops-video-snapshot-001	Layanan Tangkapan Video 001 (ops-video-snapshot-001) menyediakan kemampuan ekstraksi konten video untuk menangkap keyframe dari video. Dikombinasikan dengan layanan embedding multimoda atau kemampuan penguraian gambar, memungkinkan pengambilan lintas modus.	5 Catatan Untuk mengajukan QPS yang lebih tinggi, kirimkan tiket.

Informasi otentikasi diperoleh.
Saat memanggil layanan Platform AI Search Open menggunakan API, Anda perlu mengotentikasi identitas pemanggil.
Alamat akses layanan diperoleh.
Anda dapat memanggil layanan melalui Internet atau virtual private cloud (VPC). Untuk informasi lebih lanjut, lihat Dapatkan alamat pendaftaran layanan.

Buat tugas asinkron

Metode permintaan: POST

URL

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

host: Alamat untuk memanggil layanan. Anda dapat memanggil layanan API melalui Internet atau VPC. Untuk informasi lebih lanjut, lihat Dapatkan alamat pendaftaran layanan.

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

Parameter permintaan

Parameter Header

Otentikasi API-KEY

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

Parameter Body

Parameter	Tipe	Diperlukan	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	Diperlukan	Deskripsi
content	String	Tidak	Data encoding Base64 dari konten video. Format yang didukung termasuk mp4, avi, mkv, mov, flv, dan webm. Catatan Parameter input.content dan input.oss bersifat eksklusif. Anda hanya dapat menentukan salah satu dari mereka. Menggunakan data BASE64: Kirim data BASE64 yang telah dienkod ke parameter `content` dalam format `data:video/<FORMAT>;base64,<BASE64_VIDEO>`, dimana: `video/<FORMAT>`: Format video. Sebagai contoh, jika video berformat mp4, atur ini menjadi `video/mp4`. `<BASE64_VIDEO>`: Data BASE64 dari gambar. Contoh: data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	Tidak	Jalur OSS dari file input, misalnya oss://<BUCKET_NAME>/xxx/xxx.mp4.
file_name	String	Tidak	Nama file video. Jika tidak disetel, nama file diurai dari konten.

Parameters

Parameter	Tipe	Diperlukan	Deskripsi
interval	Int	Tidak	Interval keyframe. Nilai default: 1. Satuan: detik.
format	String	Tidak	Format output yang didukung untuk penangkapan frame adalah jpg dan png. Format default adalah jpg.

output

Parameter

Tipe

Diperlukan

Deskripsi

type

String

Tidak

base64: Mengembalikan konten gambar dalam format base64, hanya didukung dalam panggilan sinkron.

oss: Menyimpan file snapshot di OSS (default).

oss

String

Tidak

Jalur OSS dari file output. Parameter ini diperlukan saat type diatur 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/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 layanan API melalui Internet atau melalui VPC. Untuk informasi lebih lanjut, lihat Dapatkan alamat akses layanan.

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

Parameter permintaan

Parameter	Tipe	Diperlukan	Deskripsi	Contoh
service_id	String	Ya	ID layanan.	ops-video-snapshot-001
task_id	String	Ya	ID tugas dari respons saat membuat tugas tangkapan video asinkron.	snapshot-xxxx-abc-123

Parameter respons

Parameter	Tipe	Deskripsi	Contoh
result.task_id	String	ID unik dari tugas ekstraksi video.	snapshot-xxxx-abc-123
result.status	String	Status tugas: PENDING: Tertunda SUCCESS: Tugas selesai dengan sukses FAIL: Tugas gagal dan dihentikan	PENDING
result.error	String	Pesan kesalahan ketika status=FAIL. Kosong dalam kondisi normal.
result.data	List(SnapshotResult)	Hasil pemrosesan video.
usage.image_count	Int	Jumlah gambar yang dihasilkan dari snapshot.

SnapshotResult

Parameter	Tipe	Deskripsi
frame_index	Int	Nomor frame dalam video.
path	String	Jalur OSS dari file. Ketika pengguna menentukan OSS sebagai output, ini adalah jalur penyimpanan hasil snapshot di OSS, dienkripsi URL.
content	String	Konten gambar yang dienkod Base64. Hanya salah satu dari content atau path yang akan ada, dan content hanya dikembalikan saat menjalankan tugas sinkron.
frame_time	Float	Timestamp frame snapshot saat ini dalam video, dalam 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: Alamat untuk memanggil layanan. Anda dapat memanggil layanan API melalui Internet atau VPC. Untuk informasi lebih lanjut, lihat Dapatkan alamat pendaftaran layanan.

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

Parameter permintaan

Parameter Header

Otentikasi API-KEY

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

Parameter Body

Parameter	Tipe	Diperlukan	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	Diperlukan	Deskripsi
content	String	Tidak	Data encoding Base64 dari konten video. Format yang didukung termasuk mp4, avi, mkv, mov, flv, dan webm. Catatan Parameter input.content dan input.oss bersifat eksklusif. Anda hanya dapat menentukan salah satu dari mereka. Menggunakan data BASE64: Kirim data BASE64 yang telah dienkod ke parameter `content` dalam format `data:video/<FORMAT>;base64,<BASE64_VIDEO>`, dimana: `video/<FORMAT>`: Format video. Sebagai contoh, jika video berformat mp4, atur ini menjadi `video/mp4`. `<BASE64_VIDEO>`: Data BASE64 dari gambar. Contoh: data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlzbWZj...
oss	String	Tidak	Jalur OSS dari file input, misalnya oss://<BUCKET_NAME>/xxx/xxx.mp4.
file_name	String	Tidak	Nama file video. Jika tidak disetel, nama file diurai dari konten.

Parameters

Parameter	Tipe	Diperlukan	Deskripsi
interval	Int	Tidak	Interval keyframe. Nilai default: 1. Satuan: detik.
format	String	Tidak	Format output yang didukung untuk penangkapan frame adalah jpg dan png. Format default adalah jpg.

output

Parameter

Tipe

Diperlukan

Deskripsi

type

String

Tidak

base64: Mengembalikan konten gambar dalam format base64, hanya didukung dalam panggilan sinkron.

oss: Menyimpan file snapshot di OSS (default).

oss

String

Tidak

Jalur OSS dari file output. Parameter ini diperlukan saat type diatur 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
                }                
              ]
            }
}

Kode status

Jika terjadi kesalahan dalam permintaan, hasil output akan menunjukkan penyebab kesalahan melalui kode dan pesan.

{
    "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, termasuk skenario kegagalan tugas. Status tugas sebenarnya perlu ditentukan dari result.status.
404	BadRequest.TaskNotExist	Pesan kesalahan yang dikembalikan karena tugas tidak ada.
400	InvalidParameter	Permintaan Tidak Valid.
500	InternalServerError	Kesalahan internal.

Untuk informasi lebih lanjut tentang kode status, lihat Kode status.