AI agents: Memulai - ApsaraVideo VOD - Alibaba Cloud Documentation Center

Panduan ini membantu developer mengintegrasikan AI agents dengan Alibaba Cloud Video on Demand (VOD), menyediakan petunjuk quick-start dan struktur dokumentasi API yang dirancang khusus untuk Large Language Models (LLMs).

Apa yang dapat Anda capai

Dengan dokumen ini, AI agent dapat:

Memahami kemampuan inti VOD: Pelajari fitur-fitur utama VOD—seperti upload media, transcoding, pemutaran, dan manajemen aset media—melalui ikhtisar modul terstruktur.
Belajar memanggil API: Gunakan indeks llms.txt untuk menemukan dokumentasi spesifik modul yang mencakup operasi API, deskripsi parameter, dan contoh penggunaan guna memandu AI agent dalam memanggil API VOD.
Memahami autentikasi dan otorisasi: Pelajari cara mengonfigurasi kredensial untuk panggilan API VOD melalui metode autentikasi yang didukung, seperti AccessKey dan kredensial sementara STS.
Menangani error umum: Selesaikan masalah secara mandiri menggunakan daftar kode error umum dan metode troubleshooting yang disediakan.

Prasyarat

Sebelum menggunakan API VOD, selesaikan langkah-langkah berikut:

Aktifkan VOD: Aktifkan Alibaba Cloud Video on Demand (VOD) di Konsol Alibaba Cloud.
Buat AccessKey: Buat ID AccessKey dan AccessKey Secret di Konsol RAM. Untuk alasan keamanan, kami merekomendasikan membuat Pengguna RAM khusus untuk panggilan API VOD dan memberikan izin AliyunVODFullAccess.
Instal SDK: Gunakan SDK Alibaba Cloud untuk memanggil API VOD. Kode produk POP untuk VOD adalah vod, dan versi API-nya adalah 2017-03-21.

Parameter default dan konvensi

Sebelum memanggil API VOD, pahami nilai default dan konvensi berikut:

ID aplikasi default: app-1000000. Jika sistem multi-aplikasi tidak diaktifkan, semua panggilan API dikaitkan dengan aplikasi default.
Penyimpanan default: Jika Anda tidak menentukan StorageLocation, file akan diupload ke alamat penyimpanan default.
Kelompok template transkoding default: Jika Anda tidak menentukan TemplateGroupId dan tidak ada workflow yang dikaitkan, template transkoding default (kelompok template tanpa transkoding) akan digunakan.
Protokol panggilan API: Gunakan HTTPS untuk semua panggilan API guna memastikan transfer data yang aman.
Tanda tangan permintaan: Semua permintaan API memerlukan verifikasi tanda tangan. Metode penandatanganan menggunakan HMAC-SHA1. SDK secara otomatis menangani proses penandatanganan.

llms.txt

File <a class="text-blue-link hover:text-black dark:text-blue-link-dark dark:hover:text-white" href="https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/llms.txt" id="cbd45583b0yim">llms.txt</a> adalah indeks dokumentasi VOD yang dioptimalkan untuk Large Language Models (LLMs) dan dihosting di Alibaba Cloud OSS. File ini mengatur ulang dokumentasi resmi berdasarkan skenario, API, dan jalur sub-dokumen, serta mengekstrak daftar Kesalahan umum yang harus dihindari untuk memandu pembuatan kode. Hal ini memungkinkan agen pengodean untuk memuat file sekaligus dan memperluas bagian sesuai permintaan.

URL dasar untuk mengakses file indeks adalah:

https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/llms.txt

Hubungan dengan dokumentasi resmi: llms.txt adalah indeks. Sub-dokumen, seperti Media Upload/Upload from URL.md, merupakan versi ringkas dari informasi penting dalam dokumentasi resmi. Isinya tetap konsisten dan disinkronkan dengan situs web resmi oleh tim dokumentasi VOD.

Modul VOD

Fitur VOD terdiri atas sejumlah modul, masing-masing sesuai dengan serangkaian operasi API. Tabel berikut mencantumkan modul-modul tersebut dan menyediakan tautan ke dokumentasinya, yang juga diindeks dalam <a class="text-blue-link hover:text-black dark:text-blue-link-dark dark:hover:text-white" data-init-id="cbd45583b0yim" href="https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/llms.txt" id="ba1236e6f155b">llms.txt</a>. Tautan-tautan ini dirancang untuk dikonsumsi langsung oleh agen AI.

Modul	Deskripsi	Tautan dokumen llms
Media upload	Upload aset media audio, video, gambar, dan aset media pendukung menggunakan Konsol, SDK sisi klien, API sisi server, atau URL.	Media Upload Overview
Media asset management	Mengelola aset media yang telah diupload. Lakukan operasi seperti mengkueri informasi, memperbarui metadata, menghapus aset, dan mengatur status.	Media Asset Management Overview
Media processing	Memproses file audio dan video menggunakan fitur-fitur seperti transcoding, pengambilan snapshot, pembuatan gambar animasi, dan pencampuran watermark. Mendukung kelompok template transkoding kustom, orkestrasi workflow, dan template AI untuk tinjauan cerdas serta pembuatan cover cerdas.	Media Processing Overview
Audio and video playback	Memutar konten audio dan video yang telah diupload dan diproses. Pemutaran tersedia melalui Konsol, Player SDK, atau pemutar pihak ketiga.	Audio and Video Playback
Media security	Kerangka kerja keamanan yang mencegah hotlinking, unduhan tidak sah, dan distribusi ilegal konten audio dan video melalui mekanisme seperti pembatasan akses, autentikasi URL, enkripsi video, dan watermark digital.	Media Security Overview
Media review	Menyediakan kemampuan tinjauan cerdas dan tinjauan manual. Tinjauan cerdas secara otomatis mengidentifikasi konten yang tidak sesuai (seperti konten pornografi, kekerasan, dan politik) dalam audio dan video, serta mendukung template tinjauan AI kustom. Tinjauan manual menyediakan API untuk membuat tugas tinjauan dan mengirimkan hasilnya.	Smart review
Video AI	Menjalankan analisis dan pemrosesan otomatis terhadap konten audio dan video, termasuk tinjauan cerdas, pengenalan tag, perbandingan DNA, dan pembuatan cover.	Video AI Overview
Cloud editing	Menyediakan kemampuan editing di cloud. Anda dapat menggunakan API untuk membuat proyek editing, mengelola materi, dan melakukan pencampuran video.	Media Production (Cloud Editing)
CDN distribution and acceleration	Konfigurasikan nama domain yang dipercepat dan peroleh URL pemutaran serta kredensial pemutaran untuk mendistribusikan dan memutar audio dan video. Mendukung fitur pemutaran aman seperti akselerasi CDN, autentikasi URL, dan enkripsi DRM.	CDN Distribution and Acceleration
Event notification	Terima notifikasi tentang event pemrosesan media, seperti selesainya upload atau transcoding, melalui callback HTTP atau Message Service (MNS).	Event Notification
Data statistics	Kueri penggunaan, pantau konsumsi resource, dan lakukan analisis statistik untuk memahami penggunaan layanan dan pemanfaatan resource.	Data Monitoring
Multi-application system	Buat beberapa aplikasi dalam satu Akun Alibaba Cloud untuk mengisolasi secara logis aset media, konfigurasi, dan izin. Ini mendukung kontrol tingkat aplikasi atas upload media, pemutaran, manajemen aset media, dan callback pesan.	Multi-application System
Server-side SDK	Gunakan SDK untuk Java, Python, PHP, dan C/C++ untuk memanggil API guna upload, manajemen, dan pemrosesan media.	Server-side SDK
Live-to-VOD	Merekam live stream secara real-time dan secara otomatis menyimpannya sebagai aset media on-demand untuk pemutaran, manajemen, dan distribusi selanjutnya.	Configure Live-to-VOD
Billing	Menawarkan penagihan bayar sesuai penggunaan dan langganan berdasarkan metrik seperti kapasitas penyimpanan, traffic dan bandwidth, durasi transcoding, manajemen media, dan layanan bernilai tambah.	Billing Overview
Mini-series solution	Solusi satu atap untuk produksi dan operasional mini-series berbasis VOD. Menyediakan produksi konten, manajemen aset media, wawasan data, serta distribusi dan pemutaran yang efisien.	Mini-series Solution
Player SDK	Alat pemutaran audio dan video lintas platform yang dikembangkan oleh Alibaba Cloud untuk Web, Android, dan iOS yang menyediakan pemutaran streaming on-demand dan live yang stabil dan lancar.	Player SDK Overview
AliPlayerKit	Kerangka kerja UI pemutar low-code untuk layanan video yang menawarkan komponen yang dapat diperluas dan solusi berbasis skenario untuk integrasi cepat dengan skenario on-demand, live streaming, dan lainnya.	PlayerKits Overview
API reference	Menyediakan OpenAPI untuk seluruh siklus hidup aset media, mendukung operasi seperti upload, manajemen, pemrosesan, distribusi, dan pemutaran.	API Overview

Media upload

VOD menyediakan beberapa metode untuk mengupload media:

Upload sisi server: Panggil operasi CreateUploadVideo untuk mendapatkan URL upload dan kredensial, lalu upload file menggunakan SDK atau melalui HTTP. Metode ini ideal untuk upload dari server backend.
Upload sisi klien: Upload video langsung dari klien menggunakan AccessKey atau kredensial sementara STS.
Upload dari URL: Panggil operasi UploadMediaByURL dan berikan URL file sumber. Layanan VOD secara otomatis menarik dan mengupload file tersebut. Metode ini ideal untuk migrasi massal atau mengimpor media dari URL pihak ketiga.

Parameter utama

Parameter berikut sangat penting saat memanggil CreateUploadVideo:

Parameter	Tipe	Wajib	Default	Deskripsi
FileName	String	Ya	—	Jalur lengkap dan nama file media sumber, termasuk ekstensi (misalnya, `video_01.mp4`).
Title	String	Ya	—	Judul media. Maksimal 128 karakter.
Description	String	Tidak	—	Deskripsi audio atau video. Panjang maksimum: 1.024 karakter.
CateId	Long	Tidak	—	ID kategori. Anda dapat menemukan ID ini di Konsol: Manajemen Konfigurasi > Konfigurasi Manajemen Aset Media > Manajemen Kategori.
Tags	String	Tidak	—	Maksimal 16 tag yang dipisahkan koma. Setiap tag maksimal 32 karakter.
TemplateGroupId	String	Tidak	—	ID kelompok template transkoding. Jika Anda menentukan parameter ini, transcoding akan secara otomatis dipicu setelah upload selesai. Anda dapat menemukannya di Konsol dengan menavigasi ke Manajemen Konfigurasi > Pemrosesan Media > Kelompok Template Transkoding.
WorkflowId	String	Tidak	—	ID workflow. Jika Anda menentukan parameter ini, workflow akan secara otomatis dipicu setelah upload selesai. Jika kedua parameter `WorkflowId` dan `TemplateGroupId` ditentukan, `WorkflowId` memiliki prioritas lebih tinggi.
StorageLocation	String	Tidak	—	Alamat penyimpanan. Jika tidak ditentukan, file akan diupload ke alamat penyimpanan default. Anda dapat menemukannya di Konsol dengan menavigasi ke Manajemen Konfigurasi > Konfigurasi Manajemen Aset Media > Penyimpanan.
CoverURL	String	Tidak	—	URL cover video kustom.
AppId	String	Tidak	`app-1000000`	ID aplikasi. Menentukan aplikasi dalam sistem multi-aplikasi.

Media asset management

Modul manajemen aset media digunakan untuk mengelola aset media audio, video, dan aset media pendukung yang telah diupload. Operasi inti meliputi:

Kueri informasi aset media: GetVideoInfo (mengkueri satu video), GetVideoInfos (mengkueri beberapa video sekaligus), SearchMedia (mencari aset media)
Perbarui informasi aset media: UpdateVideoInfo (memperbarui informasi video), UpdateImageInfos (memperbarui informasi gambar)
Hapus aset media: DeleteVideo (menghapus video), DeleteAttachedMedia (menghapus aset media pendukung)
Operasi massal: BatchGetMediaInfos (mengambil informasi hingga 20 aset media sekaligus)

Catatan

ID media (VideoId, MediaId, atau ImageId) adalah pengenal unik untuk mengelola aset media. Saat Anda mengupload video, CreateUploadVideo mengembalikan VideoId. Saat Anda mengupload aset media pendukung, CreateUploadAttachedMedia mengembalikan MediaId.

Media processing

Modul pemrosesan media menyediakan kemampuan seperti transcoding audio dan video, pengambilan snapshot, dan tinjauan AI.

Transcoding: Konfigurasikan parameter transcoding menggunakan kelompok template transkoding (AddTranscodeTemplateGroup). Anda dapat memicu transcoding otomatis dengan menentukan TemplateGroupId saat upload atau menggunakan workflow. Anda dapat mengatur parameter seperti kodek video (misalnya, H.264), resolusi (misalnya, 640×360), dan bitrate (misalnya, 400 kbps).
Pengambilan snapshot: Konfigurasikan parameter snapshot menggunakan template snapshot (AddVodTemplate dengan TemplateType diatur ke Snapshot). Mendukung berbagai jenis, termasuk snapshot standar dan sprite.
Tinjauan cerdas: Konfigurasikan item tinjauan (seperti konten pornografi, kekerasan, dan politik) dan cakupan (gambar cover, konten video, dan teks judul) menggunakan template AI (AddAITemplate dengan TemplateType diatur ke AIMediaAudit). Tinjauan secara otomatis dipicu setelah video diupload. Anda juga dapat memanggil CreateAudit untuk tinjauan manual.
Cover cerdas: Secara otomatis menghasilkan cover video menggunakan template AI (dengan TemplateType diatur ke AIImage).

Parameter tinjauan cerdas

Saat memanggil AddAITemplate untuk membuat template tinjauan AI:

Parameter	Type	Wajib	Default	Deskripsi
TemplateName	String	Ya	—	Nama template AI. Panjang maksimum: 128 byte.
TemplateType	String	Ya	—	Tipe template: `AIMediaAudit` (tinjauan cerdas) atau `AIImage` (cover cerdas).
TemplateConfig	String	Ya	—	Konfigurasi template dalam bentuk string JSON. Termasuk `AuditItem` (item tinjauan seperti `terrorism` dan `porn`), `AuditRange` (cakupan tinjauan seperti `image-cover`, `text-title`, dan `video`), dan `AuditAutoBlock` (apakah konten diblokir secara otomatis: `yes`/`no`).

Distribusi dan pemutaran

Modul distribusi dan pemutaran menyediakan pengambilan URL pemutaran video dan kemampuan pemutaran aman.

Dapatkan URL pemutaran: Panggil GetPlayInfo untuk mendapatkan URL pemutaran video. Anda dapat menentukan format output (seperti MP4, FLV, atau HLS) dan definisi.
Dapatkan kredensial pemutaran: Panggil GetVideoPlayAuth untuk mendapatkan kredensial pemutaran guna pemutaran terenkripsi (baik enkripsi standar HLS maupun enkripsi proprietary Alibaba Cloud).
Manajemen nama domain: Panggil AddVodDomain untuk menambahkan nama domain yang dipercepat, BatchStartVodDomain untuk mengaktifkannya, dan BatchStopVodDomain untuk menonaktifkannya.

Parameter konfigurasi domain

Saat memanggil AddVodDomain untuk menambahkan nama domain yang dipercepat:

Parameter	Tipe	Wajib	Default	Deskripsi
DomainName	String	Ya	—	Nama domain yang dipercepat. Nama domain wildcard didukung, seperti `*.example.com`.
Sources	String	Ya	—	Daftar alamat origin dalam bentuk array JSON. Format: `[{"content":"1.1.1.1","type":"ipaddr","priority":"20","port":80}]`.
Scope	String	Tidak	`domestic`	Cakupan akselerasi: `domestic` (Tiongkok daratan), `overseas` (wilayah di luar Tiongkok daratan, termasuk Hong Kong, Makau, dan Taiwan), atau `global` (akselerasi global).

Error umum dan troubleshooting

Kode kesalahan	Deskripsi	Troubleshooting
InvalidAccessKeyId.NotFound	ID AccessKey yang ditentukan tidak ada.	Gunakan `aliyun configure` untuk memverifikasi konfigurasi AccessKey Anda, atau periksa status AccessKey di Konsol RAM.
SignatureDoesNotMatch	Tanda tangan tidak sesuai dengan hasil perhitungan.	Aktifkan log debug SDK untuk menangani masalah tanda tangan: `export ALIBABA_CLOUD_LOG_LEVEL=debug`.
InvalidParameter	Parameter tidak valid.	Periksa apakah parameter permintaan memenuhi persyaratan (seperti tipe, panjang, dan apakah wajib diisi) dengan merujuk pada dokumentasi masing-masing API.
Forbidden.AccessDenied	Izin tidak mencukupi.	Konfirmasi bahwa Pengguna RAM telah diberikan izin VOD yang diperlukan, seperti `AliyunVODFullAccess`. Anda dapat memeriksa kebijakan yang diberikan dengan menjalankan `aliyun ram ListPoliciesForUser --UserName <user>`.
ServiceUnavailable	Layanan sementara tidak tersedia.	Ini menunjukkan masalah sementara pada layanan. Ulangi permintaan dengan exponential backoff.
QuotaExceeded.UploadVideo	Jumlah video yang diupload telah melebihi kuota.	Periksa kuota upload akun Anda. Anda dapat mengajukan tiket untuk meminta peningkatan kuota.
MediaNotFound	Aset media tidak ada.	Konfirmasi bahwa `VideoId` atau `MediaId` benar dan aset media belum dihapus.
InvalidStatus.Media	Aset media berada dalam status yang tidak valid untuk operasi ini.	Aset berada dalam status yang mencegah operasi ini (misalnya, 'sedang ditinjau'). Panggil `GetVideoInfo` untuk memeriksa status saat ini sebelum mencoba lagi.