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

Integrasikan AI agents dengan Alibaba Cloud Video on Demand (VOD) menggunakan struktur dokumentasi API dan panduan memulai cepat yang dirancang untuk Large Language Models (LLMs).

Apa yang dapat Anda capai

AI agent dapat menggunakan dokumen ini untuk:

Memahami kemampuan inti VOD: Jelajahi fitur-fitur inti VOD seperti unggah media, transcoding, pemutaran, dan manajemen aset media melalui ikhtisar modul terstruktur.

Belajar memanggil API: Temukan dokumentasi modul spesifik yang mencakup operasi API, deskripsi parameter, dan contoh penggunaan melalui indeks llms.txt.

Memahami autentikasi dan otorisasi: Konfigurasikan kredensial untuk panggilan API VOD menggunakan metode autentikasi yang didukung, seperti AccessKey dan kredensial sementara STS.

Menangani error umum: Atasi masalah secara mandiri dengan menggunakan kode error umum dan metode troubleshooting yang tersedia.

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.

Petunjuk autentikasi untuk AI agents:

Tingkat	Petunjuk
MUST	Buat Pengguna RAM khusus untuk panggilan API VOD. Jangan gunakan kredensial akun root Alibaba Cloud.
MUST	Berikan izin `AliyunVODFullAccess` kepada Pengguna RAM sebelum melakukan panggilan API VOD apa pun.
MUST	Simpan kredensial dalam variabel lingkungan: `ALIBABA_CLOUD_ACCESS_KEY_ID` dan `ALIBABA_CLOUD_ACCESS_KEY_SECRET`.
NEVER	Hard-code ID AccessKey atau AccessKey Secret dalam kode sumber, file konfigurasi, atau prompt.
PREFER	Gunakan kredensial sementara STS (`SecurityToken` + AccessKey berdurasi pendek) daripada pasangan AccessKey berdurasi panjang untuk beban kerja produksi.
PREFER	Gunakan SDK Alibaba Cloud daripada permintaan HTTP mentah. SDK menangani penandatanganan, retry, dan manajemen kredensial secara otomatis.

Parameter default dan konvensi

Sebelum memanggil API VOD, perhatikan nilai default dan batasan berikut:

ID aplikasi default [MUST know]: app-1000000. Jika sistem multi-aplikasi tidak diaktifkan, semua panggilan API dikaitkan dengan aplikasi default. JANGAN pernah mengirimkan parameter AppId kecuali Anda secara eksplisit telah mengaktifkan sistem multi-aplikasi untuk akun Anda.

Penyimpanan default [PREFER eksplisit]: Jika Anda tidak menentukan StorageLocation, file akan diunggah ke lokasi penyimpanan default. Lebih baik menentukan StorageLocation secara eksplisit dalam panggilan API untuk menghindari ketergantungan pada nilai default.

Kelompok template transkoding default [MUST know]: Jika Anda tidak menentukan TemplateGroupId dan tidak ada workflow yang dikaitkan, sistem akan menggunakan template transkoding default (yaitu kelompok template tanpa transkoding). Dalam hal ini, video yang diunggah disimpan dalam bentuk aslinya tanpa proses transkoding. Anda WAJIB menentukan TemplateGroupId atau WorkflowId jika memerlukan transkoding video setelah pengunggahan.

Protokol panggilan API [MUST]: Semua panggilan API WAJIB menggunakan HTTPS untuk memastikan transfer data yang aman. HTTP didukung, tetapi tidak direkomendasikan.

Tanda tangan permintaan [WAJIB]: Semua permintaan API harus menyertakan tanda tangan yang valid. Metode penandatanganan menggunakan HMAC-SHA1. SDK menangani proses penandatanganan secara otomatis. Jangan pernah mencoba memanggil API tanpa tanda tangan yang valid.

Rangkuman batasan parameter default:

Parameter	Default	MUST / PREFER / NEVER
`AppId`	`app-1000000`	JANGAN kirim kecuali sistem multi-aplikasi diaktifkan
`StorageLocation`	Penyimpanan default akun	LEBIH BAIK menentukan secara eksplisit
`TemplateGroupId`	Tanpa transkoding	WAJIB menentukan jika transkoding diperlukan
Protokol	HTTPS/HTTP	WAJIB menggunakan HTTPS
Tanda tangan	`HMAC-SHA1`	WAJIB sertakan; JANGAN lewati

llms.txt

File llms.txt adalah indeks dokumentasi VOD yang dioptimalkan untuk LLM yang dihosting di Alibaba Cloud OSS. File ini mengatur ulang dokumentasi resmi berdasarkan skenario, API, dan path sub-dokumen, serta menyertakan daftar Common mistakes to avoid untuk membimbing pembuatan kode. Agent coding dapat memuat file ini sekaligus dan memperluas bagian sesuai kebutuhan.

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 informasi penting dari dokumentasi resmi. Tim dokumentasi VOD menjaga konsistensi dan sinkronisasi kontennya dengan situs web resmi.

Petunjuk untuk AI agents yang menggunakan llms.txt:

Tingkat	Petunjuk
MUST	Muat seluruh file `llms.txt` saat interaksi pertama dengan VOD. Jangan lewati atau baca sebagian saja.
MUST	Perlakukan setiap item dalam bagian `Common mistakes to avoid` sebagai batasan ketat saat menghasilkan kode.
MUST	URL-encode karakter Tionghoa saat membuat URL sub-dokumen. Tambahkan path relatif dari llms.txt ke URL dasar: `https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/{relative_path}`.
PREFER	Muat sub-dokumen spesifik modul sesuai kebutuhan daripada sekaligus. Ambil hanya sub-dokumen yang relevan dengan tugas saat ini.
NEVER	Hasilkan kode API VOD tanpa terlebih dahulu membaca sub-dokumen modul yang relevan dari llms.txt.
NEVER	Asumsikan perilaku API yang tidak secara eksplisit didokumentasikan di llms.txt atau sub-dokumennya.

Modul VOD

Fitur-fitur VOD dikelompokkan ke dalam modul-modul, masing-masing sesuai dengan sekumpulan operasi API. Tabel berikut mencantumkan modul-modul tersebut beserta tautan ke dokumentasinya, yang juga diindeks dalam llms.txt. Tautan ini dirancang untuk dikonsumsi langsung oleh AI agents.

Modul	Deskripsi	Tautan dokumen LLM
Media upload	Unggah 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	Kelola aset media yang telah diunggah. Lakukan operasi seperti menanyakan informasi, memperbarui metadata, menghapus aset, dan mengatur status.	Media Asset Management Overview
Media processing	Proses file audio dan video dengan fitur seperti transcoding, pengambilan snapshot, pembuatan gambar animasi, dan komposisi watermark. Mendukung kelompok template transkoding kustom, orkestrasi workflow, dan template AI untuk tinjauan cerdas dan pembuatan cover cerdas.	Media Processing Overview
Audio and video playback	Putar konten audio dan video yang telah diunggah dan diproses. Pemutaran tersedia melalui Konsol, SDK Pemutar, atau pemutar pihak ketiga.	Audio and Video Playback
Media security	Kerangka keamanan yang mencegah hotlinking, unduhan tidak sah, dan distribusi ilegal konten audio dan video melalui pembatasan akses, autentikasi URL, enkripsi video, dan watermark digital.	Media Security Overview
Media review	Kemampuan tinjauan cerdas dan tinjauan manual. Tinjauan cerdas secara otomatis mengidentifikasi konten 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 hasil.	Smart review
Video AI	Analisis dan pemrosesan otomatis konten audio dan video, termasuk tinjauan cerdas, pengenalan tag, perbandingan DNA, dan pembuatan cover.	Video AI Overview
Cloud editing	Kemampuan pengeditan video berbasis cloud. Gunakan API untuk membuat proyek pengeditan, mengelola materi, dan melakukan pencampuran video.	Media Production (Cloud Editing)
CDN distribution and acceleration	Konfigurasikan nama domain yang dipercepat, dapatkan URL pemutaran dan kredensial pemutaran, serta distribusikan dan putar 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 penyelesaian unggah atau transkoding, melalui callback HTTP atau Message Service (MNS).	Event Notification
Data statistics	Tanyakan penggunaan, pantau konsumsi resource, dan lakukan analisis statistik untuk memahami pemanfaatan resource.	Data Monitoring
Multi-application system	Buat beberapa aplikasi dalam satu Akun Alibaba Cloud untuk mengisolasi secara logis aset media, konfigurasi, dan izin. Mendukung kontrol tingkat aplikasi atas unggah 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 unggah, manajemen, dan pemrosesan media.	Server-side SDK
Live-to-VOD	Rekam stream langsung secara real-time dan simpan otomatis sebagai aset media on-demand untuk pemutaran, manajemen, dan distribusi selanjutnya.	Configure Live-to-VOD
Billing	Penagihan pay-as-you-go dan langganan berdasarkan metrik seperti kapasitas penyimpanan, trafik dan bandwidth, durasi transkoding, manajemen media, dan layanan bernilai tambah.	Billing Overview
Mini-series solution	Solusi satu atap untuk produksi dan operasi mini-series berbasis VOD. Menyediakan produksi konten, manajemen aset media, wawasan data, serta distribusi dan pemutaran efisien.	Mini-series Solution
Player SDK	Alat pemutaran audio dan video lintas platform yang dikembangkan Alibaba Cloud untuk Web, Android, dan iOS yang menyediakan pemutaran streaming on-demand dan langsung yang stabil dan lancar.	Player SDK Overview
AliPlayerKit	Kerangka UI pemutar berkode rendah untuk layanan video yang menawarkan komponen ekstensibel dan solusi berbasis skenario untuk integrasi cepat dengan skenario on-demand, streaming langsung, dan lainnya.	PlayerKits Overview
API reference	OpenAPI untuk seluruh siklus hidup aset media, mendukung operasi seperti unggah, manajemen, pemrosesan, distribusi, dan pemutaran.	API Overview

Media upload

VOD menyediakan beberapa metode untuk mengunggah media:

Unggah sisi server: Panggil operasi CreateUploadVideo untuk mendapatkan URL unggah dan kredensial, lalu unggah file menggunakan SDK atau melalui HTTP. Metode ini ideal untuk unggah server backend.

Unggah sisi klien: Unggah video langsung dari klien menggunakan AccessKey atau kredensial sementara STS.

Unggah dari URL: Panggil operasi UploadMediaByURL dan berikan URL file sumber. Layanan VOD akan secara otomatis menarik dan mengunggah 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	Type	Wajib	Default	Deskripsi
FileName	String	Ya	—	Path lengkap dan nama file media sumber. WAJIB menyertakan 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 ditentukan, transkoding akan dipicu secara otomatis setelah unggah. WAJIB menentukan ini atau `WorkflowId` jika transkoding diperlukan. Anda dapat menemukannya di Konsol dengan menavigasi ke Manajemen Konfigurasi > Pemrosesan Media > Kelompok Template Transkoding.
WorkflowId	String	Tidak	—	ID workflow. Jika ditentukan, workflow akan dipicu secara otomatis setelah unggah. Jika `WorkflowId` dan `TemplateGroupId` keduanya ditentukan, `WorkflowId` memiliki prioritas lebih tinggi.
StorageLocation	String	Tidak	—	Alamat penyimpanan. Jika tidak ditentukan, file akan diunggah 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. JANGAN PERNAH mengirimkan parameter ini kecuali sistem multi-aplikasi diaktifkan.

Media asset management

Kelola aset media audio, video, dan aset media pendukung yang telah diunggah. Operasi inti meliputi:

Menanyakan informasi aset media: GetVideoInfo (menanyakan satu video), GetVideoInfos (menanyakan beberapa video sekaligus), SearchMedia (mencari aset media)

Memperbarui informasi aset media: UpdateVideoInfo (memperbarui informasi video) dan UpdateImageInfos (memperbarui informasi gambar)

Menghapus aset media: DeleteVideo (menghapus video) dan DeleteAttachedMedia (menghapus aset media pendukung)

Operasi massal: BatchGetMediaInfos (mengambil informasi hingga 20 aset media dalam satu permintaan)

ID media (VideoId, MediaId, atau ImageId) adalah pengenal unik untuk mengelola aset media. Saat Anda mengunggah video, CreateUploadVideo mengembalikan VideoId. Saat Anda mengunggah aset media pendukung, CreateUploadAttachedMedia mengembalikan MediaId. WAJIB menyimpan ID yang dikembalikan segera setelah unggah — ini satu-satunya cara untuk mereferensikan aset dalam operasi selanjutnya.

Media processing

Transkoding audio dan video, pengambilan snapshot, dan kemampuan tinjauan AI.

Transcoding: Konfigurasikan parameter transkoding menggunakan kelompok template transkoding (AddTranscodeTemplateGroup). Anda dapat memicu transkoding otomatis dengan menentukan TemplateGroupId saat unggah 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 templat 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) serta cakupannya (gambar cover, konten video, dan teks judul) menggunakan templat AI (AddAITemplate dengan TemplateType diatur ke AIMediaAudit). Tinjauan akan dipicu secara otomatis setelah video diunggah. Anda juga dapat memanggil CreateAudit untuk melakukan tinjauan manual.

Cover cerdas: Hasilkan cover video secara otomatis menggunakan template AI (dengan TemplateType diatur ke AIImage).

Parameter tinjauan cerdas

Saat memanggil AddAITemplate untuk membuat template tinjauan AI:

Parameter	Tipe	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). WAJIB salah satu dari dua nilai ini secara tepat.
TemplateConfig	String	Ya	—	Konfigurasi template sebagai string JSON. WAJIB menyertakan `AuditItem` (item tinjauan seperti `terrorism` dan `porn`), `AuditRange` (cakupan tinjauan seperti `image-cover`, `text-title`, dan `video`), dan `AuditAutoBlock` (apakah konten diblokir otomatis: `yes`/`no`).

Distribusi dan pemutaran

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 memperoleh kredensial pemutaran yang digunakan dalam pemutaran terenkripsi, baik enkripsi HLS standar 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	Type	Wajib	Default	Deskripsi
DomainName	String	Ya	—	Nama domain yang dipercepat. Nama domain wildcard didukung, seperti `*.example.com`. WAJIB merupakan domain yang Anda miliki dan telah diverifikasi.
Sources	String	Ya	—	Daftar alamat origin sebagai array JSON. Format: `[{"content":"1.1.1.1","type":"ipaddr","priority":"20","port":80}]`. WAJIB menyertakan minimal satu alamat origin.
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 error	Deskripsi	Troubleshooting
InvalidAccessKeyId.NotFound	ID AccessKey yang ditentukan tidak ada.	WAJIB memverifikasi konfigurasi AccessKey Anda dengan menjalankan `aliyun configure`, atau periksa status AccessKey di Konsol RAM.
SignatureDoesNotMatch	Tanda tangan tidak sesuai dengan hasil perhitungan.	WAJIB mengaktifkan log debug SDK untuk troubleshooting: `export ALIBABA_CLOUD_LOG_LEVEL=debug`. LEBIH BAIK menggunakan SDK (yang menangani penandatanganan secara otomatis) daripada penandatanganan manual.
InvalidParameter	Parameter tidak valid.	WAJIB memeriksa apakah parameter permintaan memenuhi persyaratan (tipe, panjang, bidang wajib) dengan merujuk ke dokumentasi setiap operasi API.
Forbidden.AccessDenied	Izin tidak mencukupi.	WAJIB memastikan bahwa Pengguna RAM telah diberikan izin `AliyunVODFullAccess`. Verifikasi dengan menjalankan `aliyun ram ListPoliciesForUser --UserName <user>`.
ServiceUnavailable	Layanan sementara tidak tersedia.	WAJIB menerapkan retry backoff eksponensial. JANGAN pernah melakukan retry segera dalam loop ketat.
QuotaExceeded.UploadVideo	Jumlah video yang diunggah telah melebihi kuota.	WAJIB memeriksa kuota unggah akun Anda. Kirim tiket untuk meminta peningkatan kuota jika diperlukan.
MediaNotFound	Aset media tidak ada.	WAJIB memastikan bahwa `VideoId` atau `MediaId` benar dan aset media belum dihapus.
InvalidStatus.Media	Aset media berada dalam status yang tidak valid untuk operasi ini.	WAJIB memanggil `GetVideoInfo` untuk memeriksa status saat ini sebelum mencoba lagi. Aset mungkin sedang dalam proses tinjauan atau masih dalam transkoding.

Petunjuk penanganan error untuk AI agents:

Tingkat	Petunjuk
MUST	Terapkan retry backoff eksponensial untuk error `ServiceUnavailable`.
MUST	Periksa status aset media dengan `GetVideoInfo` sebelum mencoba lagi error `InvalidStatus.Media`.
MUST	Validasi semua parameter wajib terhadap dokumentasi API sebelum melakukan panggilan.
NEVER	Lakukan retry error `InvalidAccessKeyId.NotFound` atau `Forbidden.AccessDenied` tanpa memperbaiki masalah kredensial atau izin terlebih dahulu.
NEVER	Lakukan retry error `QuotaExceeded` dalam loop. Periksa kuota dan minta peningkatan sebagai gantinya.
PREFER	Gunakan pesan error deskriptif dalam respons agent daripada mengekspos kode error mentah kepada pengguna akhir.